Artifact Analysis API を使用してメタデータにアクセスする

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

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

Artifact Analysis API
Cloud Storage

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

セキュリティメタデータ

Artifact Analysis は、オープンソースの Grafeas モデルに従ってメタデータストレージを提供します。パッケージの各バージョンについて、次の情報が提供されます。

Assured OSS によってリリースされたパッケージの各バージョンに対する PackageNote。パッケージのメモには次のものが含まれます。
- distribution ここで、各 distribution は Assured OSS によって提供される 1 つのアーティファクトに対応します。これには、バイナリと再現可能なソースの場所とダイジェスト url（署名とハッシュをダウンロードできる場所）が含まれます。
- ビルドの来歴、テストの証明書、脆弱性などのメタデータへのリンクを含む relatedURL。
BuildOccurrence。このビルドオカレンスへのリンクは、パッケージノートの relatedURL セクションでラベル BUILD_OCCURRENCE に対して指定されます。ビルドオカレンスの intotoStatement には、SLSA v0.2 来歴が含まれています。
2 つ目の BuildOccurrenance。このビルドオカレンスへのリンクは、パッケージノートの relatedURL セクションでラベル ORIGINAL_SOURCE_PROVENANCE に対して指定されます。このファイルには、ソースの形式で元のソース（GitHub）の詳細が含まれています。
AttestationOccurrence。この証明書オカレンスへのリンクは、パッケージメモの relatedURL セクションのラベル TEST_OCCURRENCE に対して指定されています。構成証明のシリアル化されたペイロードには、パッケージバージョンに対して実施されたすべてのセキュリティテストを表す JSON が含まれています。
2 つ目の AttestationOccurrence。この証明書のオカレンスへのリンクは、パッケージメモの PACKAGE_ATTESTATION_OCCURRENCE ラベルに対する relatedURL セクションに記載されています。証明書の 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 プロジェクトの英数字の識別子。
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 の場合は、URL https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2 を使用します。
Python の場合は、URL 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 API と GetOccurrence API、または curl コマンドを使用します。BUILD_OCCURRENCE の場合、API を使用するときに https://containeranalysis.googleapis.com/v1/ の最初の接頭辞を削除します。他のエンティティについては、API パラメータで URL を note_name または occurrence_name として直接使用します。

Python スクリプトのサンプル

ダウンロードしたメタデータ全体を出力する Python スクリプトのサンプルは、次の Cloud Storage の場所で README ファイルとともに提供されています。

gs://cloud-aoss/utils/python-download-metadata/v1.1

Google Cloud CLI を使用してスクリプトをダウンロードする手順は次のとおりです。

アプリケーションのデフォルト認証情報（ADC）を使用して認証を設定します。
コンテナ分析クライアントライブラリをインストールします。具体的には、このコマンドで次のものをインストールする必要があります。
```
pip install google-cloud-containeranalysis
```
次のコマンドを使用して、cloud-kms パッケージと cryptography パッケージをインストールします。
```
pip install --upgrade google-cloud-kms
pip install --upgrade cryptography
```
次のコマンドを使用して、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 は、ファイルを保存するローカルパスに置き換えます。
次のコマンドを使用して、スクリプトの使用手順を含む 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`

Artifact Analysis API を使用してメタデータにアクセスする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

セキュリティ メタデータ

Artifact Analysis からセキュリティ メタデータにアクセスする

ステップ 1 - 認証を設定する

ステップ 2 - セキュリティ メタデータを取得する

サンプル メタデータ