cdbkk/vuln-monkey
GitHub: cdbkk/vuln-monkey
vuln-monkey 是一款利用 LLM 对 API 端点进行安全模糊测试的工具，通过自动生成攻击 payload 并分析响应来发现接口逻辑缺陷。
Stars: 14 | Forks: 1
vuln-monkey 使用 LLM 来分析 API endpoint，生成攻击 payload，发送它们，并对响应进行分类。它会生成终端摘要以及 Markdown 和 JSON 报告。**v0.3.0** 版本增强了该 pipeline 的安全性和正确性。
## 快速开始
```
# one-shot
npx vuln-monkey "curl -X POST https://api.example.com/users -H 'Authorization: Bearer tok_xxx' -d '{\"name\":\"test\"}'"
# 或全局安装
npm install -g vuln-monkey
vuln-monkey "curl -X GET https://api.example.com/users/42 -H 'Authorization: Bearer tok_xxx'"
```
默认模型是 `claude-cli`（你本地的 Claude Code CLI）。报告会存放在 `./reports/` 目录中。
使用 OpenAPI 替代 curl：
```
vuln-monkey --spec https://api.example.com/openapi.json \
-H "Authorization: Bearer $API_TOKEN" \
--credential-origin https://api.example.com \
--model openai --concurrency 10
```
## 提供者
使用 `--model` 选择后端（默认：`claude-cli`）。
### CLI 后端（进程内无需 API key）
| 模型 | 要求 |
|:------|:---------|
| `claude-cli` *（默认）* | `PATH` 中的 `claude` CLI |
| `gemini-cli` | `PATH` 中的 `gemini` CLI |
| `codex-cli` | `PATH` 中的 `codex` CLI |
```
vuln-monkey --model gemini-cli "curl https://api.example.com/users"
vuln-monkey --model codex-cli "curl https://api.example.com/users"
```
CLI prompt 会通过 stdin 从一个新创建的临时目录中发送。Claude 会收到一个空的工具列表，Gemini 会收到一个全部拒绝（deny-all）的工具策略，而 Codex 会保持 `--full-auto` 模式，但所有工具功能都会在一个只读的临时 sandbox 中被禁用。
### API 后端
| 模型 | 提供者 | 环境变量 |
|:------|:---------|:----|
| `claude` | Anthropic | `ANTHROPIC_API_KEY` |
| `gemini` | Google Generative AI | `GEMINI_API_KEY` |
| `openai` | 兼容 OpenAI 的 HTTP API | `OPENAI_API_KEY`（可选 `OPENAI_BASE_URL` / `OPENAI_API_BASE`） |
```
ANTHROPIC_API_KEY=sk-... vuln-monkey --model claude "curl https://api.example.com/users"
OPENAI_API_KEY=sk-... vuln-monkey --model openai "curl https://api.example.com/users"
GEMINI_API_KEY=... vuln-monkey --model gemini "curl https://api.example.com/users"
```
### 本地 / 自托管
| 模型 | 默认 base URL | 说明 |
|:------|:-----------------|:------|
| `ollama` | `http://localhost:11434/v1` | 默认模型名称为 `llama3.1` |
| `local` | `http://localhost:1234/v1` | LM Studio, vLLM, llama.cpp server 等 |
两者都使用兼容 OpenAI 的客户端。如果 `OPENAI_BASE_URL` 或 `OPENAI_API_BASE` 指向**本地**主机（`localhost`、`127.*`、`::1`、……），则会使用该 URL 而不是默认 URL。
```
vuln-monkey --model ollama "curl https://api.example.com/users"
OPENAI_BASE_URL=http://localhost:1234/v1 vuln-monkey --model local "curl https://api.example.com/users"
OPENAI_MODEL=qwen3:8b vuln-monkey --model ollama "curl https://api.example.com/users"
```
有效的 `--model` 值：`claude-cli`、`gemini-cli`、`codex-cli`、`claude`、`gemini`、`openai`、`ollama`、`local`。
## 输入
**Curl 命令**（位置参数）—— 解析为 method、URL、headers、body 和 auth：
```
vuln-monkey "curl -X POST https://api.example.com/login -d '{\"user\":\"a\",\"password\":\"b\"}'"
```
**OpenAPI / Swagger JSON** —— 获取远程 JSON spec 并对提取的每个 endpoint 进行模糊测试：
```
vuln-monkey --spec https://api.example.com/openapi.json \
-H "Authorization: Bearer $API_TOKEN" \
--credential-origin https://api.example.com
```
你必须传递一个 curl 字符串**或者** `--spec
`，不能同时传递两者。可以重复使用 `-H` 为 OpenAPI 操作提供凭证或 headers，并通过 `--credential-origin` 显式允许每个接收方；spec 无法将这些凭证重定向到另一台服务器。除非你显式传递 `--allow-private`，否则私有和本地地址会被阻止。
### CLI 选项
| 选项 | 说明 | 默认值 |
|:-------|:------------|:--------|
| `[curl]` | 要进行模糊测试的 Curl 命令 | — |
| `--spec ` | OpenAPI/Swagger JSON spec URL | — |
| `--model ` | LLM 后端（见上文） | `claude-cli` |
| `--output ` | 报告输出目录 | `./reports` |
| `--concurrency ` | 并行请求工作线程，最大为 100 | `5` |
| `--timeout ` | 单次请求超时时间 | `10000` |
| `-H, --header ` | 应用于每个 endpoint 的 header；可重复使用 | — |
| `--credential-origin ` | 允许接收 `-H` 凭证的 origin；可重复使用 | — |
| `--allow-private` | 允许私有/本地的 spec 和目标地址 | off |
| `--fail-on ` | 发现达到或超过指定严重级别的问题时以非零状态退出 | `none` |
| `--dry-run` | 仅生成 payload；不发送请求 | off |
```
vuln-monkey --dry-run "curl https://api.example.com/users"
vuln-monkey --model ollama --timeout 20000 --output ./out "curl -X POST https://api.example.com/login -d '{}'"
```
## 工作原理
1. **解析** —— curl 或 OpenAPI → endpoint 列表（method、URL、headers、body、auth）。
2. **分析** —— LLM 为每个 endpoint 建议潜在的漏洞类型。
3. **生成 payload** —— LLM 构建攻击请求；如果生成失败或未返回任何内容，内置的回退机制会合成常见的探测请求（例如 auth-bypass / mass-assignment 风格的变体）。
4. **执行** —— 同源 payload 在 DNS pinning、可配置的并发量以及端到端 DNS + HTTP 超时的控制下发送（`--dry-run` 会在此步骤之前停止）。
5. **报告** —— 具有证据支持的非通过（non-pass）结果将成为发现（findings）；被阻止或失败的请求将作为未验证项单独报告。
### 输出
- **终端** —— 实时的单条 payload 行输出及摘要（目标、模型、扫描的 endpoint、发送的 payload、发现、风险分数/评级、持续时间）。
- **Markdown** —— `./reports/….md`（或 `--output`）。
- **JSON** —— 用于 CI / 自动化的 `./reports/….json`。
风险评级为 `Fail`、`Needs Attention` 或 `Acceptable`（分数 0–100）其中之一。
对于 CI，请使用 `--fail-on high`（或 `critical`、`medium` 或 `low`）。带有未验证 payload 的不完整扫描也会以非零状态退出。
## 安全与防护
这是一个**安全测试工具**。仅对你获得授权测试的系统运行此工具。
v0.3.0 专注于增强安全性，而不是增加新的攻击面：
- **SSRF 防护**，包含 DNS pinning、全局地址验证以及同源 payload 强制执行
- 通过 `--allow-private` 实现**显式的私有网络同意（opt-in）**
- 在调用模型和写入报告前进行**密钥脱敏**
- 针对 target、OpenAPI spec 以及兼容 OpenAI 的提供者的**响应大小限制**
- **LLM 输出验证**以及针对无 auth 探测的显式标记
- **隔离的 coding-CLI 执行**，使用 stdin prompt 和临时工作目录
此外：解析为敏感系统目录（`/etc`、`/proc`、……）的报告路径会被拒绝；终端输出会清理控制字符。
## 限制
- 结果由 **LLM 驱动** —— 建议和 payload 会因模型而异，可能会遗漏问题或产生无用的噪音。
- OpenAPI 输入当前**仅支持 JSON**，不支持 YAML。
- 查询字符串 API key 方案需要凭证已经存在于 spec 中；`-H` 用于提供 header/cookie 凭证。
- 你需要一个可用的 **CLI 后端、API key 或本地兼容 OpenAI 的服务器**。
- 在将分类和发现视为确认的漏洞之前，需要**人工筛查**。
- 密钥清理涵盖了常见的凭证字段和模式，但任意业务数据可能仍然敏感；请妥善保护生成的报告。
- 回退 payload 是通用的；它们是一个安全兜底措施，不能完全替代优秀的模型输出。
## 环境要求
- Node.js **≥ 20**
- 以下之一：Claude / Gemini / Codex CLI，或 Claude / Gemini / 兼容 OpenAI 的 API key，或本地模型服务器（Ollama, LM Studio, ……）
## 贡献
欢迎在 [github.com/cdbkk/vuln-monkey](https://github.com/cdbkk/vuln-monkey) 提交 Issue 和 PR。
```
git clone https://github.com/cdbkk/vuln-monkey.git
cd vuln-monkey && npm install
npm test
npm run dev -- --help
```
## 许可证
[MIT](LICENSE)标签：AI风险缓解, API安全, CISA项目, DLL 劫持, GNU通用公共许可证, JSON输出, LNA, MITM代理, Node.js, 大语言模型, 安全测试, 攻击性安全, 暗色界面, 自动化攻击