ModelAudit

在部署之前保护你的 AI 模型。 静态扫描器，可检测 ML 模型文件中的恶意代码、潜在后门指标和安全漏洞——而无需加载或执行它们。

为什么选择 ModelAudit

模型从未受信任的注册表下载，经过 CI，最终在生产环境中运行。传统的 SAST 工具不会检查 pickle 操作码、HDF5 组布局、ONNX proto 图或 TensorFlow SavedModel 签名——而 ModelAudit 可以：

静态扫描。 任何模型都不会被加载、反序列化或执行。
覆盖你实际交付的格式。 40+ 个扫描器，涵盖 pickle、PyTorch、SafeTensors、ONNX、TensorFlow、Keras、GGUF、压缩包和配置文件。
集成到 CI。 机器可读输出（JSON、SARIF）、严格模式、退出代码以及可选择的扫描器。
暴露覆盖范围限制。 已识别的扫描器会报告有界分析的缺口，例如截断读取或预算耗尽，而不是将其呈现为完全覆盖的结果。

同类工具：picklescan（仅支持 pickle，基于 Python）、fickling（仅支持 pickle，基于 AST）、modelscan（pickle + TensorFlow + Keras 子集）。ModelAudit 覆盖范围更广，并通过其同伴包 modelaudit-picklescan 提供原生的 Rust pickle 引擎。

快速开始

需要 Python 3.10-3.13```bash pip install "modelaudit[all]"

Scan a file or directory

modelaudit model.pkl modelaudit ./models/

Export results for CI/CD

modelaudit model.pkl --format json --output results.json

I'm ready to translate the provided content, but the INPUT section appears to be empty. Please provide the actual chunk 3 content so I can translate it.```
$ 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 密钥、令牌和凭据
网络指标 — 可能导致数据外泄的 URL、IP 和套接字使用情况
归档漏洞利用 — ZIP/TAR/7z 文件中的路径遍历、符号链接攻击
不安全的 ML 操作 — Lambda 层、自定义操作、TorchScript/JIT、模板注入
供应链风险 — 篡改、许可证违规、可疑配置

支持的格式

ModelAudit 包含 45 个已注册的扫描器，涵盖模型、归档和配置文件格式：

另有针对 ZIP、TAR、7-Zip、OCI 层、Jinja2 模板、JSON/YAML 元数据、清单、模型卡、文本文件和 RAR 识别的扫描器。RAR 压缩包会被报告为不支持/失败关闭（fail-closed），而不是被跳过。

结构有效的 TensorFlow SavedModel 和 MetaGraph protobuf，在重命名为非模型后缀时也会被识别。

CoreML 模型在重命名后也能被识别，并且会明确报告覆盖不完整的情况。

具有过大但看似合理的帧结构的 SafeTensors 文件，会在未被其他格式认领的后缀（如 .jpg）下保留，以进行有界且非结论性的分析。

结构上看似合理的 Flax/JAX MessagePack 检查点在重命名为非模型后缀时也会被识别；无法完整分类的重命名结构会被报告为覆盖不完整。

结构化的 JAX/Orbax JSON 检查点元数据在重命名后同样会被识别；过大的模糊候选会被报告为覆盖不完整；在有限的检查前缀中可观察到的安全模式仍会被保守报告。

查看完整的格式文档

远程来源

直接从远程仓库和云存储扫描模型：```bash

Hugging Face

modelaudit https://huggingface.co/gpt2 modelaudit hf://microsoft/DialoGPT-medium

Cloud storage

modelaudit s3://bucket/model.pt modelaudit gs://bucket/models/

MLflow registry

Non-local artifact stores: export MODELAUDIT_MLFLOW_ALLOWED_ARTIFACT_URIS=s3://trusted-bucket/models

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 模型注册表
- `MODELAUDIT_MLFLOW_ALLOWED_ARTIFACT_URIS` 用于非本地 MLflow 工件根路径（逗号分隔的 URI 前缀）
- 使用具体的后端根路径，如 `s3://bucket/prefix`；逻辑上的 `models:/` 或 `runs:/` URI 以及百分号编码的远程路径将被拒绝。
- `JFROG_API_TOKEN` 或 `JFROG_ACCESS_TOKEN` 用于 JFrog Artifactory
- `MODELAUDIT_JFROG_ALLOWED_HOSTS` 用于逗号分隔的自定义 JFrog 主机名，这些主机名可能接收凭据
- `MODELAUDIT_JFROG_ALLOWED_REDIRECT_HOSTS` 用于逗号分隔的外部重定向主机名，这些主机名可以在不使用凭据的情况下下载
- 将凭据存储在环境变量或密钥管理器中，切勿提交令牌/密钥。

## 安装```bash
# Broad scanner coverage (recommended; excludes the TensorFlow runtime and platform-specific TensorRT)
pip install "modelaudit[all]"

