Praetor

Agentic pentest & red-team harness — web (Burp) + network/AD, one operator log.

v1.0 — the repo is github.com/TyrusRC/praetor. Binaries: praetor-mcp (MCP server) and praetor-burp-ext-<version>.jar (Burp extension). The Python package directory is praetor/ (import-path rename completed in v1.1).

Praetor is a Model Context Protocol (MCP) server that turns Claude Code (or any MCP-aware LLM client) into an agentic pentester and red-teamer across two co-equal lanes:

• Web lane (Burp): HTTP capabilities, scanner, sitemap, proxy history, and Collaborator, plus a knowledge-driven probe engine (128+ matchers), SAST + secrets layer (opengrep / gitleaks / trufflehog / git-dumper / Noir), and native vuln-class orchestrators. Every request routes through Burp, so every finding is replayable from the Burp UI and citable by Logger index.
• Network / red-team lane: advanced network recon and post-exploitation that Burp can't see — run_network_recon (a chained discover → service-aware enum → leads pipeline), run_nmap, a sanctioned runner for impacket / netexec / responder / bloodhound-python / certipy / kerbrute / enum4linux-ng / smbmap / evil-winrm, offline cracking (crack_hashes), and a reusable credential store. Every action is recorded in a MITRE ATT&CK-tagged operator log with loot chain-of-custody — the non-Burp evidence a red-team report cites in place of a Logger index.

Both lanes forward into Ghostwriter as the central reporting/oplog hub, and share one save-finding pipeline with persistent target memory. Nothing in Praetor is an optional add-on tool — the web stack (nuclei/ffuf/sqlmap/…) and the network stack (nmap/netexec/impacket/…) are both core.

Authorized Use

This is an offensive security tool. Use only on systems where you have explicit written permission to test (bug bounty scope, signed penetration test, red team contract, internal lab). The authors are not responsible for misuse.

Architecture

                                      ┌─ web lane ──> Java Burp extension <- Montoya -> Burp Suite
LLM client <- stdio MCP -> MCP server ┤                 (127.0.0.1:8111, proxy :8080)
                                      └─ network lane ─> nmap / impacket / netexec / responder / ...
                                                          (bypass Burp; operator log + loot)
                          both lanes ─> Ghostwriter (GraphQL) : central reporting / oplog hub

