# pentest-mcp

An authorization-gated penetration testing MCP server for agentic AI — 80 tools
that install into **any MCP-capable agent**: Claude Code, Claude Desktop, Cursor,
Windsurf, Cline, Roo Code, Zed, OpenCode, Continue, and anything else that speaks
the Model Context Protocol.

Every network-touching tool **refuses to run** without an engagement file that
records the client's written authorization and the exact in-scope targets. The
gate lives in code, not in a prompt, so no conversation can talk the plugin into
testing something it is not allowed to test.

## Capabilities

| Area | Tools |
| --- | --- |
| Engagement & scope | `pentest_load_engagement`, `pentest_scope_check`, `pentest_rules` |
| Recon & OSINT | `pentest_recon_dns`, `pentest_recon_whois`, `pentest_recon_subdomains`, `pentest_recon_portscan`, `pentest_recon_tech` |
| Advanced OSINT | `pentest_osint_crtsh`, `pentest_osint_wayback`, `pentest_osint_js_secrets`, `pentest_osint_cloud_assets`, `pentest_osint_takeover`, `pentest_osint_shodan` |
| Vulnerability scanning | `pentest_vuln_nmap`, `pentest_vuln_nmap_preset`, `pentest_vuln_nuclei`, `pentest_vuln_tls`, `pentest_vuln_sslscan`, `pentest_vuln_testssl`, `pentest_vuln_wpscan`, `pentest_vuln_cve_lookup` |
| Web app testing | `pentest_web_headers`, `pentest_web_crawl`, `pentest_web_dirbust`, `pentest_web_reflection`, `pentest_web_param_discovery`, `pentest_web_cors`, `pentest_web_jwt`, `pentest_web_open_redirect`, `pentest_web_host_header`, `pentest_web_secrets_scan`, `pentest_web_sqlmap` |
| Exploit & post-exploit | `pentest_exploit_search`, `pentest_exploit_msf_check`, `pentest_exploit_msf_run`, `pentest_exploit_payload_generate`, `pentest_exploit_credential_test` |
| Orchestration | `pentest_assess_web`, `pentest_attack_surface` |
| CTF: crypto & encodings | `pentest_ctf_decode`, `pentest_ctf_encode`, `pentest_ctf_xor`, `pentest_ctf_cipher_brute`, `pentest_ctf_hash_identify`, `pentest_ctf_hash_crack`, `pentest_ctf_rsa` |
| CTF: forensics & pwn | `pentest_ctf_file_info`, `pentest_ctf_strings`, `pentest_ctf_binwalk`, `pentest_ctf_exif`, `pentest_ctf_stego`, `pentest_ctf_pcap`, `pentest_ctf_cyclic`, `pentest_ctf_cheatsheet` |
| CTF: challenge ops | `pentest_ctf_init`, `pentest_ctf_web_probe`, `pentest_ctf_remote` |
| Integrations | `pentest_burp_import`, `pentest_burp_status`, `pentest_burp_api`, `pentest_zap_status`, `pentest_zap_import`, `pentest_zap_spider`, `pentest_zap_active_scan`, `pentest_zap_scan_status`, `pentest_zap_alerts`, `pentest_defectdojo_status`, `pentest_defectdojo_export`, `pentest_report_generic_json` |
| Reporting & intel | `pentest_add_finding`, `pentest_list_findings`, `pentest_report`, `pentest_report_html`, `pentest_report_sarif`, `pentest_remediation_plan`, `pentest_cvss`, `pentest_assets`, `pentest_tool_status`, `pentest_audit_tail` |

### Highlights

- **`pentest_assess_web(url, deep=True)`** — one call runs the whole web battery:
  headers, fingerprinting, crawl, sensitive paths, TLS, CORS, secrets, then
  reflection and hidden-parameter discovery.
- **`pentest_attack_surface(domain)`** — maps the external attack surface: DNS,
  WHOIS, certificate transparency (crt.sh), Wayback Machine, subdomain takeover,
  cloud storage buckets. Active steps only run when the engagement allows them.
- **CVE intelligence** — `pentest_vuln_cve_lookup` pulls published CVEs from NVD
  based on the product/version fingerprints.
