SecAI-Hub/gguf-guard

# gguf-guard GGUF 模型文件的静态分析与完整性验证。无需运行推理即可检测权重级异常、结构篡改和量化感知攻击。 ## 为什么需要 来自公共模型中心的 GGUF 文件可能遭到篡改 —— 木马权重、损坏的量化块、被替换的张量。`gguf-guard` 通过分析每个张量的原始二进制结构和统计属性，并将其与已知良好的基线进行比对来捕捉这些问题。 ## 功能特性 - **全量异常扫描** —— 每个张量的统计分析（均值、方差、峰度、离群值比率、稀疏度）与分层评分 - **量化感知块分析** —— 检查原始量化块（Q4_0, Q4_K, Q5_K, Q6_K, Q8_0）的尺度熵异常、重复块、桶饱和度 - **鲁棒统计** —— 中位数/MAD、截尾均值、Tukey 栅栏，以减少重尾分布上的误报 - **结构策略检查** —— 验证 GGUF 版本、张量偏移/重叠、元数据一致性、已知架构模式 - **模型族匹配** —— 通过张量命名和形状模式识别架构（llama, mistral, mixtral, qwen2, gemma, phi） - **谱系验证** —— 将源（FP/BF16）模型与量化后的 GGUF 进行比对，根据格式归一化预期的量化损失 - **逐张量完整性清单** —— 每个张量的 SHA-256 哈希及 Merkle 树根，用于高效验证 - **参考配置** —— 从多个纯净样本构建，合并以获得更宽的范围，并按置信度层级（高/中/低）进行比较 - **指纹识别** —— 确定性结构哈希，用于快速身份检查 - **对 CI 友好** —— `--quiet` 模式输出 `PASS/WARN/FAIL score=N.NN`，失败时退出码为 2 ## 安装 ``` go install github.com/SecAI-Hub/gguf-guard/cmd/gguf-guard@latest ``` 或从源码构建： ``` git clone https://github.com/SecAI-Hub/gguf-guard.git cd gguf-guard go build -o gguf-guard ./cmd/gguf-guard ``` ## 快速开始 ``` # 全面扫描 gguf-guard scan model.gguf # CI 模式 (单行输出，FAIL 时退出码为 2) gguf-guard scan --quiet model.gguf # 使用 reference profile 扫描 gguf-guard scan --reference llama-7b-ref.json model.gguf # 仅结构检查 (快速) gguf-guard inspect model.gguf # 显示模型元数据 gguf-guard info model.gguf # 生成完整性清单 gguf-guard manifest model.gguf --output manifest.json # 根据清单验证 gguf-guard verify-manifest model.gguf manifest.json # 比较两个模型 gguf-guard compare baseline.gguf candidate.gguf # 血缘检查 (源 FP 模型 vs 量化) gguf-guard lineage source-f32.gguf candidate-q4k.gguf # 从多个纯净样本构建 reference gguf-guard build-reference clean1.gguf clean2.gguf --output ref.json ``` ## 命令 | 命令 | 描述 | |---------|-------------| | `scan` | 具有分层评分的全量异常扫描 | | `fingerprint` | 生成结构指纹 | | `compare` | 逐个张量比较两个 GGUF 文件 | | `profile` | 从单个模型生成参考配置 | | `build-reference` | 从多个样本构建合并参考 | | `lineage` | 根据 FP/BF16 源验证量化模型 | | `manifest` | 生成逐张量 SHA-256 完整性清单 | | `verify-manifest` | 根据完整性清单验证模型 | | `inspect` | 运行结构策略检查和模型族匹配 | | `info` | 显示模型元数据和张量类型摘要 | 运行 `gguf-guard --help` 查看特定命令的标志。 ## 退出码 | 代码 | 含义 | |------|---------| | 0 | PASS —— 无显著异常 | | 1 | 错误（解析失败、文件丢失） | | 2 | FAIL —— 评分超过阈值或违反策略 | ## 评分 扫描产生一个从 0.0（纯净）到 1.0（高度可疑）的综合评分，由四个层级构成： | 层级 | 权重 | 检查内容 | |-------|--------|----------------| | 张量局部 | 0.30 | 逐张量矩、离群值比率、NaN/Inf | | 角色组 | 0.25 | 跨层一致性（z-score + 鲁棒 z-score） | | 模型全局 | 0.20 | 异常集中模式 | | 参考 | 0.25 | 偏离已知良好的参考配置 | 阈值：`score > 0.2` = WARN，`score > 0.5` = FAIL。 详情请见 [docs/scoring.md](docs/scoring.md)。 ## 支持的量化类型 反量化：F32, F16, BF16, Q8_0, Q4_0, Q4_1 块级分析：Q4_0, Q4_1, Q4_K, Q5_K, Q6_K, Q8_0 ## 项目结构 ``` gguf/ parser.go GGUF v2/v3 binary parser types.go GGML type definitions dequant.go Dequantization routines block.go Block-level quantization analysis analysis/ stats.go Tensor statistics (mean, variance, kurtosis, percentiles) anomaly.go Layered anomaly detection and scoring robust.go Robust statistics (median, MAD, trimmed mean, Tukey) quant.go Quant-format-aware anomaly checks reference.go Reference profiles (single/multi-sample, provenance) compare.go Model-to-model comparison lineage.go Lineage diff (source vs quantized) fingerprint.go Structural fingerprinting manifest.go Per-tensor integrity manifests (SHA-256 + Merkle) policy.go Structural policy validation families.go Model family matching heuristics cmd/gguf-guard/ main.go CLI entry point ``` ## 文档 - [Architecture](docs/architecture.md) —— 设计与分析流水线 - [Scoring](docs/scoring.md) —— 异常评分方法 - [CLI Reference](docs/cli-reference.md) —— 所有命令与标志 ## 测试 ``` go test ./... -v ``` 73 个测试，覆盖解析器、反量化、块分析、统计、异常检测、鲁棒统计、清单、策略检查、模型族匹配、谱系以及量化感知分析。 ## 许可证 Apache License 2.0。见 [LICENSE](LICENSE)。 ## 安全 有关报告漏洞，请见 [SECURITY.md](SECURITY.md)。

标签：AI安全, Apex, API密钥扫描, Chat Copilot, CI/CD安全, DevSecOps, EVTX分析, Gemma, GGUF, Go语言, Llama, LLM, Merkle Tree, Mistral, Phi, Qwen2, Unmanaged PE, Zenmap, 上游代理, 二进制分析, 云安全监控, 云安全运维, 后门检测, 哈希验证, 大语言模型安全, 完整性校验, 实时告警, 异常检测, 恶意模型检测, 数据完整性, 文件结构验证, 日志审计, 木马检测, 机器学习, 机密管理, 权重分析, 模型指纹, 模型篡改检测, 深度伪造防御, 程序破解, 网络安全, 量化感知攻击, 隐私保护, 静态分析