CatNotBat/ai-pentest-suite
GitHub: CatNotBat/ai-pentest-suite
一个容器化的AI渗透测试代理，在Kali中通过MCP封装常用工具，实现IoT/固件测试的自动化与状态持久化。
Stars: 0 | Forks: 0
# IoT 与固件渗透测试套件
一个用于 IoT/嵌入式目标的容器化 AI 渗透测试代理。Claude 在 Kali Linux 中运行，并通过一组 MCP 服务器封装了常见渗透测试工具——nmap、john、searchsploit、NVD API 以及串口 UART 访问。发现结果和状态会在会话之间持久化。
## 工作原理
Claude Code 作为代理运行。在启动时读取结构化的参与状态文件，通过 MCP 服务器运行渗透测试工具，并将结果写入报告文件——全程不离开当前会话。每个会话都会从上一次结束的位置继续。
```
Host
├── mcp/ ← MCP server Python files
├── scripts/ ← entrypoint, utilities, standalone tools
├── squashfs-root/ ← extracted firmware (bind-mounted read-only at /firmware)
├── flash_dump/ ← raw flash dumps from live device (gitignored)
├── reports/ ← audit findings, written by the agent (gitignored)
├── demos/ ← runnable exploit PoC scripts, written by the agent (gitignored)
├── ENGAGEMENT_STATE.md ← persistent agent memory (gitignored)
└── CLAUDE.md ← agent instructions (loaded automatically)
Container (kali-rolling)
├── Claude Code ← the agent
├── /firmware ← squashfs-root mounted here (ro)
└── MCP servers
├── nmap-adapter ← port scanning
├── hash-cracker ← john + rockyou wordlist
├── uart-adapter ← serial/UART hardware access
├── searchsploit ← ExploitDB search and PoC retrieval
└── cve-lookup ← NVD API for CVE details and scoring
```
## 先决条件
- Docker + Docker Compose
- Claude Max 订阅（或 Anthropic API 密钥）
- 提取的固件文件，位于 `./squashfs-root/` —— 使用 `unsquashfs -d squashfs-root firmware.bin`
- 对于 UART：需将 USB-to-serial 适配器（CP2102、CH340 或 FTDI）焊接到目标的 TX/RX/GND 焊盘
## 安装与设置
```
# 提取固件
unsquashfs -d squashfs-root firmware.bin
# 构建容器
docker compose up -d --build
# 执行并认证（仅首次 — 令牌在命名卷中持久化）
docker exec -it claude-pentest-sandbox bash
claude login
# 启动代理
claude
```
开始提示：`Read the engagement state and start where you left off.`
## MCP 工具
| 服务器 | 工具 | 描述 |
|--------|------|-------------|
| `nmap-adapter` | `scan_target(ip, type)` | `quick` / `full` / `vuln` 扫描，返回解析后的开放端口与 NSE 脚本输出 |
| `hash-cracker` | `crack_hash(hash, format)` | 针对 rockyou 字典运行 john，5 分钟超时 |
| `uart-adapter` | `uart_open(port, baud)` | 打开串口连接（默认 `/dev/ttyUSB0`，波特率 115200） |
| | `uart_read(timeout_s)` | 读取输出——用于捕获启动日志 |
| | `uart_send(data)` | 快速写入 |
| | `uart_send_recv(cmd, timeout_s)` | 写入并读取响应——用于交互式 Shell |
| | `uart_send_break()` | 发送 BREAK 信号以中断 U-Boot 自动启动 |
| | `uart_close()` | 关闭连接 |
| `searchsploit` | `search_exploits(query)` | 按 CVE ID、产品或关键词搜索 ExploitDB |
| | `get_exploit_file(edb_id)` | 通过 EDB-ID 读取完整的 PoC 源码 |
| `cve-lookup` | `lookup_cve(cve_id)` | NVD 查询：CVSS 评分、描述、受影响的版本及引用 |
| | `search_cves_by_keyword(kw)` | 按产品名称或关键词查找 CVE |
## UART 设置
当 USB-UART 适配器物理连接到目标的串口焊盘时：
```
# 在插入后在 HOST 上查找设备
dmesg | grep tty
# 取消注释并更新 docker-compose.yml，然后重启
# devices:
# - /dev/ttyUSB0:/dev/ttyUSB0
docker compose up -d
```
Claude 内部典型工作流程：
1. `uart_open("/dev/ttyUSB0", 115200)`
2. 对路由器进行上电复位，然后 `uart_read(timeout_s=60)` 捕获启动日志
3. 如果 U-Boot 显示倒计时，再次上电复位并立即调用 `uart_send_break()`
4. 从 Shell 执行：`uart_send_recv("cat /proc/mtd")`、`uart_send_recv("cat /proc/version")`
## 状态与持久化
代理会在会话之间维护 `ENGAGEMENT_STATE.md`。它会跟踪当前阶段、已发现的服务、已破解的凭据、已确认的安全发现，以及一个 `## Last Session` 叙事块，记录决策背后的 *推理过程*（而不仅仅是事实）。这使得下一个会话可以“热启动”而非从零开始。
认证令牌存储在名为 `claude-root-data` 的 Docker 命名卷中，容器重启后仍保留。
## 发现结果与演示
所有发现结果写入 `reports/router_audit.md`。对于每一个确认的非平凡漏洞（预认证 RCE、内存损坏、协议级漏洞、漏洞链），代理会在 `demos/` 中生成一个可运行的演示脚本。仅默认凭据不足以构成有效发现。
这两个目录均被加入 `.gitignore` —— 它们可能包含已破解的密码、可用的漏洞利用程序以及在线设备的凭据。
## 路由修复
如果路由器通过 DHCP 推送默认网关并覆盖你的互联网路由，可在主机上运行以下命令：
```
sudo bash scripts/fix_router_default_route.sh
```
它会自动检测 NetworkManager / systemd-networkd / dhcpcd，并应用相应的持久化修复。
## 添加新的 MCP 服务器
1. 使用 FastMCP 编写 `mcp/yourserver_server.py`
2. 通过 `register` 函数将其添加到 `scripts/entrypoint.sh`
3. 将预批准的工具调用添加到 `.claude/settings.json`
4. 重建镜像：`docker compose up -d --build`
## 自主模式
以完全自主循环运行 Claude —— 无需人工确认，会话在速率限制窗口重置时（约 5 小时）自动重启。
```
# 从项目根目录（容器必须已经运行并认证）
bash scripts/pentest_loop.sh
```
每次会话启动 Claude 时使用 `--dangerously-skip-permissions` 并附带简短提示，用于读取 `ENGAGEMENT_STATE.md` 并继续执行“下一步操作”。会话结束时，循环等待 5 分钟并启动新一轮。会话日志写入 `reports/session_N_.log`。
**Telegram 通知（可选）**
```
export TELEGRAM_TOKEN="bot"
export TELEGRAM_CHAT_ID=""
bash scripts/pentest_loop.sh
```
当设置 `TELEGRAM_TOKEN` 和 `TELEGRAM_CHAT_ID` 时，`scripts/notify.sh` 会在会话开始和结束时发送消息。该 Hook 为占位符——可在 `notify.sh` 中扩展以提供更丰富的告警。
**安全性**
自主模式的安全规则通过 `CLAUDE.md` 强制执行——范围锁定在 `192.168.1.1`，禁止外部数据外泄，禁止闪存写入。这些规则会在每个会话中自动加载。
## 安全说明
仅在你拥有或已获得明确授权的设备上使用本容器。容器以 `network_mode: host` 运行，以便直接访问本地网络目标。
标签：AI安全代理, Claude Code, CVE查询, Docker, Docker Compose, DOS头擦除, IoT安全, John the Ripper, MCP服务器, NIDS, NVD API, SearchSploit, squashfs, UART, 串口调试, 固件安全, 固件提取, 安全防御评估, 容器化, 密码破解, 嵌入式安全, 持久化状态, 硬件接口, 自动化渗透, 请求拦截, 逆向工具