Ü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 das kostenlose Kontingent.

Sicherheitsmetadatendateien

Die Sicherheitsmetadaten für jede Assured OSS-Paketversion werden 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. wenn das Paket neu erstellt wird, das Zertifikat rotiert wird oder neue Felder hinzugefügt werden.
  • vexinfo.zip: Diese Datei enthält die Informationen zu Sicherheitslücken für ein Paket im CycloneDX 1.4-Format. Dieser Wert ändert sich, sobald 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. Das kann sich ändern, wenn der Teststatus eines Pakets geändert wird. Das kann beispielsweise der Fall sein, wenn ein neuer Sicherheitstest durchgeführt wird oder sich das Ergebnis der Abdeckung ändert.
  • licenseinfo.zip: Diese Datei enthält Metadaten zu den Lizenzinformationen eines Pakets. Die Lizenzinformationen eines Pakets können sich ändern, wenn der Verlag des Pakets die Informationen ändert.

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

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

JSON-Dateistruktur

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

buildInfo.json

  • creationTime: Die Erstellungszeit 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 Anfragen oder Beschwerden.
  • buildDetails: die Details zum Erstellen des Binärprogramms. 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. Dies wird von Cloud Build generiert.
    • envelope: Ein String, der einen DSSE-Umschlag darstellt, mit dem die Integrität des Herkunftsnachweisdokuments überprüft werden kann. Dies wird auch von Cloud Build generiert.
    • slsaLevel: Gibt die vom Build-System eingehaltene SLSA-Stufe an.
    • buildTool: Name des Tools, das zum Erstellen des Pakets verwendet wird, nämlich Cloud Build. Weitere Informationen finden Sie unter Cloud Build.
    • transitiveClosureState: Dies ist ein ENUM, das angibt, ob alle Build-Abhängigkeiten für das Paket (direkt oder indirekt) auch im Portfolio von Assured OSS vorhanden sind. Dieses Feld kann zwei Werte haben:
      • OPEN: Wenn keine oder nur teilweise transitive Abhängigkeiten von Assured OSS unterstützt werden.
      • CLOSED: Gibt an, ob 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 dem Release angehängt ist.
    • tag: Das Release-Tag, das der Paketversion zugeordnet ist.
    • host: Name des Systems, das den Quellcode auf GitHub hostet.
    • commitTime: Die Zeit eines Commits im RFC 3339-Stringformat.
  • sbom – SBOM-String im SPDX 2.3-Format.

vexInfo.json

  • creationTime: Die Erstellungszeit 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 Anfragen oder Beschwerden.
  • vexData: VEX-String (Vulnerability Exploitability eXchange) im CycloneDX 1.4-Format.

healthInfo.json

  • creationTime: Die Erstellungszeit 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 Anfragen oder Beschwerden.
  • testingData: die Details zu den Sicherheitstests, die für ein Paket durchgeführt wurden. Die folgenden Details werden angegeben:
    • testType: Der durchgeführte Testtyp. 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: Für das Paket war kein Test erforderlich. Fuzzing ist beispielsweise nicht für ein Paket erforderlich, das nur Schnittstellen enthält.
      • 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 mit dem Paket verknüpfte Lizenz.

Auf Sicherheitsmetadaten aus Cloud Storage zugreifen

So greifen Sie über Cloud Storage auf die Sicherheitsmetadaten zu:

Schritt 1: Authentifizierung einrichten

Informationen zum Einrichten der Authentifizierung finden Sie unter Authentifizierung einrichten.

Schritt 2: URL erstellen

Sie können die Metadaten mit den Befehlen 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 es groupId:artifactId und für Python packageName. Der Wert muss in Kleinbuchstaben angegeben 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 angegeben werden.

Beispiel-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 angegeben werden.

Beispiel-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, Informationen zum Status 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 werden auf drei ZIP-Dateien (buildinfo.zip, healthinfo.zip, vexinfo.zip) verteilt und in den Ausgabefolder 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. Unter macOS oder Linux verwenden Sie 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 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