Offizielle Website - Bundesrepublik Deutschland
Menü

Tutorial: Erstes Image auf container.gov.de veröffentlichen

In diesem Tutorial lernen Sie, wie Sie ein Container-Image auf container.gov.de veröffentlichen.

Voraussetzungen für dieses Tutorial:

Was Sie am Ende haben werden: Ein Container-Image, das in der Container-Registry von openCode liegt, durch DevGuard auf Schwachstellen geprüft wurde, ein VEX-Dokument besitzt und die container.gov.de-Compliance-Policy erfüllt.

Dieses Tutorial nutzt die openCode-Instanz von DevGuard für das Schwachstellenmanagement. Die container.gov.de-Richtlinie erfordert allerdings ausschließlich, dass ein Schwachstellenmanagement durchgeführt und Ergebnisse an das Image attestiert werden. Es steht Ihnen frei, andere Tools zu verwenden.

Schritt 1: DevGuard-Projektinformationen beschaffen

Öffnen Sie devguard.opencode.de und melden Sie sich mit Ihrem openCode-Account an. DevGuard importiert alle Ihre Gruppen und Projekte automatisch.

  1. Navigieren Sie zu Ihrem Projekt, in dem das Image gebaut werden soll. Die Struktur der Projekte in DevGuard spiegelt die Projekte bei openCode wider. Wenn Sie also ein Projekt beispiel-projekt auf openCode unter dem Pfad oci-community > ihre-gruppe > beispiel-projekt haben, finden Sie dieses Projekt auch in DevGuard unter demselben Pfad.

    Hier sehen Sie später die Ergebnisse der Schwachstellenscans und können Bewertungen vornehmen.

  2. Um die CI/CD-Pipeline mit DevGuard zu verbinden, benötigen Sie einen API-Token und ihren devguard_asset_name. Auf dem Onboarding Screen ihres Projekts finden Sie beide Informationen unter Essential Project Information. Kopieren Sie den API-Token und den Asset-Namen, Sie benötigen diese später für die CI/CD-Pipeline.

Hinweis: Wenn Sie ein Projekt vor kurzem angelegt haben, kann es notwendig sein, in DevGuard in der openCode-Ansicht auf den Button Import Projects zu klicken, damit das Projekt in DevGuard erscheint.

Schritt 2: Containerfile erstellen

Dieses Containerfile dient als Ausgangspunkt für Ihr Image, das auf container.gov.de gelistet werden soll. Sie können natürlich auch ein komplexeres Image bauen. In diesem Tutorial verwenden wir ein einfaches Debian-basiertes Image:

Bennen Sie die Datei Containerfile und fügen Sie folgenden Inhalt hinzu:

FROM registry.opencode.de/oci-community/images/zendis/nodejs:20-main-amd64

# Anwendung als non-root User ausführen
USER 53111

Weitere Anforderungen entnehmen Sie der Härtungs-Checkliste.

Schritt 3: GitLab-CI/CD-Pipeline einrichten

Erstellen Sie in Ihrem Repository eine .gitlab-ci.yml. Die folgende Pipeline nutzt die CI-Komponenten, um ein OCI-Image zu bauen, automatisch auf Schwachstellen zu scannen und die Ergebnisse als Attestierung an das Image zu hängen.

Setzen Sie die folgenden CI/CD-Variablen in Ihrem GitLab-Projekt (Einstellungen → CI/CD → Variablen):

VariableWert
DEVGUARD_TOKENIhr DevGuard API-Token aus Schritt 1
DEVGUARD_ASSET_NAMEIhr DevGuard Asset-Name im Format @opencode/projects/<gruppe>/assets/<project> aus Schritt 1
stages:
  - test
  - oci-image
  - attestation
 
.common: &common
  devguard_asset_name: $DEVGUARD_ASSET_NAME
  devguard_token: '$DEVGUARD_TOKEN'
  devguard_api_url: 'https://api.devguard.opencode.de'
  devguard_web_ui: 'https://devguard.opencode.de'
 
include:
  - component: $CI_SERVER_FQDN/l3montree/devguard-ci-components/secret-scanning@v1.0.1
    inputs:
      <<: *common
  - component: $CI_SERVER_FQDN/l3montree/devguard-ci-components/infrastructure-as-code-scanning@v1.0.1
    inputs:
      <<: *common
  # The container lifecycle generates a tag, builds an OCI image, scans it, signs it and attests it.
  - component: $CI_SERVER_FQDN/l3montree/devguard-ci-components/container-lifecycle@v1.0.1
    inputs:
      <<: *common
      build_args: '--context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Containerfile'
      fail_on_cvss: 'high'

Schritt 4: Pipeline ausführen und Scan-Ergebnis prüfen

Pushen Sie Ihr Containerfile und die .gitlab-ci.yml. Die Pipeline startet automatisch und DevGuard führt nach dem Build einen Vulnerability-Scan durch.

In der gegebenen Konfiguration schlägt die Pipeline fehl, wenn kritische oder hohe Schwachstellen gefunden werden. Sie können die Details der Schwachstellen in DevGuard einsehen und bewerten. Bei dem nächsten Pipeline-Durchlauf, schlägt die Pipeline für diese Findings dann nicht mehr an. Die Bewertungen werden bei jedem Durchlauf der Pipeline aus DevGuard gelesen und als VEX-Attestierung an das Image angehängt, was wiederum die Compliance-Prüfung beeinflusst.

