软件物料清单 (SBOM)

软件物料清单（简称“SBOM”）是一份用于共享有关软件及其组成方式的信息的文档。此格式最常在安全领域中使用，用于使用漏洞数据库（如 CVE 和 OSV）检查软件及其依赖项是否存在漏洞。CPython 项目使用的 SBOM 格式是 SPDX，如有必要，消费者可以将其转换为其他格式。

CPython 有多个第三方依赖项来源。有些是提供给 CPython 自身源代码的（如 mpdecimal 提供给 Modules/_decimal/libmpdec），或者它们可以在构建期间（如 Windows）使用来自 python/cpython-source-deps 存储库的依赖项进行可选拉取。

每当添加或更新第三方依赖项时，可能需要对 SBOM 进行更新，以跟踪版本和软件标识符。

更新依赖项

CPython 的捆绑依赖项的 SBOM 保存在 Misc/sbom.spdx.json 中。在将依赖项更新到新版本时，你需要在 SBOM 中编辑此依赖项的版本和其他元数据。

推荐的工作流是

  1. 将新依赖项下载为存档。记下新版本、下载 URL 和已下载存档的校验和。

  2. 更新 CPython 源树中的提供代码。

  3. 编辑 Misc/sbom.spdx.json 以添加相应 package 的新 versionInfo、downloadLocation、checksums 和 externalReferences。对于大多数此类更新，只需更新 URL 和项目标识符中的嵌入式版本即可。不要更新 files 和 relationships 中的任何信息，因为这将由 SBOM 工具自动生成。

  4. 运行 make regen-sbom 或 python Tools/build/generate_sbom.py。确保这不会因验证错误而失败。

  5. 运行 git diff Misc/sbom.spdx.json 并检查 diff 是否与预期更改匹配。

  6. 将更改提交到 Misc/sbom.spdx.json，以及对依赖项代码的更新。

添加新依赖项

添加依赖项时，重要的是拥有以下信息

  • 项目的名称、版本和下载 URL

  • 项目的许可证，作为 SPDX 许可证表达式

  • 与漏洞数据库中的值匹配的软件标识符 (CPE 和 软件包 URL 或“PURL”)

  • 与此依赖项对应的 CPython 源代码树中要包含和排除的路径

收集此信息后

  1. 将信息添加到文件 Misc/sbom.spdx.json 中 packages 的新条目中。不用担心格式，该工具会自动格式化您手动编写的 JSON。要填写的字段包括

    • name 表示项目名称。

    • SPDXID 将是 "SPDXRef-PACKAGE-{name}"。

    • licenseConcluded 表示项目许可证的 SPDX 许可证标识符。

    • versionInfo 表示项目的版本。

    • downloadLocation 应是项目下载的 HTTPS URL（作为存档）。

    • checksums[0].checksumValue 和 .algorithm 将是下载的存档的 SHA-256 校验和。

    • originator 表示原始作者信息，根据作者/维护情况，前缀为 Organization: 或 Person:。

    • primaryPackagePurpose 可能为 "SOURCE"。

    • externalReferences 是一个或多个项目标识符的列表，可以是 CPE 或软件包 URL。referenceLocator 的值必须包含 versionInfo 中的值，以确保标识符对应于软件的正确版本。您可以在 SPDX SBOM 规范 中阅读有关外部引用的更多信息。

  2. 如果要使用新的许可证 ID，请将许可证表达式添加到 Tools/build/generate_sbom.py 中的 ALLOWED_LICENSE_EXPRESSIONS。

  3. 将要包含和排除的路径添加到 PackageFiles 实例中，其键对应于软件包的 SBOM ID（SPDXID，不带 SPDXRef-PACKAGE-* 前缀）在 Tools/build/generate_sbom.py 中。

  4. 使用 make regen-sbom 或 python Tools/build/generate_sbom.py 运行该工具。确保该工具不会因任何验证错误而失败。

  5. 使用 git diff 比较 Misc/sbom.spdx.json 的更改，检查所有信息是否正确。

  6. 将更改提交到 Misc/sbom.spdx.json 和 Tools/build/generate_sbom.py。

移除依赖项

移除依赖项时

  1. 从 Misc/sbom.spdx.json 中的 packages 字段中移除条目。

  2. 从 Tools/build/generate_sbom.py 中移除相应的 PackageFiles 条目。

  3. 使用 make regen-sbom 或 python Tools/build/generate_sbom.py 运行该工具。确保该工具不会因任何验证错误而失败。

  4. 使用 git diff 比较 Misc/sbom.spdx.json 的更改，检查是否已从 SBOM 中移除正确的包。

  5. 将更改提交到 Misc/sbom.spdx.json 和 Tools/build/generate_sbom.py。