originsec/pocsmith
GitHub: originsec/pocsmith
pocsmith 是一个自动化Windows内核漏洞概念验证生成工具，利用AI驱动在虚拟机中测试和验证POC。
Stars: 16 | Forks: 5
# d the text carefully: "There are exactly 19 line(s) below; output exactly 19 line(s) of translation, one per line, in the same order."
一个自主的 Windows 概念验证 (POC) 开发器。它读取 [patchwatch](https://github.com/originsec/patchwatch) 生成的 CVE 报告，并驱动一个 Claude 智能体完成在远程内核调试器下针对预补丁 Windows 虚拟机进行的编写、构建、部署、运行和验证概念验证 (POC) 的全过程。
pocsmith 将多个 MCP 服务器和一个 LLM 连接成一个工作流：
- **[patchwatch](https://github.com/originsec/patchwatch)** — 生成 pocsmith 所需的 CVE 报告（描述、排名的二进制文件、ghidriff 输出）。
- **[hyperv-mcp](https://github.com/originsec/hyperv-mcp)** — Hyper-V 虚拟机生命周期管理：快照、KD 配置、PowerShell-Direct 客户机执行。
- **[kd-mcp](https://github.com/originsec/kd-mcp)** — 远程内核调试器包装器（断点、寄存器/内存检查、`!analyze -v`）。
- **[pyghidra-mcp](https://github.com/clearbluejar/pyghidra-mcp)** — Ghidra 在应用了 PDB 符号的预补丁二进制文件上运行。
- **pocsmith-mcp** — 智能体用于编译、记录尝试、宣布成功和结束阶段的驱动工具。在本仓库中实现。
- **Anthropic API** — 驱动循环的智能体。模型可配置。
它设计为**在本地**针对您自己的基础设施运行：您的 Hyper-V 主机、您的虚拟机、您的 ISO。唯一的出站流量是流向您配置的 LLM 端点。
## 安全性
pocsmith 会生成并运行漏洞利用代码。系统提示将执行限制在通过 `hyperv-mcp` 访问的目标 Hyper-V 虚拟机内；有效负载从不在主机上运行。将生成的任何产物（POC 源码、复现脚本）视为授权研究成果并妥善处理。仅用于您控制或明确授权测试的系统。
## 前置条件
### 硬件
- 启用了 Hyper-V 的 Windows 11 主机（建议 32 GB RAM）。
- 至少一个匹配 CVE 补丁 KB 的 Windows ISO（例如，24H2 版本）。
### 软件
| 依赖项 | 获取方式 | 备注 |
|---|---|---|
| Python 3.12+ | | 必须位于 `PATH` 中。 |
| Visual Studio 2022 | | 安装 *使用 C++ 的桌面开发* 工作负载。 |
| Windows SDK (调试工具) | | 用于 `kd.exe`。 |
| Docker Desktop | | 用于 `ghidra.mode: docker`（推荐）。 |
| Java 21+ | | 仅用于 `ghidra.mode: local`。 |
| Ghidra 11.x | | 仅用于 `ghidra.mode: local`；设置 `GHIDRA_INSTALL_DIR`。 |
| pyghidra-mcp | `pip install pyghidra-mcp` | 仅用于 `ghidra.mode: local`。 |
| patchwatch | | 生成 pocsmith 消耗的 CVE 报告。 |
| hyperv-mcp | | 通过 `setup.ps1` 以可编辑模式安装；通过 `python -m hyperv_mcp` 调用。 |
| kd-mcp | | 通过 `setup.ps1` 以可编辑模式安装；通过 `python -m kd_mcp` 调用。 |
### 环境变量
在工作区根目录的 `.env` 文件中设置这些变量（可以复制 `.env.example` 开始）：
```
ANTHROPIC_API_KEY your Anthropic API key
HYPERV_GUEST_USERNAME guest VM admin username (e.g. Administrator)
HYPERV_GUEST_PASSWORD guest VM admin password
HYPERV_GUEST_VICTIM_USERNAME optional: unprivileged account for EoP scenarios
HYPERV_GUEST_VICTIM_PASSWORD optional: password for the victim account
GHIDRA_INSTALL_DIR e.g. C:\Tools\ghidra_11.3 (only for ghidra.mode=local)
```
## 快速入门
```
# In the user's message, after "Live smoke tests are gated by RUN_LIVE=1", there might be a missing line, or I need to count the numbers correctly. Looking back, the headings include "CLI" and then several points. Perhaps "CLI" is a heading, and then the points under it.
git clone https://github.com/originsec/pocsmith.git
cd pocsmith
# Re-reading the user's input:
# - "pocsmith" – line 1
.\scripts\setup.ps1
# - "1. Clone and enter the project" – line 2
.\.venv\Scripts\Activate.ps1
# - "2. Run the setup script. Creates a venv, installs deps, generates a config template, and pulls the pyghidra-mcp Docker image." – line 3
copy .env.example .env
notepad .env
# - "3. Activate the venv" – line 4
copy pocsmith.example.yaml pocsmith.yaml
notepad pocsmith.yaml
# - "4. Copy and edit the env file" – line 5
patchwatch export-poc-context CVE-2026-XXXXX --out C:\Research\pocsmith-workspaces
# - "5. Copy and edit the config file" – line 6
pocsmith run --cve CVE-2026-XXXXX --config pocsmith.yaml
```
要在不安装任何东西的情况下检查前置条件：
```
.\scripts\check-prereqs.ps1
```
## - "6. Export a CVE from patchwatch" – line 7
```
# - "7. Run pocsmith" – line 8
pocsmith run --cve CVE-2026-XXXXX --config pocsmith.yaml
# - "CLI" – line 9
pocsmith run --cve CVE-2026-XXXXX --config pocsmith.yaml `
--hint "The bug is in the pool allocation path; try heap spray with large IRPs first."
# - "Start a fresh run on an exported CVE" – line 10
pocsmith resume --cve CVE-2026-XXXXX --config pocsmith.yaml
# - "Steer the agent with a hint injected into the first phase kickoff" – line 11
pocsmith inspect --workspace-root C:\Research\pocsmith-workspaces
# - "Resume an interrupted run (re-uses notes.md and attempt history)" – line 12
pocsmith report --cve CVE-2026-XXXXX --config pocsmith.yaml
# - "List CVE workspaces under the configured workspace root" – line 13
pocsmith tail --cve CVE-2026-XXXXX --config pocsmith.yaml --tail
# - "Regenerate the report.md for a workspace that already reached a success status" – line 14
pocsmith tail --file C:\Research\pocsmith-workspaces\CVE-2026-XXXXX\session.jsonl --thinking
```
`run` 和 `resume` 命令的可选标志：
| 标志 | 默认值 | 描述 |
|---|---|---|
| `--level A/B/C` | A | A = 崩溃复现，B = 受控原语，C = 完整漏洞利用。 |
| `--config` | — | `pocsmith.yaml` 文件的路径。 |
| `--workspace-root` | 来自配置 | 覆盖工作区根目录。 |
| `--vm-name` | 来自配置 | Hyper-V 虚拟机名称。 |
| `--hint TEXT` | _(无)_ | 注入到智能体首次启动消息中的提示。 |
| `--model` | `claude-opus-4-7` | Anthropic 模型 ID。 |
| `--skip-build-check` | 关闭 | 跳过验证虚拟机构建版本是否匹配 `context.json` 中的 `patched_build`。 |
## 配置
`pocsmith.example.yaml` 是标准示例。最值得了解的字段包括：
```
vm:
backend: hyperv # only supported backend
vm_root: C:\VMs\pocsmith # where Hyper-V VHDXs live
default_profile: win11-24h2 # VM used when no --vm-name given
mcp_module: hyperv_mcp # python -m hyperv_mcp (installed in venv)
kd:
module: kd_mcp # python -m kd_mcp (installed in venv)
hyperv_guest:
username_env: HYPERV_GUEST_USERNAME # env var holding the admin username
password_env: HYPERV_GUEST_PASSWORD
victim_username_env: HYPERV_GUEST_VICTIM_USERNAME # optional unprivileged account
victim_password_env: HYPERV_GUEST_VICTIM_PASSWORD
ghidra:
mode: docker # docker | local
image: ghcr.io/clearbluejar/pyghidra-mcp
port: 8000
compile:
vcvarsall: C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat
arch: x64
attacker_py:
venv: C:\Research\pocsmith-workspaces\attacker-venv
sysinternals_dir: C:\Research\pocsmith-workspaces\sysinternals # optional
packages: [impacket]
llm:
model: claude-opus-4-7
api_key_env: ANTHROPIC_API_KEY
context_threshold_pct: 70
ceilings:
level_a: { wall_min: 60, iterations: 40, dollars: 10.0, phases: 8 }
level_b: { wall_min: 240, iterations: 80, dollars: 50.0, phases: 16 }
level_c: { wall_min: 240, iterations: 80, dollars: 50.0, phases: 16 }
paths:
patchwatch_bin: C:\Tools\patchwatch\patchwatch.exe
workspace_root: C:\Research\pocsmith-workspaces
```
### 本地 Ghidra（无 Docker）
```
ghidra:
mode: local
pyghidra_mcp_cmd: pyghidra-mcp
ghidra_install_dir: C:\Tools\ghidra_11.3
```
## 工作原理
```
patchwatch report --> pocsmith run --> Claude agent (Agent SDK)
|
+--------------------------+--------------------------+
v v v
hyperv-mcp kd-mcp pyghidra-mcp
(VM lifecycle, (kernel debugger) (pre-patch binary
guest exec, + PDB analysis)
KD setup)
| |
+----------+---------------+
|
pocsmith-mcp
(compile_c, attacker_py,
record_attempt, end_phase,
report_outcome, cve_context)
|
pre-patch VM
(kernel-debugged)
```
每次运行都是一个*阶段*序列，每个阶段都是一个有边界的 Claude Agent SDK 会话。
智能体循环执行：编辑 POC 源码、编译、部署到虚拟机、触发漏洞捕获 KD 输出、记录尝试、回滚、重复。在 `report_outcome` 时，pocsmith 会在全新的回滚状态上重放尝试以验证信号，然后才将产物提升为正式产物。
### 阶段
一个*阶段*是一段连贯的工作——通常是 3-6 次迭代，追求一个假设。一次运行包含 3-8 个阶段。当智能体调用 `end_phase`（主动，在改变假设或遇到瓶颈时）或当驱动程序的输入令牌阈值（默认为模型上下文窗口的 70%）达到时，阶段结束。阶段结束时，完整转录将刷新到 `transcripts/phase-N.jsonl`，会话关闭，下一个阶段全新开始——读取 `notes.md` 和 `attempts/*/status.json` 的紧凑摘要，而不是重放转录。
### 重放验证
`report_outcome` 是终止调用。对于成功状态，pocsmith 会：
1. 将虚拟机回滚到干净快照。
2. 重新附加 kd，重新部署记录的 POC 产物，重新运行记录的调用。
3. 将智能体声明的信号与重放的 kd 输出进行评估。
信号是五种类型之一：`bugcheck`、`usermode_exception`、`kd_breakpoint_hit`、`service_crash`、`assertion`。此集合之外的任何内容都被记录为 `unverified_claim`，不会提升为产物。
`kd_breakpoint_hit` 信号上的 `register_predicate` DSL 支持寄存器读取、带偏移量的解引用、整数比较以及 AND/OR 操作。
### 预算
| 等级 | 挂钟时间 | 迭代次数 | 美元消耗 | 阶段数 |
|---|---|---|---|---|
| A | 60 分钟 | 40 | $10 | 8 |
| B | 4 小时 | 80 | $50 | 16 |
| C | 4 小时 | 80 | $50 | 16 |
在任何上限达到 75% 时，pocsmith 会在下一次迭代前注入一行提醒。达到 100% 时，它强制智能体调用 `report_outcome` 并拒绝进一步的工具调用。
## 工作区布局
`paths.workspace_root` 是所有 pocsmith 运行时数据的根目录：共享的攻击者虚拟环境、Sysinternals 工具缓存，以及每个 CVE 的独立子目录。
```
\
attacker-venv\ shared Python venv with impacket etc. (setup.ps1)
sysinternals\ Sysinternals Suite, host-side stage (setup.ps1)
CVE-XXXX-NNNNN\
context.json static CVE context from patchwatch
pre-patch\ pre-patch binaries (hardlinked from patchwatch cache)
post-patch\ post-patch binaries
ghidriff\ ghidriff diff outputs
symbols\ _NT_SYMBOL_PATH cache
ghidra-project\ pyghidra .gpr (cached by pre-patch SHA)
poc\ agent's POC sources and builds
notes.md agent exobrain - survives phase boundaries
attempts\NNN\ per-iteration: status.json, kd.log, target.log
transcripts\phase-N.jsonl full session transcript per phase
artifacts\ written on verified success:
poc\ the verified POC
repro.md reproduction steps
verification.json signal match record
summary.md run summary
report.md LLM-written narrative report
.mcp.json auto-generated MCP server config
pocsmith-run.lock prevents concurrent runs on this workspace
```
当设置 `attacker_py.sysinternals_dir` 时，智能体在 pocsmith MCP 上接收 `POCSMITH_SYSINTERNALS` 作为环境变量，并被指示通过 `hyperv_guest_put` 将这些二进制文件部署到客户机中，而不是在主机上执行它们。
## 架构说明
- **阶段作用域会话**：每个阶段是一个全新的 Agent SDK 会话。持久状态存储在 `notes.md`（由智能体管理）和 `attempts/*/status.json`（由驱动程序写入）。转录刷新到磁盘但不重放。
- **用于昂贵读取的子智能体**：系统提示引导智能体通过 `Task` 子智能体路由大令牌读取（完整反编译、kd 转储、ghidriff JSON），这些子智能体返回简短的结构化摘要——这是针对 Ghidra 密集型 CVE 的最大令牌成本杠杆。
- **仅限虚拟机的漏洞利用执行**：系统提示禁止在主机上运行漏洞利用代码。`attacker_py` 用于针对虚拟机的网络端工具（例如 impacket），而不是主机端漏洞利用。
- **幂等恢复**：`pocsmith resume` 复用现有工作区、`notes.md` 和尝试历史记录。它启动一个新阶段，而不是完整的转录重放。
- **驱动程序管理的 MCP 监督**：`.mcp.json` 为每个工作区生成；kd-mcp 和 pyghidra-mcp 在崩溃后重启；hyperv-mcp 失败会中止运行。
参见 [docs/design.md](docs/design.md) 获取完整的设计规范，包括信号谓词类型、上下文窗口管理和 MCP 服务器契约。
## 测试
```
# - "Live-tail the active session transcript in human-readable form" – line 15
pytest
# - "...or point it at any session.jsonl directly:" – line 16
$env:RUN_LIVE = "1"; pytest -k smoke
```
## 许可证
Apache 2.0 — 参见 [LICENSE](./LICENSE) 和 [NOTICE](./NOTICE)
由 [Origin](https://originhq.com) 为安全研究和红队行动而构建。
标签：AI 驱动安全, Claude AI, CVE 分析, exploit 开发, Ghidra, Hyper-V, kernel exploit, LLM 应用, Maven, MCP 服务器, POC 开发, Python, RFI远程文件包含, VM 管理, Web报告查看器, Windows 安全, 二进制分析, 云安全运维, 内核调试, 安全测试, 攻击性安全, 无后门, 本地部署, 漏洞验证, 系统运维工具, 虚拟机管理, 补丁分析, 请求拦截, 软件漏洞, 远程调试, 逆向工具