# Core only (static scanners, pickle, NumPy, archives, manifests, metadata)
pip install modelaudit

# Specific frameworks (TensorFlow installs on Python 3.11-3.12; ONNX installs on Python 3.10-3.12)
pip install "modelaudit[tensorflow,pytorch,h5,onnx,safetensors]"

# CI/CD environments
pip install "modelaudit[all-ci]"

# On Python 3.11-3.12, add TensorFlow only when you need runtime-dependent checkpoint or weight analysis
pip install "modelaudit[all,tensorflow]"

# Docker
docker run --rm -v "$(pwd)":/app ghcr.io/promptfoo/modelaudit:latest model.pkl

ONNX extra（包括 modelaudit[all] 中的 ONNX 部分）适用于 Python 3.10-3.12。包含 PyTorch 的 extra 需要 Python 3.10-3.12 或标准（启用 GIL 的）CPython 3.13；修补版 PyTorch 2.13 wheel 不支持 free-threaded CPython 3.13t。请使用标准 CPython，因为 ModelAudit 的原生 pickle 扫描器同样不支持 CPython 3.13t。在 Apple Silicon 上，包含 PyTorch 的 extra 需要 macOS 14 或更高版本，因为这些 wheel 以 macosx_14_0_arm64 为目标；仅核心安装仍可用于在 macOS 11-13 上进行静态扫描。

CLI 选项

主要命令：```bash modelaudit [PATHS...] # Default scan command modelaudit scan [OPTIONS] PATHS... # Explicit scan command modelaudit scan --list-scanners # List scanner IDs for targeted scans 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]

常见扫描选项：```text
--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                     Process files one-by-one; remote downloads are deleted after scanning
--assume-shard-family        Treat explicitly listed cross-directory shards as one model family
--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
--scanners LIST              Only run selected scanners (IDs/classes; comma-separated or repeated)
--exclude-scanner NAME       Exclude a scanner from the active set (comma-separated or repeated)
--list-scanners              List scanner IDs, class names, extensions, and dependencies

定向扫描器选择：```bash

Discover scanner IDs and class names

modelaudit scan --list-scanners modelaudit scan --list-scanners --format json

Run only selected scanners

modelaudit scan ./models --scanners pickle,tf_savedmodel modelaudit scan ./model.pkl --scanners PickleScanner

Run the default scanner set except a noisy or slow scanner

modelaudit scan ./models --exclude-scanner weight_distribution

For container formats, include both the container scanner and nested scanner

modelaudit scan ./archive.zip --scanners zip,pickle

`--scanners` 从显式允许列表开始。`--exclude-scanner` 从该允许列表或默认扫描器集中移除扫描器。扫描器选择会在 JSON 输出中的 `scanner_selection` 下体现。

对于远程文件夹，ModelAudit 会在安全时按所选扫描器扩展名缩小下载范围。基于内容的重命名包装器路由在获取后应用；当存储库文件名可能被有意误导时，请扫描直接文件 URL。

## 元数据提取```bash
# 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 启用可能反序列化模型内容的扫描器元数据加载器。仅在隔离环境中对受信任的工件使用此选项。

退出代码

0：未检测到安全问题
1：检测到安全问题
2：扫描错误

遥测与隐私

ModelAudit 包含用于产品可靠性和使用分析的遥测功能。

收集的元数据可包括命令和功能使用情况、扫描和下载时间或大小元数据、扫描器/文件类型使用情况、稳定规则或 CVE 标识符、严重性聚合、注册的文件扩展名、粗略的来源或提供程序类别，以及运行时版本、平台和 CI 元数据。
遥测不包括原始本地路径、文件名、模型 ID 或名称、存储库或工件标识符、存储桶或对象键、远程 URL 路径、自由格式的问题或错误文本、URL 用户信息、查询字符串、片段或模型二进制内容。
打包安装默认启用遥测。当设置了 CI=true 或 IS_TESTING=true 时，遥测会自动禁用；在可编辑的开发安装中也会禁用，除非设置 MODELAUDIT_TELEMETRY_DEV=1。从其他 CI 提供程序（TeamCity、CodeBuild、Bitbucket Pipelines、Jenkins）发送的事件会被标记为 isRunningInCi=true，以便在下游进行过滤。
持久化的假名用户标识符存储在 ~/.promptfoo/promptfoo.yaml 中，用于与 Promptfoo 进行跨工具关联，并且每个遥测会话都使用新的会话标识符。升级后首次运行时，会迁移 ~/.modelaudit/user_config.json 中的现有 ID。该文件中的旧版电子邮件值（如果存在）可能会附加到分析用户配置文件中。

通过以下任一环境变量显式选择退出：```bash export PROMPTFOO_DISABLE_TELEMETRY=1

or

export NO_ANALYTICS=1

要在可编辑/开发安装期间选择加入：```bash
export MODELAUDIT_TELEMETRY_DEV=1

输出示例```bash

JSON for CI/CD pipelines