Mengakses metadata menggunakan Cloud Storage

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

Dokumen ini hanya berlaku untuk paket gratis. Untuk mengetahui petunjuk tentang cara mengakses metadata menggunakan Artifact Analysis API, lihat Mengakses metadata menggunakan Artifact Analysis API.

File metadata keamanan

Metadata keamanan untuk setiap versi paket Assured OSS didistribusikan di empat file berikut dalam bucket Cloud Storage:

  • buildinfo.zip: File ini berisi metadata tentang informasi build paket. Metadata ini akan berubah dalam skenario yang sangat jarang terjadi seperti pembuatan ulang paket, rotasi sertifikat, dan penambahan kolom baru.
  • vexinfo.zip: File ini berisi informasi kerentanan untuk paket dalam format CycloneDX 1.4. Hal ini diperkirakan akan berubah setiap kali ada informasi tentang kerentanan untuk paket tersebut.
  • healthinfo.zip: File ini berisi detail tentang pengujian yang dilakukan pada paket. Hal ini dapat berubah jika status pengujian paket diubah. Misalnya, jika pengujian keamanan baru dilakukan atau jika hasil cakupan diubah.
  • licenseinfo.zip: File ini berisi metadata yang berkaitan dengan informasi lisensi paket. Informasi lisensi paket dapat berubah jika penerbit paket mengubah informasi tersebut.

Setiap file zip berisi dua file berikut:

  • File JSON yang berisi data.
  • File signature.zip yang berisi tanda tangan untuk data tersebut.

Struktur file JSON

Struktur untuk file JSON dijelaskan di bagian berikut:

buildInfo.json

  • creationTime: waktu pembuatan dokumen ini dalam format string RFC 3339.
  • creator: pemilik dokumen. Detail berikut diberikan:
    • name: nama organisasi yang membuat dokumen ini.
    • email: alamat email organisasi jika ada pertanyaan atau keluhan.
  • buildDetails: detail terkait pembuatan biner. Detail berikut diberikan:
    • packageFileName: nama file yang menerapkan detail build.
    • buildProvenance: string yang mewakili provenance build paket dalam format SLSA v0.2. Ini dibuat oleh Cloud Build.
    • envelope: string yang mewakili envelope DSSE yang dapat digunakan untuk memverifikasi integritas dokumen provenance. Ini juga dibuat oleh Cloud Build.
    • slsaLevel: Menunjukkan level SLSA yang dipatuhi oleh sistem build.
    • buildTool: Nama alat yang digunakan untuk membangun paket, yaitu Cloud Build. Untuk mengetahui informasi selengkapnya, lihat Cloud Build.
    • transitiveClosureState: Ini adalah ENUM yang menunjukkan apakah semua dependensi build untuk paket (langsung atau tidak langsung) juga ada dalam portofolio Assured OSS atau tidak. Ini dapat memiliki dua nilai:
      • OPEN: Jika tidak ada atau hanya sebagian dependensi transitif yang didukung oleh Assured OSS.
      • CLOSED: Jika semua dependensi transitif didukung oleh Assured OSS.
  • sourceInfo: informasi tentang kode sumber yang digunakan untuk membangun paket. Detail berikut diberikan:
    • sourceUrl: string URL GitHub.
    • commitHash: string hash commit yang dilampirkan ke rilis.
    • tag: tag rilis yang terkait dengan versi paket.
    • host: nama sistem yang menghosting kode sumber di GitHub.
    • commitTime: waktu commit dalam format string RFC 3339.
  • sbom - String SBOM dalam format SPDX 2.3.

vexInfo.json

  • creationTime: waktu pembuatan dokumen ini dalam format string RFC 3339.
  • creator: pemilik dokumen. Detail berikut diberikan:
    • name: nama organisasi yang membuat dokumen ini.
    • email: alamat email organisasi jika ada pertanyaan atau keluhan.
  • vexData: String Vulnerability Exploitability eXchange (VEX) dalam format CycloneDX 1.4.

healthInfo.json

  • creationTime: waktu pembuatan dokumen ini dalam format string RFC 3339.
  • creator: pemilik dokumen. Detail berikut diberikan:
    • name: nama organisasi yang membuat dokumen ini.
    • email: alamat email organisasi jika ada pertanyaan atau keluhan.
  • testingData: detail tentang pengujian keamanan yang dilakukan pada paket. Detail berikut diberikan:
    • testType: jenis pengujian yang dilakukan. Contoh, FUZZ.
    • tool: nama alat yang digunakan untuk melakukan pengujian.
    • testStatus: status pengujian. Statusnya dapat berupa salah satu dari berikut:
      • TESTED: pengujian dijalankan.
      • NOT_REQUIRED: pengujian tidak diperlukan untuk paket. Misalnya, pengujian fuzz tidak diperlukan pada paket yang hanya berisi antarmuka.
      • UNTESTED: paket tidak diuji.

licenseInfo.json

  • package_name: Nama paket dalam format string.
  • package_version: Versi paket.
  • license_info: Lisensi yang terkait dengan paket.

Mengakses metadata keamanan dari Cloud Storage

Untuk mengakses metadata keamanan dari Cloud Storage, ikuti langkah-langkah berikut:

Langkah 1 - Menyiapkan autentikasi

Untuk mengetahui informasi tentang cara menyiapkan autentikasi, lihat Menyiapkan autentikasi.

Langkah 2 - Buat URL

Anda dapat menggunakan perintah gcloud storage atau curl untuk mendownload metadata. Buat URL untuk keduanya menggunakan informasi berikut:

  • Bahasa: java atau python. Nilai harus dalam huruf kecil.
  • Package_ID: untuk Java, yaitu groupId:artifactId dan untuk Python, yaitu packageName. Nilai harus dalam huruf kecil.
  • Version: versi paket.
  • Metadata_Type: pilih antara buildinfo.zip, vexinfo.zip, dan healthinfo.zip.

URL harus memiliki format berikut:

gcloud

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

Perhatikan bahwa URL harus dalam huruf kecil.

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

Contoh URL 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>

Perhatikan bahwa URL harus dalam huruf kecil.

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

Contoh URL Java: https://storage.googleapis.com/cloud-aoss-metadata/java/com.google.errorprone:error_prone_annotations/2.15.0/buildinfo.zip

Langkah 3 - Download metadata

Gunakan perintah berikut untuk mendownload metadata:

gcloud

gcloud storage cp  "gs://cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>" outputFolderLocation

Untuk mendownload semua jenis metadata seperti informasi build, informasi kesehatan, dan informasi VEX secara bersamaan untuk paket dan versi tertentu, gunakan perintah berikut:

gcloud storage cp "gs://cloud-aoss-metadata/<language>/<package_id>/<version>" outputFolderLocation --recursive

Metadata didistribusikan di tiga file zip (buildinfo.zip, healthinfo.zip, vexinfo.zip) dan didownload ke folder output.

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

Langkah 4 - Mengekstrak metadata

Ekstrak file ZIP. Di macOS atau Linux, gunakan perintah unzip: unzip input.zip -d outputFolder. Setiap file ZIP berisi file JSON dan file signature.zip. File JSON berisi metadata keamanan yang sebenarnya dan file signature.zip berisi file untuk memverifikasi tanda tangan Google di JSON.

Mendownload informasi lisensi

Informasi lisensi untuk semua paket Assured OSS tersedia dalam satu file JSON. Untuk mendownload file ini, jalankan perintah berikut:

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

Untuk mendownload tanda tangan file metadata lisensi, jalankan perintah berikut:

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

Langkah berikutnya