Über Cloud Storage auf Metadaten zugreifen

Assured OSS bietet Sicherheitsmetadaten für jedes verfügbare Paket. Jede Version des Pakets hat eigene Metadaten. Auf dieser Seite wird erläutert, welche Informationen als Teil der Metadaten bereitgestellt werden und wie Sie auf diese Metadaten zugreifen können.

Sie können auf die Sicherheitsmetadaten mit einer der folgenden Optionen zugreifen:

  • Artifact Analysis API
  • Cloud Storage

Diese Seite gilt nur für die kostenlose Stufe.

Dateien mit Sicherheitsmetadaten

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

  • buildinfo.zip: Diese Datei enthält Metadaten zu den Build-Informationen eines Pakets. Diese Metadaten ändern sich nur in sehr seltenen Fällen, z. B. beim erneuten Erstellen 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. Diese Datei ändert sich immer, 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. Diese Datei kann sich ändern, wenn der Teststatus eines Pakets geändert wird. Das ist beispielsweise der Fall, 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 Herausgeber des Pakets die Informationen ändert.

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

  • Eine JSON-Datei mit Daten.
  • Eine Datei signature.zip mit der Signatur für diese Daten.

JSON-Dateistruktur

Die Struktur für die JSON-Dateien wird im folgenden Abschnitt beschrieben:

buildInfo.json

  • creationTime: Der Zeitpunkt der Erstellung dieses Dokuments im RFC 3339-Stringformat.
  • 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, auf die sich die Build-Details beziehen.
    • buildProvenance: Ein String, der die Build-Herkunft des Pakets im SLSA v0.2-Format darstellt. Dieser String wird von Cloud Build generiert.
    • envelope: Ein String, der einen DSSE-Umschlag darstellt, mit dem die Integrität des Herkunftsnachweisdokuments überprüft werden kann. Dieser String wird ebenfalls von Cloud Build generiert.
    • slsaLevel: Gibt die SLSA-Stufe an, die vom Build-System eingehalten wird.
    • buildTool: Der Name des Tools, das zum Erstellen des Pakets verwendet wird. In diesem Fall ist das Cloud Build. Weitere Informationen finden Sie unter Cloud Build.
    • transitiveClosureState: Eine ENUM, die angibt, ob alle Build-Abhängigkeiten für das Paket (direkt oder indirekt) auch im Portfolio von Assured OSS vorhanden sind. Dieser Wert 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: Die Informationen zum Quellcode, der zum Erstellen des Pakets verwendet wurde. Die folgenden Details werden angegeben:
    • sourceUrl: Der GitHub-URL-String.
    • commitHash: Der Commit-Hash-String, der an den Release angehängt ist.
    • tag: Das Release-Tag, das mit der Paketversion verknüpft ist.
    • host: Der Name des Systems, auf dem der Quellcode in GitHub gehostet wird.
    • commitTime: Der Zeitpunkt eines Commits im RFC 3339-Stringformat.
  • sbom - SBOM-String im SPDX 2.3-Format.

vexInfo.json

  • creationTime: Der Zeitpunkt der Erstellung dieses Dokuments im RFC 3339-Stringformat.
  • 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) in CycloneDX 1.4-Format.

healthInfo.json

  • creationTime: Der Zeitpunkt der Erstellung dieses Dokuments im RFC 3339-Stringformat.
  • 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: Die Details zu den Sicherheitstests, die für ein Paket durchgeführt wurden. Die folgenden Details werden angegeben:
    • testType: Der Typ des Tests, der durchgeführt wurde. Beispiel: FUZZ.
    • tool: Der Name des Tools, das zum Ausführen des Tests verwendet wurde.
    • testStatus: Der Status des Tests. Der Status kann einer der folgenden sein:
      • TESTED: Der Test wurde ausgeführt.
      • NOT_REQUIRED: Der Test war für das Paket nicht erforderlich. Fuzzing ist beispielsweise für ein Paket, das nur Schnittstellen enthält, nicht erforderlich.
      • UNTESTED: Das Paket wurde nicht getestet.

licenseInfo.json

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

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 Befehle gcloud storage oder curl verwenden, um die Metadaten herunterzuladen. Erstellen Sie die URL für beide Befehle mit den folgenden Informationen:

  • Sprache:java oder python. Der Wert muss in Kleinbuchstaben geschrieben werden.
  • Package_ID: Für Java ist das groupId:artifactId und für Python ist das 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 für eine Python-URL: gs://cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Beispiel für eine 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 für eine Python-URL: https://storage.googleapis.com/cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Beispiel für eine 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

Wenn Sie alle Metadatentypen wie Build-Informationen, Statusinformationen und VEX-Informationen für ein bestimmtes Paket und eine bestimmte Version herunterladen möchten, verwenden Sie den folgenden Befehl:

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

Die Metadaten sind auf drei ZIP-Dateien (buildinfo.zip, healthinfo.zip, vexinfo.zip) verteilt und werden in den Ausgabefordner 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 unzip Befehl: unzip input.zip -d outputFolder. Jede ZIP-Datei enthält eine JSON-Datei und eine Datei signature.zip. Die JSON-Datei enthält die eigentlichen Sicherheitsmetadaten und die Datei signature.zip enthält Dateien zum Überprüfen der Google-Signatur in der JSON-Datei.

Lizenzinformationen herunterladen

Die Lizenzinformationen für alle Assured OSS-Pakete sind in einer einzelnen 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