• Web lane: the Java extension exposes a REST API on 127.0.0.1:8111 and tunnels HTTP through Burp's proxy listener (127.0.0.1:8080), so every probe appears in Proxy history and carries a Logger index.
• Network lane: external tools run directly (TCP/SMB/LDAP/Kerberos — Burp can't proxy them); each run is recorded in the operator log (.burp-intel/<domain>/network/oplog.jsonl, ATT&CK-tagged) with output under material/tool-output/ and captured secrets in network/loot/. That operator-log id is the evidence a network finding cites.
• The Python MCP server is a thin client the LLM speaks to via stdio.
• Target intelligence, the operator log, loot, and the credential store all persist under .burp-intel/<domain>/ (gitignored).
• Ghostwriter (optional but core when present) is the reporting hub both lanes forward into via GraphQL.

Features

• MCP tool surface covering recon, scan, exploit, browser, auth, research, and reporting.
• HTTP send tools that route through Burp's proxy (curl-style, raw, repeater, intruder, concurrent).
• Adaptive scan engine driven by a JSON knowledge base (matchers + craft guidance) mapped to OWASP Top 10 (Web / API / LLM / Mobile), OWASP WSTG, PayloadsAllTheThings, HackTricks Web + Cloud — see the Coverage table.
• Native vuln-class orchestrators where no third-party covers the surface: test_csrf, test_ssrf, test_ssti (SSTImap-modeled, multi-phase: polyglot → math distinguisher → engine-specific capability probes → optional blind sleep), test_xxe, test_websocket (CSWSH upgrade-handshake), test_prototype_pollution.
• Native auth attack tooling with zero external deps: forge_jwt (8 attack modes), crack_jwt_secret (HS dictionary), test_login_bypass, test_mfa_bypass, test_session_lifecycle, analyze_reset_tokens (entropy + sequential detection).
• Third-party wrappers proxied through Burp: sqlmap, dalfox, commix, nuclei, ffuf, katana, subfinder, amass, wafw00f, arjun, gau, waybackurls, wpscan, nikto.
• Network / red-team lane: run_network_recon chains nmap discovery → service-aware enumeration → prioritized leads → auto-loot, and bridges discovered web services back to Burp. A sanctioned runner drives impacket / netexec / responder / bloodhound-python / certipy / kerbrute / enum4linux-ng / smbmap / evil-winrm; crack_hashes (offline hashcat/john) plus a credential store close the capture → crack → reuse loop. Every action is logged to a MITRE ATT&CK-tagged operator log with loot chain-of-custody, and forwards to Ghostwriter. HARD safety (Rules 5–9) refuses destructive/brute args; scope is engagement-mode-aware.
• SAST + secrets layer (v1.0): audit_crawled_artifacts opengrep-over-proxy-bodies (DOM clobbering / proto pollution / postMessage), run_opengrep_source source-tree SAST, run_gitleaks + run_trufflehog (live verification = HIGH severity floor), dump_exposed_git chains with discover_common_files .git/HEAD to reconstruct repo + extract secrets. Noir OpenAPI ingest via import_scope --format noir_json.
• Active LLM/MCP probes (v1.0): ai_prompt_injection, rag_injection, mcp_server_attacks, mcp_tool_poisoning, vector_db_injection, echoleak (CVE-2025-32711). Declarative prompt-injection guardrail (inspect_for_prompt_injection).
• CI integration (v1.0): SARIF 2.1.0 + JUnit XML exporters, compliance-framework tags (OWASP / PCI-DSS / HIPAA / SOC2 / GDPR / CWE), intensity=safe|normal|aggressive flag, per-engagement cost cap (set_engagement_cost_cap), auto-PoC generate_repro_script rendering runnable curl from the finding's logger_index.
• Save-finding pipeline with a 7-question gate (assess_finding) and per-program policy overrides.
• False-positive defenses: payload-tied reflection-liveness (a payload reflected only HTML/JS-encoded is not XSS), dual-baseline access-control check (compare_auth_states probes unauthenticated — public data is not an IDOR), OOB-mandatory verdicts for blind classes (blind SSRF/XXE/XSS need a resolved Collaborator interaction), AND-composed matchers with baseline deltas, and ≥3× replay for timing/blind classes.
• Stealth headless browser (CloakBrowser — patched Chromium binary with source-level fingerprint fixes, not JS shims) that proxies through Burp.
• Fast history queries: get_proxy_count (sub-ms), since_index tail polling, host exact-match filter, ByteArray in-place body search.
• Persistent target memory with staleness detection and cross-target pattern reuse.
• Operator override surfaces for severity, scope filter, NEVER-SUBMIT class, confidence floor.

Requirements

Core (both lanes):

• Burp Suite Professional or Community Edition — web lane
• Java 21+, Python 3.11+ with uv, Go (for the ProjectDiscovery tools)
• An MCP-aware LLM client (Claude Code, Claude Desktop, etc.)
• Web tools (core, not optional): nuclei, ffuf, sqlmap, katana, subfinder, dalfox, httpx, amass, gau, waybackurls, wpscan, nikto, opengrep, gitleaks, trufflehog
• Network / red-team tools (core, not optional): nmap, netexec, impacket-scripts, responder, bloodhound-python, certipy, kerbrute, enum4linux-ng, smbmap, evil-winrm, hashcat, john, gobuster, seclists
• Docker + Docker Compose — for the Ghostwriter reporting hub

./setup.sh installs all of the above (Kali/Parrot via apt, other distros via apt/uv/go with clone fallbacks). ./doctor.sh reports what's present. On Kali most tools are preinstalled or one apt away.

Best with Burp Professional (scanner control + Collaborator); Community degrades gracefully — see below.

Burp Edition Compatibility

Professional — full support. Default target environment.

Community — supported with manual setup. Almost everything works because the extension and MCP server use Burp's Montoya API for HTTP/proxy/scope, not the Pro-only scanner pipeline. Pro-only features degrade gracefully:

Run check_pro_features() at session start to confirm which Pro capabilities the operator's instance exposes — the MCP server detects them at runtime, so Community users get a clear "not available" message instead of a silent hang.

First-Time Setup

The shortest path from a fresh clone to a working agent. Each step links to its
detailed section below.

# 1. Clone
git clone https://github.com/TyrusRC/praetor.git && cd praetor

# 2. One-shot install — Java/Maven/Python/uv, builds the extension, installs the
#    MCP server, writes .mcp.json. (Manual steps are under Installation.)
./setup.sh            # Linux/macOS   ·   ./setup.ps1 / ./setup.bat on Windows

# 3. Verify the install
./doctor.sh

1. Load the Burp extension. In Burp: Extensions → Add → Java →
   target/praetor-burp-ext-<version>.jar (path printed by the build). On the
   Praetor config tab, defaults 127.0.0.1:8111 already match the server — no
   change needed on a single host (WSL is different).

2. Point your MCP client at the server. setup.sh writes .mcp.json for
   you; confirm it launches python -m praetor (see Configuration).
   Reload your MCP client so the tools appear.

3. Session smoke test. Ask the agent to run check_pro_features() and
   list_tier1_tools() — that confirms the MCP ↔ Burp link and shows the tool
   entry points.

4. (Optional) Reporting hub. Stand up Ghostwriter for centralized
   oplog/findings — one script, default praetor login.
   Praetor works fully without it; local .burp-intel/ stays the source of truth.

5. (Optional) Tune env. Copy .env.example to .env and edit only what you
   need (Environment Variables); every value has a
   working default.

You're ready — pick a lane in Usage.

Installation

Pick the level of automation you want.

Quick — uvx (no clone needed for the MCP server)

The MCP server runs straight from the source tree with uvx. You still need the Burp extension JAR loaded in Burp Suite — see the Manual section below for that part.

uvx --from "git+https://github.com/TyrusRC/praetor.git#subdirectory=mcp-server" \
    praetor-mcp

Or in .mcp.json:

{
  "mcpServers": {
    "praetor": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/TyrusRC/praetor.git#subdirectory=mcp-server",
        "praetor-mcp"
      ]
    }
  }
}