- **JWT & secret hunting** — offline JWT analysis (`alg=none`, embedded `jwk`,
  missing claims, common HMAC secret cracking) and leaked-credential detection in
  JS/responses with values **always redacted**.
- **Layered exploitation** — Metasploit check mode first, msfvenom payloads into
  the evidence directory only, hydra capped at 50 users / 50 passwords.
- **Dashboard-ready output** — SARIF 2.1.0 (GitHub code scanning, DefectDojo),
  standalone HTML, CVSS v3.x calculator, and a wave-based remediation plan.
- **Tooling integrations** — import Burp (XML) and ZAP (JSON) reports into
  standardized findings, drive the ZAP API from the agent, controlled passthrough
  to the Burp REST API, and one-call export to DefectDojo (with `dry_run`).
- **CTF toolkit** — encodings (auto-detect), XOR brute-force, Caesar/frequency
  attacks, hash identification + cracking, RSA factoring (trial/Fermat/Pollard
  rho/Wiener) with decryption, file forensics (magic bytes, entropy, embedded
  carving), strings, stego checks, PCAP analysis, De Bruijn cyclic offsets,
  payload cheatsheets, and CTF web probes (SSTI/LFI/command injection). Offline
  analysis runs without an engagement; `pentest_ctf_init(target)` creates a
  scoped engagement for a challenge box in one call.

## Security model

1. **Authorization first.** The engagement file must contain a written
   authorization statement and validity dates. After expiry, every active tool stops.
2. **Strict scope.** Only `scope.domains` / `cidrs` / `ips` / `urls` may be
   touched. `scope.excluded` always wins, and resolved IPs outside the scope are
   refused too.
3. **No DoS.** Per-target rate limits, capped port/path/credential lists, and
   destructive Metasploit modules are blocked while `rules.no_dos` is set.
4. **Layered exploitation.** `check` mode first; `msf_run` and `payload_generate`
   require `rules.allow_payload_execution = true` **and** a `confirm_phrase`
   equal to the `engagement_id`. `credential_test` requires its own
   `rules.credential_testing = true` flag.
5. **Audit trail.** Every tool call lands in `audit.jsonl`; findings are stored in
   `findings.jsonl` with IDs and status (open/verified/false-positive); discovered
   assets accumulate in `assets.json`.
6. **Sensitive data.** Credentials, tokens and personal data are reported as
   location + type with the value `[REDACTED]` — including inside evidence snippets.

## Install

Requires Python 3.10+. External tools are optional: when missing, the related
tool reports `available: false` and the built-in capabilities (TCP port scan, TLS
audit, header audit, crawl, reflection, CORS, JWT) keep working.

```bash
pipx install pentester-mcp          # recommended: isolated per user
# or
uvx --from pentester-mcp pentest-mcp --version
# or
pip install --user pentester-mcp
```

