OSS-Fuzz 新项目准入指南:提交条件、project.yaml 配置与验收流程
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。
二、提交新项目的总体流程
原文档给出的提交流程非常简洁,总共三步:
- 创建一个 Pull Request,其中包含新的
projects/<project_name>/project.yaml文件(示例见 projects/libarchive/project.yaml)。- 注意:
project_name只能包含字母数字字符(alphanumeric)、下划线(_)或短横线(-)。
- 注意:
- 在该文件中提供以下信息:
- 项目主页(
homepage) - 项目主仓库 URL(
main_repo) - 项目主语言(
language) - 工程联系人的邮箱地址(
primary_contact),用于在新 issue 上抄送,且需满足下述资质要求。
- 项目主页(
- 项目被接受后,按照 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(项目主语言)
声明项目的主要编程语言。当前仓库支持并在文档中列出的取值包括:
cc++go(参见 docs/getting-started/new-project-guide/go_lang.md)rust(参见 docs/getting-started/new-project-guide/rust_lang.md)python(参见 docs/getting-started/new-project-guide/python_lang.md)jvm(Java、Kotlin、Scala 及其他 JVM 语言,参见 docs/getting-started/new-project-guide/jvm_lang.md)swift(参见 docs/getting-started/new-project-guide/swift_lang.md)javascript(参见 docs/getting-started/new-project-guide/javascript_lang.md)
language 字段决定后续使用哪种基础镜像(base image)以及相应的构建工具链,例如 Go 项目使用 gcr.io/oss-fuzz-base/base-builder-go。
4.4 primary_contact(工程联系人,资质要求最严格)
primary_contact 是新 issue 会被抄送的邮箱地址,也是所有联系人中要求最严格的字段,必须同时满足以下两条:
- 该地址属于项目已确立的 committer(established project committer),以版本控制系统(VCS)日志为准。
- 如果该地址不是你自己,或者与 VCS 提交记录中的地址不一致,OSS-Fuzz 会要求进行一次非正式的邮箱验证(informal email verification)。
- 该地址必须关联一个 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 的官方说明可以帮助你自我评估项目是否合适:
- 如何判断项目是否适合? 重点找那些"消费不可信输入"(用户输入、网络数据)、"消费复杂输入数据(即使被信任)"、或存在"两套及以上算法实现"(可用于等价性验证)的代码位置;同时参考 projects 下已有项目的 fuzz target 寻找相似性。
- 为什么 bug 默认归档在 OSS-Fuzz 的 issue tracker? 出于安全访问控制考虑,OSS-Fuzz 检测到的问题默认只归档在 OSS-Fuzz tracker;如需在 GitHub 可见,可在
project.yaml中增加file_github_issue属性(仅为可见性目的,实际细节仍需跳转 OSS-Fuzz tracker 查看)。 - fuzz target 源码与构建脚本暂未被上游接受怎么办? 可以暂时存放在 OSS-Fuzz 仓库的
projects/<your_project>目录中;但 OSS-Fuzz 不接受依赖 fork 仓库的集成方式,长期方案参考 ideal integration 指南。
七、总结:从准入到上线的关键要点
- 先自我评估:项目是否满足"显著用户基础"或"对全球 IT 基础设施至关重要"的准入标准,评估维度可参考 docs/faq.md。
- 命名合规:
projects/<project_name>/必须符合正则^[a-z0-9_-]+$(见 infra/presubmit.py),否则 PR 会被 presubmit 拦截。 - 信息完整:
project.yaml至少包含homepage、main_repo、language、primary_contact四个必需字段。 - 联系人资质:
primary_contact必须是 VCS 日志中的项目 committer 邮箱,且关联 Google 账号;避免使用备用邮箱以免丢失 ClusterFuzz dashboard 访问权限(AppEngine API 限制)。 - 接受后继续:按照 New Project Guide 补齐 Dockerfile 与 build.sh,并用
infra/helper.py本地验证构建、运行与覆盖率,再合入 PR,等待自动构建与 ClusterFuzz 上线(通常不到 1 天)。
至此,一个开源项目从"申请准入"到"被接受并进入正式配置"的完整路径已经清晰:提交一个合规的 project.yaml PR 只是第一步,后续的构建脚本与 fuzz target 质量才是决定项目能否长期高效运行模糊测试的关键。