内容
# 安全模型上下文协议服务器（SecMCP）
MCP服务器暴露安全操作工具（VirusTotal、MITRE Caldera、LimaCharlie）给AI代理，具有深度防御安全控制。为SANS SEC598课程由Scott Thornton构建。
**3个服务器，20个工具，7个资源，153个测试。** 默认情况下，所有写入/破坏性操作均被禁用，并具有故障关闭安全控制。
<p align="center">
<img src="docs/images/secmcp-demo.png" alt="SecMCP终端演示" width="700">
</p>
## 背景
[模型上下文协议](https://modelcontextprotocol.io/)（MCP）是连接AI代理与外部工具和数据源的开放标准。SecMCP填补了AI安全工具生态系统的一个空白：没有已发布的MCP服务器用生产级安全控制包装常见的安全操作平台。
每个服务器都包装了一个安全平台的REST API，并将其公开为MCP工具，具备以下功能：
- **输入验证**：所有参数（哈希、IP地址、UUID、技术ID）
- **审计日志**：自动敏感值删除
- **MCP工具注释**：声明每个工具的读/写/破坏性
- **每工具启用标志** 和 **干运行模式** 用于写入/破坏性操作
## 仓库布局
```
secmcp/
├── packages/
│ ├── secmcp-shared/ # 薄共享库（配置、错误、审计）
│ ├── secmcp-virustotal/ # 6个工具 — 威胁情报查找 + 文件提交
│ ├── secmcp-caldera/ # 7个工具 — 对手仿真，具有6层安全保护
│ └── secmcp-limacharlie/ # 7个工具 — EDR传感器，D&R规则，YARA扫描
├── tests/ # 所有软件包和MCP协议合规性测试，共153个测试
├── docs/
│ ├── architecture.md # 系统设计和原则
│ ├── security-guide.md # 威胁模型和安全控制
│ └── servers/ # 每服务器工具参考
├── .github/workflows/ci.yml # GitHub Actions：lint、格式、测试
├── .env.example # 所有配置变量，安全默认值
└── pyproject.toml # uv工作区根目录
```
## 服务器
| 服务器 | 平台 | 工具 | 安全控制 |
|--------|----------|-------|-----------------|
| `secmcp-virustotal` | VirusTotal API v3 | 6（5读，1写） | 速率限制器（免费层4请求/分钟） |
| `secmcp-caldera` | MITRE Caldera | 7（5读，1写，1破坏） | 每工具标志，组允许列表，干运行，审计 |
| `secmcp-limacharlie` | LimaCharlie EDR | 7（4读，2写，1破坏） | 每工具标志，干运行，JWT身份验证 |
## 快速入门
**1. 克隆和安装**
```bash
git clone https://github.com/scthornton/secmcp.git
cd secmcp
uv sync --all-packages
```
**2. 配置**
```bash
cp .env.example .env
# 编辑.env文件，填写您的API密钥
```
**3. 运行测试**
```bash
uv run pytest tests/ -v
```
**4. 添加到Claude Code**
```bash
# VirusTotal服务器
export SECMCP_VT_VT_API_KEY="您的密钥"
claude mcp add virustotal -- uv run python -m secmcp_virustotal
# Caldera服务器（安全默认值：干运行开启，所有写工具禁用）
export SECMCP_CALDERA_CALDERA_API_KEY="您的密钥"
claude mcp add caldera -- uv run python -m secmcp_caldera
# LimaCharlie服务器（安全默认值：干运行开启，所有写工具禁用）
export SECMCP_LC_LC_OID="您的组织ID"
export SECMCP_LC_LC_API_KEY="您的密钥"
claude mcp add limacharlie -- uv run python -m secmcp_limacharlie
```
**5. 添加到Claude Desktop**
添加到`~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"secmcp-virustotal": {
"command": "uv",
"args": ["run", "--project", "/path/to/secmcp", "python", "-m", "secmcp_virustotal"],
"env": {
"SECMCP_VT_VT_API_KEY": "您的密钥"
}
},
"secmcp-caldera": {
"command": "uv",
"args": ["run", "--project", "/path/to/secmcp", "python", "-m", "secmcp_caldera"],
"env": {
"SECMCP_CALDERA_CALDERA_URL": "http://localhost:8888",
"SECMCP_CALDERA_CALDERA_API_KEY": "您的密钥",
"SECMCP_CALDERA_DRY_RUN": "true",
"SECMCP_CALDERA_ENABLE_CREATE_OPERATION": "false",
"SECMCP_CALDERA_ENABLE_EXECUTE_ABILITY": "false",
"SECMCP_CALDERA_ALLOWED_GROUPS_STR": ""
}
},
"secmcp-limacharlie": {
"command": "uv",
"args": ["run", "--project", "/path/to/secmcp", "python", "-m", "secmcp_limacharlie"],
"env": {
"SECMCP_LC_LC_OID": "您的组织ID",
"SECMCP_LC_LC_API_KEY": "您的密钥",
"SECMCP_LC_DRY_RUN": "true",
"SECMCP_LC_ENABLE_DEPLOY_RULE": "false",
"SECMCP_LC_ENABLE_DELETE_RULE": "false",
"SECMCP_LC_ENABLE_YARA_SCAN": "false"
}
}
}
}
```
## 安全控制
Caldera和LimaCharlie服务器实现了独立的、可组合的安全层：
| 层 | 描述 | 默认值 |
|-------|-------------|---------|
| **每工具启用标志** | 必须显式启用每个写入/破坏工具 | 禁用 |
| **组允许列表**（Caldera） | 操作只能针对列出的代理组 | 空 = 所有阻止 |
| **干运行模式** | 写入工具描述它们将执行的操作，而不实际执行 | 启用 |
| **输入验证** | UUID、paw ID、技术ID、组名、规则名验证 | 始终开启 |
| **审计日志** | JSON日志，带有删除的参数，破坏工具的完整输出 | 始终开启 |
| **MCP工具注释** | `destructiveHint=True` 在AI客户端中触发人工确认 | 始终开启 |
所有安全默认值都是**故障关闭**的。未配置的服务器会阻止所有写入操作。
## 架构
```
AI主机（Claude Code / Claude Desktop / Cursor）
|
| MCP协议（stdio传输）
|
+-- secmcp-virustotal --> VirusTotal API v3（HTTPS，API密钥头）
+-- secmcp-caldera --> Caldera REST API（HTTP，KEY头）
+-- secmcp-limacharlie --> LimaCharlie API（HTTPS，JWT交换）
|
+-- secmcp-shared（配置、错误、审计）
```
## 技术栈
- **Python 3.12+**，使用`uv`工作区进行单体仓库管理
- **MCP SDK**（`mcp` 1.16+），使用FastMCP进行高级工具/资源注册
- **httpx**，用于异步HTTP客户端，**Pydantic v2**，用于模型和配置
- **pytest** + **respx**，用于异步测试和模拟的HTTP响应
- **ruff**，用于代码检查和格式化
## 重要注意事项
- **仅stdio传输**（v1）— 服务器作为MCP主机的子进程运行。计划在v2中支持HTTP传输和OAuth 2.1。
- **环境变量中的API密钥** — 绝不提交到仓库中。复制`.env.example`到`.env`并填写您的值。
- **速率限制** — VirusTotal免费层允许4个请求/分钟。服务器会自动强制执行此限制。
- **Caldera必须运行** 在本地（默认：`http://localhost:8888`），Caldera服务器才能连接。
## 贡献
1. 分叉仓库
2. 创建一个功能分支（`git checkout -b feature/my-feature`）
3. 运行测试（`uv run pytest tests/ -v`）和代码检查（`uv run ruff check packages/ tests/`）
4. 提交拉取请求
## 许可证
MIT — 请参阅[LICENSE](LICENSE)了解详情。
---
## 联系方式
**Scott Thornton** — AI安全研究员
- 网站：[perfecxion.ai](https://perfecxion.ai/)
- 电子邮件：[scott@perfecxion.ai](mailto:scott@perfecxion.ai)
- LinkedIn：[linkedin.com/in/scthornton](https://www.linkedin.com/in/scthornton)
- ORCID：[0009-0008-0491-0032](https://orcid.org/0009-0008-0491-0032)
- GitHub：[@scthornton](https://github.com/scthornton)
**安全问题**：请通过[SECURITY.md](SECURITY.md)报告。
