Cloud Storage を使用してメタデータにアクセスする

Assured OSS は、利用可能なすべてのパッケージに対してセキュリティ メタデータを提供します。パッケージの各バージョンには独自のメタデータがあります。このページでは、メタデータの一部として提供される情報と、このメタデータにアクセスする方法について説明します。

セキュリティ メタデータには、次のいずれかの方法でアクセスできます。

  • Artifact Analysis API
  • Cloud Storage

このページの内容は、無料枠にのみ適用されます。

セキュリティ メタデータ ファイル

各 Assured OSS パッケージ バージョンのセキュリティ メタデータは、Cloud Storage バケット内の次の 4 つのファイルに分散されています。

  • buildinfo.zip: このファイルには、パッケージのビルド情報に関するメタデータが含まれています。このメタデータは、パッケージの再構築、証明書のローテーション、新しいフィールドの追加など、非常にまれなシナリオで変更されます。
  • vexinfo.zip: このファイルには、CycloneDX 1.4 形式のパッケージの脆弱性情報が含まれています。パッケージの脆弱性に関する情報があるたびに変更されることが想定されています。
  • healthinfo.zip: このファイルには、パッケージに対して実行されたテストの詳細が含まれています。パッケージのテスト ステータスが変更されると、この値も変更される可能性があります。たとえば、新しいセキュリティ テストが実行された場合や、カバレッジの結果が変更された場合などです。
  • licenseinfo.zip: このファイルには、パッケージのライセンス情報に関するメタデータが含まれています。パッケージのライセンス情報は、パッケージのパブリッシャーが情報を変更すると変更されることがあります。

各 ZIP ファイルには、次の 2 つのファイルが含まれています。

  • データを含む JSON ファイル。
  • そのデータの署名を含む signature.zip ファイル。

JSON ファイルの構造

JSON ファイルの構造については、次のセクションで説明します。

buildInfo.json

  • creationTime: このドキュメントの作成時間（RFC 3339 文字列形式）。
  • creator: ドキュメントのオーナー。次の詳細情報が提供されます。
    • name: このドキュメントを作成した組織の名前。
    • email: 問い合わせや苦情があった場合の組織のメールアドレス。
  • buildDetails: バイナリのビルドに関連する詳細。次の詳細情報が提供されます。
    • packageFileName: ビルドの詳細が適用されるファイルの名前。
    • buildProvenance: SLSA v0.2 形式のパッケージのビルド プロベナンスを表す文字列。これは Cloud Build によって生成されます。
    • envelope: Provenance ドキュメントの完全性を検証するために使用できる DSSE エンベロープを表す文字列。これも Cloud Build によって生成されます。
    • slsaLevel: ビルドシステムが準拠している SLSA レベルを示します。
    • buildTool: パッケージのビルドに使用されるツール（Cloud Build）の名前。詳細については、Cloud Build をご覧ください。
    • transitiveClosureState: パッケージのすべてのビルド依存関係（直接または間接）が Assured OSS のポートフォリオにも存在するかどうかを示す列挙型です。次の 2 つの値のいずれかになります。
      • OPEN: Assured OSS でサポートされている推移的依存関係がゼロまたは一部のみの場合。
      • CLOSED: すべての推移的依存関係が Assured OSS でサポートされている場合。
  • sourceInfo: パッケージのビルドに使用されたソースコードに関する情報。次の詳細情報が提供されます。
    • sourceUrl: GitHub の URL 文字列。
    • commitHash: リリースに付加された commit ハッシュ文字列。
    • tag: パッケージ バージョンに関連付けられているリリース タグ。
    • host: GitHub でソースコードをホストするシステムの名前。
    • commitTime: RFC 3339 文字列形式の commit の時間。
  • 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 - URL を作成する

gcloud storage コマンドと curl コマンドのいずれかを使用して、メタデータをダウンロードできます。次の情報を使用して、両方の URL を作成します。

  • 言語: java または python。値は小文字にする必要があります。
  • Package_ID: Java の場合は groupId:artifactId、Python の場合は packageName です。値は小文字にする必要があります。
  • バージョン: パッケージのバージョン。
  • Metadata_Type: buildinfo.zip、vexinfo.zip、healthinfo.zip のいずれかを選択します。

URL は次の形式にする必要があります。

gcloud

gs://cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>

URL は小文字にする必要があります。

Python の URL の例: gs://cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Java の URL の例: 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>

URL は小文字にする必要があります。

Python の URL の例: https://storage.googleapis.com/cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Java の URL の例: 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

メタデータは 3 つの 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 パッケージのライセンス情報は、1 つの 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

次のステップ