pentest-guide-kb

pentest-guide-kb

A read-only, versioned knowledge base for OWASP testing guides, served overthe Model Context Protocol (MCP) so AI agents and IDEs can query themprecisely instead of relying on training-data memory.

This project is not an official OWASP project and is not endorsed byOWASP. It compiles and re-serves content from independent OWASPtesting guides under their own licenses -- see Licensing.

1. Purpose

• Precise lookup of a specific OWASP test by id (versioned or canonical).
• Natural-language search across test procedures (full-text + semantic).
• Browsing a guide by version, category, platform, or feature keyword.
• Cross-guide relationship traversal, with provenance on every edge.
• Version comparison for a test across two compiled guide releases.
• Candidate-test generation for a target system profile -- explicitlylabeled as unverified candidates, never a completed test plan.
• Full provenance (repository, commit, path, content hash, license) onevery result, so a citation can always be traced back to the exactupstream source it came from.

2. Non-goals

This repository does not contain, and will not accept, any of:

• Execution of Nmap, sqlmap, Nuclei, Frida, ADB, or any other scanning/exploitation tool.
• An arbitrary shell-execution MCP tool.
• Automated vulnerability exploitation, or network access to a caller-specified target.
• An autonomous pentest agent.
• MCP tools that sync sources, run ingestion, or otherwise mutate data --those are offline CLI-only operations (see Security).

This is a knowledge retrieval service, not an offensive securityexecution platform.

3. Architecture

Official OWASP Git Repositories (wstg, mastg, owasp-istg, www-project-ai-testing-guide)
        |
        v
Source Mirror and Version Lock        sources/sources.lock.yaml, sources/.cache/
        |
        v
