使用 Artifact Analysis API 访问元数据

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

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

  • Artifact Analysis API
  • Cloud Storage

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

安全元数据

Artifact Analysis 根据开源 Grafeas 模型提供元数据存储服务。系统会针对软件包的每个版本提供以下信息：

  • Assured OSS 发布的软件包的每个版本的 PackageNote。软件包注释包含以下内容：

    • distribution 其中每个 distribution 都对应于 Assured OSS 提供的一个制品。 它包含二进制文件和可重现来源的位置和摘要 url（可从中下载签名和哈希）。
    • relatedURL，其中包含指向 build 出处、测试证明和漏洞等元数据的链接。

  • 一个 BuildOccurrence。 此 build 实例的链接位于软件包注释的 relatedURL 部分，标签为 BUILD_OCCURRENCE。build occurrence 中的 intotoStatement 包含 SLSA v0.2 出处。

  • 第二个 BuildOccurrenance。 此 build 实例的链接位于软件包注释的 relatedURL 部分，标签为 ORIGINAL_SOURCE_PROVENANCE。此文件包含 Source 形式的原始来源 (GitHub) 详细信息。

  • AttestationOccurrence。 此证明实例的链接位于软件包备注的 relatedURL 部分，对应于标签 TEST_OCCURRENCE。证明中的序列化载荷包含表示对相应软件包版本进行的所有安全测试的 JSON。

  • 第二个 AttestationOccurrence。此证明发生实例的链接位于软件包备注的 relatedURL 部分，对应于标签 PACKAGE_ATTESTATION_OCCURRENCE。证明中的 JSON 序列化载荷是软件包注释的载荷及其签名。此证明用于验证软件包注释内容的完整性。

  • 与软件包关联的每个漏洞的 VulnerabilityNote 和 VulnerabilityOccurrence。注释和出现次数结合在一起，可提供有关漏洞的信息，例如漏洞摘要或说明、严重程度、CVSSV3 得分、受影响和已修复的版本信息以及修复措施。

从 Artifact Analysis 访问安全元数据

您可以使用不同语言的 Artifact Analysis API 客户端从 Artifact Analysis 访问安全元数据。如需开始使用 Artifact Analysis API 的 Cloud 客户端库，请参阅安装所需的 Artifact Analysis 客户端库。

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

第 1 步 - 设置身份验证

使用应用默认凭据 (ADC) 设置身份验证。

第 2 步 - 获取安全元数据

如需提取安全元数据，请使用以下信息创建 note_name 软件包：

  • Project_ID：您的 Google Cloud 项目的字母数字标识符。
  • Package Language：Java 或 Python。必须采用大写形式。
  • Package_ID：对于 Java，它是 groupId_artifactId；对于 Python，它是 packageName。该值区分大小写。如需了解软件包发布名称的有效大小写形式，请参阅列出 Assured OSS 中的所有软件包。
  • Version：软件包的版本。

note_name 应具有以下结构：projects/<project_id>/notes/<language>-<package_id>-<version>。

例如：projects/cloud-aoss/notes/JAVA-org.apache.commons_commons-compress-1.21

选项 1：

如果您使用的是 Container Analysis 客户端库，请使用带有 note_name 的 getNotes 来查询 PackageNote。PackageNote 包含指向其他注释和出现次数的链接。

选项 2：

如果您使用的是 curl 命令，请使用以下命令：

curl  -H "Content-Type: application/json" -H   "Authorization: Bearer $(gcloud auth print-access-token)" $URL
  • 对于 Java，请使用网址：https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2
  • 对于 Python，请使用网址：https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/PYTHON-Flask-Cors-3.0.10

示例元数据

{
  "name": "projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2",
  "kind": "PACKAGE",
  "relatedUrl": [
    {
      "url": "projects/cloud-aoss/occurrences/621d7e7b-8e6c-4313-b24b-eae3a1d1b884",
      "label": "ORIGINAL_SOURCE_PROVENANCE"
    },
    {
      "url": "https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/occurrences/a0967d97-634c-4066-b6da-0a723273a165",
      "label": "BUILD_OCCURRENCE"
    },
    {
      "url": "projects/cloud-aoss/occurrences/6005db73-7310-44f9-9a36-6ca0174732a1",
      "label": "TEST_OCCURRENCE"
    },
    {
      "url": "projects/cloud-aoss/notes/GHSA-gp7f-rwcx-9369",
      "label": "VULNERABILITY_GHSA-gp7f-rwcx-9369"
    }
  ],
  "createTime": "2022-10-12T06:48:19.162016Z",
  "updateTime": "2022-10-18T05:31:15.081736Z",
  "package": {
    "distribution": [
      {
        "cpeUri": "cpe:2.3:a:JAVA::org.jsoup:jsoup:1.15.2:*:*:*:*:*:*:*",
        "url": "https://us-maven.pkg.dev/…/org/jsoup/jsoup/1.15.2/jsoup-1.15.2.jar",
        "description": "..."
      },
      {
        "cpeUri": "cpe:2.3:a:JAVA::org.jsoup:jsoup:1.15.2:*:*:*:*:*:*:*",
        "url": "https://us-maven.pkg.dev/…/org/jsoup/jsoup/1.15.2/jsoup-1.15.2-sources.jar",
        "description": "..."
      }
]}}

使用 relatedURL 映射中提供的注释和发现项名称来提取与来源、 build、测试和漏洞相关的其他数据。为此，请使用 GetNote 和 GetOccurrence API 或 curl 命令。 对于 BUILD_OCCURRENCE，使用 API 时，请移除 https://containeranalysis.googleapis.com/v1/ 的初始前缀。对于其他实体，请直接在 API 参数中使用相应网址作为 note_name 或 occurrence_name。

Python 脚本示例

以下 Cloud Storage 位置提供了一个用于打印整个下载元数据的示例 Python 脚本及其 README 文件：

gs://cloud-aoss/utils/python-download-metadata/v1.1

按照以下步骤使用 Google Cloud CLI 下载脚本：

  1. 使用应用默认凭据 (ADC) 设置身份验证。

  2. 安装 Container Analysis 客户端库。 具体来说，此命令应安装：

    pip install google-cloud-containeranalysis

  3. 使用以下命令安装 cloud-kms 和 cryptography 软件包：

    pip install --upgrade google-cloud-kms
pip install --upgrade cryptography

  4. 使用以下命令将 download_metadata.py 下载到您的系统：

    gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/download_metadata.py
PATH_TO_LOCAL_STORE --recursive

    将 PATH_TO_LOCAL_STORE 替换为要保存文件的本地路径。

  5. 使用以下命令下载包含脚本使用说明的 README.md：

    gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/README.md PATH_TO_LOCAL_STORE --recursive

    将 PATH_TO_LOCAL_STORE 替换为您要保存文件的本地路径。

命令示例

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1'

如需验证容器分析元数据中的签名，请将以下命令添加到脚本中：

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1' -s`

后续步骤