pentester-mcp 0.3.0__tar.gz

pentester_mcp-0.3.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+evidence/
+evidence-*/
+dist/
+build/

pentester_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pentest-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pentester_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,429 @@
+Metadata-Version: 2.5
+Name: pentester-mcp
+Version: 0.3.0
+Summary: Authorization-gated penetration testing MCP server for agentic AI
+Project-URL: Documentation, https://github.com/keselyoleren/pentest-mcp#readme
+Project-URL: Source, https://github.com/keselyoleren/pentest-mcp
+Project-URL: Issues, https://github.com/keselyoleren/pentest-mcp/issues
+Author: keselyoleren
+License: MIT License
+        
+        Copyright (c) 2026 pentest-agent contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,mcp,osint,pentest,security,vulnerability-scanning
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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.