promptfoo/modelaudit
GitHub: promptfoo/modelaudit
AI 模型文件静态安全扫描器，在部署前检测恶意代码、后门和敏感信息泄露，无需加载执行模型。
Stars: 35 | Forks: 6
# ModelAudit
**在部署前保障您的 AI 模型安全。** 静态扫描器，用于检测 ML 模型文件中的恶意代码、后门和安全漏洞 —— 无需加载或执行它们。
[](https://pypi.org/project/modelaudit/)
[](https://pypi.org/project/modelaudit/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/promptfoo/modelaudit/blob/main/LICENSE)
**[完整文档](https://www.promptfoo.dev/docs/model-audit/)** | **[使用示例](https://www.promptfoo.dev/docs/model-audit/usage/)** | **[支持的格式](https://www.promptfoo.dev/docs/model-audit/scanners/)**
## 快速开始
**需要 Python 3.10+**
```
pip install modelaudit[all]
# 扫描文件或目录
modelaudit model.pkl
modelaudit ./models/
# 为 CI/CD 导出结果
modelaudit model.pkl --format json --output results.json
```
```
$ modelaudit suspicious_model.pkl
Files scanned: 1 | Issues found: 2 critical, 1 warning
1. suspicious_model.pkl (pos 28): [CRITICAL] Malicious code execution attempt
Why: Contains os.system() call that could run arbitrary commands
2. suspicious_model.pkl (pos 52): [WARNING] Dangerous pickle deserialization
Why: Could execute code when the model loads
```
## 检测内容
- **代码执行攻击**：位于 Pickle、PyTorch、NumPy 和 Joblib 文件中
- **模型后门**：包含隐藏功能或可疑权重模式
- **嵌入的敏感信息**：模型权重或元数据中的 API key、token 和凭证
- **网络指标**：可能导致数据泄露的 URL、IP 和 socket 用法
- **压缩包漏洞**：ZIP/TAR/7z 文件中的路径遍历、符号链接攻击
- **不安全的 ML 操作**：Lambda 层、自定义 ops、TorchScript/JIT、模板注入
- **供应链风险**：篡改、许可证违规、可疑配置
## 支持的格式
ModelAudit 包含涵盖模型、压缩包和配置格式的专用扫描器：
| 格式 | 扩展名 | 风险等级 |
| ----------------------- | ------------------------------------- | ------ |
| **Pickle** | `.pkl`, `.pickle`, `.dill` | HIGH |
| **PyTorch** | `.pt`, `.pth`, `.ckpt`, `.bin` | HIGH |
| **Joblib** | `.joblib` | HIGH |
| **NumPy** | `.npy`, `.npz` | HIGH |
| **R Serialized** | `.rds`, `.rda`, `.rdata` | HIGH |
| **TensorFlow** | `.pb`, `.meta`, SavedModel 目录 | MEDIUM |
| **Keras** | `.h5`, `.hdf5`, `.keras` | MEDIUM |
| **ONNX** | `.onnx` | MEDIUM |
| **CoreML** | `.mlmodel` | LOW |
| **MXNet** | `*-symbol.json`, `*-NNNN.params` | LOW |
| **NeMo** | `.nemo` | MEDIUM |
| **CNTK** | `.dnn`, `.cmf` | MEDIUM |
| **RKNN** | `.rknn` | MEDIUM |
| **Torch7** | `.t7`, `.th`, `.net` | HIGH |
| **CatBoost** | `.cbm` | MEDIUM |
| **XGBoost** | `.bst`, `.model`, `.ubj` | MEDIUM |
| **LightGBM** | `.lgb`, `.lightgbm`, `.model` | MEDIUM |
| **Llamafile** | `.llamafile`, 无扩展名, `.exe` | MEDIUM |
| **TorchServe** | `.mar` | HIGH |
| **SafeTensors** | `.safetensors` | LOW |
| **GGUF/GGML** | `.gguf`, `.ggml` | LOW |
| **JAX/Flax** | `.msgpack`, `.flax`, `.orbax`, `.jax` | LOW |
| **TFLite** | `.tflite` | LOW |
| **ExecuTorch** | `.ptl`, `.pte` | LOW |
| **TensorRT** | `.engine`, `.plan` | LOW |
| **PaddlePaddle** | `.pdmodel`, `.pdiparams` | LOW |
| **OpenVINO** | `.xml` | LOW |
| **Skops** | `.skops` | HIGH |
| **PMML** | `.pmml` | LOW |
| **Compressed Wrappers** | `.gz`, `.bz2`, `.xz`, `.lz4`, `.zlib` | MEDIUM |
此外，还支持 ZIP、TAR、7-Zip、OCI layers、Jinja2 模板、JSON/YAML 元数据、manifest 以及文本文件的扫描器。
[查看完整格式文档](https://www.promptfoo.dev/docs/model-audit/scanners/)
## 远程来源
直接从远程仓库和云存储扫描模型：
```
# Hugging Face
modelaudit https://huggingface.co/gpt2
modelaudit hf://microsoft/DialoGPT-medium
# 云存储
modelaudit s3://bucket/model.pt
modelaudit gs://bucket/models/
# MLflow registry
modelaudit models:/MyModel/Production
# JFrog Artifactory (files and folders)
# Auth: export JFROG_API_TOKEN=...
modelaudit https://company.jfrog.io/artifactory/repo/model.pt
modelaudit https://company.jfrog.io/artifactory/repo/models/
# DVC-tracked models
modelaudit model.dvc
```
### 身份验证环境变量
- `HF_TOKEN` 用于私有 Hugging Face 仓库
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`（以及可选的 `AWS_SESSION_TOKEN`）用于 S3
- `GOOGLE_APPLICATION_CREDENTIALS` 用于 GCS
- `MLFLOW_TRACKING_URI` 用于 MLflow 仓库访问
- `JFROG_API_TOKEN` 或 `JFROG_ACCESS_TOKEN` 用于 JFrog Artifactory
- 将凭证存储在环境变量或 secrets manager 中，切勿提交 token/key。
## 安装
```
# Everything (recommended)
pip install modelaudit[all]
# Core only (pickle, numpy, archives)
pip install modelaudit
# Specific frameworks
pip install modelaudit[tensorflow,pytorch,h5,onnx,safetensors]
# CI/CD environments
pip install modelaudit[all-ci]
# Docker
docker run --rm -v "$(pwd)":/app ghcr.io/promptfoo/modelaudit:latest model.pkl
```
## CLI 选项
主要命令：
```
modelaudit [PATHS...] # Default scan command
modelaudit scan [OPTIONS] PATHS... # Explicit scan command
modelaudit metadata [OPTIONS] PATH # Extract model metadata safely (no deserialization by default)
modelaudit doctor [--show-failed] # Diagnose scanner/dependency availability
modelaudit debug [--json] [--verbose] # Environment and configuration diagnostics
modelaudit cache [stats|clear|cleanup] [OPTIONS]
```
常用扫描选项：
```
--format {text,json,sarif} Output format (default: auto-detected)
--output FILE Write results to file
--strict Fail on warnings, scan all file types, strict license validation
--sbom FILE Generate CycloneDX SBOM
--stream Download, scan, and delete files one-by-one (saves disk)
--max-size SIZE Size limit (e.g., 10GB)
--timeout SECONDS Override scan timeout
--dry-run Preview what would be scanned
--verbose / --quiet Control output detail
--blacklist PATTERN Additional patterns to flag
--no-cache Disable result caching
--cache-dir DIR Set cache directory for downloads and scan results
--progress Force progress display
```
## 元数据提取
```
# Human-readable summary (safe default: no model deserialization)
modelaudit metadata model.safetensors
# Machine-readable output
modelaudit metadata ./models --format json --output metadata.json
# Focus only on security-relevant metadata fields
modelaudit metadata model.onnx --security-only
```
`--trust-loaders` 启用可能会反序列化模型内容的扫描器元数据加载器。仅在隔离环境中的受信任 artifacts 上使用此功能。
## 退出代码
- `0`：未检测到安全问题
- `1`：检测到安全问题
- `2`：扫描错误
## 遥测与隐私
ModelAudit 包含用于产品可靠性和使用情况分析的遥测功能。
- 收集的元数据可能包括命令使用情况、扫描时间、扫描器/文件类型使用情况、问题严重程度/类型汇总、原始及哈希处理的路径/URL 标识符，以及文件扩展名/域名等粗略元数据。
- 原始 URL 遥测字段可能包含查询参数（例如预签名/SAS 凭证）。在启用遥测时，请避免传递包含凭证的 URL。
- 模型文件在本地扫描，ModelAudit 不会将模型二进制内容作为遥测事件上传。
- 在 CI/测试环境以及可编辑的开发安装中，遥测默认自动禁用。
使用以下任一环境变量显式退出：
```
export PROMPTFOO_DISABLE_TELEMETRY=1
# or
export NO_ANALYTICS=1
```
要在可编辑/开发安装期间选择加入：
```
export MODELAUDIT_TELEMETRY_DEV=1
```
## 输出示例
```
# JSON for CI/CD pipelines
modelaudit model.pkl --format json --output results.json
# SARIF for code scanning platforms
modelaudit model.pkl --format sarif --output results.sarif
```
## 故障排除
- 运行 `modelaudit doctor --show-failed` 以列出不可用的扫描器和缺失的可选依赖项。
- 运行 `modelaudit debug --json` 以收集用于 Bug 报告的环境/配置诊断信息。
- 使用 `modelaudit cache cleanup --max-age 30` 安全地删除过期的缓存条目。
- 如果 `pip` 安装了旧版本，请验证 Python 是否为 `3.10+`（`python --version`）。
- 有关更多故障排除和云身份验证指南，请参阅：
- https://www.promptfoo.dev/docs/model-audit/
- https://www.promptfoo.dev/docs/model-audit/usage/
## 文档
- **[完整文档](https://www.promptfoo.dev/docs/model-audit/)** — 设置、配置和高级用法
- **[使用示例](https://www.promptfoo.dev/docs/model-audit/usage/)** — CI/CD 集成、远程扫描、SBOM 生成
- **[支持的格式](https://www.promptfoo.dev/docs/model-audit/scanners/)** — 详细的扫描器文档
- **[支持政策](SUPPORT.md)** — 支持的 Python/OS 版本和维护政策
- **[安全模型与局限性](docs/user/security-model.md)** — ModelAudit 能保证和不能保证的内容
- **[兼容性矩阵](docs/user/compatibility-matrix.md)** — 文件格式与可选依赖项对照
- **[元数据提取指南](docs/user/metadata-extraction.md)** — 安全的元数据工作流和 `--trust-loaders` 指导
- **[离线/物理隔离指南](docs/user/offline-air-gapped.md)** — 无互联网访问的安全操作
- **[扫描器贡献者快速入门](docs/agents/new-scanner-quickstart.md)** — 新扫描器开发的安全工作流
- **故障排除** — 运行 `modelaudit doctor --show-failed` 检查扫描器可用性
## 许可证
MIT License — 详情请参阅 [LICENSE](LICENSE)。
**[完整文档](https://www.promptfoo.dev/docs/model-audit/)** | **[使用示例](https://www.promptfoo.dev/docs/model-audit/usage/)** | **[支持的格式](https://www.promptfoo.dev/docs/model-audit/scanners/)**
## 快速开始
**需要 Python 3.10+**
```
pip install modelaudit[all]
# 扫描文件或目录
modelaudit model.pkl
modelaudit ./models/
# 为 CI/CD 导出结果
modelaudit model.pkl --format json --output results.json
```
```
$ modelaudit suspicious_model.pkl
Files scanned: 1 | Issues found: 2 critical, 1 warning
1. suspicious_model.pkl (pos 28): [CRITICAL] Malicious code execution attempt
Why: Contains os.system() call that could run arbitrary commands
2. suspicious_model.pkl (pos 52): [WARNING] Dangerous pickle deserialization
Why: Could execute code when the model loads
```
## 检测内容
- **代码执行攻击**：位于 Pickle、PyTorch、NumPy 和 Joblib 文件中
- **模型后门**：包含隐藏功能或可疑权重模式
- **嵌入的敏感信息**：模型权重或元数据中的 API key、token 和凭证
- **网络指标**：可能导致数据泄露的 URL、IP 和 socket 用法
- **压缩包漏洞**：ZIP/TAR/7z 文件中的路径遍历、符号链接攻击
- **不安全的 ML 操作**：Lambda 层、自定义 ops、TorchScript/JIT、模板注入
- **供应链风险**：篡改、许可证违规、可疑配置
## 支持的格式
ModelAudit 包含涵盖模型、压缩包和配置格式的专用扫描器：
| 格式 | 扩展名 | 风险等级 |
| ----------------------- | ------------------------------------- | ------ |
| **Pickle** | `.pkl`, `.pickle`, `.dill` | HIGH |
| **PyTorch** | `.pt`, `.pth`, `.ckpt`, `.bin` | HIGH |
| **Joblib** | `.joblib` | HIGH |
| **NumPy** | `.npy`, `.npz` | HIGH |
| **R Serialized** | `.rds`, `.rda`, `.rdata` | HIGH |
| **TensorFlow** | `.pb`, `.meta`, SavedModel 目录 | MEDIUM |
| **Keras** | `.h5`, `.hdf5`, `.keras` | MEDIUM |
| **ONNX** | `.onnx` | MEDIUM |
| **CoreML** | `.mlmodel` | LOW |
| **MXNet** | `*-symbol.json`, `*-NNNN.params` | LOW |
| **NeMo** | `.nemo` | MEDIUM |
| **CNTK** | `.dnn`, `.cmf` | MEDIUM |
| **RKNN** | `.rknn` | MEDIUM |
| **Torch7** | `.t7`, `.th`, `.net` | HIGH |
| **CatBoost** | `.cbm` | MEDIUM |
| **XGBoost** | `.bst`, `.model`, `.ubj` | MEDIUM |
| **LightGBM** | `.lgb`, `.lightgbm`, `.model` | MEDIUM |
| **Llamafile** | `.llamafile`, 无扩展名, `.exe` | MEDIUM |
| **TorchServe** | `.mar` | HIGH |
| **SafeTensors** | `.safetensors` | LOW |
| **GGUF/GGML** | `.gguf`, `.ggml` | LOW |
| **JAX/Flax** | `.msgpack`, `.flax`, `.orbax`, `.jax` | LOW |
| **TFLite** | `.tflite` | LOW |
| **ExecuTorch** | `.ptl`, `.pte` | LOW |
| **TensorRT** | `.engine`, `.plan` | LOW |
| **PaddlePaddle** | `.pdmodel`, `.pdiparams` | LOW |
| **OpenVINO** | `.xml` | LOW |
| **Skops** | `.skops` | HIGH |
| **PMML** | `.pmml` | LOW |
| **Compressed Wrappers** | `.gz`, `.bz2`, `.xz`, `.lz4`, `.zlib` | MEDIUM |
此外，还支持 ZIP、TAR、7-Zip、OCI layers、Jinja2 模板、JSON/YAML 元数据、manifest 以及文本文件的扫描器。
[查看完整格式文档](https://www.promptfoo.dev/docs/model-audit/scanners/)
## 远程来源
直接从远程仓库和云存储扫描模型：
```
# Hugging Face
modelaudit https://huggingface.co/gpt2
modelaudit hf://microsoft/DialoGPT-medium
# 云存储
modelaudit s3://bucket/model.pt
modelaudit gs://bucket/models/
# MLflow registry
modelaudit models:/MyModel/Production
# JFrog Artifactory (files and folders)
# Auth: export JFROG_API_TOKEN=...
modelaudit https://company.jfrog.io/artifactory/repo/model.pt
modelaudit https://company.jfrog.io/artifactory/repo/models/
# DVC-tracked models
modelaudit model.dvc
```
### 身份验证环境变量
- `HF_TOKEN` 用于私有 Hugging Face 仓库
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`（以及可选的 `AWS_SESSION_TOKEN`）用于 S3
- `GOOGLE_APPLICATION_CREDENTIALS` 用于 GCS
- `MLFLOW_TRACKING_URI` 用于 MLflow 仓库访问
- `JFROG_API_TOKEN` 或 `JFROG_ACCESS_TOKEN` 用于 JFrog Artifactory
- 将凭证存储在环境变量或 secrets manager 中，切勿提交 token/key。
## 安装
```
# Everything (recommended)
pip install modelaudit[all]
# Core only (pickle, numpy, archives)
pip install modelaudit
# Specific frameworks
pip install modelaudit[tensorflow,pytorch,h5,onnx,safetensors]
# CI/CD environments
pip install modelaudit[all-ci]
# Docker
docker run --rm -v "$(pwd)":/app ghcr.io/promptfoo/modelaudit:latest model.pkl
```
## CLI 选项
主要命令：
```
modelaudit [PATHS...] # Default scan command
modelaudit scan [OPTIONS] PATHS... # Explicit scan command
modelaudit metadata [OPTIONS] PATH # Extract model metadata safely (no deserialization by default)
modelaudit doctor [--show-failed] # Diagnose scanner/dependency availability
modelaudit debug [--json] [--verbose] # Environment and configuration diagnostics
modelaudit cache [stats|clear|cleanup] [OPTIONS]
```
常用扫描选项：
```
--format {text,json,sarif} Output format (default: auto-detected)
--output FILE Write results to file
--strict Fail on warnings, scan all file types, strict license validation
--sbom FILE Generate CycloneDX SBOM
--stream Download, scan, and delete files one-by-one (saves disk)
--max-size SIZE Size limit (e.g., 10GB)
--timeout SECONDS Override scan timeout
--dry-run Preview what would be scanned
--verbose / --quiet Control output detail
--blacklist PATTERN Additional patterns to flag
--no-cache Disable result caching
--cache-dir DIR Set cache directory for downloads and scan results
--progress Force progress display
```
## 元数据提取
```
# Human-readable summary (safe default: no model deserialization)
modelaudit metadata model.safetensors
# Machine-readable output
modelaudit metadata ./models --format json --output metadata.json
# Focus only on security-relevant metadata fields
modelaudit metadata model.onnx --security-only
```
`--trust-loaders` 启用可能会反序列化模型内容的扫描器元数据加载器。仅在隔离环境中的受信任 artifacts 上使用此功能。
## 退出代码
- `0`：未检测到安全问题
- `1`：检测到安全问题
- `2`：扫描错误
## 遥测与隐私
ModelAudit 包含用于产品可靠性和使用情况分析的遥测功能。
- 收集的元数据可能包括命令使用情况、扫描时间、扫描器/文件类型使用情况、问题严重程度/类型汇总、原始及哈希处理的路径/URL 标识符，以及文件扩展名/域名等粗略元数据。
- 原始 URL 遥测字段可能包含查询参数（例如预签名/SAS 凭证）。在启用遥测时，请避免传递包含凭证的 URL。
- 模型文件在本地扫描，ModelAudit 不会将模型二进制内容作为遥测事件上传。
- 在 CI/测试环境以及可编辑的开发安装中，遥测默认自动禁用。
使用以下任一环境变量显式退出：
```
export PROMPTFOO_DISABLE_TELEMETRY=1
# or
export NO_ANALYTICS=1
```
要在可编辑/开发安装期间选择加入：
```
export MODELAUDIT_TELEMETRY_DEV=1
```
## 输出示例
```
# JSON for CI/CD pipelines
modelaudit model.pkl --format json --output results.json
# SARIF for code scanning platforms
modelaudit model.pkl --format sarif --output results.sarif
```
## 故障排除
- 运行 `modelaudit doctor --show-failed` 以列出不可用的扫描器和缺失的可选依赖项。
- 运行 `modelaudit debug --json` 以收集用于 Bug 报告的环境/配置诊断信息。
- 使用 `modelaudit cache cleanup --max-age 30` 安全地删除过期的缓存条目。
- 如果 `pip` 安装了旧版本，请验证 Python 是否为 `3.10+`（`python --version`）。
- 有关更多故障排除和云身份验证指南，请参阅：
- https://www.promptfoo.dev/docs/model-audit/
- https://www.promptfoo.dev/docs/model-audit/usage/
## 文档
- **[完整文档](https://www.promptfoo.dev/docs/model-audit/)** — 设置、配置和高级用法
- **[使用示例](https://www.promptfoo.dev/docs/model-audit/usage/)** — CI/CD 集成、远程扫描、SBOM 生成
- **[支持的格式](https://www.promptfoo.dev/docs/model-audit/scanners/)** — 详细的扫描器文档
- **[支持政策](SUPPORT.md)** — 支持的 Python/OS 版本和维护政策
- **[安全模型与局限性](docs/user/security-model.md)** — ModelAudit 能保证和不能保证的内容
- **[兼容性矩阵](docs/user/compatibility-matrix.md)** — 文件格式与可选依赖项对照
- **[元数据提取指南](docs/user/metadata-extraction.md)** — 安全的元数据工作流和 `--trust-loaders` 指导
- **[离线/物理隔离指南](docs/user/offline-air-gapped.md)** — 无互联网访问的安全操作
- **[扫描器贡献者快速入门](docs/agents/new-scanner-quickstart.md)** — 新扫描器开发的安全工作流
- **故障排除** — 运行 `modelaudit doctor --show-failed` 检查扫描器可用性
## 许可证
MIT License — 详情请参阅 [LICENSE](LICENSE)。标签：AI供应链安全, AI基础设施安全, AMSI绕过, CI/CD安全, DevSecOps, DNS 反向解析, Linux系统监控, Llama, LLM防护, LNA, MLOps安全, Pickle安全, Python安全工具, PyTorch安全, Webshell检测, 上游代理, 云安全监控, 人工智能安全, 反序列化漏洞, 合规性, 后门检测, 威胁检测, 对抗攻击, 敏感信息检测, 文档安全, 文档结构分析, 机器学习模型扫描, 模型安全, 模型投毒检测, 模型文件审计, 网络安全, 请求拦截, 逆向工具, 隐私保护, 静态分析, 风险合规