chrisshaiman/sandbox-pilot
GitHub: chrisshaiman/sandbox-pilot
一个基于 QEMU 与 Claude 视觉的 AI 辅助沙箱自动化 detonation 代理，解决恶意软件需用户交互才能触发的问题。
Stars: 0 | Forks: 0
# sandbox-pilot
[](https://github.com/chrisshaiman/sandbox-pilot/actions/workflows/ci.yml)
用于 QEMU 沙箱的 AI 辅助恶意软件引爆 agent。
许多恶意软件样本需要用户交互才能完全执行：点击 Office 宏上的“启用内容”，关闭安全对话框，导航安装向导，或输入密码。sandbox-pilot 监控 QEMU 虚拟机的屏幕，并使用 Claude 的视觉 API 来了解正在发生的情况，发送正确的键盘/鼠标输入，以帮助样本引爆。
## 工作原理
```
QEMU VM (malware running) sandbox-pilot
+-----------------------+ +------------------+
| | screen | |
| Windows guest |---------->| screendump |
| with sample | dump | | |
| | | heuristic check |
| | sendkey | | |
| |<----------| Claude vision |
| | mouse | | |
+-----------------------+ | execute action |
+------------------+
```
1. 通过 QEMU monitor socket 截取屏幕
2. 启发式过滤器跳过未更改的屏幕（节省 60-80% 的 API 调用）
3. 将已更改/卡住的屏幕发送给 Claude 的视觉 API
4. Claude 分析屏幕并推荐操作
5. Agent 将操作转换为 QEMU 键盘/鼠标输入
6. 重复此过程，直到样本运行或超时
## 安装
```
pip install -e ".[dev]"
```
需要 Python 3.10+ 和一个 [Anthropic API 密钥](https://console.anthropic.com/)。
## 用法
```
export ANTHROPIC_API_KEY=sk-ant-...
# 基础 — 连接到 QEMU monitor socket
sandbox-pilot --socket /path/to/qemu-monitor.sock
# 带有 sample 的相关上下文
sandbox-pilot --socket /path/to/qemu-monitor.sock \
--hint "Word document with macros, expect Enable Content prompt"
# 调优
sandbox-pilot --socket /path/to/qemu-monitor.sock \
--interval 5 \
--max-iterations 60 \
--timeout 300 \
--resolution 1920x1080
```
### 选项
| 参数 | 默认值 | 描述 |
|------|---------|-------------|
| `--socket` | (必填) | QEMU monitor Unix socket 的路径 |
| `--hint` | 无 | 提供给 Claude 的关于样本的上下文 |
| `--interval` | 5 | 观察之间的间隔秒数 |
| `--max-iterations` | 60 | 最大观察循环次数 |
| `--timeout` | 300 | 总超时时间（以秒为单位） |
| `--resolution` | 1920x1080 | 虚拟机屏幕分辨率 |
| `--model` | claude-sonnet-4-20250514 | 用于视觉的 Claude 模型 |
| `--verbose` | 关闭 | 启用调试日志 |
## 示例输出
```
sandbox-pilot v0.1.0
Socket: /tmp/qemu-monitor.sock
Model: claude-sonnet-4-20250514
Resolution: 1920x1080
Interval: 5s
Hint: Word document with macros
sandbox-pilot finished: 12 iterations, 3 actions taken, 5 API calls
[00:05] CLICK(450, 320) — "Enable Content" button on macro warning
[00:15] KEY(enter) — Dismissed Windows security dialog
[01:00] DONE — Malware process running normally in task manager
```
## 安全
**预期用途：** 在隔离的沙箱环境中进行授权的恶意软件分析。
系统提示告诉 Claude，它正在一个没有互联网访问权限且使用一次性虚拟机快照的气隙隔离引爆环境中运行。此设定是 Claude 协助执行恶意软件所必需的，并且必须准确反映您的实际环境。
**防 prompt 注入缓解措施：**
了解 AI 辅助沙箱的恶意软件作者可能会尝试视觉 prompt 注入（在屏幕上渲染对抗性文本）。sandbox-pilot 包括：
- **TYPE 长度上限（100 个字符）：** 阻止“输入此 shell 命令”攻击
- **可疑模式检测：** 在日志中标记 shell 元字符和注入短语（不阻止——这是威胁情报）
- **完整审计日志：** 记录每个操作、推理和截图以供审查
## 架构
```
sandbox_pilot/
cli.py # Entry point, main loop, logging
monitor.py # QEMU monitor socket (sendkey, mouse, screendump)
vision.py # Claude API (vision analysis, system prompt)
heuristics.py # Screenshot change detection (API call filter)
actions.py # Action translation + anti-injection
```
## 要求
- Python 3.10+
- 启用了 monitor socket 的 QEMU (`-monitor unix:/path/to/sock,server,nowait`)
- Anthropic API 密钥（`ANTHROPIC_API_KEY` 环境变量）
- 带有显示器 (VGA) 的虚拟机 —— 屏幕转储需要 framebuffer
## 许可证
Apache 2.0 — 详见 [LICENSE](LICENSE)。
## 作者
Christopher Shaiman
标签：AI自动化, DAST, DLL 劫持, QEMU, 内联执行, 大语言模型, 恶意软件分析, 搜索语句（dork）, 沙箱