Über Cloud Storage auf Metadaten zugreifen

Assured Open Source Software (Assured OSS) bietet Sicherheitsmetadaten für jedes verfügbare Paket und jede Paketversion. Sie können in Cloud Storage auf diese Metadaten zugreifen, um Build-Details, den Status von Sicherheitslücken, Testergebnisse und Lizenzinformationen zu prüfen.

Dieses Dokument gilt nur für die kostenlose Stufe. Eine Anleitung zum Zugriff auf Metadaten mithilfe der Artifact Analysis API finden Sie unter Mit der Artefaktanalyse API auf Metadaten zugreifen.

Sicherheitsmetadatendateien

Die Sicherheitsmetadaten für jede Assured OSS-Paketversion sind auf die folgenden vier Dateien in einem Cloud Storage-Bucket verteilt:

  • buildinfo.zip: Diese Datei enthält Metadaten zu den Build-Informationen eines Pakets. Diese Metadaten würden sich in sehr seltenen Fällen ändern, z. B. beim Neuerstellen des Pakets, bei der Zertifikatsrotation und beim Hinzufügen neuer Felder.
  • vexinfo.zip: Diese Datei enthält die Informationen zu Sicherheitslücken für ein Paket im CycloneDX 1.4-Format. Dieser Wert ändert sich, wenn Informationen zu einer Sicherheitslücke für das Paket vorliegen.
  • healthinfo.zip: Diese Datei enthält Details zu den Tests, die für ein Paket durchgeführt wurden. Dies kann sich ändern, wenn der Teststatus eines Pakets geändert wird. Beispielsweise, wenn ein neuer Sicherheitstest durchgeführt wird oder sich das Abdeckungsergebnis ändert.
  • licenseinfo.zip: Diese Datei enthält Metadaten zu den Lizenzinformationen eines Pakets. Die Lizenzinformationen eines Pakets können sich ändern, wenn der Publisher des Pakets die Informationen ändert.

Jede ZIP-Datei enthält die folgenden beiden Dateien:

  • Eine JSON-Datei mit Daten.
  • Eine signature.zip-Datei, die die Signatur für diese Daten enthält.

JSON-Dateistruktur

Die Struktur der JSON-Dateien wird im folgenden Abschnitt beschrieben:

buildInfo.json

  • creationTime: der Erstellungszeitpunkt für dieses Dokument im Stringformat RFC 3339.
  • creator: der Inhaber des Dokuments. Die folgenden Details werden angegeben:
    • name: der Name der Organisation, die dieses Dokument erstellt hat.
    • email: die E-Mail-Adresse der Organisation für Fragen oder Beschwerden.
  • buildDetails: die Details zum Erstellen der Binärdatei. Die folgenden Details werden angegeben:
    • packageFileName: der Name der Datei, für die die Build-Details gelten.
    • buildProvenance: ein String, der die Build-Herkunft des Pakets im SLSA v0.2-Format darstellt. Diese wird von Cloud Build generiert.
    • envelope: Ein String, der einen DSSE-Envelope darstellt, mit dem die Integrität des Herkunftsdokuments überprüft werden kann. Diese wird ebenfalls von Cloud Build generiert.
    • slsaLevel: Gibt die SLSA-Stufe an, die vom Build-System eingehalten wird.
    • buildTool: Name des Tools, das zum Erstellen des Pakets verwendet wird, also Cloud Build. Weitere Informationen finden Sie unter Cloud Build.
    • transitiveClosureState: Dies ist ein ENUM, der angibt, ob alle Build-Abhängigkeiten für das Paket (direkt oder indirekt) auch im Portfolio von Assured OSS vorhanden sind oder nicht. Dieses kann zwei Werte haben:
      • OPEN: Wenn keine oder nur teilweise transitive Abhängigkeiten von Assured OSS unterstützt werden.
      • CLOSED: Wenn alle transitiven Abhängigkeiten von Assured OSS unterstützt werden.
  • sourceInfo: Informationen zum Quellcode, der zum Erstellen des Pakets verwendet wurde. Die folgenden Details werden angegeben:
    • sourceUrl: der GitHub-URL-String.
    • commitHash: Commit-Hash-String, der an den Release angehängt ist.
    • tag: das Release-Tag, das der Paketversion zugeordnet ist.
    • host: Name des Systems, das den Quellcode in GitHub hostet.
    • commitTime: der Zeitpunkt eines Commits im Stringformat RFC 3339.
  • sbom: SBOM-String im SPDX 2.3-Format.

