Pentests MCP

最顶层MCP桥（Go）

这个项目是 模型上下文协议（MCP）服务器 用Go写的。它将MCP兼容客户端（Cursor、Claude等）连接到 Kali/Linux主机上的pentest工具.

• 使用官方的Go SDK： github.com/modelcontextprotocol/go-sdk/mcp (文档).
• 提供一套不断增长的面向pentest的MCP工具(nmap, wfuzz, gobuster, nikto, sqlmap, …).
• 支持多种部署模式：

- 本地标准。 - 远程SSH。 - 远程HTTP网桥+本地HTTP代理（无SSH，公共Kali）。

需求

• 转到1.21+
• Git（用于获取Go模块）
• Docker（可选，适用于Kali镜像）

______________________________________________________________________

安装和建造

从您的机器：

cd /path/to/pentest-mcps

# Initialize or verify the module (already done, safe to re-run)
go mod init github.com/restuhaqza/pentest-mcps

# Fetch MCP SDK and tidy deps
go get github.com/modelcontextprotocol/go-sdk/mcp@latest
go mod tidy

# Build main server binary
make build           # bin/pentest-mcps

# Optional: build client and HTTP components
make build-client    # bin/pentest-mcps-client
make build-http-server   # bin/pentest-mcps-http
make build-http-proxy    # bin/pentest-mcps-http-proxy

# Build for multiple architectures (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, windows/arm64)
make build-multi-arch    # Builds all binaries for all platforms in bin/-/ directories

______________________________________________________________________

运行MCP服务器

核心服务器(pentest-mcps)通过MCP讲话 标准正如MCP客户所期望的那样。

• 发展：

  go run .

• 二元的：

  ./bin/pentest-mcps

______________________________________________________________________

Docker：Kali测试环境

使用GitHub容器注册表中的预构建映像

Docker镜像会自动构建，并在每次推送时推送到GitHub容器注册表（GHCR） main 分支或创建标签时。

# Pull the latest image
docker pull ghcr.io/usebadik/pentests-mcp:latest

# Or pull a specific version
docker pull ghcr.io/usebadik/pentests-mcp:v0.1.0

# Run container (stdio-based MCP server)
docker run --rm -it ghcr.io/usebadik/pentests-mcp:latest

# Run HTTP server
docker run --rm -it -p 8080:8080 \
  ghcr.io/usebadik/pentests-mcp:latest \
  go run ./cmd/http-server --addr :8080 --server-cmd /usr/local/bin/pentest-mcps

注： 您可能需要先向GHCR进行身份验证：

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

在当地建设

构建并运行一个基于Kali的镜像，其中包含Go和常用工具：

# Build Kali-based testing image
docker build -f machines/kali.Dockerfile -t pentest-mcps-kali .

# Run container (stdio-based MCP server; you can also override CMD to run http-server)
docker run --rm -it pentest-mcps-kali

您可以根据需要使用其他Kali工具扩展此映像（例如。， metasploit-framework, burpsuite).

使用Docker Compose

默认情况下，要在Docker中运行HTTP服务器，请使用 docker-compose.yml:

docker compose up --build kali-http

这暴露了HTTP端点：

• http://127.0.0.1:8080/call-tool -通过HTTP POST调用MCP工具
• http://127.0.0.1:8080/health -健康检查端点（GET）
• http://127.0.0.1:8080/tools -列出具有输入模式（GET）的可用工具

______________________________________________________________________

部署拓扑

1.本地stdio（您计算机上的所有内容）

1. 构建：

   make build

1. 运行：

   ./bin/pentest-mcps

1. 将您的MCP客户端指向 ./bin/pentest-mcps 通过stdio（参见 MCP客户端集成 在......下面

2.远程SSH（编辑器↔ 安全外壳协议↔ 卡利）

1. 关于卡利：

   make build
   scp bin/pentest-mcps user@KALI_IP:/opt/pentest-mcps/

1. 在MCP客户端中，使用SSH command 运行 /opt/pentest-mcps/pentest-mcps （见下面的JSON示例）。

3.公共Kali（HTTP网桥+本地HTTP代理，无SSH）

在Kali（远程/公共）上：

make build build-http-server
./bin/pentest-mcps-http --addr :8080 --server-cmd ./bin/pentest-mcps
# HTTP API now available at:
# - http://KALI_PUBLIC_IP:8080/call-tool (POST - call tools)
# - http://KALI_PUBLIC_IP:8080/health (GET - health check)
# - http://KALI_PUBLIC_IP:8080/tools (GET - list tools with schemas)

