Mengakses metadata menggunakan Artifact Analysis API

Assured Open Source Software (Assured OSS) menyediakan metadata keamanan untuk setiap paket dan versi paket yang tersedia. Anda dapat mengakses metadata ini di Artifact Analysis untuk meninjau detail build, status kerentanan, hasil pengujian, dan informasi lisensi.

Dokumen ini hanya berlaku untuk paket gratis. Untuk mengetahui petunjuk cara mengakses metadata menggunakan Cloud Storage, lihat Mengakses metadata menggunakan Cloud Storage.

Metadata keamanan

Artifact Analysis menyediakan penyimpanan metadata sesuai dengan model Grafeas open source. Informasi berikut diberikan untuk setiap versi paket:

  • PackageNote untuk setiap versi paket yang dirilis oleh Assured OSS. Catatan paket berisi hal berikut:

    • distribution dengan setiap distribution sesuai dengan satu artefak yang disediakan oleh Assured OSS. Hal ini mencakup lokasi dan ringkasan url (tempat tanda tangan dan hash dapat didownload) untuk sumber biner dan yang dapat direproduksi.
    • relatedURL yang berisi link ke metadata seperti provenance build, pengesahan pengujian, dan kerentanan.

  • BuildOccurrence. Link ke kemunculan build ini diberikan di bagian relatedURL catatan paket pada label BUILD_OCCURRENCE. intotoStatement dalam kemunculan build berisi provenance SLSA v0.2.

  • BuildOccurrenance kedua. Link ke kemunculan build ini diberikan di bagian relatedURL catatan paket pada label ORIGINAL_SOURCE_PROVENANCE. File ini berisi detail sumber asli (GitHub) dalam bentuk Source.

  • AttestationOccurrence. Link ke kemunculan pengesahan ini diberikan di bagian relatedURL catatan paket terhadap label TEST_OCCURRENCE. Payload yang diserialisasi dalam pengesahan berisi JSON yang mewakili semua pengujian keamanan yang dilakukan pada versi paket.

  • AttestationOccurrence kedua. Link ke kemunculan pengesahan ini diberikan di bagian relatedURL catatan paket terhadap label PACKAGE_ATTESTATION_OCCURRENCE. Payload yang diserialisasi JSON dalam pengesahan adalah payload catatan paket dan tanda tangannya. Pengesahan ini digunakan untuk memverifikasi integritas konten catatan paket.

  • VulnerabilityNote dan VulnerabilityOccurrence untuk setiap kerentanan yang terkait dengan paket. Gabungan catatan dan kemunculan memberikan informasi tentang kerentanan seperti ringkasan atau deskripsi kerentanan, tingkat keparahan, skor CVSSV3, informasi versi yang terpengaruh dan diperbaiki, serta perbaikan.

Mengakses metadata keamanan dari Artifact Analysis

Anda dapat mengakses metadata keamanan dari Artifact Analysis menggunakan klien Artifact Analysis API yang tersedia dalam berbagai bahasa. Untuk mulai menggunakan Library Klien Cloud untuk Artifact Analysis API, lihat Menginstal library klien Artifact Analysis yang diperlukan.

Untuk mengakses metadata keamanan, ikuti langkah-langkah berikut:

Langkah 1 - Menyiapkan autentikasi

Siapkan autentikasi menggunakan Kredensial Default Aplikasi (ADC).

Langkah 2 - Mengambil metadata keamanan

Untuk mengambil metadata keamanan, buat paket note_name menggunakan informasi berikut:

  • Project_ID: ID alfanumerik untuk project Google Cloud Anda.
  • Package Language: Java atau Python. Nilai ini harus dalam huruf besar.
  • Package_ID: untuk Java, nilainya adalah groupId_artifactId dan untuk Python, nilainya adalah packageName. Nilai ini peka huruf besar/kecil. Casing yang valid untuk nama rilis paket dapat ditemukan di Mencantumkan semua Paket di Assured OSS.
  • Version: Versi paket.

note_name harus memiliki struktur berikut: projects/<project_id>/notes/<language>-<package_id>-<version>.

Contoh: projects/cloud-aoss/notes/JAVA-org.apache.commons_commons-compress-1.21

Opsi 1:

Jika Anda menggunakan Library Klien Container Analysis, gunakan getNotes dengan note_name untuk mengkueri PackageNote. PackageNote memiliki link ke catatan dan kemunculan lainnya.

Opsi 2:

Jika Anda menggunakan perintah curl, gunakan perintah berikut:

curl  -H "Content-Type: application/json" -H   "Authorization: Bearer $(gcloud auth print-access-token)" $URL
  • Untuk Java, gunakan URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2
  • Untuk Python, gunakan URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/PYTHON-Flask-Cors-3.0.10

Metadata Sampel

{
  "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": "..."
      }
]}}

Gunakan nama catatan dan kemunculan yang disediakan dalam peta relatedURL untuk mengambil data tambahan terkait sumber, build, pengujian, dan kerentanan. Untuk melakukannya, gunakan API GetNote dan GetOccurrence atau perintah curl. Untuk BUILD_OCCURRENCE, hapus awalan awal https://containeranalysis.googleapis.com/v1/ saat Anda menggunakan API. Untuk entitas lain, gunakan URL secara langsung sebagai note_name atau occurrence_name dalam parameter API.

Contoh skrip Python

Contoh skrip Python yang mencetak seluruh metadata yang didownload tersedia di lokasi Cloud Storage berikut beserta file README-nya:

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

Ikuti langkah-langkah berikut untuk mendownload skrip menggunakan Google Cloud CLI:

  1. Siapkan autentikasi menggunakan Kredensial Default Aplikasi (ADC).

  2. Instal library klien container-analysis. Secara khusus, perintah ini akan menginstal:

    pip install google-cloud-containeranalysis

  3. Instal paket cloud-kms dan cryptography menggunakan perintah berikut:

    pip install --upgrade google-cloud-kms
pip install --upgrade cryptography

  4. Download download_metadata.py ke sistem Anda menggunakan perintah berikut:

    gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/download_metadata.py
PATH_TO_LOCAL_STORE --recursive

    Ganti PATH_TO_LOCAL_STORE dengan jalur lokal tempat Anda ingin menyimpan file.

  5. Download README.md yang berisi petunjuk untuk menggunakan skrip menggunakan perintah berikut:

    gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/README.md PATH_TO_LOCAL_STORE --recursive

    Ganti PATH_TO_LOCAL_STORE dengan jalur lokal tempat Anda ingin menyimpan file.

Contoh Perintah

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1'

Untuk memverifikasi tanda tangan dalam metadata analisis container, tambahkan perintah berikut ke skrip:

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1' -s`

Langkah berikutnya