pentest-mcp-toolkit

```text __ __ __ ____ _ __ ____ ___ ____ / /____ _____/ /_ ____ ___ _________ / /_____ ____ / / /__(_) /_ / __ \/ _ \/ __ \/ __/ _ \/ ___/ __/_____/ __ `__ \/ ___/ __ \______/ __/ __ \/ __ \/ / //_/ / __/ / /_/ / __/ / / / /_/ __(__ ) /_/_____/ / / / / / /__/ /_/ /_____/ /_/ /_/ / /_/ / / ,< / / /_ / .___/\___/_/ /_/\__/\___/____/\__/ /_/ /_/ /_/\___/ .___/ \__/\____/\____/_/_/|_/_/\__/ /_/ /_/ 50 Kali security tools · one MCP server over Docker stdio · driven 100% by AI agents ``` > **You are responsible for authorization.** For authorized self-environment > pentests of systems you own. ## About **Pentest MCP Toolkit** is a [FastMCP](https://github.com/jlowin/fastmcp) server that exposes **50 Kali Linux security tools over MCP stdio**, packed into a `kalilinux/kali-rolling` Docker container. It is built to be **driven 100% by AI agents**: point an MCP client like **Claude Code** or **Codex** (or Cursor / Gemini CLI / LM Studio / Open WebUI) at the container and the agent becomes the operator — it picks the tool, builds the argv, validates the target, and reads the output. The agent runs the pentest; the toolkit just makes Kali available as a set of callable MCP tools. Scope (`MCP_PENTEST_SCOPE`) controls *where* the agent may scan, not *whether* it may. It ships **default-open with a loud warning**; you are the authorization gate. Use it only against systems you own or are explicitly authorized to test — see the [Legal disclaimer](#-legal--educational-disclaimer) at the bottom. Pick a tier, run one command, connect your client. --- ## Quick start Run **one command** — it checks Docker, builds the tier image, and registers the `pentest` MCP server with your client. Then open the client; the tool is ready. Pick a tier, pick a client, paste. macOS / Linux / Git-Bash use the `curl | bash` line; Windows PowerShell uses the `irm` line. Both do the same thing. ### 50 tools — full set (default, recommended) **Claude Code** — registers `pentest` at user scope (available in every project): ```bash # macOS / Linux / Git-Bash curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 50 --client claude-code ``` ```powershell # Windows PowerShell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 50 -Client claude-code ``` **Codex** — writes `~/.codex/config.toml`: ```bash # macOS / Linux / Git-Bash curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 50 --client codex ``` ```powershell # Windows PowerShell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 50 -Client codex ``` First build pulls Kali + tool packages (~5–10 min). Image ~1.5 GB (metasploit is large). ### 25 tools — lightweight TCP-only subset **Claude Code**: ```bash # macOS / Linux / Git-Bash curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 25 --client claude-code ``` ```powershell # Windows PowerShell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 25 -Client claude-code ``` **Codex**: ```bash # macOS / Linux / Git-Bash curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 25 --client codex ``` ```powershell # Windows PowerShell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 25 -Client codex ``` Faster build, ~370 MB image. No raw-socket or heavy tools. Need another client, or building by hand? See [docs/CLIENTS.md](docs/CLIENTS.md) and [Build from source](#build-from-source--verify) below. --- ## Connect your client The canonical launch command (every client speaks stdio, so only the **config file + key** differs per client): ```bash docker run -i --rm \ --cap-add=NET_RAW --cap-add=NET_ADMIN \ -e MCP_PENTEST_SCOPE= \ -e MAX_OUTPUT=50000 \ -e CMD_TIMEOUT=300 \ -e PENTEST_TIER=50 \ -v "$(pwd)/work:/work" \ pentest-mcp-toolkit:50 ``` - **Claude Desktop** / **Codex** / **Claude Code** / **Cursor** / **Gemini CLI** / **LM Studio** / **Open WebUI** — exact file path + snippet in [docs/CLIENTS.md](docs/CLIENTS.md). The installer writes it for you: `bash install/install.sh --tier 50 --client claude-desktop`. > Tier 25: swap `:50`→`:25` and drop the two `--cap-add` flags. --- ## Scope ⚠️ important `MCP_PENTEST_SCOPE` controls **where** the AI may scan, not **whether** it may. By default it is **empty** = the toolkit can scan **any host**. This matches "any device, no configuring" but means: **you** are the only authorization check. Tighten it to your lab when scanning real targets: ```bash -e MCP_PENTEST_SCOPE=10.0.0.0/8,192.168.0.0/16,my-lab.local # or at install time: bash install/install.sh --tier 50 --client codex --scope 192.168.1.0/24 ``` See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) § Scope guard for the full behavior (IP-in-CIDR, CIDR `subnet_of`, domain suffix). --- ## Capabilities (raw-socket scans) Raw-socket scans need **both** file caps (baked at build time) **and** the runtime cap on `docker run`: | Tool | Flag | |---|---| | `nmap -sS` (syn scan_type) | `--cap-add=NET_RAW` | | `masscan_scan` | `--cap-add=NET_RAW --cap-add=NET_ADMIN` | | `naabu` syn | `--cap-add=NET_RAW` | | `traceroute_host` | `--cap-add=NET_RAW` | The canonical launch command above already includes them. Default `nmap_scan` is `-sT` (TCP connect), needs no caps. Tier 25 ships TCP-only by default (no `--cap-add` needed); setcap on nmap/naabu is baked so you *can* add the flag. --- ## Tools by tier ### Tier 25 (25 tools — lightweight) | Category | Tools | |---|---| | Network (3) | `nmap_scan`, `naabu_port_scan`, `nc_banner_grab` | | DNS / OSINT (6) | `subfinder_enum`, `assetfinder_enum`, `theharvester_enum`, `dnsrecon_scan`, `dig_lookup`, `whois_lookup` | | Web (6) | `whatweb_scan`, `http_probe`, `nuclei_scan`, `nikto_scan`, `wapiti_scan`, `wpscan_scan` | | Content / fuzz (4) | `gobuster_dir`, `ffuf_scan`, `dirsearch_scan`, `feroxbuster_scan` | | Injection / crawl (4) | `sqlmap_scan`, `dalfox_xss`, `arjun_params`, `hakrawler_crawl` | | Local / offline (2) | `searchsploit_search`, `hashid_identify` | ### Tier 50 (50 tools — everything) Tier 25 is a strict subset. Tier 50 adds: | Category | Added tools (on top of tier 25) | |---|---| | Network (5) | + `masscan_scan`, `traceroute_host` | | DNS / OSINT (10) | + `spiderfoot_scan`, `dnsenum_scan`, `dnstwist_scan`, `fierce_scan` | | Web (7) | + `joomscan_scan` | | Content / fuzz (8) | + `dirb_scan`, `gobuster_dns`, `gobuster_vhost`, `wfuzz_scan` | | Injection / crawl (5) | + `dotdotpwn_traversal` | | Exploit (2) | `searchsploit_search` + `msfvenom_payload` | | Net services / brute (8) | `enum4linux_scan`, `smbclient_list`, `smbmap_enum`, `netexec_smb`, `snmpwalk_enum`, `onesixtyone_snmp`, `smtp_user_enum`, `hydra_brute` | | Hashes / wordlist (4) | `john_crack`, `hashid_identify`, `cewl_wordlist`, `crunch_wordlist` | | Forensics (1) | `binwalk_scan` | --- ## Build from source / verify ```bash # syntax check (no deps needed) python -m py_compile src/_helpers.py src/server.py src/tools/*.py # MCP round-trip: confirm the tier serves the right tool count echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \ docker run -i --rm pentest-mcp-toolkit:50 # full smoke test (init + tools/list + a real tools/call) python scripts/smoke_test.py --tier both # hermetic python scripts/smoke_test.py --tier 50 --net # + live scanme.nmap.org scan ``` --- ## Architecture One `src/` tree, two Dockerfiles; the `PENTEST_TIER` env gates which tools register. Tool functions are bare `async def`s in `src/tools/<category>.py`; `src/server.py` applies `@mcp.tool()` at registration time. The contract — no shell, validate before run, scope guard, strings out, single-line docstrings — lives in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Dev rules in [docs/CLAUDE.md](docs/CLAUDE.md). --- ## License [MIT](LICENSE). Kali tool licenses are their upstream projects'; this toolkit only packages and orchestrates them. --- ## ⚖️ Legal & Educational Disclaimer > **This is not legal advice.** What follows is a general disclaimer drafted > from common open-source security-tooling conventions. It does not create an > attorney-client relationship. If you are unsure whether a given test is > lawful in your jurisdiction, consult a qualified attorney **before** you run > it. This project — source, Docker images, and installer — is provided **strictly for educational purposes, defensive security auditing, authorized vulnerability verification, and penetration testing of systems you own or are explicitly authorized to test.** **Authorized use only.** The toolkit ships with `MCP_PENTEST_SCOPE` default-open, meaning an agent can be directed at any reachable host by default. That default exists for convenience, **not as permission**. Deploying this container grants **no authorization** to scan any system. You must obtain explicit, written permission from the owner/operator of every target before scanning, probing, fuzzing, brute-forcing, or otherwise interacting with it. "I was just testing" is not consent. **You bear all responsibility.** The author(s) assume no liability and are not responsible for any misuse, damage, data loss, service disruption, or illegal activity conducted with this software. By deploying or using this toolkit you agree that you — not the author(s) — are solely responsible for compliance with all applicable local, state, national, and international laws, including but not limited to: - **United States** — Computer Fraud and Abuse Act, 18 U.S.C. § 1030; Electronic Communications Privacy Act, 18 U.S.C. § 2510 et seq.; and state unauthorized-access statutes. - **United Kingdom** — Computer Misuse Act 1990. - **EU / EEA** — Directive 2013/40/EU on attacks against information systems, as transposed into national law by each member state. - **Other jurisdictions** — analogous computer-misuse, unauthorized-access, data-protection (e.g., GDPR / UK GDPR), and privacy statutes in your country. Unauthorized access to a computer system is a crime in most jurisdictions, regardless of intent or whether a tool made it easy. A tool that *can* reach a host is not a license to scan a host you don't own. **No warranty.** This software is provided "AS IS" under the [MIT License](LICENSE), without warranty of any kind, express or implied, including without limitation the warranties of merchantability, fitness for a particular purpose, and non-infringement. The entire risk as to the quality and performance of the software is with you. **Indemnification.** By using this software you agree to indemnify and hold harmless the author(s) and contributors from any claim, damages, loss, or expense (including reasonable attorneys' fees) arising from your use or misuse of the software, or your violation of any law or third-party right. **Third-party tools.** The Kali tools orchestrated here (nmap, nuclei, sqlmap, metasploit, etc.) are copyrighted and licensed by their upstream projects. This toolkit only packages and invokes them; it claims no rights over them and is not affiliated with Kali Linux or those projects. Their licenses and usage terms apply independently of this one. **Export / re-export.** Some security tooling may be subject to export-control regulations (e.g., U.S. EAR, EU dual-use regimes). You are responsible for complying with applicable export and re-export controls when you download, deploy, or redistribute this software. **If you do not agree with these terms, do not deploy or use this toolkit.**