内容
# 模型安全MCP
恶意或不安全的机器学习模型构件是一个现实的供应链问题。已经有真实的案例表明，在野外发现了恶意或可疑的模型，包括托管在公共平台上的模型和较大批次的不安全AI/ML构件。参见 [RL识别Hugging Face上托管的恶意ML模型](https://www.reversinglabs.com/blog/rl-identifies-malware-ml-model-hosted-on-hugging-face) 和 [在Hugging Face上发现超过100个恶意AI/ML模型](https://thehackernews.com/2024/03/over-100-malicious-aiml-models-found-on.html)。
其中一个重要的原因是反序列化风险。许多模型格式，尤其是基于pickle和特定框架的格式，在加载或重建时可以执行代码或调用不安全的逻辑。这意味着模型文件可以成为执行向量，而不仅仅是一个被动的权重块。
`model-safety` 是一个用于在加载、运输或信任机器学习模型构件之前进行检查的MCP服务器。
它旨在进行实际分类：
- 扫描本地模型文件
- 扫描可下载的模型URL
- 分类整个目录的构件
- 将启发式检查与专用扫描器结合
- 返回规范化的发现结果和具体的下一步行动
## 功能
服务器目前提供了这些工具：
- `available_scanners`
显示已安装并准备就绪的扫描器后端。
- `artifact_safety_report`
对单个模型构件运行最广泛的扫描，并返回每个扫描器的结果、规范化的发现结果、最高严重性级别和推荐的行动。
- `modelscan_scan`
直接对本地文件或URL运行ModelScan。
- `picklescan_scan`
直接对本地文件或URL运行PickleScan。
- `deep_model_inspect`
运行轻量级结构检查，检查风险扩展、嵌入的pickle成员和可疑的打包模式。
- `scan_directory`
对目录中的每个文件运行`artifact_safety_report`，并聚合风险文件。
## 快速入门
1. 使用此仓库中的本地Python运行时将MCP服务器添加到Cursor或Claude Code。
2. 从本地文件或直接URL开始使用`artifact_safety_report`。
3. 查看`normalized_findings`、`highest_severity`和`recommended_actions`。
4. 当需要分类整个模型文件时，使用`scan_directory`。
最小Cursor配置：
```json
{
"mcpServers": {
"model-safety": {
"type": "stdio",
"command": "C:/Users/Lenovo/Documents/ModelSafetyMCP/python312/python.exe",
"args": ["C:/Users/Lenovo/Documents/ModelSafetyMCP/run_server.py"]
}
}
}
```
## 当前检测能力
该MCP在扫描以下内容时最为强大：
- PyTorch检查点，例如`.pt`和`.pth`
- 类似pickle的构件，例如`.pkl`、`.pickle`和`.joblib`
- Keras和TensorFlow HDF5模型，例如`.h5`
- 实际上是ZIP或TAR容器的模型包
它目前结合了：
- `modelscan`
最佳通用后端，尤其是针对Keras `Lambda`等特定模型的不安全模式。
- `picklescan`
针对pickle导向构件的最佳支持后端。
- `deep_model_inspect`
快速启发式回退，当专用扫描器静默时，可以捕获风险打包。
## 支持的输入
您可以扫描：
- 本地文件系统路径
- 直接`http`或`https`构件URL
对于Hugging Face，请使用直接文件URL：
- 良好：`https://huggingface.co/<repo>/resolve/main/model.h5`
- 不理想：`https://huggingface.co/<repo>/blob/main/model.h5`
`blob` URL通常返回HTML页面，而`resolve` URL返回实际的构件字节。
## 运行时
此仓库包括[`python312`](C:/Users/Lenovo/Documents/ModelSafetyMCP/python312)中的本地Python 3.12运行时。该运行时得到支持，因为它适用于：
- `mcp`
- `modelscan`
- `picklescan`
- `h5py`
如果您需要手动重建该运行时：
```bash
python312\python.exe -m pip install mcp picklescan modelscan h5py
```
## 启动服务器
使用以下命令启动MCP服务器：
```bash
python312\python.exe run_server.py
```
启动器是存储库本地的，并使用此项目中已经捆绑的运行时。
## Cursor设置
在Cursor MCP设置中添加服务器：
- 名称：`model-safety`
- 类型：`stdio`
- 命令：`C:/Users/Lenovo/Documents/ModelSafetyMCP/python312/python.exe`
- 参数：`C:/Users/Lenovo/Documents/ModelSafetyMCP/run_server.py`
等效JSON：
```json
{
"mcpServers": {
"model-safety": {
"type": "stdio",
"command": "C:/Users/Lenovo/Documents/ModelSafetyMCP/python312/python.exe",
"args": ["C:/Users/Lenovo/Documents/ModelSafetyMCP/run_server.py"]
}
}
}
```
复制粘贴示例也位于[`cursor.mcp.example.json`](C:/Users/Lenovo/Documents/ModelSafetyMCP/cursor.mcp.example.json)。
## Claude Code设置
使用以下命令添加服务器：
```bash
claude mcp add model-safety -- C:/Users/Lenovo/Documents/ModelSafetyMCP/python312/python.exe C:/Users/Lenovo/Documents/ModelSafetyMCP/run_server.py
```
## 工作流程
### 1. 确认服务器已连接
在您的MCP客户端中，询问：
```text
使用model-safety MCP服务器中的available_scanners
```
您应该看到已安装的后端，包括`modelscan`和`picklescan`。
### 2. 从广泛的报告开始
对于本地文件：
```text
使用artifact_safety_report，路径="C:/path/to/model.pth"
```
对于直接URL：
```text
使用artifact_safety_report，网址="https://example.com/model.h5"
```
这是单个构件扫描的默认入口。
### 3. 阅读规范化的发现结果
`artifact_safety_report` 返回：
- 原始的每个扫描器的输出
- `normalized_findings`
- `highest_severity`
- `finding_count`
- `recommended_actions`
这意味着该工具对于详细调查和快速决策都很有用。
### 4. 根据需要深入调查
使用：
- `modelscan_scan` 当您想要专用ModelScan输出时
- `picklescan_scan` 当您想要pickle特定细节时
- `deep_model_inspect` 当您想要轻量级打包和存档启发式时
### 5. 批量分类文件夹
如果您有一整批模型：
```text
使用scan_directory，路径="C:/path/to/model-folder"
```
这将返回：
- 聚合的规范化发现结果
- 目录级最高严重性
- `risky_files` 用于快速优先级排序
- 每文件嵌套报告
`scan_directory` 最适用于主要包含模型构件的文件夹，而不是通用源代码。
## 示例
### 示例：可疑的PyTorch检查点
```text
使用artifact_safety_report，路径="C:/Users/Lenovo/Documents/ModelSafetyMCP/credit-risk-pytorch-v1.1.pth"
```
典型结果形状：
- 风险扩展`.pth`
- 存档中嵌入的pickle成员
- 推荐在审查前避免受信任的加载
### 示例：来自Hugging Face的可疑Keras模型
```text
使用artifact_safety_report，网址="https://huggingface.co/MrKrauzer/FacenetRetweeted/resolve/main/facenet-retrained.h5"
```
典型结果形状：
- 风险扩展`.h5`
- ModelScan `H5LambdaDetectScan` 发现
- 建议在反序列化前检查Keras `Lambda`层
## 输出理念
服务器将扫描器视为互补的：
- `modelscan` 是主要的后端
- `picklescan` 是专门的后端
- `deep_model_inspect` 是快速的结构性回退
服务器还生成规范化的发现结果，而不仅仅是让用户解释每个工具：
- `scanner`
- `severity`
- `category`
- `evidence`
- `source`
- `recommended_action`
## 限制
该工具帮助分类风险。 它并不证明模型是安全的。
重要的限制：
- 一些格式的覆盖范围比其他格式更好
- 清洁扫描并不保证无害行为
- 远程URL扫描取决于URL指向实际的构件字节
- 目录扫描是字面的，对于非模型文件夹可能会很吵
- 模型行为风险与序列化风险和打包风险不同
## 开发
快速验证：
```bash
python312\python.exe -m compileall src run_server.py
```
