Accedere ai metadati utilizzando Cloud Storage

Assured Open Source Software (Assured OSS) fornisce metadati di sicurezza per ogni pacchetto e versione del pacchetto disponibili. Puoi accedere a questi metadati in Cloud Storage per esaminare i dettagli della build, lo stato delle vulnerabilità, i risultati dei test e le informazioni sulle licenze.

Questo documento si applica solo al Livello senza costi. Per istruzioni su come accedere ai metadati utilizzando l'API Artifact Analysis, consulta Accedi ai metadati utilizzando l'API Artifact Analysis.

File di metadati di sicurezza

I metadati di sicurezza per ogni versione del pacchetto Assured OSS sono distribuiti nei seguenti quattro file in un bucket Cloud Storage:

  • buildinfo.zip: questo file contiene i metadati relativi alle informazioni di build di un pacchetto. Questi metadati cambiano in scenari molto rari, come la ricostruzione del pacchetto, la rotazione dei certificati e l'aggiunta di nuovi campi.
  • vexinfo.zip: questo file contiene le informazioni sulle vulnerabilità di un pacchetto nel formato CycloneDX 1.4. Questo valore dovrebbe cambiare ogni volta che sono disponibili informazioni su una vulnerabilità per il pacchetto.
  • healthinfo.zip: questo file contiene dettagli sui test eseguiti su un pacchetto. Questo può cambiare se lo stato di test di un pacchetto viene modificato. Ad esempio, se viene eseguito un nuovo test di sicurezza o se il risultato della copertura viene modificato.
  • licenseinfo.zip: questo file contiene i metadati relativi alle informazioni sulla licenza di un pacchetto. Le informazioni sulla licenza di un pacchetto possono cambiare se l'editore del pacchetto le modifica.

Ogni file ZIP contiene i seguenti due file:

  • Un file JSON contenente i dati.
  • Un file signature.zip contenente la firma per i dati.

Struttura del file JSON

La struttura dei file JSON è descritta nella sezione seguente:

buildInfo.json

  • creationTime: la data e l'ora di creazione di questo documento nel formato stringa RFC 3339.
  • creator: il proprietario del documento. Vengono forniti i seguenti dettagli:
    • name: il nome dell'organizzazione che ha creato questo documento.
    • email: l'indirizzo email dell'organizzazione in caso di domande o reclami.
  • buildDetails: i dettagli relativi alla creazione del file binario. Vengono forniti i seguenti dettagli:
    • packageFileName: il nome del file a cui si applicano i dettagli della build.
    • buildProvenance: una stringa che rappresenta la provenienza della build del pacchetto nel formato SLSA v0.2. Questo viene generato da Cloud Build.
    • envelope: una stringa che rappresenta una busta DSSE che può essere utilizzata per verificare l'integrità del documento di provenienza. Anche questo viene generato da Cloud Build.
    • slsaLevel: indica il livello SLSA rispettato dal sistema di compilazione.
    • buildTool: il nome dello strumento utilizzato per la creazione del pacchetto, ovvero Cloud Build. Per saperne di più, consulta Cloud Build.
    • transitiveClosureState: si tratta di un ENUM che indica se tutte le dipendenze di build per il pacchetto (dirette o indirette) sono presenti o meno nel portfolio di Assured OSS. Può avere due valori:
      • OPEN: se Assured OSS supporta zero o solo dipendenze transitive parziali.
      • CLOSED: se tutte le dipendenze transitive sono supportate da Assured OSS.
  • sourceInfo: le informazioni sul codice sorgente utilizzato per creare il pacchetto. Vengono forniti i seguenti dettagli:
    • sourceUrl: la stringa dell'URL GitHub.
    • commitHash: stringa hash del commit allegata alla release.
    • tag: il tag di release associato alla versione del pacchetto.
    • host: il nome del sistema che ospita il codice sorgente in GitHub.
    • commitTime: l'ora di un commit nel formato stringa RFC 3339.
  • sbom: stringa SBOM in formato SPDX 2.3.

