AB
AB
AiBoss站

全部分类

教程

Anthropic OSS Scanner 接入与无人工复核报告处理指南

教程

Anthropic OSS Scanner 接入与无人工复核报告处理指南

面向开源维护者的 OSS Scanner 实操指南：从判断项目是否适合接入、配置 project.yaml 与威胁模型、提交注册 PR，到收到模型生成且未经人工复核的漏洞报告后如何复现、重新定级、修复与决定披露。

Anthropic 推出的 OSS Scanner 是一项可选加入（opt-in）的开源项目漏洞扫描服务：项目注册后，服务会定期用模型对代码做安全扫描，并把发现的问题直接以邮件形式发给维护者，中间不经过人工复核。报告通常附带复现代码（PoC）、说明，以及在可用的情况下附带修复补丁建议。它的价值在于「快」——问题可能在很短时间内就送到你面前；代价是准确性没有人工背书，官方也明确说明报告可能包含不准确之处，例如严重级别判断错误。这篇教程面向正在考虑接入、或者即将开始接收这类报告的 OSS 维护者，把「接入前要准备什么」和「收到报告后按什么顺序处理」两段流程讲清楚。

需要先说明一个前提：本教程整理的是服务本身的机制与操作流程，不涉及任何实际注册或实际收报的经验。所有涉及价格、配额、支持范围、联系方式等易变信息，请以官网当前公布的内容为准。

准备工作

先判断项目是否适合接入

OSS Scanner 并不是对所有开源项目开放。官方在评估时主要看两个维度：一是项目是否暴露在远程攻击面之下，例如处理不可信输入的库；二是项目的使用者数量与被依赖程度。此外，注册时会人工核验申请人是否为项目的核心维护者。因此在动手写配置之前，先回答两个问题：

  • 项目里是否存在处理不可信输入的代码路径，例如跨网络接收的数据、用户上传的文件？
  • 如果每周收到数条 high / critical 级别的报告，团队里是否有人能在合理时间内看完并处理？

第二个问题尤其关键。官方对接收方提出的隐含条件是：项目已经具备处理经过验证的 high / critical 漏洞报告的能力。如果团队规模小、没有稳定的安全响应人力，那么勉强接入只会积压报告。官方也为这类项目保留了另一条路径——继续按项目自己的漏洞披露策略接收人工验证过的披露。不注册本身不会带来任何劣势。

准备接收渠道

报告的收件人由 project.yaml 中的两个字段决定：primary_contact（必填）与 auto_ccs（可选）。这里有三个必须先想清楚的点：

  • 邮箱地址会被公开。写进 project.yaml 的地址是公开可见的，因此应当使用类似 security@ 这样的角色别名，而不是维护者的个人邮箱，否则会变成垃圾邮件与定向钓鱼的入口。
  • PGP 加密与 CC 不能同时使用。如果在配置中设置了 pgp 公钥，报告会被加密，但收件人只剩 primary_contact 一个，auto_ccs 不再生效。
  • SECURITY.md 是另一条独立通道。OSS Scanner 本身并不要求项目提供 SECURITY.md，但 GitHub 的文档建议在 SECURITY.md 中写明受支持的版本范围与漏洞报告方式。由于项目还会收到来自其他渠道的报告，把入口统一到一处，后续分流会轻松很多。

如果由团队共同接收，需要先做一个取舍：要加密（只有一个收件人），还是要即时共享（不加密、用 CC 分发）。小规模项目通常更适合「公开别名 + CC」的组合，因为加密之后还需要另外设计一套解密后如何共享的流程。

准备威胁模型与构建环境

threat_model 字段是可选的，但官方仓库的 README 与模板都强烈建议填写。模板给出的结构包含五个部分：

部分写什么示例
项目做什么、不可信输入从哪来说明输入边界压缩库，所有输入都视为不可信
重要组件 / 非重要组件划定扫描关注范围解码器是重点；contrib/ 属第三方，不在范围内
如何运行给出可执行的入口examples/ 下有小驱动，test/ 下有回归语料
如何评定严重级别给出项目自己的定级标准缓冲区溢出至少 high；可导致 RCE 则 critical；DoS 一律 medium
不希望被报告的内容排除已知无害或有意为之的行为x86 SIMD 路径上的非对齐访问不必报告