Öffnen Sie das Ergebnis in DevGuard:

  1. Navigieren Sie zu Ihrem Projekt auf devguard.opencode.de
  2. Klicken Sie auf Dependency Risk
  3. Sie sehen nun alle gefundenen Schwachstellen aufgelistet

Schritt 5: Schwachstellen bewerten (VEX)

Damit Ihr Image die Compliance-Anforderungen erfüllt, muss jede kritische oder hohe Schwachstelle bewertet sein. Eine Schwachstelle im Status in_triage gilt als unbewertet und verhindert das Listing.

Für jede nach CVSS kritische oder hohe CVE (CVSS-Score ≥ 7,0) in DevGuard müssen Sie diese entweder beheben oder bewerten:

Schwachstelle beheben: Wenn möglich, aktualisieren Sie Ihr Containerfile oder die zugrunde liegenden Pakete, um die Schwachstelle zu beseitigen. Beim nächsten Push wird die Pipeline erneut ausgeführt und der Scan aktualisiert.

Hinweis: Wenn Sie in DevGuard auf eine Schwachstelle klicken, sehen Sie die Details und mögliche Behebungsmaßnahmen. Details finden Sie auch in der Dokumentation zu Mitigationsstrategien.

Schwachstelle bewerten: Wenn eine Behebung nicht möglich ist, müssen Sie die Schwachstelle bewerten. Wählen Sie für jede kritische oder hohe CVE einen der folgenden Status:

StatusBedeutung
Falsch-PositivCVE gilt nicht für dieses Image
Risiko akzeptiertRisiko dokumentiert und bewusst akzeptiert

Hinweis: Alle kritischen und hohen CVEs müssen bewertet sein, bevor das Image gelistet werden kann. CVEs mit mittlerem oder niedrigem Schweregrad können im Status in_triage verbleiben.

Schritt 6: Pipeline erneut ausführen

Führen Sie Ihre Pipeline erneut aus, damit die Bewertungen als VEX-Attestierung an das Image angehängt werden. Sobald alle kritischen und hohen Schwachstellen bewertet sind, sollte die Compliance-Prüfung erfolgreich sein.

Nach erfolgreichem Pipeline-Durchlauf sind dem Image mehrere Attestierungen angehängt (.att): standardmäßig die generierte SBOM, der VEX mit den in DevGuard erzeugten Zuständen sowie eine SLSA Build Provenance des Images. Alle Attestierungen sind über die SHA256-Prüfsumme des Images verknüpft und in der Container Registry einsehbar.

Screenshot der Container Registry, zeigt ein Image und die Verbindung über die SHA256 Pürfsumme zu den Attestierungen und Signaturen

Schritt 7: Compliance lokal prüfen

Bevor Sie Ihr Image einreichen, können Sie die Compliance lokal gegen die container.gov.de-Policy testen.

Installieren Sie dafür die DevGuard-CLI:

go install github.com/l3montree-dev/devguard/cmd/devguard-scanner@v1.0.1

Laden Sie die aktuelle container.gov.de-Policy herunter:

curl -LO https://gitlab.opencode.de/oci-community/container-gov/-/raw/main/data-generation/container.gov.de.rego

Führen Sie anschließend die Compliance-Prüfung aus:

devguard-scanner attestations \
  registry.opencode.de/oci-community/documentation/beispiel-projekt:main-amd64 \
  --policy container.gov.de.rego

Hinweis: Ersetzen Sie registry.opencode.de/oci-community/documentation/beispiel-projekt:main durch den tatsächlichen Pfad zu Ihrem Image in der Registry. Diesen finden Sie in Ihrem Projekt auf gitlab.opencode unter Deploy → Container Registry.

Die Ausgabe zeigt:

  • Ob das Image compliant ist (runs.results.kind = pass)
  • Ob das Image noch nicht compliant ist und welche CVEs noch im Status in_triage sind (= Verstöße gegen die Compliance-Policy)

Schritt 8: Image zur Listung einreichen

Wenn die Compliance-Prüfung erfolgreich war, reichen Sie Ihr Image ein:

  1. Öffnen Sie ein Issue im Projekt oci-community/container-gov auf openCode
  2. Verwenden Sie die Vorlage Image-Listung beantragen
  3. Tragen Sie ein:
    • Den vollständigen Image-Pfad in der Registry
    • Den Namen und Maintainer des Images
    • Eine kurze Beschreibung des Images und seines Verwendungszwecks

Das SGCI-Team prüft Ihren Antrag und übernimmt das Image in die öffentliche Listung auf container.gov.de.

Zusammenfassung

Sie haben in diesem Tutorial:

  1. Ein DevGuard-Projekt angelegt und einen API-Token erstellt
  2. Ein minimales, gehärtetes Containerfile erstellt
  3. Eine GitLab CI/CD-Pipeline mit automatischem Scanning eingerichtet
  4. Alle kritischen und hohen Schwachstellen in DevGuard bewertet
  5. Die Compliance lokal gegen container.gov.de.rego geprüft
  6. Das Image zur Listung eingereicht

Nächste Schritte