Automated (full local checkout — extension + server)

./setup.sh        # Linux / macOS
./setup.ps1       # Windows PowerShell
./setup.bat       # Windows double-click

The script installs Java 21+, Maven, Python 3.11+, uv, Go where missing, builds the extension, installs the MCP server (which pulls CloakBrowser and warms its stealth Chromium download), optionally installs ProjectDiscovery tools, and writes .mcp.json.

Run ./doctor.sh afterwards to verify the install.

Manual

# 1. Build the Burp extension
cd burp-extension
mvn package
# Load target/praetor-burp-ext-1.0.0.jar in Burp: Extensions -> Add -> Java

# 2. Install the MCP server
cd ../mcp-server
uv venv
uv sync

# 3. Configure your MCP client (see below)

pipx

pipx install "git+https://github.com/TyrusRC/praetor.git#subdirectory=mcp-server"
praetor-mcp                   # entrypoint

Configuration

Create .mcp.json in the project root. The file is gitignored; each developer maintains their own.

{
  "mcpServers": {
    "praetor": {
      "command": "/absolute/path/to/praetor/mcp-server/.venv/bin/python",
      "args": ["-m", "praetor"]
    }
  }
}

Connection defaults — no config needed on a single host. The extension's config tab defaults to Host 127.0.0.1, Port 8111, and the MCP server defaults to the same 127.0.0.1:8111. When Burp and Claude Code run on the same machine (or on WSL with mirrored networking), the two align and the MCP auto-connects with nothing to change. Edit the tab's Host/Port only for the exceptions below: a non-default port, or reaching Burp across a host boundary (WSL NAT → bind 0.0.0.0). Caller-supplied BURP_API_HOST / BURP_API_PORT env in .mcp.json override the client side.

On Windows replace the command with C:\\...\\.venv\\Scripts\\python.exe.

