Elpi97/local-ai-model-security-scanner

# 本地 AI 模型安全扫描器 一款专为网络安全分析师打造的 Python CLI 工具，他们是 AI 部门接收到本地模型权重之前的 **第一道防线**。 **组织背景：** AI 部门使用 **[vLLM](https://github.com/vllm-project/vllm)** 提供模型服务，并通常从 **Hugging Face** 拉取权重。 默认扫描绝不加载或运行模型。可选的 Ollama 式运行时探测被**暂时推迟**（改为使用检查清单 + AI 部门的 vLLM 测试床）。 **v0.3.0 的新特性：** 通过可选的 `[onnx]` 扩展，支持深度 ONNX protobuf 验证（包含 external-data 路径逃逸检测、递归 custom op-domain 检测、embedded-initializer 检查）—— 默认安装依然保持仅依赖标准库。 👉 **从这里开始：** **[HOW_TO_USE.md](HOW_TO_USE.md)** ## 分析师工作流（手动） ``` 1. Pull (or receive) the Hugging Face snapshot the AI dept requested 2. Run this scanner on the downloaded folder/files 3. Manually copy cleared artifacts into the drop folder 4. Manually notify the AI department (attach JSON + Markdown doc report) ``` 没有自动批准，没有 watch folders，也没有自动通知。然后 AI 部门会在 **vLLM** 下加载模型。 ## 主要示例：Hugging Face → vLLM 交接 ``` huggingface-cli download google/gemma-2-2b-it --local-dir ./incoming/gemma-2-2b-it python3 model_scanner.py ./incoming/gemma-2-2b-it \ --publisher google \ --hf-repo google/gemma-2-2b-it \ --serving-runtime vllm \ -v \ --report scan_report.json \ --doc-report handoff_report.md ``` `--serving-runtime vllm` 是**默认**设置。使用 `--hf-repo` 时，如果 Hub LFS digests 可用，本地 SHA256 将与之进行对比（如果不匹配 → **DANGEROUS**）。 ## 三个级别 | 级别 | 内容 | 改变判定结果？ | 需要 网络 / 运行时？ | |---|---|---|---| | **1 – 文件安全** | Pickle / zip / safetensors / GGUF / ONNX | 是 | 否 | | **2 – 信任与完整性** | Publisher 白名单、SHA256、可选的 HF metadata + LFS hash | 是 | 仅限 `--hf-repo` | | **3 – 行为检查清单** | 手动分析师检查（包括 vLLM 就绪状态） | 否（除非您之后启用推迟的探测） | 否 | ### 判定结果 | 判定 | 含义 | |---|---| | **SAFE** | 无阻碍性的文件/信任问题 | | **REVIEW** | 异常 / 未加入白名单 / HF 无法访问 — 需调查 | | **DANGEROUS** | 存在代码执行风险或 hash 不匹配 — 严禁交接 | ## 安装 ``` git clone https://github.com/Elpi97/local-ai-model-security-scanner.git cd local-ai-model-security-scanner pip install -e . # stdlib-only core pip install -e ".[onnx]" # + deep ONNX protobuf validation (onnx>=1.15) ``` 核心部分**仅依赖标准库** (Python 3.9+)。`[onnx]` 扩展可启用深度 ONNX protobuf 解析；若未安装，ONNX 文件将回退至字节扫描，并被标记为 REVIEW，以便随时凸显扫描覆盖不足的情况。 ## 快速开始 ``` python3 model_scanner.py /path/to/hf-snapshot -v \ --hf-repo ORG/NAME --publisher ORG \ --report scan_report.json --doc-report handoff_report.md ``` ## Tier 1 检查内容 | 格式 | 扩展名 | 检查项 | |---|---|---| | Legacy pickle | `.pt` `.pth` `.bin` `.ckpt` `.pkl` | 危险的 opcodes | | PyTorch zip | `.pt` `.pth` `.bin` | `data.pkl` + zip-slip | | Safetensors | `.safetensors` | Header / offsets（推荐用于 vLLM） | | GGUF | `.gguf` | Magic / 版本 / 完整性 | | ONNX | `.onnx` | 路径遍历 / custom ops（使用 [onnx] 扩展进行深度 protobuf 解析；否则回退为字节扫描） | ### ONNX 深度扫描 flags | Flag | 用途 | |---|---| | `--no-onnx-deep` | 跳过深度 protobuf 解析（字节扫描快速路径；输出 INFO 提示，而非 REVIEW）。 | | `--allow-onnx-domain DOMAIN` | 将 custom op domain 的级别从 CRITICAL 降级为 REVIEW（可重复使用）。 | 深度 ONNX 解析（需启用 `[onnx]`）：external-data 逃逸（`..`、绝对路径、URL）→ DANGEROUS；非标准 op domains（通过 `If`/`Loop`/`Scan` 子图和函数体进行递归检测）→ DANGEROUS；白名单 domains / 可疑函数名 / 大于 100 MiB 的 embedded initializers → REVIEW。 ## 配置与示例 - [`config/publishers.allowlist.json`](config/publishers.allowlist.json) - [`examples/`](examples/) — 包括 [`examples/DEMO.md`](examples/DEMO.md)，针对真实模型的实时运行（涵盖所有格式、一个被捕获的恶意 ONNX，以及一次真实的 HF 出处检查） ## 自动化测试 ``` python3 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" pytest ``` ## 已知限制 - 静态 Tier 1 属于尽力而为。 - Hash/HF LFS 匹配 ≠ 不存在语义后门。 - 在 **vLLM** 下的运行时行为测试是在文件检查通过后，由 AI 部门进行的（Ollama 探测已推迟）。 - Pickle/ONNX/zip-pickle 的深度读取默认上限为 **512 MiB**（`--max-read-bytes`；`0` = 无限制）。 - 目录扫描会跳过 symlinks 以及逃逸出扫描根目录的路径。 ## 许可证 MIT

标签：CNCF毕业项目, DLL 劫持, Python CLI, 云安全监控, 人工智能安全, 合规性, 大语言模型, 实时告警, 逆向工具, 静态分析