其中第四项「如何评定严重级别」是对「严重级别虚高」这一问题最直接的应对手段：提前把项目自己的定级标准交给扫描器，收到报告后重新定级的负担就会小很多。

构建环境通过 Dockerfile 提供。需要注意其运行方式：首次初始化阶段可以联网，之后的安全审计阶段在无网络条件下运行。这意味着构建与测试所需的一切依赖，都必须在 Dockerfile 阶段完成下载与安装。Dockerfile 建议放在项目自己的仓库里，这样每次调整构建步骤都不必向注册仓库提 PR。

本地工具

提交注册 PR 之前，需要在本地做校验，所需环境为 git、Docker，以及装有 PyYAML 的 Python 3。

操作步骤

第一步：编写 project.yaml

在注册仓库中新建 projects/<name>/project.yaml。下面是一个结构示例，其中的值均为占位内容，请替换为项目自己的信息：

# projects/example-lib/project.yaml
repo: https://github.com/example/example-lib
primary_contact: security@example.org
auto_ccs:
  - maintainer@example.org
homepage: https://example.org
# pgp: 填入公钥后，报告将加密发送，且 auto_ccs 不再生效
disabled: false
dockerfile: .oss-scanner/Dockerfile
threat_model: .oss-scanner/threat_model.md

几个字段的取舍：primary_contact 必填且会公开；auto_ccs 用于团队共享；dockerfile 与 threat_model 指向项目仓库内的相对路径；disabled 用于临时暂停报告（见注意事项）。

第二步：本地校验

提交之前先用仓库自带的校验脚本检查目录结构：

python3 tools/validate.py projects/<name>/

然后用 tools/check 在与扫描器相同的条件下做一次构建，并进入无网络的 shell 验证测试能否通过：

tools/check <name>

README 中的判断标准是：如果构建出的镜像里测试能够通过，那么扫描器大概率也能正常工作。注意：tools/check 会以联网方式运行 Dockerfile，因此只应对可信的项目使用。

第三步：提交注册 PR

向注册仓库提交一个只新增 projects/<name>/ 目录内容的 PR。该仓库只接受这一路径下的改动，对 tools/、templates/ 等目录的贡献不会被接受。PR 合并后，扫描会按服务侧的节奏定期运行。

第四步：收到报告后先复现

报告由模型生成，官方也承认其可能不准确，因此在把内容当作事实之前，必须先复现。复现时有三个要点：

  • 在隔离环境中运行 PoC。扫描器一侧的 agent 本身运行在禁用互联网连接的沙箱中；接收方同样应当在断网的容器里执行 PoC，避免复现过程本身带来风险。
  • 固定版本。报告中在可能的情况下会附带二分定位结果，指出缺陷是在哪个提交引入的。这对判断受影响版本范围、决定是否需要向后移植修复很有帮助。
  • 先怀疑重复。在早期验证中，未达到披露标准的报告里有相当比例属于与已知问题或其他报告重复的情况。复现前先检索已有 Issue、安全公告，以及经由漏洞聚合渠道转来的报告。

第五步：按自己的标准重新定级

报告中的严重级别只作为起点，最终级别要对照第一步写好的威胁模型重新评估。可以从三个角度审视：

  • 可达性：不可信输入是否真的能到达出问题的代码？如果只有测试或内部工具会调用，级别应当下调。
  • 影响范围：只是崩溃，还是内存破坏进而可导致任意代码执行？
  • 默认配置下的暴露面：问题是否只存在于默认关闭的功能中？

无论上调还是下调，都建议通过回复邮件说明理由。官方将邮件回复列为反馈的推荐途径。

第六步：修复与披露决策

报告附带的补丁建议只是「可用时的候选」，不应直接合并，而要经过常规代码审查与回归测试。披露时机由维护者自己决定：OSS Scanner 对未经人工验证的指摘不设 90 天协调披露期限，Anthropic 一侧也不会主动公开。修复版本发布后是否发布 GitHub 安全公告、是否申请 CVE，按项目自身策略决定。如果要在致谢中署名，官方示例的格式是在其中包含报告 ID，例如 Discovered by Anthropic's OSS Scanner, as vulnerability ANT-2026-ABCD1234。

