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)
AI-assisted malware detonation agent for QEMU sandboxes.
Many malware samples require user interaction to fully execute: clicking
"Enable Content" on Office macros, dismissing security dialogs, navigating
installer wizards, or entering passwords. sandbox-pilot watches a QEMU VM's
screen and uses Claude's vision API to understand what's happening and send
the right keyboard/mouse input to help samples detonate.
## 如何工作
```
QEMU VM (malware running) sandbox-pilot
+-----------------------+ +------------------+
| | screen | |
| Windows guest |---------->| screendump |
| with sample | dump | | |
| | | heuristic check |
| | sendkey | | |
| |<----------| Claude vision |
| | mouse | | |
+-----------------------+ | execute action |
+------------------+
```
1. Takes a screenshot via QEMU monitor socket
2. Heuristic filter skips unchanged screens (saves 60-80% of API calls)
3. Sends changed/stuck screens to Claude's vision API
4. Claude analyzes the screen and recommends an action
5. Agent translates the action into QEMU keyboard/mouse input
6. Repeats until the sample is running or timeout
## 安装
```
pip install -e ".[dev]"
```
Requires Python 3.10+ and an [Anthropic API key](https://console.anthropic.com/).
## 用法
```
export ANTHROPIC_API_KEY=sk-ant-...
# 基础 — 连接到 QEMU 监控器套接字
sandbox-pilot --socket /path/to/qemu-monitor.sock
# 带示例上下文
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
```
### 选项
| Flag | Default | Description |
|------|---------|-------------|
| `--socket` | (required) | Path to QEMU monitor Unix socket |
| `--hint` | none | Context about the sample for Claude |
| `--interval` | 5 | Seconds between observations |
| `--max-iterations` | 60 | Max observation cycles |
| `--timeout` | 300 | Total timeout in seconds |
| `--resolution` | 1920x1080 | VM screen resolution |
| `--model` | claude-sonnet-4-20250514 | Claude model for vision |
| `--verbose` | off | Enable debug logging |
## 示例输出
```
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
```
## 安全
**Intended use:** Authorized malware analysis in isolated sandbox environments.
The system prompt tells Claude it is operating inside an air-gapped detonation
environment with no internet access and disposable VM snapshots. This framing
is required for Claude to assist with malware execution and must accurately
reflect your actual environment.
**Anti-prompt-injection mitigations:**
Malware authors aware of AI-assisted sandboxes could attempt visual prompt
injection (rendering adversarial text on screen). sandbox-pilot includes:
- **TYPE length cap (100 chars):** Blocks "type this shell command" attacks
- **Suspicious pattern detection:** Flags shell metacharacters and injection
phrases in logs (does not block — this is threat intelligence)
- **Full audit log:** Every action, reasoning, and screenshot logged for review
## 架构
```
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+
- QEMU with monitor socket enabled (`-monitor unix:/path/to/sock,server,nowait`)
- Anthropic API key (`ANTHROPIC_API_KEY` environment variable)
- A VM with a display (VGA) — screendump requires a framebuffer
## 许可证
Apache 2.0 — see [LICENSE](LICENSE).
## 作者
Christopher Shaiman
标签：AI辅助, Apex, APT检测, Claude API, DAST, DNS解析, Python, QEMU, 云资产清单, 内联执行, 屏幕监控, 开源项目, 恶意软件分析, 无后门, 机器学习, 样本脱壳, 沙箱, 漏洞分析, 用户交互模拟, 计算机视觉, 路径探测, 身份验证强制, 逆向工具, 逆向工程, 键盘鼠标模拟