使用 Artifact Analysis API 存取中繼資料

Assured Open Source Software (Assured OSS) 會為每個可用的套件和套件版本提供安全性中繼資料。您可以在 Artifact Analysis 中存取這項中繼資料，查看建構作業詳細資料、安全漏洞狀態、測試結果和授權資訊。

本文僅適用於免費方案。如需使用 Cloud Storage 存取中繼資料的操作說明，請參閱「使用 Cloud Storage 存取中繼資料」。

安全性中繼資料

Artifact Analysis 根據開放原始碼 Grafeas 模型提供中繼資料儲存空間。每個套件版本都會提供下列資訊：

  • Assured OSS 發布的每個套件版本都有 PackageNote。套件附註包含下列內容：

    • distribution 其中每個 distribution 都對應 Assured OSS 提供的構件。其中包含二進位檔和可重現來源的位置和摘要 url (可從中下載簽章和雜湊)。
    • relatedURL，其中包含建構作業來源資訊、測試認證和安全漏洞等中繼資料的連結。

  • BuildOccurrence。這個建構作業項目的連結位於套件附註的 relatedURL 區段，標籤為 BUILD_OCCURRENCE。建構項目中的 intotoStatement 包含 SLSA 0.2 版來源。

  • 第二個 BuildOccurrenance。這個建構作業項目的連結位於套件附註的 relatedURL 區段，標籤為 ORIGINAL_SOURCE_PROVENANCE。這個檔案包含原始來源 (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 專案的英數字元 ID。
  • 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 對應中提供的附註和發生項目名稱，擷取與來源、建構、測試和安全漏洞相關的其他資料。請使用 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`

後續步驟