osv-scanner 开源贡献实战指南：从报告问题、构建测试到提交 PR 的完整流程

osv-scanner 开源贡献实战指南从报告问题、构建测试到提交 PR 的完整流程【免费下载链接】osv-scannerVulnerability scanner written in Go which uses the data provided by https://osv.dev项目地址: https://gitcode.com/GitHub_Trending/os/osv-scanner本文面向希望参与 osv-scanner 开源项目的开发者系统梳理从报告 Bug、搭建开发环境、构建二进制、运行测试与快照Snapshot/VCR 录制体系、通过 lint 检查到按 Conventional Commits 规范提交 PR、以及为文档仓库做贡献的完整流程。读完本文你将掌握 osv-scanner 的 Makefile 测试目标、SNAPS/ACC/VCR等测试开关的真实含义与源码级实现能够独立完成一次高质量的开源贡献。贡献入口先报告问题再谈代码osv-scanner 的贡献流程严格遵循Issue 优先Issue-First的工作流即Issue 分配 - Pull Request。无论是新功能、Bug 修复还是其他改进都应先创建 Issue 讨论方案并等待被分配而不是直接提交 PR。这样做可以确保你的工作与项目目标一致并避免重复劳动。报告问题Report Problems如果你发现了疑似 Bug请走以下路径使用项目的 GitHub issue 跟踪系统提交问题提交前务必先搜索已有 Issue确认你的问题是否已被覆盖避免重复提交报告 Bug 时应包含清晰的真实世界场景和最小可复现用例并说明期望行为与实际行为。仓库根目录的 AGENTS.md 进一步细化了该工作流的细节已有但未分配的 Issue在 Issue 下评论你的方案并等待分配无对应 Issue先创建 Issue 说明为什么需要这项工作并确认没有重复已被他人分配的 Issue不要重复开工或为其打开 PR如果某 Issue 长期无人处理可在 Issue 中与维护者沟通。贡献前需要了解的协作约定贡献者许可协议CLA对项目的贡献必须附带 Contributor License Agreement。你或你的雇主保留贡献的版权协议只是授予项目使用和再分发贡献的许可。一般只需签署一次如果你已为其他项目签过通常无需重复签署。代码评审所有提交包括项目成员自身的提交都必须经过评审评审通过 GitHub Pull Request 进行。PR 模板创建 PR 时请使用仓库提供的 PR 模板见 CONTRIBUTING.md 中引用的.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md并填写各部分内容以保障评审顺畅。社区准则项目遵循 Google 的开源社区行为准则。开发环境准备根据 CONTRIBUTING.md开始编码前需要安装Go 1.21以go version检查当前仓库 go.mod 中声明的 Go 版本为1.27.0go 1.27.0这是测试的基准版本GoReleaser可选仅当你需要可复现构建时。注意scripts/目录下的脚本预期在仓库根目录下运行。一个实用的环境技巧为了获得一致的测试结果请使用与 go.mod 一致的 Go 工具链运行例如GOTOOLCHAINgo1.27.0。当你的本机 Go 版本过旧导致 lint 或测试工具链报错时同样可以通过GOTOOLCHAINgo版本切换编译器版本例如GOTOOLCHAINgo1.27.0 ./scripts/run_lints.sh。构建 osv-scanner 二进制方式一仅用 go 构建在项目目录执行./scripts/build.sh该脚本内容非常简单本质上是一条go build命令见 scripts/build.sh#!/usr/bin/env bash set -e go build ./cmd/osv-scanner/构建产物osv-scanner二进制会出现在项目目录中。也可以使用 Makefile 目标make build。方式二用 goreleaser 构建快照如果你需要可复现构建reproducible builds可以安装 GoReleaser 后执行./scripts/build_snapshot.sh其内容为见 scripts/build_snapshot.shgoreleaser build --clean --single-target --snapshot此外你还可以检出特定 release tag并使用与正式发布时相同的 Go 版本执行goreleaser build从而复现官方发布的可下载构建产物。日常调试小工具Makefile 还提供了make scanner目标等价于go run ./cmd/osv-scanner $(ARGS)方便在开发时直接运行扫描器例如make scanner ARGSscan ./cmd/osv-scanner/fix/testdata/in-place-npm测试体系make test 与四种测试开关运行测试make test查看所有测试目标与可用选项make help测试模式开关详解make test支持四个环境变量开关分别控制测试的广度与快照行为见 Makefile 的test目标注释与变量默认值变量默认值作用SNAPStruefalse更新快照测试snapshot testsACCtruefalse运行需要额外依赖的验收测试acceptance testsSHORTfalsetrue运行完整测试套件而非默认的短套件VCRmodeReplayWithNewEpisodes设置 VCR 录制模式详见下文默认情况下需要除 Go 工具链之外额外依赖的测试会被跳过通过以下命令启用make test ACCtrue例如ACCtrue会触发 scripts/run_tests.sh 中的scripts/build_test_images.sh构建测试所需的容器镜像用于容器/镜像扫描相关的验收测试。run_tests.sh 的两种运行形态scripts/run_tests.sh 根据环境区分执行方式在 CI 中存在CI环境变量执行go test ./... -coverpkg./... -coverprofile coverage.out测试的同时生成覆盖率数据本地通过go run gotest.tools/gotestsumv1.13.0 ./...运行gotestsum 提供更友好的测试输出若设置DOCKER_TESTtrue则构建osv-scanner-test镜像并在容器内运行测试容器会挂载 Docker socket 以支持容器扫描类测试。生成 HTML 覆盖率报告./scripts/generate_coverage_report.sh该脚本先运行测试生成coverage.out再用go tool cover -html输出coverage.html见 scripts/generate_coverage_report.sh。快照测试SNAPS 与 update-snapshots仓库大量使用快照测试snapshot tests期望输出被固化在.snap文件中例如cmd/osv-scanner/__snapshots__/main_test.snap、cmd/osv-scanner/scan/__snapshots__/command_test.snap等。当你修改了影响输出的行为时需要重新生成快照make test SNAPStrue注意部分长时间运行的测试会被跳过其快照不会更新。要更新全部快照使用make update-snapshots # 等价于make test SNAPStrue ACCtrue SHORTfalse若要与 CI 测试环境完全一致的刷新全部快照所有测试、重新录制 VCR、更新快照make refresh-all # 等价于make test ACCtrue SHORTfalse VCRRecordOnly SNAPStrue关于快照冲突还有一个实用建议在解决合并冲突时如果快照文件冲突通常直接以更新标志重新运行测试、重建快照比手动解析 diff 更省力。VCR 模式让 osv.dev 请求可复现cmd相关测试使用go-vcr为发往 osv.devquerybulk端点的请求提供自定义http.Client并把请求/响应记录为**磁带cassette**快照文件以减少安全公告变化带来的测试噪音同时提供较高的置信度。VCR 模式通过make test VCRmode控制。可用的模式见 Makefile 与 vcr.go 中的determineRecorderMode值名称/数字行为RecordOnly/0只录制新的磁带ReplayOnly/1只回放磁带缺失即报错ReplayWithNewEpisodes/2回放已有交互新交互录制并追加本地默认RecordOnce/3仅在缺失时录制Passthrough/4禁用 VCR直连网络# 示例禁用 VCR直通网络请求 make test VCRPassthrough本地默认模式是ReplayWithNewEpisodes在 CI 中默认是ReplayOnly缺失交互直接报错见 vcr.go。从源码看VCR 的实现还有几个值得注意的设计细节见 cmd/osv-scanner/internal/testcmd/vcr.goPassthrough 白名单/v1/vulns/路径的漏洞详情请求体量大、对快照影响小以及.zip/.gz/.bin/.db/.tar/.tgz/.jar/.aar/.whl等二进制下载请求不进入磁带自定义匹配器仅按 Method、URL、Headers、Body 匹配请求忽略User-Agent、Content-Length等易变头JSON 请求体在做键排序规范化后比较磁带去噪 Hook录制时删除Date、Server、Etag等易变响应头将响应时长置 0并对 JSON 体做键排序格式化显著减小磁带体积与 diff测试名头注入每个请求会附加X-Test-Name头测试结束时磁带内的交互按测试名排序进一步缩小交互变更时的 diff磁带缺失诊断当请求未命中磁带时工具会输出详细的差异报告记录请求与实际请求的 diff便于定位是测试改动还是网络环境问题vcr.go。测试数据的特殊约定如果你为测试添加了带已知漏洞的 lockfile还应在测试数据目录中添加一个osv-scanner.toml配置文件将这些漏洞从仓库自身的扫描结果中排除参见 configuration.md 了解配置格式。仓库根目录的 osv-scanner.toml 就是这一约定的产物。代码质量Lint 与格式化提交代码前请运行 lint./scripts/run_lints.sh该脚本使用 golangci-lint v2版本号由.golangci-lint-version文件固定默认以GOTOOLCHAINgo1.27.0运行见 scripts/run_lints.shexport GOTOOLCHAIN${GOTOOLCHAIN:-go1.27.0} go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint$(cat .golangci-lint-version) run ./... $Makefile 中也有对应目标make lint # 运行 lint make lint-fix # 运行 lint 并自动修复 make format # 运行格式化脚本scripts/run_formatters.sh自动化验证清单在请求评审之前请确保以下检查全部通过见 AGENTS.mdLint./scripts/run_lints.sh无警告与错误测试make test全部通过覆盖率新功能、Bug 修复或重构必须有对应测试单元、集成或快照测试快照影响快照的行为变更需更新快照如make test SNAPStrueVCR 磁带新增 HTTP 交互的测试需按 CONTRIBUTING.md 的描述录制/更新磁带文档与注释影响用户可见行为或新增功能的变更需同步更新文档复杂逻辑需有清晰注释不要删除仍然有效的旧注释。提交规范Conventional Commits合并提交squash commit通常基于 PR 标题必须遵循 Conventional Commits 规范这有助于自动化 changelog 生成并保持提交历史清晰一致。常用类型包括feat:新功能fix:修复docs:文档chore:杂务refactor:重构PR 标题与提交同样遵循该规范。维护者会依据提交历史自动生成 changelog仓库根目录的 CHANGELOG.md 即由此维护。为文档仓库做贡献除了代码osv-scanner 也欢迎文档贡献。完整的文档贡献步骤如下见 CONTRIBUTING.mdFork 仓库在 Fork 中完成所需的文档修改预览变更为你的 Fork 开启 GitHub Pages并从工作分支构建进入 Fork 的 Settings 页的 Pages 设置Build and deployment 选择 GitHub Actions在.github/workflows/docs-deploy.yml工作流文件的第 5 行on.push.branches中加入你的工作分支推送提交并等待 Pages 构建完成构建成功后点击链接预览文档预览确认无误后记得将你的分支从docs-deploy.yml中移除。对变更满意后打开 PR在 PR 中链接你的 Fork 的 GitHub Pages 地址方便维护者预览变更。如需在本地运行文档站点可以使用./scripts/run_local_docs.sh该脚本基于 docs/docs.Dockerfile 构建osv-scanner-docs镜像并在 4000 端口运行本地文档服务见 scripts/run_local_docs.sh配合 Makefile 的make local-docs目标使用。代码归属与 osv-scalibr 的分工理解代码归属对提对地方的问题至关重要。osv-scanner依赖 osv-scalibr 作为核心分析引擎负责依赖提取与丰富化如漏洞匹配逻辑osv-scanner调用 osv-scalibr 库执行实际的扫描与依赖提取见 AGENTS.md。两者以插件化架构Extractors支撑不同生态依赖提取 / 解析逻辑如某个 lockfile 解析 bug、支持新的包管理器这类逻辑在 osv-scalibr 中实现应在osv-scalibr 仓库提交 Issue 或 PR扫描器 CLI / 输出 / 配置如 CLI 参数、SARIF/JSON 等输出格式、通用配置处理这类变更属于本仓库osv-scanner提交到当前仓库即可。从本仓库的目录结构也能印证这一分工internal/scalibrextract/目录下仅保留了少部分与 osv-scanner 强相关的提取器如 npmnode_modules、osv-scanner JSON、Git 提交等而internal/scalibr/、internal/scalibrplugin/等则是对 osv-scalibr 引擎的封装与插件装配。小结完成一次 osv-scanner 贡献的完整链路是搜索并创建 Issue - 等待分配 - 搭建 Go 1.27 工具链环境 - 编写代码与测试 -make test按需SNAPS/ACC/VCR-./scripts/run_lints.sh- 遵循 Conventional Commits 提交 - 使用 PR 模板发起 PR 并等待评审。文档类贡献则需额外经历 GitHub Pages 预览环节。遵循 CONTRIBUTING.md、AGENTS.md 与本文梳理的流程你的贡献将更容易被维护者接纳也能减少来回修改的成本。【免费下载链接】osv-scannerVulnerability scanner written in Go which uses the data provided by https://osv.dev项目地址: https://gitcode.com/GitHub_Trending/os/osv-scanner创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考