Mit der Artifact Analysis API auf Metadaten zugreifen

Assured Open Source Software (Assured OSS) bietet Sicherheitsmetadaten für jedes verfügbare Paket und jede Paketversion. Sie können in Artefaktanalyse 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 mit Cloud Storage finden Sie unter Mit Cloud Storage auf Metadaten zugreifen.

Sicherheitsmetadaten

Artifact Analysis bietet Metadatenspeicherung gemäß dem Open-Source-Modell Grafeas. Für jede Version des Pakets werden die folgenden Informationen bereitgestellt:

  • Eine PackageNote für jede Version des Pakets, die von Assured OSS veröffentlicht wurde. Die Paketnotiz enthält Folgendes:

    • distribution wobei jedes distribution einem Artefakt entspricht, das von Assured OSS bereitgestellt wird. Sie enthält den Speicherort und den Digest url (von dem die Signatur und der Hash heruntergeladen werden können) für binäre und reproduzierbare Quellen.
    • relatedURL, die Links zu Metadaten wie Build-Herkunft, Testbestätigung und Sicherheitslücken enthält.

  • Ein BuildOccurrence. Der Link zu diesem Build-Vorkommen wird im Abschnitt relatedURL des Pakethinweises neben dem Label BUILD_OCCURRENCE angegeben. Das intotoStatement im Build-Vorkommen enthält die SLSA v0.2-Herkunft.

  • Ein zweites BuildOccurrenance. Der Link zu diesem Build-Vorkommen wird im Abschnitt relatedURL des Pakethinweises neben dem Label ORIGINAL_SOURCE_PROVENANCE angegeben. Diese Datei enthält die ursprünglichen Quelldetails (GitHub) in Form von Source.

  • Ein AttestationOccurrence. Der Link zu diesem Attestierungsvorkommen wird im Abschnitt relatedURL des Pakethinweises neben dem Label TEST_OCCURRENCE angegeben. Die serialisierte Nutzlast in der Attestierung enthält JSON, das alle Sicherheitstests darstellt, die für die Paketversion durchgeführt wurden.

  • Ein zweites AttestationOccurrence. Der Link zu diesem Attestierungsvorkommen wird im Abschnitt relatedURL des Pakethinweises neben dem Label PACKAGE_ATTESTATION_OCCURRENCE angegeben. Die JSON-serialisierte Nutzlast in der Attestierung ist die Nutzlast des Pakethinweises und die zugehörige Signatur. Diese Attestierung wird verwendet, um die Integrität des Inhalts des Paket-Hinweises zu prüfen.

  • Eine VulnerabilityNote und ein VulnerabilityOccurrence für jede mit dem Paket verknüpfte Sicherheitslücke. Die Kombination aus Hinweis und Vorkommen liefert Informationen zu Sicherheitslücken, z. B. eine Zusammenfassung oder Beschreibung der Sicherheitslücke, den Schweregrad, den CVSSV3-Score, Informationen zu betroffenen und behobenen Versionen sowie Abhilfemaßnahmen.

Auf Sicherheitsmetadaten aus Artefaktanalyse zugreifen

Sie können über die Artifact Analysis API-Clients, die in verschiedenen Sprachen verfügbar sind, auf die Sicherheitsmetadaten von Artefaktanalyse zugreifen. Informationen zu den ersten Schritten mit den Cloud-Clientbibliotheken für die Artifact Analysis API finden Sie unter Erforderliche Artefaktanalyse-Clientbibliotheken installieren.

So greifen Sie auf die Sicherheitsmetadaten zu:

Schritt 1: Authentifizierung einrichten

Richten Sie die Authentifizierung mit Standardanmeldedaten für Anwendungen ein.

Schritt 2: Sicherheitsmetadaten abrufen

Wenn Sie Sicherheitsmetadaten abrufen möchten, erstellen Sie ein note_name-Paket mit den folgenden Informationen:

  • Project_ID: Die alphanumerische Kennung für Ihr Google Cloud -Projekt.
  • Package Language: Java oder Python. Dieser muss in Großbuchstaben angegeben werden.
  • Package_ID: Für Java ist es groupId_artifactId und für Python packageName. Bei diesem Wert wird die Groß- und Kleinschreibung berücksichtigt. Die gültige Schreibweise für den Releasenamen des Pakets finden Sie unter Alle Pakete in Assured OSS auflisten.
  • Version: Die Version des Pakets.

Der note_name sollte die folgende Struktur haben: projects/<project_id>/notes/<language>-<package_id>-<version>.

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

Option 1:

Wenn Sie die Container Analysis-Clientbibliotheken verwenden, verwenden Sie getNotes mit dem note_name, um die PackageNote abzufragen. Der PackageNote enthält Links zu anderen Notizen und Vorkommen.

Methode 2:

Wenn Sie den Befehl curl verwenden, geben Sie Folgendes ein:

curl  -H "Content-Type: application/json" -H   "Authorization: Bearer $(gcloud auth print-access-token)" $URL
  • Verwenden Sie für Java die URL https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2.
  • Verwenden Sie für Python die URL https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/PYTHON-Flask-Cors-3.0.10.

Beispielmetadaten

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

Verwenden Sie die in der relatedURL-Zuordnung angegebenen Notiz- und Vorkommensnamen, um zusätzliche Daten zu Quelle, Build, Test und Sicherheitslücke abzurufen. Verwenden Sie dazu die APIs GetNote und GetOccurrence oder die curl-Befehle. Entfernen Sie für BUILD_OCCURRENCE das anfängliche Präfix https://containeranalysis.googleapis.com/v1/, wenn Sie die API verwenden. Verwenden Sie für andere Entitäten die URLs direkt als note_name oder occurrence_name im API-Parameter.

Python-Beispielskript

Ein Python-Beispielskript, das die gesamten heruntergeladenen Metadaten ausgibt, ist am folgenden Cloud Storage-Speicherort zusammen mit der zugehörigen README-Datei verfügbar:

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

So laden Sie das Script mit der Google Cloud CLI herunter:

  1. Richten Sie die Authentifizierung mit Standardanmeldedaten für Anwendungen ein.

  2. Installieren Sie die Container Analysis-Clientbibliothek. Mit diesem Befehl sollte Folgendes installiert werden:

    pip install google-cloud-containeranalysis

  3. Installieren Sie die Pakete „cloud-kms“ und „cryptography“ mit den folgenden Befehlen:

    pip install --upgrade google-cloud-kms
pip install --upgrade cryptography

  4. Laden Sie die download_metadata.py mit dem folgenden Befehl auf Ihr System herunter:

    gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/download_metadata.py
PATH_TO_LOCAL_STORE --recursive

    Ersetzen Sie PATH_TO_LOCAL_STORE durch den lokalen Pfad, unter dem Sie die Datei speichern möchten.

  5. Laden Sie mit dem folgenden Befehl die README.md-Datei herunter, die die Anleitung zur Verwendung des Scripts enthält:

    gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/README.md PATH_TO_LOCAL_STORE --recursive

    Ersetzen Sie PATH_TO_LOCAL_STORE durch den lokalen Pfad, unter dem Sie die Datei speichern möchten.

Beispielbefehl

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

Fügen Sie dem Script den folgenden Befehl hinzu, um die Signaturen in den Container Analysis-Metadaten zu prüfen:

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

Nächste Schritte