KoaBrown/pentest-mcp-toolkit

``` __ __ __ ____ _ __ ____ ___ ____ / /____ _____/ /_ ____ ___ _________ / /_____ ____ / / /__(_) /_ / __ \/ _ \/ __ \/ __/ _ \/ ___/ __/_____/ __ `__ \/ ___/ __ \______/ __/ __ \/ __ \/ / //_/ / __/ / /_/ / __/ / / / /_/ __(__ ) /_/_____/ / / / / / /__/ /_/ /_____/ /_/ /_/ / /_/ / / ,< / / /_ / .___/\___/_/ /_/\__/\___/____/\__/ /_/ /_/ /_/\___/ .___/ \__/\____/\____/_/_/|_/_/\__/ /_/ /_/ 50 Kali security tools · one MCP server over Docker stdio · driven 100% by AI agents ``` ## 关于 **Pentest MCP Toolkit** 是一个 [FastMCP](https://github.com/jlowin/fastmcp) 服务器， 它**通过 MCP stdio 暴露了 50 个 Kali Linux 安全工具**，并打包在 `kalilinux/kali-rolling` Docker 容器中。它的设计旨在**由 AI agent 100% 驱动**： 将 **Claude Code** 或 **Codex**（或 Cursor / Gemini CLI / LM Studio / Open WebUI）等 MCP 客户端指向该容器，agent 就会成为 操作者 —— 它会选择工具、构建 argv、验证目标并 读取输出。由 agent 执行渗透测试；该工具包只是将 Kali 作为一组可调用的 MCP 工具提供出来。 作用域 (`MCP_PENTEST_SCOPE`) 控制 agent *可以在哪里* 扫描，而不是 *是否* 可以扫描。它默认**开放并带有醒目的警告**；你才是 授权的把关者。仅对你拥有的系统或获得明确授权测试的系统使用它 —— 请参阅底部的 [法律免责声明](#-legal--educational-disclaimer)。 选择一个版本层级，运行一条命令，连接你的客户端。 ## 快速开始 运行**一条命令** —— 它会检查 Docker、构建对应版本的镜像，并将 `pentest` MCP 服务器注册到你的客户端。然后打开客户端；工具就准备好了。 选择层级，选择客户端，然后粘贴。macOS / Linux / Git-Bash 使用 `curl | bash` 命令；Windows PowerShell 使用 `irm` 命令。两者的作用相同。 ### 50 个工具 — 完整集（默认，推荐） **Claude Code** — 在用户作用域注册 `pentest`（在每个项目中都可用）： ``` # 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** — 写入 `~/.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 ``` 首次构建会拉取 Kali 和工具包（约 5-10 分钟）。镜像约为 1.5 GB（metasploit 较大）。 ### 25 个工具 — 轻量级纯 TCP 子集 **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 ``` 构建速度更快，镜像约 370 MB。不包含原始套接字或重型工具。 需要其他客户端，或者想手动构建？请参阅下方的 [docs/CLIENTS.md](docs/CLIENTS.md) 和 [从源码构建](#build-from-source--verify)。 ## 连接你的客户端 标准的启动命令（每个客户端都通过 stdio 通信，因此每个客户端仅 **配置 文件 + 密钥** 不同）： ``` 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** — 确切的文件路径和代码片段详见 [docs/CLIENTS.md](docs/CLIENTS.md)。安装程序会为你写入： `bash install/install.sh --tier 50 --client claude-desktop`。 ## 作用域 ⚠️ 重要提示 `MCP_PENTEST_SCOPE` 控制 AI **可以在哪里** 扫描，而不是 **是否** 可以扫描。 默认情况下它是**空的** = 该工具包可以扫描**任何主机**。这符合 “任意设备，无需配置”的理念，但意味着：**你** 是唯一的授权 检查者。在扫描真实目标时，请将其收紧到你的实验室范围内： ``` -e MCP_PENTEST_SCOPE=10.0.0.0/8,192.168.0.0/16,my-lab.local # 或者在安装时： bash install/install.sh --tier 50 --client codex --scope 192.168.1.0/24 ``` 请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) § Scope guard 了解完整行为 （CIDR 中的 IP、CIDR `subnet_of`、域名后缀）。 ## 功能（原始套接字扫描） 原始套接字扫描**同时**需要文件 capabilities（在构建时固化）**以及** `docker run` 时的运行时 capabilities： | 工具 | 标志 | |---|---| | `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` | 上面标准的启动命令已经包含了它们。默认的 `nmap_scan` 是 `-sT`（TCP connect），不需要 capabilities。第 25 层默认仅提供 TCP 工具（不需要 `--cap-add`）；nmap/naabu 上的 setcap 已经固化，因此你*可以*添加该标志。 ## 按层级划分的工具 ### 第 25 层（25 个工具 — 轻量级） | 分类 | 工具 | |---|---| | 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` | | 内容 / fuzz (4) | `gobuster_dir`, `ffuf_scan`, `dirsearch_scan`, `feroxbuster_scan` | | 注入 / 爬取 (4) | `sqlmap_scan`, `dalfox_xss`, `arjun_params`, `hakrawler_crawl` | | 本地 / 离线 (2) | `searchsploit_search`, `hashid_identify` | ### 第 50 层（50 个工具 — 全部） 第 25 层是其严格子集。第 50 层增加了： | 分类 | 新增工具（在第 25 层基础上） | |---|---| | Network (5) | + `masscan_scan`, `traceroute_host` | | DNS / OSINT (10) | + `spiderfoot_scan`, `dnsenum_scan`, `dnstwist_scan`, `fierce_scan` | | Web (7) | + `joomscan_scan` | | 内容 / fuzz (8) | + `dirb_scan`, `gobuster_dns`, `gobuster_vhost`, `wfuzz_scan` | | 注入 / 爬取 (5) | + `dotdotpwn_traversal` | | Exploit (2) | `searchsploit_search` + `msfvenom_payload` | | 网络服务 / 暴力破解 (8) | `enum4linux_scan`, `smbclient_list`, `smbmap_enum`, `netexec_smb`, `snmpwalk_enum`, `onesixtyone_snmp`, `smtp_user_enum`, `hydra_brute` | | Hashes / 字典 (4) | `john_crack`, `hashid_identify`, `cewl_wordlist`, `crunch_wordlist` | | 取证 (1) | `binwalk_scan` | ## 从源码构建 / 验证 ``` # 语法检查（无需 deps） python -m py_compile src/_helpers.py src/server.py src/tools/*.py # MCP round-trip：确认 tier 提供正确的 tool 数量 echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \ docker run -i --rm pentest-mcp-toolkit:50 # 完整 smoke test（init + tools/list + 实际的 tools/call） python scripts/smoke_test.py --tier both # hermetic python scripts/smoke_test.py --tier 50 --net # + live scanme.nmap.org scan ``` ## 架构 单个 `src/` 目录树，两个 Dockerfile；`PENTEST_TIER` 环境变量控制注册哪些工具。 工具函数是 `src/tools/.py` 中的原生 `async def`； `src/server.py` 在注册时应用 `@mcp.tool()`。规约 — 没有 shell，运行前验证，作用域防护，输出字符串，单行 docstring — 位于 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 中。开发规则在 [docs/CLAUDE.md](docs/CLAUDE.md) 中。 ## 许可证 [MIT](LICENSE)。Kali 工具的许可证归其上游项目所有；本工具包 仅对它们进行打包和编排。 ## ⚖️ 法律与教育免责声明 本项目 — 源码、Docker 镜像和安装程序 — 的提供**严格 出于教育目的、防御性安全审计、授权 漏洞验证，以及对你拥有或获得明确 授权测试的系统进行渗透测试。** **仅限授权使用。** 该工具包默认将 `MCP_PENTEST_SCOPE` 设置为开放，这意味着默认情况下可以将 agent 指向任何可访问的主机。 该默认值是为了方便而存在的，**而不是作为许可**。部署 此容器并不授予扫描任何系统的**任何授权**。在 扫描、探测、模糊测试、暴力破解或以其他方式与之交互之前，你必须获得 每个目标所有者/运营者的明确书面许可。 “我只是在测试”不构成同意。 **你承担所有责任。** 作者不承担任何责任，并且 不对使用本软件进行的任何滥用、损害、数据丢失、服务中断或 非法活动负责。通过部署或使用本 工具包，你同意你 — 而不是作者 — 对遵守所有适用的地方、州、国家和国际法律 负全部责任， 包括但不限于： - **美国** — 《计算机欺诈和滥用法》，18 U.S.C. § 1030； 《电子通信隐私法》，18 U.S.C. § 2510 et seq.；以及各州关于 未经授权访问的法规。 - **英国** — 《1990 年计算机滥用法》。 - **欧盟 / 欧洲经济区** — 《关于打击信息系统的指令》(Directive 2013/40/EU)， 已由各成员国转换为国内法。 - **其他司法管辖区** — 你所在国家/地区的类似计算机滥用、未经授权访问、 数据保护（例如 GDPR / 英国 GDPR）和隐私法规。 在大多数司法管辖区，未经授权访问 计算机系统都是犯罪行为， 无论意图如何，也无论工具是否使其变得容易。一个*能够*连接到 某台主机的工具，并不意味着你有权扫描你不拥有的主机。 **无保修。** 本软件在 [MIT 许可证](LICENSE)下按“原样”提供，不提供任何类型的明示或暗示保证， 包括但不限于对适销性、特定用途的 适用性和非侵权的保证。关于软件质量和 性能的全部风险由你承担。 **赔偿。** 使用本软件即表示你同意赔偿并使 作者和贡献者免受因你使用或滥用 软件，或因你违反任何法律或第三方权利而引起的任何索赔、损害、损失或 费用（包括合理的律师费）的损害。 **第三方工具。** 此处编排的 Kali 工具（nmap、nuclei、sqlmap、 metasploit 等）受其上游项目的版权和许可保护。 本工具包仅对它们进行打包和调用；它不对它们主张任何权利，并且 不隶属于 Kali Linux 或这些项目。它们的许可和使用 条款独立于本协议适用。 **出口 / 再出口。** 某些安全工具可能受出口管制 法规（例如美国 EAR、欧盟两用品法规）的约束。当你在下载、 部署或重新分发本软件时，你有责任 遵守适用的出口和再出口管制规定。 **如果你不同意这些条款，请不要部署或使用本工具包。**

标签：AI代理, Docker, DOE合作, MCP服务器, 安全防御评估, 实时处理, 密码管理, 插件系统, 自动化安全工具, 请求拦截, 逆向工具