使用 Cloud Storage 存取中繼資料

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

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

安全性中繼資料檔案

每個 Assured OSS 套件版本的安全性中繼資料，會分散在 Cloud Storage bucket 中的下列四個檔案：

  • buildinfo.zip：這個檔案包含套件建構資訊的中繼資料。這項中繼資料只會在極少數情況下變更，例如重新建構套件、輪替憑證和新增欄位。
  • 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：套用建構作業詳細資料的檔案名稱。
    • buildProvenance：此字串代表套件的建構作業來源資訊，格式為 SLSA v0.2。這項資訊由 Cloud Build 產生。
    • envelope：代表 DSSE 信封的字串，可用於驗證來源文件的完整性。這項資訊也是由 Cloud Build 產生。
    • slsaLevel：表示建構系統遵循的 SLSA 等級。
    • buildTool：用於建構套件的工具名稱，即 Cloud Build。詳情請參閱「Cloud Build」。
    • transitiveClosureState：這個 ENUM 會指出套件的所有建構依附元件 (直接或間接) 是否也存在於 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

如要一併下載特定套件和版本的建構資訊、健康狀態資訊和 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

後續步驟