使用 Artifact Analysis API 存取中繼資料

Assured OSS 會為每個可用套件提供安全性中繼資料。套件的每個版本都有專屬的中繼資料。本頁面說明中繼資料提供的資訊，以及如何存取這類資料。

您可以透過下列任一方式存取安全性中繼資料：

  • Artifact Analysis API
  • Cloud Storage

本頁面僅適用於免費層級。

安全性中繼資料

構件分析會根據開放原始碼 Grafeas 模型提供中繼資料儲存空間。系統會針對每個套件版本提供以下資訊：

  • Assured OSS 發布的每個套件版本都有對應的 PackageNote。包裹附註包含下列資訊：

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

  • BuildOccurrence。 這個建構項目的連結會顯示在套件附註的「relatedURL」部分，標籤為「BUILD_OCCURRENCE」。建構事件中的 intotoStatement 包含 SLSA v0.2 來源資訊。

  • 第二個 BuildOccurrenance。 這個建構項目的連結會顯示在套件附註的「relatedURL」部分，標籤為「ORIGINAL_SOURCE_PROVENANCE」。這個檔案包含原始來源 (GitHub) 詳細資料，形式為「來源」。

  • AttestationOccurrence。 這個認證事件的連結會顯示在套件附註的 relatedURL 區段中，標籤為 TEST_OCCURRENCE。認證中的序列化酬載包含 JSON，代表對套件版本執行的所有安全性測試。

  • 第二個 AttestationOccurrence。這個認證事件的連結會顯示在套件附註的 relatedURL 區段中，標籤為 PACKAGE_ATTESTATION_OCCURRENCE。驗證中的 JSON 序列化酬載是套件附註的酬載和簽章。這項認證可用於驗證套件附註內容的完整性。

  • 與套件相關聯的每個安全漏洞，都會有 VulnerabilityNote 和 VulnerabilityOccurrence。附註和發生次數加總後，即可提供安全漏洞相關資訊，例如安全漏洞摘要或說明、嚴重程度、CVSSV3 分數、受影響和已修正的版本資訊，以及修復方式。

從構件分析存取安全性中繼資料

您可以使用不同語言的 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 指令。使用 API 時，請移除 BUILD_OCCURRENCE 的初始前置字元 https://containeranalysis.googleapis.com/v1/。如為其他實體，請直接在 API 參數中將網址做為 note_name 或 occurrence_name。

Python 指令碼範例

如需範例 Python 指令碼，請前往下列 Cloud Storage 位置，並下載 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`

後續步驟