LeoMartinezTAMUK/mcp-strike
GitHub: LeoMartinezTAMUK/mcp-strike
MCP-Strike 是一款针对 MCP 服务器的运行时主动对抗安全扫描器，通过真实攻击探测、LLM 评判和自适应代理帮助开发者发现自建 MCP 服务器中的安全漏洞。
Stars: 0 | Forks: 0
# MCP-Strike
**针对 MCP 服务器的运行时主动对抗测试：将其指向你自己的服务器，看看哪里会出问题。**
大多数现有的 MCP 扫描器会以*静态*方式读取工具描述和配置。MCP-Strike 会连接到一个活跃的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，对实际的工具接口发起一系列真实的攻击，观察返回的结果，并（可选地）使用 LLM-as-judge 和基于 LLM 的自适应代理来为每个发现进行评分。
它的切入点在于：这是一款实用、*主动*且由个人开发者开发的工具，专为那些构建自己的 MCP 服务器、只想得到“把它指向我的服务器，告诉我哪里有问题”这一答案的开发者而设计。企业级供应商面向的是安全团队；学术基准测试是为了发表论文；而这款工具是为你准备的。
## 快速开始
```
pip install mcp-strike # or: uvx mcp-strike demo
mcp-strike demo
```
就是这样。`demo` 会启动一个内置的、故意留有漏洞的 MCP 服务器，对其进行扫描，并打印出一份彩色报告。不需要任何密钥（只有当你设置了 `OPENAI_API_KEY` 时，LLM 功能才会自动启用）。
## 你能得到什么
一次典型的 `mcp-strike demo --no-judge --no-agent` 运行：
```
╭────────────────────── Responsible use ──────────────────────╮
│ MCP-Strike is a defensive tool for testing MCP servers you │
│ own. Running it against systems you don't control may be │
│ illegal in your jurisdiction. See the "Responsible use" │
│ section of this README for the full note. │
╰─────────────────────────────────────────────────────────────╯
Scan summary: 29 check(s) ran. 5 SUCCESS, 2 UNCERTAIN, 22 FAILURE
┏━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳──────────────────────────────────────┓
┃ Verdict ┃ Stage ┃ Attack ┃ Tool ┃ Rationale ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇──────────────────────────────────────┩
│ SUCCESS │ metadata │ description_prompt_injection │ get_weather │ Description contains 2 known │
│ │ │ │ │ prompt-injection markers. │
│ SUCCESS │ metadata │ overreaching_parameters │ submit_feedback │ Tool requests 'user_password', │
│ │ │ │ │ 'api_key'. │
│ SUCCESS │ parameters │ path_traversal_probe │ read_file │ Tool returned /etc/passwd content │
│ │ │ │ │ for traversal payload. │
│ SUCCESS │ response │ data_exfiltration_probe │ fetch_status │ Response matched 3 exfiltration │
│ │ │ │ │ patterns. │
│ SUCCESS │ response │ response_injection_probe │ get_news │ Response contains 2 injection │
│ │ │ │ │ markers. │
│ UNCERTAIN │ response │ data_exfiltration_probe │ read_file │ Tool errored on benign input; │
│ │ │ │ │ cannot probe normal behavior. │
│ UNCERTAIN │ response │ response_injection_probe │ read_file │ Tool errored on benign input; │
│ │ │ │ │ cannot probe normal behavior. │
└───────────┴────────────┴──────────────────────────────┴─────────────────┴──────────────────────────────────────┘
```
为了提高可读性，默认情况下会隐藏 `FAILURE` 行；传入 `--show-all` 也可以查看通过的检查。
## 工作原理
扫描分为三层运行，优先运行成本最低的：
1. **确定性静态攻击** 会扫描工具接口以查找已知的恶意模式。零成本，速度快。
2. **LLM judge**（可选）会审查每个发现，并进行确认或驳回。成本低（默认为 gpt-4o-mini），每次运行有上限限制。
3. **自适应 LLM 代理**（可选）通过多轮推理探测每个工具，寻找静态模式无法发现的问题。
v0.1 版本内置了五种静态攻击，根据它们所针对的 MCP 流水线阶段进行分类：
| 攻击 | 阶段 | 是否主动? | 捕获内容 |
|---|---|---|---|
| `description_prompt_injection` | metadata | passive | 带有针对调用 LLM 的注入标记的工具描述 |
| `overreaching_parameters` | metadata | passive | 其 schema 要求提供 `password`、`api_key`、`ssn` 等的工具 |
| `path_traversal_probe` | parameters | **active** | 将字符串参数作为文件系统路径处理的工具（发送 `../../etc/passwd`） |
| `response_injection_probe` | response | **active** | 响应中包含针对调用 LLM 的注入内容的工具 |
| `data_exfiltration_probe` | response | **active** | 响应中诱导 LLM 向某个接收端 POST/发送数据的工具 |
**自适应代理** 是它的核心差异点：给定工具接口后，LLM 会提出 payload，观察响应，并针对每个工具最多进行 3 轮迭代。它可以捕获那些静态启发式方法无法提前枚举的社会工程学和异常注入模式。
## 配置 LLM 功能（可选）
judge 和代理默认是关闭的；一旦检测到可用的 `OPENAI_API_KEY`，它们就会自动启用，无论该变量是通过 shell export 设置的，还是存放在仓库根目录的 `.env` 文件中。
```
# Option A：shell export
export OPENAI_API_KEY=sk-...
# Option B：.env file（已被 gitignore；会被 CLI 自动加载）
echo 'OPENAI_API_KEY=sk-...' > .env
mcp-strike demo # judge + agent both run
```
关于优先级的注意事项：通过 shell export 的变量始终优先于 `.env`。如果你希望 `.env` 优先，请先在 shell 中 `unset` 该变量。
## 所有 CLI 参数
运行 `mcp-strike --help`、`mcp-strike scan --help` 或 `mcp-strike demo --help` 查看完整的各命令详情。最常用的参数：
**全局参数**
| 参数 | 效果 |
|---|---|
| `--version` / `-V` | 打印已安装的版本并退出。 |
**扫描形态**（适用于 `scan` 和 `demo`）
| 参数 | 效果 |
|---|---|
| `--only NAME` | 仅运行指定名称的攻击（可重复使用）。识别特殊名称 `adaptive_agent`。 |
| `--call-timeout SECONDS` | 每次 MCP 调用的超时时间（默认为 30）。存在缺陷或恶意的服务器无法在此时间之外阻塞扫描。 |
| `--show-all` | 在终端报告中包含 FAILURE 行（默认隐藏）。 |
| `--notice` / `--no-notice` | 在启动时打印负责任使用声明（默认开启，仅限终端模式）。 |
| `--json` | 将 JSON 输出到 stdout，而不是显示终端表格。屏蔽启动声明。 |
| `--output-file PATH` | 将 JSON 报告写入文件。隐含 `--json`。 |
**LLM judge**
| 参数 | 效果 |
|---|---|
| `--judge` / `--no-judge` | 强制开启/关闭 judge。默认：自动，仅在设置了 `OPENAI_API_KEY` 时启用。 |
| `--judge-model NAME` | 覆盖默认的 judge 模型（`gpt-4o-mini`）。 |
| `--max-llm-calls N` | 每次运行中实际的 judge LLM 调用上限（默认为 20）。 |
**自适应代理**
| 参数 | 效果 |
|---|---|
| `--agent` / `--no-agent` | 强制开启/关闭代理。默认：自动，仅在设置了 `OPENAI_API_KEY` 时启用。 |
| `--agent-model NAME` | 覆盖默认的代理模型（`gpt-4o-mini`）。 |
| `--agent-max-rounds N` | 针对每个工具的代理轮次上限（默认为 3）。 |
| `--max-agent-calls N` | 每次运行中实际的代理 LLM 调用上限（默认为 50）。 |
## 扫描你自己的 MCP 服务器
```
# Stdio transport（v0.1 唯一支持的传输方式；HTTP 将在后续版本中推出）
mcp-strike scan --command python --arg -m --arg your_mcp_server
mcp-strike scan --command /path/to/your-server --arg --port --arg 8080
```
`--arg` 是可重复使用的；分别传入每个参数，以确保引号生效。
## 用于 CI 的 JSON 输出
```
mcp-strike demo --json --no-notice --output-file scan.json
```
稳定的 schema，适合用于 CI 流水线。顶层结构：
```
{
"summary": {
"total": 29,
"success": 5,
"uncertain": 2,
"failure": 22,
"llm_calls_used": 7, // null when judge didn't run
"llm_calls_cap": 20,
"agent_calls_used": null, // null when agent didn't run
"agent_calls_cap": null
},
"results": [
{
"attack_name": "description_prompt_injection",
"stage": "metadata",
"target_tool": "get_weather",
"verdict": "success",
"rationale": "...",
"evidence": { "...": "..." },
"judge": {
"verdict": "success",
"rationale": "...",
"model": "gpt-4o-mini",
"ran": true
}
}
]
}
```
即使存在漏洞发现，退出代码也为 0；CI 使用者可以自行决定什么样的判定结果才算作构建失败。
## 架构概览
| 模块 | 职责 |
|---|---|
| `mcp_strike.client` | 基于官方 `mcp` SDK 的 Stdio transport 封装 |
| `mcp_strike.target` | 标准化的 `Target` 适配器（攻击所消费的对象） |
| `mcp_strike.attacks` | `BaseAttack` ABC + 装饰器注册表 + 5 种具体的攻击 |
| `mcp_strike.judge` | LLM-as-judge 层（NullJudge 空操作 + OpenAIJudge） |
| `mcp_strike.agent` | LLM 驱动的自适应攻击者 |
| `mcp_strike.report` | 渲染器：终端（`rich`）+ JSON |
| `mcp_strike.config` | `pydantic` 配置模型 + `.env` 加载器 |
| `mcp_strike.cli` | 带有 `scan` / `list-attacks` / `demo` 的 `typer` 入口点 |
| `mcp_strike.demo_server` | 内置的包含 6 个植入漏洞的脆弱目标 |
请参阅 [`ROADMAP.md`](ROADMAP.md) 了解已发布的功能和后续计划。
## 开发
需要 Python 3.10+ 和 [`uv`](https://docs.astral.sh/uv/)。
```
git clone https://github.com/LeoMartinezTAMUK/mcp-strike.git
cd mcp-strike
uv sync --extra dev
uv run ruff check . # lint
uv run mypy src/mcp_strike # type-check
uv run pytest -v --cov # tests + coverage report
uv run mcp-strike demo # eyeball the scan output
```
## 状态与路线图
目前处于 **0.1.0 / alpha** 阶段。CI 在 Python 3.10 到 3.13 的环境中通过 `ruff` + `mypy` + `pytest` 进行检查；生产源码的代码行覆盖率约为 96%。请参阅 [`ROADMAP.md`](ROADMAP.md) 了解后续计划。
## 负责任地使用
MCP-Strike 是一款防御性工具，用于测试你拥有或被明确授权测试的 MCP 服务器。**它不是用于攻击第三方基础设施的武器。** 在你无法控制的系统上运行它可能在你所在的司法管辖区属于违法行为，这不是其所支持的用例。CLI 在启动时会打印负责任使用声明；一旦你在内化该声明后，可以通过 `--no-notice` 在脚本编写时屏蔽它。
如果你在使用此工具时发现了他人服务器中的漏洞，请遵循负责任的披露原则：在发布详细信息之前，私下联系该服务器的运营者。
如需报告 MCP-Strike 本身的安全问题（而非第三方服务器的问题），请参阅 [`SECURITY.md`](SECURITY.md)。
## 联系方式
由 **Leo Martinez III** 构建和维护。
- 邮箱：[mtz3.leo@gmail.com](mailto:mtz3.leo@gmail.com)
- LinkedIn：[linkedin.com/in/leo-martinez-iii](https://www.linkedin.com/in/leo-martinez-iii/)
- GitHub：[@LeoMartinezTAMUK](https://github.com/LeoMartinezTAMUK)
有关 MCP-Strike 本身的安全问题，请参阅 [`SECURITY.md`](SECURITY.md)。如需提交 Bug 报告和功能请求，[问题追踪器](https://github.com/LeoMartinezTAMUK/mcp-strike/issues) 是最快的途径。至于其他事宜，使用上面的邮箱和 LinkedIn 均可。
标签：AI安全, Chat Copilot, CISA项目, DLL 劫持, MCP, Petitpotam, 大语言模型, 安全规则引擎, 逆向工具