OSS-Fuzz 新项目准入指南:提交条件、project.yaml 配置与验收流程

原创2026-09-23 19:30:001,941 阅读
文章标签:网络安全开发工具CI/CD

OSS-Fuzz 新项目准入指南:提交条件、project.yaml 配置与验收流程

本文围绕 OSS-Fuzz 的《Accepting New Projects》指南展开,系统讲解开源项目加入 OSS-Fuzz 的准入标准、Pull Request 提交流程、project.yaml 必需字段(homepage、main_repo、language、primary_contact)的填写要求与资质验证规则,并结合当前仓库的源码(如 infra/presubmit.py 中的项目名校验正则)与真实项目配置(如 projects/libarchive/project.yaml)做纵深印证。读完本文,你将清楚"什么项目能被接受、如何正确提交、提交后如何进入配置阶段",并能独立完成新项目的准入 PR。

一、OSS-Fuzz 接受什么类型的项目

OSS-Fuzz 是面向开源软件的持续模糊测试(continuous fuzzing)基础设施,其核心价值在于"集中式、可扩展地"为开源项目长期运行模糊测试。因此,并不是所有开源项目都能直接加入。准入的核心标准是:

一个开源项目必须拥有显著的用户基础(significant user base),或者对全球 IT 基础设施至关重要(critical to the global IT infrastructure)。

这一标准与 docs/faq.md 中"我们接受哪些类型的项目"的说明相互印证:OSS-Fuzz 会逐案评估(case-by-case)每个申请,但评估时会重点考虑:

  • 是否暴露于远程攻击面:例如被用来处理不可信输入(untrusted input)的库。这类代码一旦出现内存安全漏洞,影响面通常是"一个输入打穿整个依赖链",模糊测试价值最高。
  • 用户数 / 依赖该项目的其他项目数量:被越多项目依赖,其漏洞放大效应越强,优先接入的合理性越大。

从 docs/faq.md 的表述看,OSS-Fuzz 也提到"希望未来放宽该要求",因此即使当前未被接受,也可以持续关注。需要特别说明的是:非开源项目不能使用 OSS-Fuzz,但可以使用 ClusterFuzz(OSS-Fuzz 所基于的开源模糊测试基础设施)在自有环境中部署运行。

从术语上理解,一个被接受的"项目(Project)"在 docs/reference/glossary.md 中被定义为:已与 OSS-Fuzz 集成的开源软件项目,每个项目拥有一组配置文件(如 projects/expat),并可能包含一个或多个 fuzz target。

二、提交新项目的总体流程

原文档给出的提交流程非常简洁,总共三步:

  1. 创建一个 Pull Request,其中包含新的 projects/<project_name>/project.yaml 文件(示例见 projects/libarchive/project.yaml)。
    • 注意:project_name 只能包含字母数字字符(alphanumeric)、下划线(_)或短横线(-)。
  2. 在该文件中提供以下信息:
    • 项目主页(homepage)
    • 项目主仓库 URL(main_repo)
    • 项目主语言(language)
    • 工程联系人的邮箱地址(primary_contact),用于在新 issue 上抄送,且需满足下述资质要求。
  3. 项目被接受后,按照 New Project Guide 完成后续配置。

三、project_name 的命名约束:源码级验证

原文档强调 project_name 只能包含字母数字、下划线(_)和短横线(-)。在 OSS-Fuzz 仓库中,这一约束并非仅靠文档约定,而是由提交前检查(presubmit)代码强制执行的。

在 infra/presubmit.py 中可以看到:

VALID_PROJECT_REGEX_STR = '^[a-z0-9_-]+$'
VALID_PROJECT_REGEX = re.compile(VALID_PROJECT_REGEX_STR)

对应的检查逻辑(check_valid_project_name)会取 projects/<name>/ 目录名进行正则匹配:

project_name = os.path.basename(os.path.dirname(self.filename))
...
if not VALID_PROJECT_REGEX.match(project_name):
    self.error(f'Projects must conform to regex {VALID_PROJECT_REGEX_STR}')

这意味着:

  • 实际生效的正则是 ^[a-z0-9_-]+$,即小写字母、数字、下划线、短横线的组合,且不允许空格、点号、斜杠等字符;
  • 提交 PR 时若目录名不合法,presubmit 会直接报错拦截;
  • 参考 projects/ 目录下的命名,如 libarchive、boringssl、expat、c-ares、json-c 等,均符合该正则。