一个完整示例

假设维护一个处理压缩文件的 C 库，希望接入扫描。完整流程如下。

1. 在项目仓库中准备构建与威胁模型文件。

example-lib/
├── .oss-scanner/
│   ├── Dockerfile
│   └── threat_model.md
├── examples/
├── test/
└── src/

2. 编写 Dockerfile。关键约束是：审计阶段无网络，所有依赖必须在构建阶段装好。

FROM debian:stable-slim
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      build-essential cmake git \
 && rm -rf /var/lib/apt/lists/*
WORKDIR /src
COPY . .
RUN cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug \
 && cmake --build build -j
RUN ctest --test-dir build --output-on-failure

3. 编写 threat_model.md。按模板五段式填写，重点写清不可信输入边界、重要组件、运行方式、定级标准与不希望被报告的内容。

4. 在注册仓库中新增配置。

# projects/example-lib/project.yaml
repo: https://github.com/example/example-lib
primary_contact: security@example.org
auto_ccs:
  - maintainer@example.org
disabled: false
dockerfile: .oss-scanner/Dockerfile
threat_model: .oss-scanner/threat_model.md

5. 本地校验并提交。

python3 tools/validate.py projects/example-lib/
tools/check example-lib
git checkout -b add-example-lib
git add projects/example-lib/
git commit -m "Add example-lib to OSS Scanner"
git push origin add-example-lib

随后在注册仓库发起 PR，等待人工核验维护者身份与项目适配性。

6. 收到报告后的处理。把 PoC 放进断网容器复现，核对二分结果确定受影响版本，检索已有 Issue 与安全公告排除重复，对照威胁模型重新定级，回复邮件说明定级理由，最后走常规审查流程合入修复并决定是否发布安全公告。

注意事项

构建失败怎么办

如果 Anthropic 侧的基础设施构建失败，primary_contact 会收到一封带错误信息的邮件。此时应检查 Dockerfile 是否在无网络条件下仍能取得全部所需依赖——最常见的原因就是审计阶段还需要联网下载。

报告太多处理不过来

在 project.yaml 中设置 disabled: true，可以保留注册状态而暂停报告。如果决定彻底退出，则删除 projects/<name>/ 目录。

未注册项目的咨询

尚未注册的项目如需咨询，官方提供了单独的咨询邮箱，具体地址请以官网当前信息为准。

准确率数字只是目标

官方给出的 true positive 率预期是超过 90%，这属于目标值，不能作为逐条报告都正确的保证。早期验证中，被评估的 critical / high 报告绝大多数符合协调披露标准，未达标的部分主要是重复而非误报；同时也有维护者反馈严重级别被夸大、项目威胁模型被误解的情况。因此「逐条复现 + 自行定级」不是可选项，而是流程的固定环节。

没有期限意味着没有外部推动力

不设 90 天期限对维护者是好事，但也意味着没有人替你设定截止时间。来自人类研究者的报告天然带有时间压力，而这类报告即使搁置，外部压力也很小。建议在 SECURITY.md 或团队内部约定中自行写明「从收到到完成复现确认」的目标天数。

威胁模型决定报告质量

严重级别错误与威胁模型误解是官方自己承认的弱点。模板中设置定级栏与「不希望被报告的内容」栏，正是用接收方的输入来弥补这一弱点。接入时最该花时间的不是 project.yaml，而是 threat_model.md。

加密与共享的取舍

启用 PGP 后收件人只剩一个，团队接收就需要另外设计解密后的共享方式。规模较小的项目，公开别名加 CC 往往更现实。

配套支持项目

官方同时公布了若干面向维护者的支持措施，包括面向开源维护者的 Claude 订阅申请计划、面向防御用途的网络安全功能扩展访问计划，以及对多个开源基金会与漏洞聚合机构的资金支持。具体资格、额度与申请方式请以官网当前信息为准。

返回