Pentest Toolkit

                      __            __                                   __              ____   _ __
    ____  ___  ____  / /____  _____/ /_      ____ ___  _________        / /_____  ____  / / /__(_) /_
   / __ \/ _ \/ __ \/ __/ _ \/ ___/ __/_____/ __ `__ \/ ___/ __ \______/ __/ __ \/ __ \/ / //_/ / __/
  / /_/ /  __/ / / / /_/  __(__  ) /_/_____/ / / / / / /__/ /_/ /_____/ /_/ /_/ / /_/ / / ,< / / /_
 / .___/\___/_/ /_/\__/\___/____/\__/     /_/ /_/ /_/\___/ .___/      \__/\____/\____/_/_/|_/_/\__/
/_/                                                     /_/

  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 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 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):

# 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

# 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:

# macOS / Linux / Git-Bash
curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 50 --client codex

# 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:

# 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

# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 25 -Client claude-code

Codex:

# macOS / Linux / Git-Bash
curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 25 --client codex

# 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 and Build from source below.

---

Connect your client

The canonical launch command (every client speaks stdio, so only the config file + key differs per client):

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. 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:

-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 § 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

# 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 defs 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. Dev rules in docs/CLAUDE.md.

---

License

MIT. 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, 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.