vexInfo.json

  • creationTime: la data e l'ora di creazione di questo documento nel formato stringa RFC 3339.
  • creator: il proprietario del documento. Vengono forniti i seguenti dettagli:
    • name: il nome dell'organizzazione che ha creato questo documento.
    • email: l'indirizzo email dell'organizzazione in caso di domande o reclami.
  • vexData: stringa Vulnerability Exploitability eXchange (VEX) in formato CycloneDX 1.4.

healthInfo.json

  • creationTime: la data e l'ora di creazione di questo documento nel formato stringa RFC 3339.
  • creator: il proprietario del documento. Vengono forniti i seguenti dettagli:
    • name: il nome dell'organizzazione che ha creato questo documento.
    • email: l'indirizzo email dell'organizzazione in caso di domande o reclami.
  • testingData: i dettagli sui test di sicurezza eseguiti su un pacchetto. Vengono forniti i seguenti dettagli:
    • testType: il tipo di test eseguito. Ad esempio, FUZZ.
    • tool: il nome dello strumento utilizzato per eseguire il test.
    • testStatus: lo stato del test. Lo stato può essere uno dei seguenti:
      • TESTED: il test è stato eseguito.
      • NOT_REQUIRED: i test non erano richiesti per il pacchetto. Ad esempio, il fuzz testing non è richiesto per un pacchetto che contiene solo interfacce.
      • UNTESTED: il pacchetto non è stato testato.

licenseInfo.json

  • package_name: il nome del pacchetto in formato stringa.
  • package_version: la versione del pacchetto.
  • license_info: la licenza associata al pacchetto.

Accedi ai metadati di sicurezza da Cloud Storage

Per accedere ai metadati di sicurezza da Cloud Storage, segui questi passaggi:

Passaggio 1: configura l'autenticazione

Per informazioni sulla configurazione dell'autenticazione, consulta Configura l'autenticazione.

Passaggio 2: crea l'URL

Per scaricare i metadati, puoi utilizzare i comandi gcloud storage o curl. Crea l'URL per entrambi utilizzando le seguenti informazioni:

  • Lingua: java o python. Il valore deve essere in minuscolo.
  • Package_ID: per Java è groupId:artifactId e per Python è packageName. Il valore deve essere in minuscolo.
  • Versione: la versione del pacchetto.
  • Metadata_Type: scegli tra buildinfo.zip, vexinfo.zip e healthinfo.zip.

L'URL deve avere il seguente formato:

gcloud

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

Tieni presente che l'URL deve essere in minuscolo.

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

URL Java di esempio: 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>

Tieni presente che l'URL deve essere in minuscolo.

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

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

Passaggio 3: scarica i metadati

Utilizza i seguenti comandi per scaricare i metadati:

gcloud

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

Per scaricare tutti i tipi di metadati, come le informazioni sulla build, sull'integrità e su VEX, per un determinato pacchetto e una determinata versione, utilizza il seguente comando:

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

I metadati vengono distribuiti in tre file ZIP (buildinfo.zip, healthinfo.zip, vexinfo.zip) e scaricati nella cartella di 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

Passaggio 4: estrai i metadati

Estrai il file ZIP. Su macOS o Linux, utilizza il comando unzip: unzip input.zip -d outputFolder. Ogni file ZIP contiene un file JSON e un file signature.zip. Il file JSON contiene i metadati di sicurezza effettivi, mentre il file signature.zip contiene i file per verificare la firma di Google sul file JSON.

Scarica le informazioni sulla licenza

Le informazioni sulla licenza per tutti i pacchetti Assured OSS sono disponibili in un unico file JSON. Per scaricare questo file, esegui il comando seguente:

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

Per scaricare la firma del file dei metadati della licenza, esegui questo comando:

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

Passaggi successivi