Mit der Artifact Analysis API 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.

Sicherheitsmetadaten

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

Eine PackageNote für jede von Assured OSS veröffentlichte Version des Pakets. Die Paketbenachrichtigung enthält Folgendes:
- distribution wobei jedes distribution einem von Assured OSS bereitgestellten Artefakt entspricht. 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 mit Links zu Metadaten wie Build-Herkunft, Testbestätigung und Sicherheitslücken.
Ein BuildOccurrence. Der Link zu diesem Build-Vorkommen ist im Abschnitt relatedURL der Paketmitteilung unter dem Label BUILD_OCCURRENCE angegeben. Die intotoStatement im Build-Vorkommen enthält die SLSA v0.2-Herkunft.
Eine zweite BuildOccurrenance. Der Link zu diesem Build-Vorkommen ist im Abschnitt relatedURL der Paketmitteilung unter dem Label ORIGINAL_SOURCE_PROVENANCE angegeben. Diese Datei enthält die ursprünglichen Quelldetails (GitHub) in Form von Source.
Eine AttestationOccurrence. Der Link zu diesem Attestierungsvorkommen ist im Abschnitt relatedURL des Paketvermerks unter 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.
Eine zweite AttestationOccurrence. Der Link zu diesem Attestierungsvorkommen ist im Abschnitt relatedURL des Paketvermerks unter dem Label PACKAGE_ATTESTATION_OCCURRENCE angegeben. Die JSON-serialisierte Nutzlast in der Attestierung ist die Nutzlast der Paketinformation und die Signatur dafür. Mit dieser Bestätigung wird die Integrität des Inhalts der Paketinformationen überprüft.
Eine VulnerabilityNote und ein VulnerabilityOccurrence für jede Sicherheitslücke, die mit dem Paket verknüpft ist. Die Anmerkung und das Vorkommen zusammen liefern Informationen zu Sicherheitslücken wie die Zusammenfassung oder Beschreibung der Sicherheitslücke, den Schweregrad, den CVSSV3-Wert, Informationen zur betroffenen und behobenen Version sowie die Behebung.

Über die Artefaktanalyse auf Sicherheitsmetadaten zugreifen

Sie können über die Artifact Analysis API-Clients, die in verschiedenen Sprachen verfügbar sind, auf die Sicherheitsmetadaten der 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

Authentifizierung mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) einrichten

Schritt 2: Sicherheitsmetadaten abrufen

Um Sicherheitsmetadaten abzurufen, erstellen Sie mit den folgenden Informationen ein note_name-Paket:

Project_ID: Die alphanumerische Kennung für Ihr Google Cloud -Projekt.
Package Language: Java oder Python. Sie 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 Release-Namen 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. Die PackageNote enthält Links zu anderen Notizen und Vorkommen.

Methode 2:

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

curl  -H "Content-Type: application/json" -H   "Authorization: Bearer $(gcloud auth print-access-token)" $URL

Für Java verwenden Sie die URL https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2.
Für Python verwenden Sie die URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/PYTHON-Flask-Cors-3.0.10

Beispiel für Metadaten

{
  "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-Karte angegebenen Anmerkungs- und Ereignisnamen, um zusätzliche Daten zu Quelle, Build, Test und Sicherheitslücke abzurufen. Verwenden Sie dazu die APIs GetNote und GetOccurrence oder die Befehle curl. Entfernen Sie für BUILD_OCCURRENCE das ursprü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.

Beispiel für ein Python-Script

Ein Beispiel für ein Python-Skript, mit dem die gesamten heruntergeladenen Metadaten ausgegeben werden, ist zusammen mit der README-Datei am folgenden Cloud Storage-Speicherort verfügbar:

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

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

Authentifizierung mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) einrichten
Clientbibliothek für die Containeranalyse installieren Mit diesem Befehl sollte Folgendes installiert werden:
```
pip install google-cloud-containeranalysis
```
Installieren Sie die Pakete „cloud-kms“ und „cryptography“ mit den folgenden Befehlen:
```
pip install --upgrade google-cloud-kms
pip install --upgrade cryptography
```
Laden Sie 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.
Laden Sie die README.md mit der Anleitung zur Verwendung des Skripts mit dem folgenden Befehl herunter:
```
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 Skript 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`