> **Naming note:** the PyPI package is `pentester-mcp` (the name `pentest-mcp` is
> blocked by PyPI's similarity guard because `pentestmcp`/`mcp-pentest` exist),
> while the command you run and the GitHub repo stay `pentest-mcp`.

From source:

```bash
cd pentest-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Optional external tools and API keys:

```bash
brew install nmap nuclei sqlmap sslscan nikto ffuf metasploit wpscan testssl hydra
# sudo apt-get install nmap sqlmap sslscan nikto ffuf metasploit-framework testssl.sh hydra

export SHODAN_API_KEY=...       # pentest_osint_shodan
export NVD_API_KEY=...          # raises NVD rate limits
export ZAP_API_URL=http://127.0.0.1:8080
export ZAP_API_KEY=...
export BURP_API_URL=https://127.0.0.1:1337
export BURP_API_KEY=...
export BURP_AUTH_STYLE=bearer   # or 'apikey' for X-API-Key
export DEFECTDOJO_URL=https://dojo.example.com
export DEFECTDOJO_API_KEY=...
```

Burp and ZAP report import needs no API at all — export from the GUI, then call
`pentest_burp_import(path)` or `pentest_zap_import(path)`.

## Register with your AI agent

### One command (recommended)

`pentest-mcp --install` detects the agents installed on your machine and writes
the MCP entry into each of their configs:

```bash
pentest-mcp --list-agents           # see what was detected
pentest-mcp --install --dry-run     # preview, writes nothing
pentest-mcp --install               # register everywhere
pentest-mcp --install --project     # also write .mcp.json in the current repo
pentest-mcp --uninstall             # remove the entry again
```

Supported auto-detection: **Claude Code** (user + project scope), **Claude
Desktop**, **Cursor**, **Windsurf**, **Cline**, **Roo Code**, **Zed**,
**OpenCode**, **Continue**. Existing config entries are preserved; re-running is
idempotent. Restart the agent afterwards.

### Manual per-agent config

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add pentest-mcp -- $(which pentest-mcp)
```
or in `.mcp.json` / `~/.claude.json`:
```json
{ "mcpServers": { "pentest-mcp": { "command": "pentest-mcp" } } }
```
</details>

<details>
<summary><b>OpenCode</b></summary>

`opencode.json`:
```json
{ "mcp": { "pentest-mcp": { "type": "local", "command": ["pentest-mcp"] } } }
```
</details>

<details>
<summary><b>Cursor / Windsurf / Cline / Roo Code / Claude Desktop</b></summary>

In the respective MCP config (`~/.cursor/mcp.json`,
`~/.codeium/windsurf/mcp_config.json`, `cline_mcp_settings.json`,
`claude_desktop_config.json`):
```json
{ "mcpServers": { "pentest-mcp": { "command": "pentest-mcp" } } }
```
</details>

<details>
<summary><b>Zed</b></summary>

In `settings.json`:
```json
{ "context_servers": { "pentest-mcp": { "command": { "path": "pentest-mcp", "args": [] } } } }
```
</details>

<details>
<summary><b>Continue</b></summary>

In `~/.continue/mcpServers.yaml`:
```yaml
mcpServers:
  pentest-mcp:
    command: pentest-mcp
    args: []
```
</details>

<details>
<summary><b>Any other MCP client</b></summary>

Stdio transport, command `pentest-mcp`, no arguments, no required environment.
</details>

### Skill pack

The agent skills ship inside the package — export them into your agent's skills
directory:

```bash
pentest-mcp --export-skills ~/.claude/skills      # Claude Code, global
pentest-mcp --export-skills .claude/skills        # per project
```

- `pentest-guardrails` — engagement rules: authorization, scope, no-DoS,
  sensitive-data handling, when to refuse.
- `pentest-workflow` — end-to-end methodology: recon → OSINT → scan → web →
  exploit → report.

## Engagement file

No engagement file, no active tools. Generate a starter and edit it:

```bash
pentest-mcp --export-engagement-template engagement.json
```

Key fields:

- `authorization` — written authorization statement plus `valid_from` / `valid_until`
- `scope.domains/ips/cidrs/urls` — the only targets allowed; `excluded` always wins
- `rules.active_scanning` — `true` when traffic may be sent to the target
- `rules.exploit_authorized` / `allow_payload_execution` / `credential_testing` —
  keep `false` unless explicitly agreed in the RoE
- `evidence_dir` — where findings, audit trail and reports are written

## Usage

Tell your agent:

```
Run a security assessment against https://app.example.com, engagement file: ./engagement.json
```

The agent loads the engagement first, then works the methodology from the
`pentest-workflow` skill. Outputs land in `evidence_dir`:

- `findings.jsonl`, `audit.jsonl`, `assets.json`
- `report-*.md`, `report-*.html`, `findings-*.sarif`, `findings-*-generic.json`

## Publish publicly

Once published, anyone in the world can install and self-register with two lines:

```bash
uv tool install pentester-mcp    # or: pipx install pentester-mcp
pentest-mcp --install
```

Maintainer — one-time setup and release flow:

1. **Push the repository** to GitHub/GitLab as `keselyoleren/pentest-mcp` and fill in
   `[project.urls]` in `pyproject.toml`. The PyPI project name is `pentester-mcp`
   (`pentest-mcp` itself is blocked by PyPI's similarity guard against the existing
   `pentestmcp`/`mcp-pentest` projects).
2. **Configure PyPI Trusted Publishing** (recommended, no long-lived token):
   pypi.org → project `pentester-mcp` → Publishing → add a pending publisher with
   your repo and workflow `release.yml`, environment `pypi`. Alternative: create a
   PyPI API token and use `twine upload` with `__token__`.
3. **Dry-run on TestPyPI** before going public:

   ```bash
   python -m build
   twine upload --repository testpypi dist/*
   uv tool install --index-url https://test.pypi.org/simple/ pentester-mcp
   ```

4. **Release with a tag** — CI (`.github/workflows/release.yml`) runs the tests,
   publishes to PyPI, and attaches the wheel to a GitHub Release:

   ```bash
   git tag v0.3.0 && git push origin v0.3.0
   ```

   Manual fallback: `python -m build && twine upload dist/*`

Distribution without PyPI works too and keeps the same user experience:

```bash
pipx install git+https://github.com/keselyoleren/pentest-mcp.git
uv tool install --from git+https://github.com/keselyoleren/pentest-mcp.git pentest-mcp
```

End users never need the repository: the wheel carries the MCP server, the skills
(`pentest-mcp --export-skills`), and the engagement template
(`pentest-mcp --export-engagement-template`). Pair public distribution with the
authorization gates in the security model — the tools refuse out-of-scope targets
no matter where the package came from.

## Team distribution

The model: **every tester runs their own local instance** — perfect isolation per
process, each with their own engagement file and evidence, no shared server to
operate or defend. Distribute through any channel from "Publish publicly" above.

Team member onboarding (5 minutes):

```bash
pipx install pentester-mcp==0.3.0
pentest-mcp --install
pentest-mcp --export-skills ~/.claude/skills
pentest-mcp --export-engagement-template engagement.json
# edit engagement.json, then: pentest_load_engagement
```

Suggested team conventions:

- One engagement file per project per operator; never share engagement files
  across projects (scope and validity dates differ).
- Keep `evidence_dir` in the team's internal version control or shared storage.
- Consolidate findings across operators in DefectDojo
  (`pentest_defectdojo_export`) — the single shared source of truth in this model.
- Pin versions on deploy so tool behaviour stays consistent across the team.

## Repository layout

```
pentest-mcp/
├── pyproject.toml              # PyPI metadata, pentest-mcp entry point
├── LICENSE
├── src/pentest_agent/
│   ├── engagement.py           # scope matching + authorization gate
│   ├── state.py                # gate() used by every tool
│   ├── runner.py               # bounded binary execution + rate limiter
│   ├── audit.py                # append-only audit trail
│   ├── findings.py             # finding model + JSONL store
│   ├── assets.py               # asset inventory (hosts, services, tech)
│   ├── patterns.py             # secret/endpoint patterns + redaction
│   ├── installer.py            # --install agent auto-detection
│   ├── engagement.example.json # bundled engagement template
│   ├── server.py               # 80 MCP tools + onboarding CLI
│   ├── skills/                 # bundled into the wheel
│   │   ├── pentest-guardrails/SKILL.md
│   │   └── pentest-workflow/SKILL.md
│   └── tools/
│       ├── recon.py            # DNS, WHOIS, subdomains, port scan, fingerprint
│       ├── osint.py            # crt.sh, Wayback, JS secrets, cloud, takeover, Shodan
│       ├── vulnscan.py         # nmap(+presets), nuclei, TLS, testssl, wpscan, CVE lookup
│       ├── webapp.py           # headers, crawl, dirbust, reflection, params, CORS,
│       │                       # JWT, open redirect, host header, secrets, sqlmap
│       ├── exploit.py          # searchsploit, Metasploit check/run, msfvenom, hydra
│       ├── ctf.py              # CTF: encodings, crypto, RSA, forensics, stego, pwn, probes
│       ├── orchestrate.py      # assess_web, attack_surface
│       ├── integrations.py     # Burp, OWASP ZAP, DefectDojo
│       └── report.py           # findings, Markdown/HTML/SARIF/generic JSON, CVSS, remediation
└── tests/                      # 64 tests: scope, gates, redaction, CVSS, SARIF, JWT,
                                # integrations, CLI, installer, CTF
```

## Development

```bash
pip install -e ".[dev]"
pytest
```

Probe the tool surface without an agent:

```bash
npx @modelcontextprotocol/inspector $(which pentest-mcp)
```

## Usage restrictions

This plugin is for security assessments that are authorised in writing. Testing
systems without authorization is a criminal offence in most jurisdictions,
including under Indonesia's ITE Law. The in-code scope gates limit accidental
damage, but legal responsibility stays with the operator and their organisation.