pentest-guide-kb

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

This project is not an official OWASP project and is not endorsed by OWASP. It compiles and re-serves content from independent OWASP testing 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 -- explicitly labeled as unverified candidates, never a completed test plan.
• Full provenance (repository, commit, path, content hash, license) on every result, so a citation can always be traced back to the exact upstream 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 security execution 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, the vector 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.md for the schema.

4. Supported guides

Guide	Short name	Upstream repository	Pinned in this repo
OWASP Web Security Testing Guide	WSTG	OWASP/wstg	tag v4.2
OWASP Mobile App Security Testing Guide	MASTG	OWASP/mastg	tag v2.0.0
OWASP IoT Security Testing Guide	ISTG	OWASP/owasp-istg	tag v1.0.1
OWASP AI Testing Guide	AITG	OWASP/www-project-ai-testing-guide	commit on main (no tagged release yet -- status: draft)

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 build from docker/postgres/ and docker/neo4j/ (both are thin FROM pins of pgvector/pgvector:pg16 and neo4j:5-community -- no :latest). No password or API key is baked into any image; all come from .env / docker-compose.yml environment variables (copy .env.example to .env first, or rely on the compose file's local-dev defaults).

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

7. Source pinning

sources/sources.lock.yaml pins each guide's repository, tag/branch, and exact 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 entry looks different (pinned to a main-branch commit, status: draft, since it 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-tree parser (ingestion/markdown_parser.py), not fragile regex scanning -- see docs/ingestion.md for how each guide's real document structure differs (WSTG's ID table, MASTG's YAML frontmatter, ISTG's multi-test-per-file bold-label sections, AITG's ID - Title heading, including a real en-dash variant that had to be handled explicitly). Ingestion is deterministic: compiling the same pinned commit twice produces byte-identical content hashes (verified in tests/unit/test_wstg_parser.py:: test_wstg_compile_is_deterministic). Unrecognized sections are preserved in sections.extra_sections with a ValidationIssue, never silently dropped.

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 tried first) -> full-text (PostgreSQL tsvector) and/or semantic (pgvector) -> Reciprocal Rank Fusion -> lexical reranking -> provenance packaging. See docs/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 MCP transports.

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" return path anywhere in this codebase. See docs/mcp-api.md for all eleven tools, ten resource URI templates, and five prompts, and skills/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), every CLI command, MCP tool, and test still works -- graph-only operations raise a 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 the graph tests, Neo4j) isn't reachable -- see tests/conftest.py. CI (.github/workflows/ci.yml) starts a real pgvector/pgvector:pg16 service container and runs everything, including a wiki build+validate pass, against it; nothing in CI depends on a paid API (the default mock embedding provider is a deterministic hash, not a real model). source-validation.yml is a separate, non-blocking workflow that checks upstream 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 across versions.
• Relationships key on canonical ids, not versioned ones -- this matters concretely for AITG, whose "version" is a commit-derived string (unreleased-<sha>) that changes on every re-pin (see docs/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. This repository does not bulk-copy OWASP guide text -- source sync + local compilation + provenance reference is the model; committed test fixtures under tests/fixtures/ are short, attributed excerpts (see each fixture directory's ATTRIBUTION.md), not full guide dumps.

17. Roadmap

See IMPLEMENTATION_STATUS.md for exactly what's implemented vs. known limitations 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 same reason); a real embedding provider wired into CI-optional eval runs to exercise true semantic (non-lexical) recall; multi-value platform/category filters for semantic search (currently full-text only); a single cross-guide SQL query for multi-guide search instead of one query per guide 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_inferred relationship could appear.
• Report vulnerabilities per SECURITY.md (GitHub private vulnerability reporting), not a public issue.

19. Not an official OWASP project

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

---

Key file paths

What	Where
Domain models	src/pentest_guide_kb/domain/models.py
Guide parsers	src/pentest_guide_kb/ingestion/{wstg,mastg,istg,aitg}.py
Storage / repositories	src/pentest_guide_kb/storage/
Retrieval pipeline	src/pentest_guide_kb/retrieval/
MCP server	src/pentest_guide_kb/mcp/{server,resources,tools,prompts}.py
CLI	src/pentest_guide_kb/cli.py
Wiki generator + Error Book	src/pentest_guide_kb/wiki/
Neo4j projection (optional)	src/pentest_guide_kb/graph/
Source lock	sources/sources.lock.yaml
Curated relationships	registry/relationships/cross-guide.yaml
Agent Skill	skills/owasp-guide-research/SKILL.md
Docs	docs/*.md
Tests	tests/{unit,integration,contract,evals}/