Accéder aux métadonnées à l'aide de l'API Artifact Analysis

Assured OSS fournit des métadonnées de sécurité pour chaque package disponible. Chaque version du package possède ses propres métadonnées. Cette page explique quelles informations sont fournies dans les métadonnées et comment y accéder.

Vous pouvez accéder aux métadonnées de sécurité à l'aide de l'une des options suivantes :

API Artifact Analysis
Cloud Storage

Cette page ne s'applique qu'au forfait sans frais.

Métadonnées de sécurité

Artifact Analysis permet de stocker les métadonnées selon le modèle Grafeas Open Source. Les informations suivantes sont fournies pour chaque version du package :

Un PackageNote pour chaque version du package publiée par Assured OSS. La note du package contient les éléments suivants :
- distribution où chaque distribution correspond à un artefact fourni par Assured OSS. Il inclut l'emplacement et le résumé url (à partir desquels la signature et le hachage peuvent être téléchargés) pour les sources binaires et reproductibles.
- relatedURL contenant des liens vers des métadonnées telles que la provenance de la compilation, l'attestation de test et les failles.
BuildOccurrence Le lien vers cette occurrence de compilation est indiqué dans la section relatedURL de la note du package, en face du libellé BUILD_OCCURRENCE. Le intotoStatement dans l'occurrence de compilation contient la provenance SLSA v0.2.
Une deuxième BuildOccurrenance. Le lien vers cette occurrence de compilation est indiqué dans la section relatedURL de la note du package, en face du libellé ORIGINAL_SOURCE_PROVENANCE. Ce fichier contient les détails de la source d'origine (GitHub) sous la forme Source.
Une AttestationOccurrence. Le lien vers cette occurrence d'attestation est indiqué dans la section relatedURL de la note du package, en face du libellé TEST_OCCURRENCE. La charge utile sérialisée dans l'attestation contient un fichier JSON représentant tous les tests de sécurité effectués sur la version du package.
Une deuxième AttestationOccurrence. Le lien vers cette occurrence d'attestation est indiqué dans la section relatedURL de la note du package, en face du libellé PACKAGE_ATTESTATION_OCCURRENCE. La charge utile sérialisée JSON dans l'attestation correspond à la charge utile de la note du package et à sa signature. Cette attestation permet de vérifier l'intégrité du contenu de la note du package.
Une VulnerabilityNote et une VulnerabilityOccurrence pour chaque faille associée au package. La note et l'occurrence combinées fournissent des informations sur les failles, telles que le résumé ou la description de la faille, sa gravité, son score CVSSV3, les informations sur les versions affectées et corrigées, ainsi que les mesures correctives.

Accéder aux métadonnées de sécurité depuis Artifact Analysis

Vous pouvez accéder aux métadonnées de sécurité d'Artifact Analysis à l'aide des clients de l'API Artifact Analysis, qui sont disponibles dans différentes langues. Pour commencer à utiliser les bibliothèques clientes Cloud pour l'API Artifact Analysis, consultez Installer les bibliothèques clientes Artifact Analysis requises.

Pour accéder aux métadonnées de sécurité, procédez comme suit :

Étape 1 : Configurez l'authentification

Configurez l'authentification à l'aide des Identifiants par défaut de l'application (ADC).

Étape 2 : Récupérer les métadonnées de sécurité

Pour récupérer les métadonnées de sécurité, créez un package note_name à l'aide des informations suivantes :

Project_ID : identifiant alphanumérique de votre projet Google Cloud .
Package Language : Java ou Python. Elle doit être en majuscules.
Package_ID : pour Java, il s'agit de groupId_artifactId et pour Python, de packageName. Cette valeur est sensible à la casse. La casse valide pour le nom de version du package est disponible dans Lister tous les packages dans Assured OSS.
Version : version du package.

Le champ note_name doit avoir la structure suivante : projects/<project_id>/notes/<language>-<package_id>-<version>.

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

Option 1 :

Si vous utilisez les bibliothèques clientes Container Analysis, utilisez getNotes avec note_name pour interroger PackageNote. La PackageNote contient des liens vers d'autres notes et occurrences.

Option 2 :

Si vous utilisez la commande curl, exécutez la commande suivante :

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

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

Exemple de métadonnées

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

Utilisez les noms de notes et d'occurrences fournis dans la carte relatedURL pour récupérer des données supplémentaires liées à la source, à la compilation, au test et à la faille. Pour ce faire, utilisez les API GetNote et GetOccurrence ou les commandes curl. Pour BUILD_OCCURRENCE, supprimez le préfixe initial https://containeranalysis.googleapis.com/v1/ lorsque vous utilisez l'API. Pour les autres entités, utilisez directement les URL en tant que note_name ou occurrence_name dans le paramètre d'API.

Exemple de script Python

Un exemple de script Python qui affiche l'intégralité des métadonnées téléchargées est disponible à l'emplacement Cloud Storage suivant, ainsi que son fichier README :

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

Pour télécharger le script à l'aide de la Google Cloud CLI, procédez comme suit :

Configurez l'authentification à l'aide des Identifiants par défaut de l'application (ADC).
Installez la bibliothèque cliente Container Analysis. Plus précisément, cette commande doit installer les éléments suivants :
```
pip install google-cloud-containeranalysis
```
Installez les packages cloud-kms et cryptography à l'aide des commandes suivantes :
```
pip install --upgrade google-cloud-kms
pip install --upgrade cryptography
```
Téléchargez download_metadata.py sur votre système à l'aide de la commande suivante :
```
gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/download_metadata.py
PATH_TO_LOCAL_STORE --recursive
```
Remplacez PATH_TO_LOCAL_STORE par le chemin d'accès local où vous souhaitez enregistrer le fichier.
Téléchargez le README.md contenant les instructions d'utilisation du script à l'aide de la commande suivante :
```
gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/README.md PATH_TO_LOCAL_STORE --recursive
```
Remplacez PATH_TO_LOCAL_STORE par le chemin d'accès local où vous souhaitez enregistrer le fichier.

Exemple de commande

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

Pour vérifier les signatures dans les métadonnées d'analyse des conteneurs, ajoutez la commande suivante au script :

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