Accéder aux métadonnées à l'aide de Cloud Storage

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.

Fichiers de métadonnées de sécurité

Les métadonnées de sécurité de chaque version du package Assured OSS sont réparties dans les quatre fichiers suivants d'un bucket Cloud Storage :

  • buildinfo.zip : ce fichier contient des métadonnées sur les informations de compilation d'un package. Ces métadonnées ne changent que dans de très rares cas, comme la reconstruction du package, la rotation des certificats et l'ajout de nouveaux champs.
  • vexinfo.zip : ce fichier contient les informations sur les failles d'un package au format CycloneDX 1.4. Cette valeur devrait changer chaque fois qu'une information sur une faille du package est disponible.
  • healthinfo.zip : ce fichier contient des informations sur les tests effectués sur un package. Cela peut changer si l'état de test d'un package est modifié. Par exemple, si un nouveau test de sécurité est effectué ou si le résultat de la couverture est modifié.
  • licenseinfo.zip : ce fichier contient des métadonnées relatives aux informations sur la licence d'un package. Les informations sur la licence d'un package peuvent changer si l'éditeur du package les modifie.

Chaque fichier ZIP contient les deux fichiers suivants :

  • Fichier JSON contenant des données.
  • Un fichier signature.zip contenant la signature de ces données.

Structure du fichier JSON

La structure des fichiers JSON est décrite dans la section suivante :

buildInfo.json

  • creationTime : heure de création de ce document au format de chaîne RFC 3339.
  • creator : propriétaire du document. Les informations suivantes sont fournies :
    • name : nom de l'organisation qui a créé ce document.
    • email : adresse e-mail de l'organisation en cas de question ou de réclamation.
  • buildDetails : détails liés à la création du binaire. Les informations suivantes sont fournies :
    • packageFileName : nom du fichier auquel s'appliquent les détails de la compilation.
    • buildProvenance : chaîne représentant la provenance de la compilation du package au format SLSA v0.2. Il est généré par Cloud Build.
    • envelope : chaîne représentant une enveloppe DSSE pouvant être utilisée pour vérifier l'intégrité du document de provenance. Il est également généré par Cloud Build.
    • slsaLevel : indique le niveau SLSA respecté par le système de compilation.
    • buildTool : nom de l'outil utilisé pour créer le package, à savoir Cloud Build. Pour en savoir plus, consultez Cloud Build.
    • transitiveClosureState : il s'agit d'un ENUM indiquant si toutes les dépendances de compilation du package (directes ou indirectes) sont également présentes dans le portefeuille Assured OSS ou non. Il peut avoir deux valeurs :
      • OPEN : si aucune dépendance transitive ou seulement une partie est prise en charge par Assured OSS.
      • CLOSED : si toutes les dépendances transitives sont prises en charge par Assured OSS.
  • sourceInfo : informations sur le code source utilisé pour compiler le package. Les informations suivantes sont fournies :
    • sourceUrl : chaîne d'URL GitHub.
    • commitHash : chaîne de hachage de commit associée à la version.
    • tag : tag de version associé à la version du package.
    • host : nom du système qui héberge le code source dans GitHub.
    • commitTime : heure d'un commit au format de chaîne RFC 3339.
  • sbom : chaîne SBOM au format SPDX 2.3.

vexInfo.json

  • creationTime : heure de création de ce document au format de chaîne RFC 3339.
  • creator : propriétaire du document. Les informations suivantes sont fournies :
    • name : nom de l'organisation qui a créé ce document.
    • email : adresse e-mail de l'organisation en cas de question ou de réclamation.
  • vexData : chaîne Vulnerability Exploitability eXchange (VEX) au format CycloneDX 1.4.

healthInfo.json

  • creationTime : heure de création de ce document au format de chaîne RFC 3339.
  • creator : propriétaire du document. Les informations suivantes sont fournies :
    • name : nom de l'organisation qui a créé ce document.
    • email : adresse e-mail de l'organisation en cas de question ou de réclamation.
  • testingData : détails des tests de sécurité effectués sur un package. Les informations suivantes sont fournies :
    • testType : type de test effectué. Exemple :FUZZ
    • tool : nom de l'outil utilisé pour effectuer le test.
    • testStatus : état du test. L'état peut être l'un des suivants :
      • TESTED : les tests ont été exécutés.
      • NOT_REQUIRED : les tests n'étaient pas requis pour le package. Par exemple, les tests fuzz ne sont pas nécessaires sur un package qui ne contient que des interfaces.
      • UNTESTED : le package n'a pas été testé.

licenseInfo.json

  • package_name : nom du package au format chaîne.
  • package_version : version du package.
  • license_info : licence associée au package.

Accéder aux métadonnées de sécurité depuis Cloud Storage

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

Étape 1 : Configurez l'authentification

Pour en savoir plus sur la configuration de l'authentification, consultez Configurer l'authentification.

Étape 2 : Construisez l'URL

Vous pouvez utiliser des commandes gcloud storage ou curl pour télécharger les métadonnées. Créez l'URL pour les deux en utilisant les informations suivantes :

  • Langue : java ou python. La valeur doit être en minuscules.
  • Package_ID: : pour Java, il s'agit de groupId:artifactId et pour Python, de packageName. La valeur doit être en minuscules.
  • Version : version du package.
  • Metadata_Type: : choisissez entre buildinfo.zip, vexinfo.zip et healthinfo.zip.

L'URL doit respecter le format suivant :

gcloud

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

Notez que l'URL doit être en minuscules.

Exemple d'URL Python : gs://cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Exemple d'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>

Notez que l'URL doit être en minuscules.

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

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

Étape 3 : Téléchargez les métadonnées

Utilisez les commandes suivantes pour télécharger les métadonnées :

gcloud

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

Pour télécharger tous les types de métadonnées (informations sur la compilation, informations sur l'état, informations VEX, etc.) pour un package et une version donnés, utilisez la commande suivante :

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

Les métadonnées sont réparties dans trois fichiers ZIP (buildinfo.zip, healthinfo.zip, vexinfo.zip) et téléchargées dans le dossier de sortie.

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

Étape 4 : Extrayez les métadonnées

Extrayez le fichier ZIP. Sur macOS ou Linux, utilisez la commande unzip : unzip input.zip -d outputFolder. Chaque fichier ZIP contient un fichier JSON et un fichier signature.zip. Le fichier JSON contient les métadonnées de sécurité proprement dites, et le fichier signature.zip contient les fichiers permettant de vérifier la signature Google sur le fichier JSON.

Télécharger les informations sur la licence

Les informations sur la licence de tous les packages Assured OSS sont disponibles dans un seul fichier JSON. Pour télécharger ce fichier, exécutez la commande suivante :

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

Pour télécharger la signature du fichier de métadonnées de licence, exécutez la commande suivante :

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

Étapes suivantes