WSL (Burp on the Windows host)

./setup.sh auto-detects WSL and its networking mode, then configures .mcp.json accordingly. Two modes:

• Mirrored (recommended, secure). Add to %UserProfile%\.wslconfig:

  [wsl2]
  networkingMode=mirrored
  

  then run wsl --shutdown in PowerShell and reopen WSL. Burp on Windows 127.0.0.1:8111 is now reachable from WSL as 127.0.0.1 — no env override, no bind change, nothing exposed off the host. Verify from WSL with Burp running: curl -s http://127.0.0.1:8111/api/health. Requires Windows 11 22H2+.

• NAT (default). Reach Burp via the Windows host IP (the WSL default-route gateway, e.g. 172.22.112.1):

  1. Add an env block to .mcp.json setting BURP_API_HOST to that IP (setup.sh writes this for you).
  2. In the Praetor config tab set Host = 0.0.0.0.
  3. Launch Burp with the JVM flag -Dpraetor.allow_non_loopback_bind=true — the extension refuses a non-loopback bind without it.

  NAT mode exposes the unauthenticated API on the WSL virtual switch; use only on a trusted host. Prefer mirrored.

Environment Variables

Ghostwriter auth precedence: admin-secret → API token → username/password login. With neither secret set, Praetor logs in to Ghostwriter's login action with GHOSTWRITER_USERNAME/GHOSTWRITER_PASSWORD (default praetor/praetor) and mints/refreshes a JWT itself — so a fresh instance with a praetor account works with only GHOSTWRITER_URL + GHOSTWRITER_OPLOG_ID set.

The Java extension also accepts JVM system properties praetor.proxy.host and praetor.proxy.port (highest precedence). ./setup-ghostwriter.sh writes the GHOSTWRITER_* values into .env automatically (see Ghostwriter setup).

Usage

Once .mcp.json is loaded by your MCP client, the tools are available to the agent. Pick the lane that fits the target (or run both — a box often has web and network surface).

Web lane (a webapp / API):

1. configure_scope to set include/exclude patterns and auto-filter tracker domains.
2. browser_crawl or discover_attack_surface to map the target.
3. auto_probe to run knowledge-driven probes on parameters.
4. assess_finding → save_finding for each suspected issue.
5. generate_report to export findings.

Network / red-team lane (a host, subnet, or AD environment):

1. run_network_recon(target, domain) — one call: nmap discovery → per-service enum (SMB/LDAP/RPC/MSSQL/Kerberos) → leads (anon access, roastable hashes, SMB signing off, Pwn3d!) → auto-loots hashes → bridges any HTTP(S) service into the web lane. Add creds='DOMAIN/user:pass' to unlock authenticated enum.
2. crack_hashes(domain, 'asrep', loot_type='asrep_hash') — offline-crack captured hashes; cracked passwords auto-land in the credential store.
3. Re-run run_network_recon with the recovered creds= (or run_network_tool for a specific impacket/netexec action) to move laterally. The kill chain loops: capture → crack → store → reuse.
4. get_operator_log(domain, 'timeline'|'attack'|'loot') — the ATT&CK-tagged evidence base for the report.
5. sync_to_ghostwriter(domain) — forward both lanes' evidence into Ghostwriter.

Every network action is auto-recorded in the operator log; captured secrets get chain-of-custody in the loot store; a HARD safety layer (Rules 5–9) refuses destructive/brute args in both engagement modes, and scope is mode-aware (configure_scope(mode='operator'|'strict')).

The agent receives expert methodology through the skill files in .claude/skills/. Operators steer the agent by passing override flags or by editing .burp-intel/programs/<slug>.json per-engagement policy.

Ghostwriter reporting hub

Ghostwriter is the central reporting/oplog hub both lanes forward into. It is a Docker stack; Praetor ships an auto-setup:

./setup-ghostwriter.sh     # clones + installs Ghostwriter, wires .env (GHOSTWRITER_*)

