使用 Cloud Storage 存取中繼資料

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

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

  • Artifact Analysis API
  • Cloud Storage

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

安全性中繼資料檔案

每個 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 格式的 Vulnerability Exploitability eXchange (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

後續步驟