Accedere ai metadati utilizzando l'API Artifact Analysis

Assured OSS fornisce metadati di sicurezza per ogni pacchetto disponibile. Ogni versione del pacchetto ha i propri metadati. Questa pagina spiega quali informazioni vengono fornite come parte dei metadati e come puoi accedervi.

Puoi accedere ai metadati di sicurezza utilizzando una delle seguenti opzioni:

API Artifact Analysis
Cloud Storage

Questa pagina si applica solo al livello senza costi.

Metadati di sicurezza

Artifact Analysis fornisce l'archiviazione dei metadati in base al modello open source Grafeas. Per ogni versione del pacchetto vengono fornite le seguenti informazioni:

Una PackageNote per ogni versione rilasciata del pacchetto da Assured OSS. La nota del pacchetto contiene quanto segue:
- distribution dove ogni distribution corrisponde a un artefatto fornito da Assured OSS. Include la posizione e il digest url (da cui è possibile scaricare la firma e l'hash) per le origini binarie e riproducibili.
- relatedURL che contiene link a metadati come la provenienza della build, l'attestazione dei test e le vulnerabilità.
Un BuildOccurrence. Il link a questa occorrenza di build è riportato nella sezione relatedURL della nota del pacchetto in corrispondenza dell'etichetta BUILD_OCCURRENCE. intotoStatement nell'occorrenza di build contiene la provenienza SLSA v0.2.
Un secondo BuildOccurrenance. Il link a questa occorrenza di build è riportato nella sezione relatedURL della nota del pacchetto in corrispondenza dell'etichetta ORIGINAL_SOURCE_PROVENANCE. Questo file contiene i dettagli dell'origine (GitHub) originale sotto forma di Origine.
Un AttestationOccurrence. Il link a questa occorrenza di attestazione è riportato nella sezione relatedURL della nota del pacchetto in corrispondenza dell'etichetta TEST_OCCURRENCE. Il payload serializzato nell'attestazione contiene JSON che rappresenta tutti i test di sicurezza eseguiti sulla versione del pacchetto.
Una seconda AttestationOccurrence. Il link a questa occorrenza di attestazione è indicato nella sezione relatedURL della nota del pacchetto in corrispondenza dell'etichetta PACKAGE_ATTESTATION_OCCURRENCE. Il payload serializzato JSON nell'attestazione è il payload della nota del pacchetto e la relativa firma. Questa attestazione viene utilizzata per verificare l'integrità dei contenuti della nota del pacchetto.
Un VulnerabilityNote e un VulnerabilityOccurrence per ogni vulnerabilità associata al pacchetto. La nota e l'occorrenza combinate forniscono informazioni sulle vulnerabilità, come il riepilogo o la descrizione della vulnerabilità, la gravità, il punteggio CVSSV3, le informazioni sulle versioni interessate e corrette e la correzione.

Accedere ai metadati di sicurezza da Artifact Analysis

Puoi accedere ai metadati di sicurezza da Artifact Analysis utilizzando i client API Artifact Analysis, disponibili in diverse lingue. Per iniziare a utilizzare le librerie client di Cloud per l'API Artifact Analysis, consulta Installare le librerie client di Artifact Analysis richieste.

Per accedere ai metadati di sicurezza:

Passaggio 1: configura l'autenticazione

Configura l'autenticazione utilizzando le Credenziali predefinite dell'applicazione (ADC).

Passaggio 2: recupera i metadati di sicurezza

Per recuperare i metadati di sicurezza, crea un pacchetto note_name utilizzando le seguenti informazioni:

Project_ID: l'identificatore alfanumerico del tuo progetto Google Cloud .
Package Language: Java o Python. Deve essere in maiuscolo.
Package_ID: per Java è groupId_artifactId e per Python è packageName. Questo valore è sensibile alle maiuscole. La combinazione di maiuscole e minuscole valida per il nome della release del pacchetto è disponibile in Elenco di tutti i pacchetti in Assured OSS.
Version: la versione del pacchetto.

Il campo note_name deve avere la seguente struttura: projects/<project_id>/notes/<language>-<package_id>-<version>.

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

Opzione 1:

Se utilizzi le librerie client Container Analysis, utilizza getNotes con note_name per eseguire query su PackageNote. PackageNote contiene link ad altre note e occorrenze.

Opzione 2:

Se utilizzi il comando curl, utilizza questo comando:

curl  -H "Content-Type: application/json" -H   "Authorization: Bearer $(gcloud auth print-access-token)" $URL

Per Java, utilizza l'URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2
Per Python, utilizza l'URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/PYTHON-Flask-Cors-3.0.10

Metadati di esempio

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

Utilizza i nomi delle note e delle occorrenze forniti nella mappa relatedURL per recuperare dati aggiuntivi relativi a origine, build, test e vulnerabilità. Per farlo, utilizza le API GetNote e GetOccurrence o i comandi curl. Per BUILD_OCCURRENCE, rimuovi il prefisso iniziale di https://containeranalysis.googleapis.com/v1/ quando utilizzi l'API. Per le altre entità, utilizza gli URL direttamente come note_name o occurrence_name nel parametro API.

Script Python di esempio

Un esempio di script Python che stampa tutti i metadati scaricati è disponibile nella seguente posizione Cloud Storage insieme al relativo file README:

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

Segui questi passaggi per scaricare lo script utilizzando Google Cloud CLI:

Configura l'autenticazione utilizzando le Credenziali predefinite dell'applicazione (ADC).
Installa la libreria client container-analysis. Nello specifico, questo comando deve installare:
```
pip install google-cloud-containeranalysis
```
Installa i pacchetti cloud-kms e cryptography utilizzando i seguenti comandi:
```
pip install --upgrade google-cloud-kms
pip install --upgrade cryptography
```
Scarica download_metadata.py sul tuo sistema utilizzando il seguente comando:
```
gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/download_metadata.py
PATH_TO_LOCAL_STORE --recursive
```
Sostituisci PATH_TO_LOCAL_STORE con il percorso locale in cui vuoi salvare il file.
Scarica il file README.md che contiene le istruzioni per utilizzare lo script utilizzando il seguente comando:
```
gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/README.md PATH_TO_LOCAL_STORE --recursive
```
Sostituisci PATH_TO_LOCAL_STORE con il percorso locale in cui vuoi salvare il file.

Comando di esempio

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

Per verificare le firme nei metadati di analisi del container, aggiungi il seguente comando allo script:

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