内容
# MCP Shield
[](https://www.python.org/)
[](https://github.com/rob925/mcp-shield/actions/workflows/ci.yml)
[](LICENSE)
[](https://modelcontextprotocol.io/)
模型上下文协议服务器、工具、提示和 AI 代理项目的静态安全扫描器。MCP Shield 帮助您在生产前捕获明显的危险部分：泄露的机密、shell 执行、风险工具描述、提示注入文本和 CI 破坏安全回归。
```bash
mcp-scan .
```
```text
[HIGH] code.shell_true server.py:42
Shell 执行已启用。
subprocess.run(cmd, shell=True)
[CRITICAL] secret.literal .env:1
可能的硬编码机密。
OPENAI_API_KEY="sk-..."
```
## 为什么使用 MCP Shield
MCP 服务器通常暴露强大的功能：文件系统访问、shell 命令、网络调用、凭证、浏览器自动化、数据库和内部工具。
这正是小错误变成昂贵的地方：
- 工具描述鼓励不安全行为
- 测试密钥成为真正的泄露令牌
- 代理可以调用具有用户控制输入的 shell 命令
- 提示或资源包含注入文本
- CI 没有针对 MCP 特定风险的安全门控
MCP Shield 是简单有效的一线防御：快速静态检查、有用的输出和风险超过阈值时的非零退出代码。
## 功能
- 作为 CLI 和 MCP 服务器运行
- 基于官方 MCP Python SDK 构建
- CI 友好的严重性门控
- 文本、JSON、Markdown 和 SARIF 输出
- 具有规则 ID 的内联抑制
- `.mcp-scan-ignore` 用于固定和故意演示
## 它能发现什么
| 风险 | 示例 |
| --- | --- |
| 硬编码机密 | API 密钥、令牌、密码、私钥 |
| 进程执行 | `subprocess`、`child_process`、`shell=True` |
| MCP 工具风险 | 命名或描述为删除、shell、令牌、机密、文件系统的工具 |
| 环境访问 | `os.environ`、`process.env` |
| 提示注入文本 | "忽略以前的指令"、系统提示泄露短语 |
## 安装
从本地检出：
```bash
pip install .
```
在不安装的情况下运行：
```bash
python -m mcp_security_scanner.cli .
```
## MCP 服务器
以 stdio MCP 服务器运行 MCP Shield：
```bash
mcp-shield-server
```
可用工具：
- `scan_path_tool` - 扫描本地 MCP 服务器或代理项目
- `list_rules` - 列出规则 ID 和描述
示例 Claude Desktop 样式命令：
```json
{
"mcpServers": {
"mcp-shield": {
"command": "mcp-shield-server"
}
}
}
```
## 用法
```bash
mcp-scan .
mcp-scan path/to/mcp-server
mcp-scan . --format json
mcp-scan . --format markdown --output mcp-security-report.md
mcp-scan . --format sarif --output mcp-shield.sarif
mcp-scan . --fail-on medium
```
格式：
- `text` 用于人类
- `json` 用于自动化
- `markdown` 用于 PR 评论和报告
- `sarif` 用于 GitHub 代码扫描
严重性门控：
- `low`
- `medium`
- `high`
- `critical`
`--fail-on high` 在存在高风险或关键发现时退出，返回代码 `1`。
## 忽略文件
在扫描目录中创建 `.mcp-scan-ignore`:
```gitignore
tests/
fixtures/
examples/unsafe-demo.py
```
将其用于故意固定的演示。不要使用它来隐藏生产风险。
## 抑制
在同一行抑制已审查的发现：
```py
subprocess.run(cmd) # mcp-shield: ignore code.subprocess
```
仅对测试固定使用 `all`:
```py
subprocess.run(cmd, shell=True) # mcp-shield: ignore all
```
## 示例
扫描故意不安全的示例：
```bash
python -m mcp_security_scanner.cli examples/unsafe-mcp-server --fail-on critical
```
## GitHub Actions
```yaml
name: MCP 安全扫描
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install .
- run: mcp-scan . --fail-on high
```
## 路线图
- 面向 Python 和 TypeScript 服务器的 MCP SDK 感知解析
- 面向企业 MCP 服务器的安全默认规则包
- 特定于提示/资源的注入检查
- 用于 `pipx install mcp-shield` 的 PyPI 发布
## 仓库主题
添加这些 GitHub 主题以便发现：
```text
mcp, model-context-protocol, ai-agents, security, security-tools, scanner, devtools, llm, prompt-injection, static-analysis
```
GitHub 建议使用仓库主题，因为它们帮助人们通过目的和主题区域发现和贡献项目。
## 范围
MCP Shield 是一个静态启发式扫描器。它可以及早发现常见风险，但它不是完整的安全审计。
## 帮助它成长
MCP 安全正在快速发展。现在最有用的贡献是现实世界中不安全的 MCP 示例、低噪声检测规则和 CI 集成。
如果 MCP Shield 捕获了有用的内容，请点亮仓库，以便更多的 MCP 构建者可以找到它。