在您的本地计算机（MCP代理服务器）上：

make build-http-proxy
./bin/pentest-mcps-http-proxy --remote-host http://KALI_PUBLIC_IP:8080

您的编辑将通过stdio与MCP对话 pentest-mcps-http-proxy，它将每个工具调用转发到Kali上的HTTP网桥。

______________________________________________________________________

MCP客户端集成（Cursor、Claude等）

此仓库通过stdio公开MCP服务器，因此您可以将它们连接到任何支持MCP的客户端。

光标(.cursor/mcp.json)

创建或编辑 .cursor/mcp.json 在repo/home目录中。使用 一 以下配置取决于您的连接方式。

注： 对于路径解析，请使用绝对路径或相对于光标启动位置的路径。如果使用相对路径，如 ./bin/pentest-mcps，确保Cursor的工作目录是项目根目录。

• 本地stdio（计算机上的二进制文件）:

  {
    "mcpServers": {
      "pentest-mcps": {
        "command": "./bin/pentest-mcps",
        "args": [],
        "env": {},
        "transport": "stdio"
      }
    }
  }

或者使用绝对路径：

  {
    "mcpServers": {
      "pentest-mcps": {
        "command": "/absolute/path/to/pentest-mcps/bin/pentest-mcps",
        "args": [],
        "env": {},
        "transport": "stdio"
      }
    }
  }

• 远程SSH（无HTTP，Kali上的工具）:

  {
    "mcpServers": {
      "pentest-mcps": {
        "command": "ssh",
        "args": ["user@KALI_IP", "/opt/pentest-mcps/pentest-mcps"],
        "env": {},
        "transport": "stdio"
      }
    }
  }

• 通过HTTP代理公开Kali（无SSH）:

  {
    "mcpServers": {
      "pentest-mcps": {
        "command": "./bin/pentest-mcps-http-proxy",
        "args": ["--remote-host", "http://KALI_PUBLIC_IP:8080"],
        "env": {},
        "transport": "stdio"
      }
    }
  }

替换 KALI_PUBLIC_IP 使用您的实际Kali服务器IP地址或主机名。

重要提示： mcpServers 必须始终指向 MCP服务器 二进制(./bin/pentest-mcps 或 ./bin/pentest-mcps-http-proxy)，而不是CLI客户端。\ 这 pentest-mcps-client 二进制文件用于手动CLI使用（例如。 --remote-host http://IP:8080)并且应该 不 被引用 mcpServers.

编辑此文件后重新启动Cursor，使其拾取配置。

Claude Desktop/其他支持MCP的编辑器

大多数UI允许您添加 自定义MCP服务器 通过指定：

• 名字: pentest-mcps
• 命令：其中之一：

- ./bin/pentest-mcps （本地） - ssh user@KALI_IP /opt/pentest-mcps/pentest-mcps （远程SSH） - ./bin/pentest-mcps-http-proxy --remote-host http://KALI_PUBLIC_IP:8080 （HTTP代理）

• 运输: stdio

配置后，您可以调用以下工具 nmap_host_scan, web_dir_enum, gobuster_enum, nikto_scan，以及 sqlmap_test 直接从编辑器的工具面板。

______________________________________________________________________

本地Go CLI MCP客户端（用于测试）

CLI客户端对于无需编辑器的快速测试非常有用。

构建：

go build -o bin/pentest-mcps-client ./cmd/client

示例（本地stdio服务器）：

# Health check (default tool is `health`)
./bin/pentest-mcps-client --server-cmd ./bin/pentest-mcps

# nmap host scan against local stdio server
./bin/pentest-mcps-client \
  --server-cmd ./bin/pentest-mcps \
  --tool nmap_host_scan \
  --args '{"host":"scanme.nmap.org","ports":"80,443"}'

# gobuster enum against local stdio server
./bin/pentest-mcps-client \
  --server-cmd ./bin/pentest-mcps \
  --tool gobuster_enum \
  --args '{"url":"https://target/"}'

# sqlmap test against local stdio server
./bin/pentest-mcps-client \
  --server-cmd ./bin/pentest-mcps \
  --tool sqlmap_test \
  --args '{"url":"https://target/vuln.php?id=1"}'

远程HTTP示例（当HTTP服务器在上运行时 http://127.0.0.1:8080):