Deterministic Guide Compilers         src/pentest_guide_kb/ingestion/*
        |
        v
Canonical Registry (PostgreSQL)       src/pentest_guide_kb/storage/*
        |
        +-- metadata + JSONB (test_cases, test_case_sections, ...)
        +-- full-text search (tsvector + GIN)
        +-- pgvector semantic search (embeddings)
        +-- Generated Markdown Wiki    src/pentest_guide_kb/wiki/*
        +-- Optional Neo4j projection  src/pentest_guide_kb/graph/*  (--profile graph)
        |
        v
Read-only MCP Server                  src/pentest_guide_kb/mcp/*
        |
        v
AI Agents and IDE Clients

The PostgreSQL registry is the single source of truth. The Wiki, thevector index, and the Neo4j graph are derived views compiled from it --none of them independently store content that could drift out of sync.See docs/architecture.md for the full write-up, and docs/data-model.mdfor the schema.

4. Supported guides

Exact pins live in sources/sources.lock.yaml; see Versioning.

5. Installation

Requires Python 3.12+, uv, and Docker.

uv sync --all-extras

6. Running with Docker Compose

docker compose up -d postgres          # PostgreSQL + pgvector
uv run alembic upgrade head            # apply the schema

docker compose --profile graph up -d neo4j   # optional -- Neo4j graph projection
docker compose up mcp                        # MCP server over streamable-http, :8000
docker compose up wiki                       # builds + serves the wiki, :8001

mcp/wiki build from the repo root Dockerfile; postgres/neo4j buildfrom docker/postgres/ and docker/neo4j/ (both are thin FROM pins ofpgvector/pgvector:pg16 and neo4j:5-community -- no :latest). Nopassword or API key is baked into any image; all come from .env /docker-compose.yml environment variables (copy .env.example to .envfirst, or rely on the compose file's local-dev defaults).

Health checks gate startup: mcp/wiki wait for postgres'spg_isready check before starting.

7. Source pinning

sources/sources.lock.yaml pins each guide's repository, tag/branch, andexact commit -- never latest. Nothing under src/pentest_guide_kb/mcp/touches the network; source sync is an explicit, offline CLI step:

uv run pentest-guide source list                       # show current pins
uv run pentest-guide source sync --guide wstg --tag v4.2   # fetch, don't pin yet
uv run pentest-guide validate                           # check what was fetched
uv run pentest-guide source sync --guide wstg --tag v4.2 --pin   # now pin it
uv run pentest-guide source verify                       # confirm local checkout == lock file
uv run pentest-guide source diff --guide wstg             # has upstream moved since the pin?

See sources/README.md for the full workflow, including why AITG's entrylooks different (pinned to a main-branch commit, status: draft, sinceit has no tagged release).

8. Ingestion

uv run pentest-guide ingest --guide wstg
uv run pentest-guide ingest --all
uv run pentest-guide validate

Each guide has its own GuideParser (src/pentest_guide_kb/ingestion/ {wstg,mastg,istg,aitg}.py) built on a shared Markdown-AST heading-treeparser (ingestion/markdown_parser.py), not fragile regex scanning -- seedocs/ingestion.md for how each guide's real document structure differs(WSTG's ID table, MASTG's YAML frontmatter, ISTG's multi-test-per-filebold-label sections, AITG's ID - Title heading, including a real en-dashvariant that had to be handled explicitly). Ingestion is deterministic:compiling the same pinned commit twice produces byte-identical contenthashes (verified in tests/unit/test_wstg_parser.py:: test_wstg_compile_is_deterministic). Unrecognized sections are preservedin sections.extra_sections with a ValidationIssue, never silentlydropped.

9. Search

uv run pentest-guide query exact WSTG-v42-ATHN-01
uv run pentest-guide query search "credentials transported over http" --mode hybrid
uv run pentest-guide query related WSTG-v42-ATHN-01 --include-inferred

Pipeline: query classification -> exact id/alias resolution (always triedfirst) -> full-text (PostgreSQL tsvector) and/or semantic (pgvector) ->Reciprocal Rank Fusion -> lexical reranking -> provenance packaging. Seedocs/retrieval.md.

10. MCP client configuration

{
  "mcpServers": {
    "pentest-guide-kb": {
      "command": "uv",
      "args": ["run", "pentest-guide", "mcp", "serve"],
      "cwd": "/path/to/pentest-guide-kb",
      "env": { "DATABASE_URL": "postgresql+psycopg://pentest_guide:pentest_guide@localhost:5432/pentest_guide_kb" }
    }
  }
}

Or point at the Dockerized streamable-http endpoint from docker compose up mcp (http://localhost:8000/mcp) if your client supports HTTP MCPtransports.

11. MCP tool example

{
  "tool": "guide_search",
  "input": {
    "query": "OAuth redirect URI testing in Android WebView",
    "guides": ["WSTG", "MASTG"],
    "platforms": ["android"],
    "search_mode": "hybrid",
    "limit": 10
  }
}

Every result carries guide: {name, version} and source: {repository, commit, path, content_hash, license} -- there is no "bare summary" returnpath anywhere in this codebase. See docs/mcp-api.md for all eleven tools,ten resource URI templates, and five prompts, andskills/owasp-guide-research/references/mcp-tools.md for when to use each.

12. Generating the Wiki

uv run pentest-guide wiki build              # writes wiki/docs/{guides,platforms,features,relationships,versions}/
uv run pentest-guide wiki validate            # Error Book: dangling links, missing provenance, collisions, ...
uv run pentest-guide wiki validate --format sarif
uv run pentest-guide wiki serve               # mkdocs serve (requires `uv sync --extra wiki`)

13. Neo4j (optional profile)

Neo4j is never required. With NEO4J_ENABLED=false (the default), everyCLI command, MCP tool, and test still works -- graph-only operations raisea clear GraphNotConfiguredError instead of failing silently.

docker compose --profile graph up -d neo4j
# .env: NEO4J_ENABLED=true, NEO4J_URI=bolt://localhost:7687, ...
uv run pentest-guide graph project
uv run pentest-guide graph validate
uv run pentest-guide graph clear

14. Testing and CI

uv run pytest                 # unit + integration + contract + evals (149 tests)
uv run pytest tests/unit tests/contract          # no database required
uv run pytest tests/integration -m integration   # requires PostgreSQL
uv run ruff check . && uv run ruff format --check . && uv run mypy src

Integration/contract/eval tests auto-skip when PostgreSQL (or, for thegraph tests, Neo4j) isn't reachable -- see tests/conftest.py. CI(.github/workflows/ci.yml) starts a real pgvector/pgvector:pg16 servicecontainer and runs everything, including a wiki build+validate pass,against it; nothing in CI depends on a paid API (the default mockembedding provider is a deterministic hash, not a real model).source-validation.yml is a separate, non-blocking workflow that checksupstream drift on the pinned commits.

15. Versioning

• Every exported test id is versioned by default (WSTG-v42-ATHN-01);canonical ids (WSTG-ATHN-01) track the same logical test acrossversions.
• Relationships key on canonical ids, not versioned ones -- thismatters concretely for AITG, whose "version" is a commit-derived string(unreleased-<sha>) that changes on every re-pin (seedocs/data-model.md).
• latest is never a valid value anywhere a version is expected --rejected by a Pydantic validator on GuideVersion.version.
• sources.lock.yaml is the only place a source's tag/commit is pinned,and only source sync --pin (run after validate) may change it.

16. Licensing

• This project's own code: Apache-2.0 (LICENSE).
• Each upstream guide's content: CC BY-SA 4.0, per sources/licenses/.Every compiled TestCase.source.license field carries this through.
• See NOTICE and docs/licensing.md for the full attribution chain. Thisrepository does not bulk-copy OWASP guide text -- source sync + localcompilation + provenance reference is the model; committed test fixturesunder tests/fixtures/ are short, attributed excerpts (see eachfixture directory's ATTRIBUTION.md), not full guide dumps.

17. Roadmap

See IMPLEMENTATION_STATUS.md for exactly what's implemented vs. knownlimitations today. Near-term candidates: a real Feature/Technique/Tool domain entity (currently guide_find_by_feature is keyword-heuristic, and the Neo4j ontology's Technique/Tool/Weakness/Component/VerificationControl node types are unpopulated for the samereason); a real embedding provider wired into CI-optional eval runs toexercise true semantic (non-lexical) recall; multi-value platform/categoryfilters for semantic search (currently full-text only); a singlecross-guide SQL query for multi-guide search instead of one query perguide merged by score.

18. Security

• The MCP server is read-only: no shell execution, no arbitrary URL fetch,no network scanning, no source sync, no ingestion, no database mutation-- see SECURITY.md for the full threat model.
• Every tool input is a bounded Pydantic model (max_query_length,max_result_limit, max_graph_traversal_depth).
• SourceReference.path rejects path traversal at ingestion time.
• include_inferred defaults to False everywhere an llm_inferredrelationship could appear.
• Report vulnerabilities per SECURITY.md (GitHub private vulnerabilityreporting), not a public issue.

19. Not an official OWASP project

This project is not an official OWASP project and is not endorsed byOWASP. It is an independent, unofficial tool that compiles publiclyavailable OWASP guide content (under each guide's own CC BY-SA 4.0license) into a queryable knowledge base. No content generated by thisproject's retrieval, ranking, or candidate-recommendation logic should bepresented as official OWASP guidance -- always cite the guide name,version, and source commit that a result actually traces back to.

Key file paths