此外,该检查还会过滤被禁止的项目名(banned names),具体逻辑同样位于 infra/presubmit.py 的 check_valid_project_name 中(先检查 banned 名称,再检查正则)。

四、project.yaml 必需字段详解

准入 PR 的核心是 projects/<project_name>/project.yaml。下面结合 docs/getting-started/new_project_guide.md 的字段定义,逐一说明这 4 个必需字段的含义与填写要点。

4.1 homepage(项目主页)

填写项目官方主页 URL。它通常是项目网站或托管在 GitHub 等平台上的仓库主页,用于在 OSS-Fuzz 界面中展示项目入口。

4.2 main_repo(主仓库 URL)

指向托管项目源代码的仓库地址,例如 https://path/to/main/repo.git。在实际配置中,projects/libarchive/project.yaml 的写法是:

main_repo: 'https://github.com/libarchive/libarchive.git'

projects/boringssl/project.yaml 则使用了非 GitHub 的源码托管地址:

main_repo: 'https://boringssl.googlesource.com/boringssl'

可见 main_repo 不限于 GitHub,只要是可克隆的源码仓库地址即可。它是后续构建时拉取代码的依据。

4.3 language(项目主语言)

声明项目的主要编程语言。当前仓库支持并在文档中列出的取值包括:

language 字段决定后续使用哪种基础镜像(base image)以及相应的构建工具链,例如 Go 项目使用 gcr.io/oss-fuzz-base/base-builder-go。

4.4 primary_contact(工程联系人,资质要求最严格)

primary_contact 是新 issue 会被抄送的邮箱地址,也是所有联系人中要求最严格的字段,必须同时满足以下两条:

  1. 该地址属于项目已确立的 committer(established project committer),以版本控制系统(VCS)日志为准。
    • 如果该地址不是你自己,或者与 VCS 提交记录中的地址不一致,OSS-Fuzz 会要求进行一次非正式的邮箱验证(informal email verification)。
  2. 该地址必须关联一个 Google 账号。

为什么必须关联 Google 账号?docs/faq.md 中专门回答了这个问题:OSS-Fuzz 的 ClusterFuzz 模糊测试基础设施和 issue tracker 都要求使用 Google 账号进行身份认证。

关于备用邮箱的注意事项(容易踩坑):如果使用一个关联到 Google 账号的备用邮箱(alternate email),那么你只能访问 issue tracker 中被提交的 bug(即 OSS-Fuzz issue tracker 中的已归档问题),无法访问 ClusterFuzz dashboard。原因是 AppEngine API 的限制(due to appengine API limitations)。这一点在原文档中作为重要提示明确标注,填写 primary_contact 前务必确认使用的是真正的 Google 账号主邮箱。

从 projects/libarchive/project.yaml 的真实配置看:

homepage: "https://github.com/libarchive/libarchive"
language: c++
primary_contact: "joerg.sonnenberger@googlemail.com"
auto_ccs:
  - "kientzle@gmail.com"
  - "martin@matuska.org"

primary_contact 是单个邮箱;除此之外,项目还可以通过可选的 auto_ccs 字段列出其他联系人。这些列出的每个人都会获得 ClusterFuzz 的访问权限(包括崩溃报告与 fuzzer 统计信息),并会在 OSS-Fuzz tracker 中归档的新 bug 上被自动抄送。

五、接受后的下一步:进入配置阶段

accepting_new_projects.md 明确说明:一旦项目被接受,就应当跟随 New Project Guide 完成正式配置。也就是说,准入 PR 只是"敲门砖",完整的接入还需要在 projects/<project_name>/ 下补齐三个关键文件:

  • project.yaml:项目元数据(准入 PR 中已提供,接受后可再补充可选字段);
  • Dockerfile:定义构建容器环境,声明构建项目及 fuzz target 所需的依赖;
  • build.sh:在容器内执行的构建脚本,负责产出 fuzz target 二进制。

从项目目录结构看(见 projects 下的各项目),每个项目目录都遵循这一"project.yaml + Dockerfile + build.sh"的组织方式。配置完成后,可以通过 infra/helper.py 本地验证:

cd /path/to/oss-fuzz
export PROJECT_NAME=<project_name>
export LANGUAGE=<project_language>
python infra/helper.py generate $PROJECT_NAME --language=$LANGUAGE
python infra/helper.py build_image $PROJECT_NAME
python infra/helper.py build_fuzzers --sanitizer address $PROJECT_NAME
python infra/helper.py check_build $PROJECT_NAME

其中 generate、build_image、build_fuzzers、check_build 等命令均定义在 infra/helper.py(对应 generate、build_image、build_fuzzers、check_build 等函数)。

关于 project.yaml 中可选字段的补充说明(接受项目后按需配置):

  • sanitizers(可选):取值 address、memory、undefined;默认启用 address 与 undefined。memory(MemorySanitizer)虽被推荐,但因未插桩的系统依赖容易产生误报,默认不启用;启用时需要用 MemorySanitizer 编译项目所需的全部库。也可以用 experimental: True 将某个 sanitizer 标记为试验性,仅生成崩溃不归档 issue(示例见 projects/libarchive/project.yaml 中 memory 的写法)。
  • architectures(可选):默认 x86_64,可增加 i386 以发现 32 位特有或仅影响 32 位用户的 bug(示例见 projects/expat/project.yaml)。
  • fuzzing_engines(可选):默认使用 libfuzzer、afl、honggfuzz、centipede;其中 libfuzzer 为 OSS-Fuzz 所必需。示例见 projects/expat/project.yaml。
  • vendor_ccs(可选):下游消费方(vendor)的邮箱列表,用于在 bug 归档时同步获知;变更需经项目维护者批准且必须使用组织邮箱。
  • builds_per_day(可选):每天构建次数,OSS-Fuzz 允许最多 4 次,默认 1 次。
  • file_github_issue(可选):是否将 issue 镜像到 GitHub,而不只在 OSS-Fuzz tracker 归档。

六、常见疑问与评估参照

在提交准入 PR 前,以下几点来自 docs/faq.md 的官方说明可以帮助你自我评估项目是否合适:

  1. 如何判断项目是否适合? 重点找那些"消费不可信输入"(用户输入、网络数据)、"消费复杂输入数据(即使被信任)"、或存在"两套及以上算法实现"(可用于等价性验证)的代码位置;同时参考 projects 下已有项目的 fuzz target 寻找相似性。
  2. 为什么 bug 默认归档在 OSS-Fuzz 的 issue tracker? 出于安全访问控制考虑,OSS-Fuzz 检测到的问题默认只归档在 OSS-Fuzz tracker;如需在 GitHub 可见,可在 project.yaml 中增加 file_github_issue 属性(仅为可见性目的,实际细节仍需跳转 OSS-Fuzz tracker 查看)。
  3. fuzz target 源码与构建脚本暂未被上游接受怎么办? 可以暂时存放在 OSS-Fuzz 仓库的 projects/<your_project> 目录中;但 OSS-Fuzz 不接受依赖 fork 仓库的集成方式,长期方案参考 ideal integration 指南。

七、总结:从准入到上线的关键要点

  1. 先自我评估:项目是否满足"显著用户基础"或"对全球 IT 基础设施至关重要"的准入标准,评估维度可参考 docs/faq.md。
  2. 命名合规:projects/<project_name>/ 必须符合正则 ^[a-z0-9_-]+$(见 infra/presubmit.py),否则 PR 会被 presubmit 拦截。
  3. 信息完整:project.yaml 至少包含 homepage、main_repo、language、primary_contact 四个必需字段。
  4. 联系人资质:primary_contact 必须是 VCS 日志中的项目 committer 邮箱,且关联 Google 账号;避免使用备用邮箱以免丢失 ClusterFuzz dashboard 访问权限(AppEngine API 限制)。
  5. 接受后继续:按照 New Project Guide 补齐 Dockerfile 与 build.sh,并用 infra/helper.py 本地验证构建、运行与覆盖率,再合入 PR,等待自动构建与 ClusterFuzz 上线(通常不到 1 天)。

至此,一个开源项目从"申请准入"到"被接受并进入正式配置"的完整路径已经清晰:提交一个合规的 project.yaml PR 只是第一步,后续的构建脚本与 fuzz target 质量才是决定项目能否长期高效运行模糊测试的关键。

登录后查看全文
oss-fuzz