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. No content from this project's retrieval or recommendation logic is official OWASP guidance; always cite the guide name, version, and source commit a result traces back to.

What it does

• 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 profile -- explicitly labeled unverified candidates, never a completed test plan.

Every result carries full provenance (repository, commit, path, content hash, license), so a citation always traces back to the exact upstream source.

It is a knowledge retrieval service, not an offensive security execution platform. It does not — and will not — execute scanning/exploitation tools, expose a shell, reach a caller-specified target, act as an autonomous pentest agent, or mutate data over MCP (source sync and ingestion are offline CLI-only steps). See SECURITY.md for the full threat model.

Related MCP server: turva-mcp

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 independently store content that could drift out of sync. See docs/architecture.md and docs/data-model.md.

Supported guides

Exact pins live in sources/sources.lock.yaml (see docs/versioning.md). latest is never a valid version anywhere -- it's rejected by a validator.

Quickstart

Requires Python 3.12+, uv, and Docker.

uv sync --all-extras
cp .env.example .env                    # local-dev defaults, no real secrets
docker compose up -d postgres           # PostgreSQL + pgvector
uv run alembic upgrade head             # apply the schema

uv run pentest-guide source sync --guide wstg   # fetch a pinned source
uv run pentest-guide ingest --all               # compile into the registry
uv run pentest-guide index embeddings           # build the semantic index

uv run pentest-guide query search "credentials over http" --mode hybrid
uv run pentest-guide mcp serve                  # stdio; --transport streamable-http for HTTP

Prefer a container? Pull the prebuilt multi-arch image instead of building: docker pull ghcr.io/sunick2009/mcp-owasp-pentesting-guide:latest -- full run/serve and MCP-client wiring in docs/deployment.md.

Documentation

Licensing

• This project's own code: Apache-2.0 (LICENSE).

• Each upstream guide's content: CC BY-SA 4.0, per sources/licenses/ -- carried through on every compiled TestCase.source.license.

This repository does not bulk-copy OWASP guide text: source sync + local compilation + provenance reference is the model; committed fixtures under tests/fixtures/ are short, attributed excerpts. See NOTICE and docs/licensing.md for the full attribution chain.

Key file paths