This downloads several GB of images and binds TCP 443 (skip in setup.sh with PRAETOR_SKIP_GHOSTWRITER=1). Afterward, open https://127.0.0.1 (accept the self-signed cert), log in as admin (cd ~/Ghostwriter && ./ghostwriter-cli-linux config get ADMIN_PASSWORD), create a Project + its Oplog, and set GHOSTWRITER_OPLOG_ID.

Auth on first setup. Praetor authenticates to Ghostwriter with the precedence admin-secret → API token → username/password login. The simplest path is username/password: in Ghostwriter create a user named praetor (any role that can write the oplog), and Praetor logs in with the default GHOSTWRITER_USERNAME/GHOSTWRITER_PASSWORD = praetor/praetor — no token to copy. Set a real password on that account and mirror it in .env (GHOSTWRITER_PASSWORD=) for any shared or remote instance; the default is a local-first-run convenience only. Prefer a static GHOSTWRITER_API_TOKEN or GHOSTWRITER_ADMIN_SECRET for unattended/CI use.

Verify with ghostwriter_status (it reports the active auth mode), then sync_to_ghostwriter('<domain>'). Praetor works fully without Ghostwriter — local .burp-intel/ stores stay the source of truth.

Tool Surface

The MCP server exposes tools across the following groups. Architecture detail and per-tool notes are in CLAUDE.md.

MCP Prompts

The server publishes ready-to-run workflow templates. Surface them in your client (/mcp listing or the prompt picker) and pass arguments to launch a phase.

MCP Resources

Read-only context the agent can attach without spending tool budget. URIs:

Knowledge Base

The adaptive scan engine reads JSON files from mcp-server/src/praetor/knowledge/. Each file declares contexts, server-side matchers, and optional craft guidance for dynamic payload generation. Add a new .json file to extend coverage; auto_probe picks it up at runtime. The full per-category breakdown lives in mcp-server/src/praetor/knowledge/_INDEX.md.

Coverage

Latest additions cover the gap surface most bug-bounty and red-team work hits in 2024–2026: cloud storage anonymous enumeration, serverless function URL discovery, K8s external exposure, mobile deep-link and WebView injection, archive extraction (Zip Slip) and argument injection (curl --upload-file, git ext::, ssh -oProxyCommand, …), GraphQL engine-specific attacks (Hasura admin-secret, Apollo APQ poisoning, federation _entities abuse, PostGraphile RLS bypass, Dgraph admin, Strawberry SDL leak), and a perimeter-appliance CVE pack (Citrix NetScaler, F5 BIG-IP, Ivanti Connect Secure, PAN-OS GlobalProtect, MOVEit, SonicWall SSLVPN, CrushFTP, Exchange, Confluence, TeamCity, GeoServer, Log4Shell).

Scope & Non-Goals

Praetor is a two-lane pentest & red-team harness: web / API / cloud / LLM DAST through Burp, and network recon + Active Directory / post-exploitation on the network lane. Both lanes are first-class — the tooling, evidence model, and reporting pipeline serve both. Internal-network / AD is in scope (this changed in the network-lane release): run_network_recon, impacket, netexec, responder, bloodhound-python, certipy, kerbrute, offline cracking, and the credential-reuse loop are all core.

The following remain out of scope by design, not gaps to be filled:

• Binary / memory-corruption exploitation — no ROP/pwntools/gdb/kernel/V8 exploit development. Praetor operates at the network/service and web layers, not on native-binary crash-to-exploit (e.g. ExploitGym-class tasks).
• Thick-client / native desktop binaries — Electron IPC/ASAR inspection ships as reference KB (desktop_electron) + skill only; no binary-instrumentation automation for native Windows/macOS apps.
• Non-HTTP protocol / binary fuzzing — fuzzing is HTTP/parameter-oriented; no boofuzz/AFL-class grammar or network-protocol fuzzing.
• Email-infrastructure security — DNS analysis notes SPF/DMARC presence only; no DKIM-selector enumeration, SMTP/STARTTLS/open-relay, or BEC/spoofing assessment.
• Container-runtime / eBPF behavioral detection — image scanning (Trivy/Grype/Hadolint) is covered; runtime (Falco-class) is not.
• Online credential brute-force — dictionary brute of a live service is refused (HARD Rule 6); default/known-cred checks, single-password spray, and offline cracking are in scope.
• Autonomous destructive actions — RCE is detection-gated; destructive/brute tool args are refused in both engagement modes. Praetor proves impact with benign markers, never with data destruction (Rules 5–8).

