使用 Cloud Storage 访问元数据

Assured OSS 为每个可用软件包提供安全元数据。软件包的每个版本都有自己的元数据。本页介绍了元数据中包含哪些信息，以及如何访问这些元数据。

您可以使用以下任一选项访问安全元数据：

  • Artifact Analysis API
  • Cloud Storage

本页面仅适用于免费层级。

安全元数据文件

每个 Assured OSS 软件包版本的安全元数据分布在 Cloud Storage 存储桶中的以下四个文件中：

  • buildinfo.zip：此文件包含有关软件包 build 信息（例如 build ID、build 变种、build 时间）的元数据。只有在极少数情况下（例如重新构建软件包、证书轮替和添加新字段），此元数据才会发生变化。
  • vexinfo.zip：此文件包含采用 CycloneDX 1.4 格式的软件包的漏洞信息。每当有关于软件包漏洞的信息时，此值预计会发生变化。
  • healthinfo.zip：此文件包含有关对软件包执行的测试的详细信息。如果软件包的测试状态发生变化，此值可能会随之变化。例如，如果执行了新的安全测试或覆盖率结果发生了变化。
  • licenseinfo.zip：此文件包含与软件包的许可信息相关的元数据。如果软件包的发布者修改了软件包的许可信息，则该信息可能会发生变化。

每个 ZIP 文件都包含以下两个文件：

  • 包含数据的 JSON 文件。
  • 一个 signature.zip 文件，其中包含相应数据的签名。

JSON 文件结构

JSON 文件的结构如下一部分中所述：

buildInfo.json

  • creationTime：相应文档的创建时间，采用 RFC 3339 字符串格式。
  • creator：文档的所有者。系统会提供以下详细信息：
    • name：创建相应文档的组织的名称。
    • email：组织的电子邮件地址，以便用户提出任何疑问或投诉。
  • buildDetails：与构建二进制文件相关的详细信息。系统会提供以下详细信息：
    • packageFileName：应用 build 详细信息的文件名。
    • buildProvenance：一个字符串，表示采用 SLSA v0.2 格式的软件包 build provenance。由 Cloud Build 生成。
    • envelope：一个字符串，表示可用于验证来源文档完整性的 DSSE 信封。这也是由 Cloud Build 生成的。
    • slsaLevel：表示构建系统遵循的 SLSA 级别。
    • buildTool：用于构建软件包的工具的名称，即 Cloud Build。如需了解详情，请参阅 Cloud Build。
    • transitiveClosureState：这是一个枚举，用于指示软件包的所有 build 依赖项（直接或间接）是否也存在于 Assured OSS 的产品组合中。此属性可以具有两个值：
      • OPEN：如果 Assured OSS 支持的传递依赖项为零或仅为部分。
      • CLOSED：如果所有传递依赖项都受 Assured OSS 支持。
  • sourceInfo：用于构建软件包的源代码的相关信息。系统会提供以下详细信息：
    • sourceUrl：GitHub 网址字符串。
    • commitHash：附加到发布版本的提交哈希字符串。
    • tag：与软件包版本关联的发布标记。
    • host：GitHub 中托管源代码的系统的名称。
    • commitTime：提交的时间，采用 RFC 3339 字符串格式。
  • sbom - 采用 SPDX 2.3 格式的 SBOM 字符串。

vexInfo.json

  • creationTime：相应文档的创建时间，采用 RFC 3339 字符串格式。
  • creator：文档的所有者。系统会提供以下详细信息：
    • name：创建相应文档的组织的名称。
    • email：组织的电子邮件地址，以便用户提出任何疑问或投诉。
  • vexData：采用 CycloneDX 1.4 格式的漏洞可利用性交流 (VEX) 字符串。

healthInfo.json

  • creationTime：相应文档的创建时间，采用 RFC 3339 字符串格式。
  • creator：文档的所有者。系统会提供以下详细信息：
    • name：创建相应文档的组织的名称。
    • email：组织的电子邮件地址，以便用户提出任何疑问或投诉。
  • testingData：有关对软件包执行的安全测试的详细信息。 系统会提供以下详细信息：
    • testType：所做测试的类型。例如 FUZZ。
    • tool：用于执行测试的工具的名称。
    • testStatus：测试的状态。状态可以是以下其中一种：
      • TESTED：已执行测试。
      • NOT_REQUIRED：相应软件包不需要进行测试。例如，如果软件包仅包含接口，则无需进行模糊测试。
      • UNTESTED：未测试软件包。

licenseInfo.json

  • package_name：以字符串格式表示的软件包名称。
  • package_version：软件包的版本。
  • license_info：与软件包关联的许可。

从 Cloud Storage 访问安全元数据

如需从 Cloud Storage 访问安全元数据，请按以下步骤操作：

第 1 步 - 设置身份验证

如需了解如何设置身份验证，请参阅设置身份验证。

第 2 步 - 构建网址

您可以使用 gcloud storage 或 curl 命令下载元数据。请使用以下信息为两者构建网址：

  • 语言： java 或 python。值必须采用小写字母。
  • Package_ID:：对于 Java，它是 groupId:artifactId；对于 Python，它是 packageName。值必须采用小写字母。
  • 版本：软件包的版本。
  • Metadata_Type:：在 buildinfo.zip、vexinfo.zip 和 healthinfo.zip 之间进行选择。

网址必须采用以下格式：

gcloud

gs://cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>

请注意，网址必须采用小写字母。

Python 网址示例：gs://cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Java 网址示例：gs://cloud-aoss-metadata/java/com.google.errorprone:error_prone_annotations/2.15.0/buildinfo.zip

curl

https://storage.googleapis.com/cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>

请注意，网址必须采用小写字母。

Python 网址示例：https://storage.googleapis.com/cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Java 网址示例：https://storage.googleapis.com/cloud-aoss-metadata/java/com.google.errorprone:error_prone_annotations/2.15.0/buildinfo.zip

第 3 步 - 下载元数据

使用以下命令下载元数据：

gcloud

gcloud storage cp  "gs://cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>" outputFolderLocation

如需下载给定软件包和版本的所有元数据类型（例如 build 信息、健康信息和 VEX 信息），请使用以下命令：

gcloud storage cp "gs://cloud-aoss-metadata/<language>/<package_id>/<version>" outputFolderLocation --recursive

元数据分布在三个 zip 文件（buildinfo.zip、healthinfo.zip、vexinfo.zip）中，并下载到输出文件夹中。

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type> -o output.zip

第 4 步 - 提取元数据

提取该 zip 文件。在 macOS 或 Linux 上，使用 unzip 命令：unzip input.zip -d outputFolder。 每个 ZIP 文件都包含一个 JSON 文件和一个 signature.zip 文件。JSON 文件包含实际的安全元数据，而 signature.zip 文件包含用于验证 JSON 上 Google 签名的文件。

下载许可信息

所有 Assured OSS 软件包的许可信息都包含在一个 JSON 文件中。如需下载此文件，请运行以下命令：

gcloud

gcloud storage cp  "gs://cloud-aoss/info/LicenseInfo.json" outputFolderLocation

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss/info/LicenseInfo.json

如需下载许可元数据文件的签名，请运行以下命令：

gcloud

gcloud storage cp "gs://cloud-aoss/info/LicenseInfo.json-sig.zip" outputFolderLocation

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss/info/LicenseInfo.json-sig.zip -o output.zip

后续步骤