vexInfo.json

  • creationTime: der Erstellungszeitpunkt für dieses Dokument im Stringformat RFC 3339.
  • creator: der Inhaber des Dokuments. Die folgenden Details werden angegeben:
    • name: der Name der Organisation, die dieses Dokument erstellt hat.
    • email: die E-Mail-Adresse der Organisation für Fragen oder Beschwerden.
  • vexData: VEX-String (Vulnerability Exploitability eXchange) im CycloneDX 1.4-Format.

healthInfo.json

  • creationTime: der Erstellungszeitpunkt für dieses Dokument im Stringformat RFC 3339.
  • creator: der Inhaber des Dokuments. Die folgenden Details werden angegeben:
    • name: der Name der Organisation, die dieses Dokument erstellt hat.
    • email: die E-Mail-Adresse der Organisation für Fragen oder Beschwerden.
  • testingData: Details zu den Sicherheitstests, die für ein Paket durchgeführt wurden. Die folgenden Details werden angegeben:
    • testType: die Art des durchgeführten Tests. Beispiel: FUZZ.
    • tool: der Name des Tools, mit dem der Test durchgeführt wurde.
    • testStatus: der Status des Tests. Der Status kann einer der folgenden sein:
      • TESTED: Tests wurden ausgeführt.
      • NOT_REQUIRED: Für das Paket waren keine Tests erforderlich. Fuzz-Tests sind beispielsweise nicht für ein Paket erforderlich, das nur Schnittstellen enthält.
      • UNTESTED: Paket wurde nicht getestet.

licenseInfo.json

  • package_name: Der Name des Pakets im Stringformat.
  • package_version: Die Version des Pakets.
  • license_info: Die mit dem Paket verknüpfte Lizenz.

Auf Sicherheitsmetadaten aus Cloud Storage zugreifen

So greifen Sie auf die Sicherheitsmetadaten aus Cloud Storage zu:

Schritt 1: Authentifizierung einrichten

Informationen zum Einrichten der Authentifizierung finden Sie unter Authentifizierung einrichten.

Schritt 2: URL erstellen

Sie können die Metadaten entweder mit dem Befehl gcloud storage oder curl herunterladen. Erstellen Sie die URL für beide mit den folgenden Informationen:

  • Sprache: java oder python. Der Wert muss in Kleinbuchstaben geschrieben werden.
  • Package_ID: Für Java ist dies groupId:artifactId und für Python packageName. Der Wert muss in Kleinbuchstaben geschrieben werden.
  • Version: Die Version des Pakets.
  • Metadata_Type: Wählen Sie zwischen buildinfo.zip, vexinfo.zip und healthinfo.zip aus.

Die URL muss das folgende Format haben:

gcloud

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

Die URL muss in Kleinbuchstaben geschrieben werden.

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

Beispiel-Java-URL: 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>

Die URL muss in Kleinbuchstaben geschrieben werden.

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

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

Schritt 3: Metadaten herunterladen

Verwenden Sie die folgenden Befehle, um die Metadaten herunterzuladen:

gcloud

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

Verwenden Sie den folgenden Befehl, um alle Metadatentypen wie Build-Informationen, Statusinformationen und VEX-Informationen für ein bestimmtes Paket und eine bestimmte Version herunterzuladen:

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

Die Metadaten werden auf drei ZIP-Dateien (buildinfo.zip, healthinfo.zip, vexinfo.zip) verteilt und in den Ausgabeordner heruntergeladen.

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

Schritt 4: Metadaten extrahieren

Extrahieren Sie die ZIP-Datei. Verwenden Sie unter macOS oder Linux den Befehl unzip: unzip input.zip -d outputFolder. Jede ZIP-Datei enthält eine JSON-Datei und eine signature.zip-Datei. Die JSON-Datei enthält die eigentlichen Sicherheitsmetadaten und die signature.zip-Datei enthält Dateien, mit denen die Google-Signatur in der JSON-Datei überprüft werden kann.

Lizenzinformationen herunterladen

Die Lizenzinformationen für alle Assured OSS-Pakete sind in einer einzigen JSON-Datei verfügbar. Führen Sie den folgenden Befehl aus, um diese Datei herunterzuladen:

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

Führen Sie den folgenden Befehl aus, um die Signatur für die Lizenzmetadatendatei herunterzuladen:

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

Nächste Schritte