Save-Finding Pipeline

Three phases enforced by the gate:

1. Replay. resend_with_modification(index) confirms the anomaly and records a logger_index.
2. Assess. assess_finding(...) runs the 7-question gate (scope, reproducibility, impact, dedup, evidence, NEVER-SUBMIT, triager) and returns REPORT / NEEDS MORE EVIDENCE / DO NOT REPORT plus a suggested confidence.
3. Save. save_finding(...) persists if the gate passed. The Java extension hard-rejects calls without resolvable evidence, NEVER-SUBMIT classes without chain_with[], and timing/blind classes without reproductions[].

Operators can override individual gate questions with overrides=["q5_evidence:<reason>", ...] (audit-trailed), pass human_verified=True, or change engagement policy with set_program_policy. See .claude/skills/user-override.md.

Skills

Behavioral skills live in .claude/skills/:

• hunt.md — systematic vulnerability hunting workflow
• verify-finding.md — per-class evidence bars and the 7-question gate
• resume.md — continue from a previous session, re-verify findings
• chain-findings.md — escalate low findings into chained impact
• report-templates.md — platform-specific report formatting
• autopilot.md — autonomous hunt loop with circuit breaker
• dispatch-agents.md — parallel agent orchestration
• burp-workflow.md, investigate.md, craft-payload.md, static-dynamic-analysis.md
• user-override.md — operator override surfaces when defaults block legitimate findings
• operational-discipline.md — cross-role discipline (pentester / BBH / red team / researcher): read before you send, replay before save, annotate live, stop when impact is proved, honour the noise budget
• security-research.md — deep-dive an interesting anomaly via research_attack_vector + WebFetch on disclosed reports / writeups; operationalizes Rule 27's 20% creative-hunting budget

Always-active rules in .claude/rules/:

• engineering.md — engineering rules (think first, simplicity, surgical changes, goal-driven execution)
• hunting.md — tiered hunting rules (HARD 1-10 tool-enforced, DEFAULT 11-21 overridable, ADVISORY 22-28 on-demand)

Agents

Project subagents in .claude/agents/, auto-loaded by Claude Code at session start. One orchestrator plus specialised workers:

• grow-agent — session orchestrator, one domain per run
• recon-agent — attack-surface mapping
• js-analyst — JS secrets and DOM source→sink flows
• vuln-scanner — vulnerability probing, one category per instance
• finding-verifier — re-verification with per-class evidence bars
• payload-crafter — WAF and filter bypass
• auth-tester — authz matrix, IDOR/BFLA, JWT
• browser-agent — SPA and JS-heavy targets
• auth-payment-agent — OAuth, FIDO2/passkeys, Apple/Google/Samsung Pay, IAP, 3DS
• fuzz-agent — tech-aware wordlist generation and ffuf
• mobile-dynamic-agent — Frida and adb (pinning bypass, runtime hooks, deep-link sinks)

Roles and parallelization patterns: AGENTS.md.

Supported Platforms

• Linux
• macOS
• Windows (use .venv\Scripts\python.exe in .mcp.json)
• WSL (Burp on the Windows host — prefer mirrored networking; NAT fallback available. See WSL)

The Java extension and Python server use platform-independent libraries.

Contributing

Issues and pull requests welcome. Please:

• Open an issue for non-trivial changes before sending a PR.
• Run the full Python test suite (cd mcp-server && uv run python -m unittest discover -s tests -v) and cd burp-extension && mvn package before submitting.
• Match the existing style (Java: camelCase methods, snake_case JSON keys; Python: PEP 8, async tools).
• Do not add external Java dependencies; the extension uses only the Montoya API and JDK.

License

Apache License 2.0.

This project integrates with Burp Suite (a product of PortSwigger Ltd) and is not affiliated with or endorsed by PortSwigger.