注意:使用 REST API 进行依赖项提交的功能目前为公共 beta 版本,可能会发生更改。
关于 依赖项提交 API
可以使用 REST API 提交项目的依赖项。 这使你可以将依赖项(如编译或生成软件时解析的依赖项)添加到 GitHub 的依赖项关系图功能,从而更全面地了解项目的所有依赖项。
依赖项关系图显示你使用 API 提交的任何依赖项,以及从存储库中的清单或锁定文件(例如 package-lock.json
JavaScript 项目中的文件)标识的任何依赖项。 有关查看依赖项关系图的详细信息,请参阅“探索仓库的依赖项”。
提交的依赖项将收到 Dependabot alerts 和 Dependabot security updates 以处理任何已知的漏洞。 你只会收到来自 GitHub Advisory Database 支持的生态系统之一的依赖关系的 Dependabot alerts。 有关这些生态系统的详细信息,请参阅“关于 GitHub 公告数据库”。 对于通过 依赖项提交 API 提交的可传递依赖项,如果更新可用,Dependabot 将自动打开拉取请求以更新父依赖项。
提交的依赖关系不会显示在依赖关系审查或组织的依赖关系见解中。__
依赖项以快照的形式提交到 依赖项提交 API。 快照是一组与提交 SHA 和其他元数据关联的依赖项,反映提交存储库的当前状态。 可根据生成时检测到的依赖项或软件物料清单 (SBOM) 生成快照。 有 GitHub Actions 支持上述任一用例。 有关 依赖项提交 API 的详细信息,请参阅“适用于依赖项提交的 REST API 终结点”。
在生成时提交依赖项
可以在 GitHub Actions 工作流中使用 依赖项提交 API,从而在生成项目时提交项目的依赖项。
使用预创建的操作
使用 依赖项提交 API 最简单的方法是向存储库添加预创建的操作,该操作将收集依赖项列表并将它转换为所需的快照格式,然后将此列表提交到 API。 GitHub Marketplace 上提供了针对各种生态系统完成这些步骤的操作。 其中一些操作由第三方提供。 可以在下表中找到当前可用操作的链接。
生态系统 | 操作 | 由 GitHub 维护 |
---|---|---|
Go | Go 依赖项提交 | 维护 |
Gradle | Gradle 依赖项提交 | 维护 |
Maven | Maven 依赖关系树依赖项提交 | 维护 |
研磨 | Mill 依赖项提交 | 维护 |
Scala | Sbt 依赖项提交 | 维护 |
NuGet 及其他 | 组件检测依赖项提交操作 | 维护 |
注意:**** 对于组件检测依赖项提交操作,其他受支持的生态系统包括 Vcpkg、Conan、Conda、Crates 以及 NuGet。
例如,以下 Go 依赖项提交工作流将计算 Go 生成目标(带有 main
函数的 Go 文件)的依赖项,并将列表提交到 依赖项提交 API。
name: Go Dependency Submission
on:
push:
branches:
- main
# The API requires write permission on the repository to submit dependencies
permissions:
contents: write
# Environment variables to configure Go and Go modules. Customize as necessary
env:
GOPROXY: '' # A Go Proxy server to be used
GOPRIVATE: '' # A list of modules are considered private and not requested from GOPROXY
jobs:
go-action-detection:
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: ">=1.18.0"
- name: Run snapshot action
uses: actions/go-dependency-submission@v1
with:
# Required: Define the repo path to the go.mod file used by the
# build target
go-mod-path: go-example/go.mod
#
# Optional. Define the repo path of a build target,
# a file with a `main()` function.
# If undefined, this action will collect all dependencies
# used by all build targets for the module. This may
# include Go dependencies used by tests and tooling.
go-build-target: go-example/cmd/octocat.go
创建自己的操作
你还可以编写你自己操作,以便在生成时提交项目的依赖项。 你的工作流应:
- 生成项目的依赖项列表。
- 将依赖项列表转换为 依赖项提交 API 接受的快照格式。 有关格式的详细信息,请参阅在“适用于依赖项提交的 REST API 终结点”中“创建存储库快照”API 终结点的正文参数。
- 将格式化的依赖项列表提交到 依赖项提交 API。
GitHub Enterprise Server 将维护依赖项提交工具包,这是一个 TypeScript 库,可帮助你生成自己的 GitHub 操作,用于将依赖项提交到 依赖项提交 API。 有关编写操作的详细信息,请参阅“创建操作”。
生成和提交软件物料清单 (SBOM)
SBOM 是一份计算机可读的正式清单,其中包含项目的依赖项和相关信息(例如版本和包标识符)。 SBOM 通过以下方式帮助降低供应链风险:
- 让存储库使用的依赖项公开透明
- 支持在流程早期识别漏洞
- 提供有关代码库中可能存在的许可证合规性、安全性或质量问题的见解
- 使你能够更好地遵守各种数据保护标准
生成软件物料清单 (SBOM)
若要生成 SBOM,可以使用:
- GitHub UI。 若要详细了解如何使用依赖项关系图中的信息导出存储库的 SBOM,请参阅“导出存储库的软件物料清单”。
- REST API 有关详细信息,请参阅“适用于软件物料清单 (SBOM) 的 REST API 终结点”。
- GitHub Actions。 以下操作将为存储库生成 SBOM,并将其附加为工作流项目 - 你可下载该项目并在其他应用程序中使用。 若要详细了解如何下载工作流项目,请参阅“下载工作流程构件”。
操作 | 详细信息 | 由 GitHub 维护 |
---|---|---|
SBOM-generator-action | 使用依赖项关系图中的信息生成 SPDX SBOM | 维护 |
Anchore SBOM 操作 | 使用 Syft 通过受支持的生态系统创建与 SPDX 2.2 兼容的 SBOM | 维护 |
Microsoft 提供的 sbom-tool | 扫描依赖项并创建与 SPDX 兼容的 SBOM | 维护 |
将软件物料清单 (SBOM) 提交到 依赖项提交 API
要接收具有已知漏洞的任何依赖项的 Dependabot alerts,可以上传 SBOM 并将其提交到 依赖项提交 API。 要将 SBOM 提交到 依赖项提交 API,可以使用下表中的任意一项操作。
Tip
SPDX 依赖项提交操作和定位点 SBOM 操作可用于生成 SBOM 并将其提交到 依赖项提交 API。
操作 | 详细信息 | 由 GitHub 维护 |
---|---|---|
SPDX 依赖项提交操作 | 使用 Microsoft 的 SBOM 工具通过受支持的生态系统创建与 SPDX 2.2 兼容的 SBOM | 维护 |
Anchore SBOM 操作 | 使用 Syft 通过受支持的生态系统创建与 SPDX 2.2 兼容的 SBOM | 维护 |
SBOM 依赖项提交操作 | 将 CycloneDX SBOM 上传到 依赖项提交 API | 维护 |
例如,以下 SPDX 依赖项提交操作工作流将计算存储库的依赖项,生成 SPDX 2.2 格式的可导出的 SBOM,并将其提交到 依赖项提交 API。
name: SBOM upload
on:
workflow_dispatch:
push:
branches: ["main"]
jobs:
SBOM-upload:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: write
steps:
- uses: actions/checkout@v4
- name: Generate SBOM
# generation command documentation: https://github.com/microsoft/sbom-tool#sbom-generation
run: |
curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
chmod +x $RUNNER_TEMP/sbom-tool
$RUNNER_TEMP/sbom-tool generate -b . -bc . -pn $ -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
- uses: actions/upload-artifact@v3
with:
name: sbom
path: _manifest/spdx_2.2
- name: SBOM upload
uses: advanced-security/spdx-dependency-submission-action@v0.0.1
with:
filePath: "_manifest/spdx_2.2/"