Anleitung: VEX-Attestierung erstellen

Diese Anleitung erklärt, wie Sie eine VEX-Attestierung (Vulnerability Exploitability eXchange) für Ihr Container-Image erstellen und an das Image anhängen.

Wann brauchen Sie das?

Ihr Image hat noch keine VEX-Attestierung
Sie haben Schwachstellen-Bewertungen in DevGuard aktualisiert und wollen das VEX-Dokument erneuern
Sie möchten die Compliance-Anforderung für container.gov.de erfüllen

Voraussetzungen:

DevGuard-Account mit Ihrem Image als Asset eingerichtet
Scan-Ergebnisse für Ihr Image in DevGuard vorhanden
Container-Image bereits in der Registry vorhanden
CI/CD-Pipeline in GitLab

container.gov.de verlangt, dass das VEX-Dokument:

Als In-Toto-Attestierung am Image hängt (nicht als separate Datei)
Den Predicate-Typ https://cyclonedx.org/vex verwendet
Alle kritischen und hohen CVEs mit einem Status versehen hat, der nicht in_triage ist

Option A: VEX Attestierung mit DevGuard CI-Komponente an ein Image anfügen

Es stehen eine Reihe an CI-Components im Rahmen des Platform-Services DevGuard zur Verfügung, mit denen Sie die Erstellung und Anfügung von VEX-Attestierungen in Ihre CI/CD-Pipeline integrieren können. Die Komponenten lesen die hinterlegten Bewertungen der CVEs in DevGuard aus, in dem sie den VEX aus DevGuard herunterladen und hängen den VEX als In-Toto-Attestierung mit dem Predicate-Typ https://cyclonedx.org/vex an das Image an.

# .gitlab-ci.yml
stages:
  - attestation
 
.common: &common
  devguard_asset_name: $DEVGUARD_ASSET_NAME
  devguard_token: '$DEVGUARD_TOKEN'
  devguard_api_url: 'https://api.devguard.opencode.de'
 
include:
  - component: $CI_SERVER_FQDN/l3montree/devguard-ci-components/attest@v1.0.1
    inputs:
      <<: *common
      devguard_artifact_name: 'pkg:oci/mein-image?repository_url=registry.opencode.de/oci-community/meine-gruppe/mein-image&arch=amd64&tag=main-amd64'
      image: $CI_REGISTRY_IMAGE:main-amd64
      attestations:
        - source: '$[[ inputs.devguard_api_url ]]/api/v1/organizations/$[[ inputs.devguard_asset_name ]]/refs/COMMIT_REF/artifacts/ARTIFACT_NAME/vex.json/'
          predicate_type: 'https://cyclonedx.org/vex'

Option B: VEX Attestierung manuell erstellen und anfügen

Diese Option eignet sich, wenn Sie keine CI/CD-Pipeline verwenden oder die Attestierung einmalig manuell durchführen möchten.

Voraussetzungen:

cosign installiert
VEX-Dokument im CycloneDX-Format als cdx.vex.json vorhanden (z. B. aus DevGuard heruntergeladen)

Schritt 1: Cosign-Schlüsselpaar erstellen

Erstellen Sie ein lokales Schlüsselpaar, mit dem Sie die Attestierung signieren:

cosign generate-key-pair

Dies erzeugt zwei Dateien:

cosign.key – privater Schlüssel (geheim halten, nicht in die Versionskontrolle einchecken)
cosign.pub – öffentlicher Schlüssel (zur späteren Verifikation)

Sie werden während der Erstellung nach einem Passwort gefragt, mit dem der private Schlüssel verschlüsselt wird. Das Passwort wird auch beim Attestieren benötigt.

Schritt 2: VEX-Dokument als Attestierung anfügen

Hängen Sie das VEX-Dokument als In-Toto-Attestierung mit dem Predicate-Typ https://cyclonedx.org/vex an Ihr Image:

cosign attest \
  --key cosign.key \
  --predicate cdx.vex.json \
  --type https://cyclonedx.org/vex \
  registry.opencode.de/oci-community/meine-gruppe/mein-image:1.0.0

Ersetzen Sie registry.opencode.de/oci-community/meine-gruppe/mein-image:1.0.0 durch den tatsächlichen Pfad zu Ihrem Image inklusive Tag.

Hinweis: Sie müssen gegenüber der Registry authentifiziert sein (docker login registry.opencode.de), damit cosign die Attestierung pushen kann.

Attestierung verifizieren

Prüfen Sie, ob die VEX-Attestierung korrekt am Image hängt:

cosign verify-attestation \
  --key cosign.pub \
  --type https://cyclonedx.org/vex \
  registry.opencode.de/oci-community/images/gruppe/mein-image:1.0.0

Alternativ zeigt der DevGuard Scanner beim Compliance-Check, ob eine VEX-Attestierung gefunden wurde:

devguard-scanner attestations \
  registry.opencode.de/oci-community/images/gruppe/mein-image:1.0.0 \
  --policy container.gov.de.rego

VEX-Dokument aktuell halten

Wichtig: VEX-Dokumente müssen aktuell sein. Wenn neue CVEs bekannt werden, muss das VEX-Dokument erneuert werden (oder eine externalReference enthalten, welche auf ein ständig aktualisiertes VEX-Dokument zeigt). Am besten integrieren Sie die Erstellung der VEX-Attestierung in Ihre CI/CD-Pipeline, damit sie automatisch bei jedem Build aktualisiert wird.:

Neue Schwachstellen werden bekannt
Bewerten Sie neue kritische/hohe CVEs in DevGuard
Starten Sie die CI/CD-Pipeline neu – sie erstellt und hängt automatisch eine neue VEX-Attestierung an