duriantaco/ceres

# Ceres **开发者优先的 AI 安全扫描器。** Ceres 是针对代码仓库的 AI-SAST：它检查 你的代码、prompt、配置、模型 artifact、数据集、RAG 文档和 AI 供应链，寻找传统 SAST/SCA 工具遗漏的安全问题。 它可以在本地、pre-commit 和 CI 中运行。 ``` ceres scan . ``` ## Ceres 检查的内容 | 层级 | 示例 | |-------------|----------| | 代码 | `trust_remote_code=True`、`pickle.load`、未设置 `weights_only=True` 的 `torch.load`、`eval`/`exec`、不受限制的 agent 工具、无审批的高风险工具、被投毒的 tool/MCP 描述 | | 模型 | `.pkl`/`.pickle` artifact、不安全的格式、未知来源/出处、可疑的 pickle opcode、缺失/更改的 SHA-256、safetensors tensor/layer 漂移、GGUF/ONNX 元数据漂移、NaN/Inf/范围异常、tokenizer / chat-template / LoRA-base 漂移 | | 数据集 | 缺失的 manifest、缺失/陈旧的 hash、来源不在 allowlist 中、重复率激增、相对于 baseline 的标签分布漂移、突然出现的罕见触发 trigram | | Eval/safety | 禁用的 safety 或回归 eval 门禁、降低的 safety 阈值、禁用的过滤器/防护栏、过高的生成温度 | | RAG corpus | prompt-injection 短语（`ignore previous instructions` 等）、不安全的用户文档索引、缺失的检索过滤器、检索后的权限检查、隐藏的 HTML / display:none、带有指令的 HTML 注释、零宽度 / bidi 控制字符、巨大的 base64 blob | | Prompt | 模板化到系统上下文中的用户输入；明确启用时可选的内联 secret 检查 | | 供应链| 配置中未锁定的 Hugging Face 模型引用、未锁定的 Git 依赖、缺失的 lockfile、未锁定的 Docker 镜像、远程安装脚本、可选的通用依赖锁定检查、标准化为 Ceres 发现结果的 `pip-audit` 结果；仅在明确启用时的 `gitleaks` | | AI-BOM | 当存在模型/数据集但没有 `ai-bom.json` 时发出警告 | 完整文档： - [文档索引](docs/index.md) - [规则目录](docs/rules.md) - [模型安全与 tensor 扫描](docs/model-security.md) Ceres **绝不导入模型文件**。模型 artifact 通过静态方式检查 （仅进行 pickle opcode 解码，不执行 `__reduce__`），并有 64 MB 的硬性上限。 ## 安装 ``` pip install ceres-scanner # 或者，从此 repo： pip install -e . ``` 可选集成：安装 [`pip-audit`](https://pypi.org/project/pip-audit/) 或者，如果你明确希望在 Ceres 内部进行通用 secret 扫描， 请在 `PATH` 中安装 [`gitleaks`](https://github.com/gitleaks/gitleaks)。Ceres 会检测 已启用的工具，并将它们的发现结果合并到同一个报告中。如果策略 启用了外部扫描器但缺失，Ceres 会发出一个低严重性的 `ceres.supplychain.scanner_unavailable` 发现，这样 CI 就不会悄悄跳过覆盖范围。 ## 快速开始 ``` ceres init # writes ceres.yml policy ceres scan . # human-readable scan with explanations ceres scan . --sarif-out out.sarif --json-out out.json ceres scan . --diff-base origin/main ceres baseline . # snapshot dataset+model+tool metadata -> .ceres/baseline.json ceres bom . --out ai-bom.json # Ceres AI-BOM ceres list-rules # show known rule IDs ``` 当存在门禁严重级别的发现时，`scan` 会以非零状态退出（默认： `critical` 和 `high` 失败；`medium` 警告）。 CLI 报告会按 AI 系统层对发现进行分组，突出显示需要优先审查的问题， 解释每个问题为何重要，在可用时展示证据，并 以下一步的修复步骤结束。 在 PR 检查中使用 `--diff-base`，以完整的代码仓库上下文进行扫描，但只报告 自 base ref 以来更改过的文件或行上的发现。 ## 示例用例 Ceres 的典型用例是审查 AI 支持 agent 的 pull request。 该 PR 更改了模型加载代码，添加了新的 RAG 文档，更新了训练 数据集，并触及了依赖项。 ``` ceres scan . --json-out ceres-report.json --sarif-out ceres.sarif ``` 示例发现： ``` CRITICAL ceres.model.loader.remote_code_enabled src/app.py:10 Model loader uses trust_remote_code=True. CRITICAL ceres.model.artifact.pickle_format models/final.pkl Pickle-based model artifact may execute code during deserialization. HIGH ceres.rag.instruction.ignore_context rag/vendor_policy.md:5 RAG document contains instruction-like text. HIGH ceres.dataset.hash_drift data/train.csv Dataset hash differs from manifest declaration. ``` 如需此代码仓库的本地演示： ``` ceres scan examples/vulnerable-ai-repo ceres scan examples/vulnerable-ai-repo \ --json-out examples/vulnerable-ai-repo/ceres-report.json \ --sarif-out examples/vulnerable-ai-repo/ceres.sarif ceres bom examples/vulnerable-ai-repo ceres baseline examples/vulnerable-ai-repo ``` 易受攻击的示例预期会失败。干净的示例应该通过： ``` ceres scan examples/clean-ai-repo ``` 对于真实世界的回归测试，运行已播种的语料库测试套件。它会复制或 克隆 AI 仓库，注入已知的恶意 model/RAG/agent/data/supply-chain 更改， 如果预期的规则没有触发则失败： ``` python scripts/real_world_check.py \ --corpus examples/real-world-corpus.yml \ --workdir /tmp/ceres-real-world \ --json-out /tmp/ceres-real-world/report.json ``` ## 策略 `ceres.yml` 控制门禁、allowlist 和豁免。默认设置具有强主观性： `pickle` 格式被阻止，`trust_remote_code` 被拒绝， 并且默认关闭通用 secret 扫描，以便 Ceres 保持专注于 AI 模型和 AI 系统风险。 ``` severity_gate: critical: fail high: fail medium: warn low: info model_policy: allowed_formats: [safetensors, onnx, gguf] blocked_formats: [pkl, pickle] require_revision_pin: true allow_trust_remote_code: false waivers: - rule_id: ceres.model.loader.remote_code_enabled file: src/research_loader.py reason: "Research-only script, not shipped" expires: "2026-12-01" approved_by: "security-team" ``` 过期的豁免将停止抑制发现，*并且* 会作为 `ceres.policy.waiver_expired` 发现被展示出来，这样它们就不会在不知不觉中失效。 ## Baseline ``` ceres baseline . git add .ceres/baseline.json ``` 一旦存在 baseline，Ceres 就会将数据集指纹（行数、重复率、 标签分布、top trigram）、模型/tokenizer 状态和工具 元数据描述与其进行对比。超出策略阈值的漂移将成为一个 发现。 ## 模型层扫描 Ceres 应该扫描模型层和 tensor 以寻找**投毒指标**，但它 不应声称静态层检查能够证明某个层被投毒。 后门可能非常微妙，可能只在特定触发器或运行时 行为下才会出现。 Ceres 目前执行安全的 `.safetensors` tensor baseline 检查，而无需 导入模型代码或将 tensor 加载到内存中。它解析 safetensors 头部，记录 baseline 中的 tensor 名称、dtype、形状、偏移量、SHA-256 hash 和 紧凑的数值统计信息，然后将未来的扫描与该 baseline 进行比较。 已实现的静态检查： - 与已知良好的 baseline 相比的每个 tensor 的 SHA-256 hash - 意外的层名称、缺失的层、添加的层或形状更改 - dtype 更改 - NaN/Inf 值和已配置的绝对值范围异常 - 相比 baseline 的 L2 范数漂移和稀疏性漂移 - GGUF 头部/元数据/tensor 清单解析，包含架构、元数据和 tensor 计数漂移检查 - ONNX protobuf 元数据解析，包含 opset、图 operator 摘要和模型 元数据漂移检查 - LoRA adapter 元数据更改，例如 base model 不匹配 - 可能隐藏除明显权重 tensor 之外的行为转变的 tokenizer、special-token 和 chat-template 更改 计划中的检查： - 针对具有类似角色的 tensor 族的跨层异常评分 - 更深层的 ONNX 图形状和 GGUF tokenizer 策略检查 良好的发现结果措辞： ``` HIGH ceres.model.tensor.norm_drift models/adapter.safetensors Layer "lm_head.weight" changed shape and has unusually large norm drift compared with baseline. ``` 推荐策略：将层/tensor 扫描用作 baseline-diff 和异常 检测器，然后将其与出处、签名、数据集检查和 动态评估相结合，然后再做出投毒判定。 有关已实现的模型规则、baseline 格式和策略调节，请参阅[模型安全与 tensor 扫描](docs/model-security.md)。 ## CI ``` # .github/workflows/ceres.yml name: Ceres on: [pull_request, push] jobs: ceres: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: { python-version: "3.11" } - run: pip install ceres-scanner - run: ceres scan . --sarif-out ceres.sarif - uses: github/codeql-action/upload-sarif@v3 if: always() with: { sarif_file: ceres.sarif } ``` ## Pre-commit ``` # .pre-commit-config.yaml repos: - repo: local hooks: - id: ceres name: Ceres AI security scanner entry: ceres scan . --policy ceres.yml language: system pass_filenames: false ``` ## 状态 Ceres 是一个年轻的项目。MVP 涵盖了代码、模型、数据、 RAG、prompt 和供应链的静态规则，外加 AI-BOM 和 baseline。目前的 产品重心是用于 AI 工作流更改的快速、静态、预生产门禁。 有关触发大部分规则的示例，请参阅 `examples/vulnerable-ai-repo/`， 有关安静的 baseline，请参阅 `examples/clean-ai-repo/`。

标签：AI供应链安全, DevSecOps, 上游代理, 人工智能安全, 代码安全扫描, 合规性, 大语言模型安全, 文档安全, 机密管理, 知识库安全, 误配置预防, 逆向工具, 配置审计, 静态应用安全测试