./bin/pentest-mcps-client \
  --remote-host http://127.0.0.1:8080 \
  --tool health

./bin/pentest-mcps-client \
  --remote-host http://127.0.0.1:8080 \
  --tool nmap_host_scan \
  --args '{"host":"scanme.nmap.org","ports":"80"}'

______________________________________________________________________

使用pentest工具进行扩展

您可以通过在中创建处理程序来添加更多工具 internal/tools/ 并将它们连接起来 main.go.

一般模式：

1. 定义一个 输入结构体 使用JSON字段作为工具的参数。
2. 使用助手 internal/core （消毒， RunCommand)调用底层二进制文件。
3. 定义一个 输出结构体 随着 tool、输入回声， error，以及 output 领域。
4. 在中添加架构函数 internal/tools/schema.go 为输入生成JSON模式。
5. 向注册工具 mcp.AddTool(server, &mcp.Tool{..., InputSchema: ...}, handlerFn).

输入架构：所有工具现在都包含其输入参数的JSON模式定义。这允许MCP客户端：

• 在发送请求之前验证输入
• 在UI中显示参数要求
• 自动生成工具执行表单
• 通过以下方式查询可用工具及其模式 /tools HTTP服务器上的端点

保持输出纯文本和JSON，以便它们在浅色和深色主题中都能很好地呈现（除非必要，否则避免使用颜色代码，或者将其设置为可选）。

当前结构：

• main.go –MCP服务器引导和工具注册。
• internal/core/ –命令执行和清理的共享助手。
• internal/tools/ –单个工具的实现。
• cmd/http-server/ –HTTP网桥暴露 /call-tool （POST）， /health （GET），以及 /tools （获取）。
• cmd/http-proxy/ –代理HTTP网桥的本地MCP服务器。
• cmd/client/ –简单的MCP客户端CLI。

______________________________________________________________________

内置工具

服务器当前包括：

• health （工具）

- 返回结构化JSON健康信息： - 总体状态、消息和版本。 - tools_status 显示关键工具可用性的地图(nmap, gobuster, nikto, sqlmap). - all_essential_tools_available 布尔值。

• nmap_host_scan （工具）

- 运行基本 nmap 对单个主机进行扫描。 - 参数： - host （字符串，必填）-主机名或IP。 - ports （字符串，可选）-例如。 "80,443" 或 "1-1024".

• web_dir_enum （工具）

- 使用以下命令进行简单目录枚举 wfuzz. - 参数： - url （字符串，必填）-基本URL，例如。 https://target/.如果 FUZZ 如果不存在，它将被附加。 - wordlist （string，可选）-单词表路径；默认为 /usr/share/wordlists/dirb/common.txt 卡利。 - extensions （字符串，可选）-保留用于未来的过滤行为。

• gobuster_enum （工具）

- 目录枚举使用 gobuster dir. - 参数： - url （字符串，必填）。 - wordlist （字符串，可选；默认为 /usr/share/wordlists/dirb/common.txt).

• nikto_scan （工具）

- 通过以下方式进行基本web服务器漏洞扫描 nikto. - 参数： - url （字符串，必填）。

• sqlmap_test （工具）

- 简单的SQL注入测试使用 sqlmap. - 参数： - url （字符串，必填）。 - data （字符串，可选）-用于测试的POST正文数据。

______________________________________________________________________

测试和覆盖范围

在本地运行测试：

make test          # go test ./...

或者在Kali图像中：

make docker-kali-build
docker run --rm -it pentest-mcps-kali go test ./...

要查看覆盖范围（在您的机器上或容器中）：

go test ./... -cover
go test ./... -coverprofile=coverage.out
go tool cover -func=coverage.out

目前的测试包括：

• internal/core：清理助手和命令执行器。
• internal/tools：验证行为 nmap_host_scan 和 web_dir_enum.
• cmd/http-proxy：代理处理程序通过本地转发/解码 httptest 服务器。

______________________________________________________________________

注意事项和安全

• 该回购故意最小化；您应该根据自己的环境和威胁模型调整工具和标志。
• 在调用系统命令之前，始终验证和清理输入。
• 小心暴露HTTP端点（特别是在公共IP上）。如果可能的话，首选SSH或控制良好的网络。
• 保持输出 在浅色和深色主题的UI中都可读；避免使用硬编码的ANSI颜色，除非您将其剥离或屏蔽\*\*\*

致谢

多亏了

• Restu Muzakir
• 嗯。Fani Akbar