SMTP Server

Direkte SMTP-Server-Kommunikation

Damit der BOMnipotent Server direkt mit Ihrem E-Mail-Server kommunizieren kann, richten Sie den SMTP-Teil Ihrer Konfigurationsdatei in etwa so ​​ein:

[smtp]
user = "you@yourdomain.com"
endpoint = "your.smtp.host"
secret = "${SMTP_SECRET}"

Die genaue Form hängt stark von Ihrem E-Mail-Anbieter ab. Manche Anbieter benötigen die vollständige E-Mail-Adresse als Benutzer, andere nicht.

Clients wie Mozilla Thunderbird können die erforderlichen Parameter in der Regel sehr gut ableiten. Falls Sie nicht weiterkommen, suchen Sie dort nach ihnen.

Kommunikation über SMTP-Relay

Wenn Sie mehrere Dienste nutzen, die E-Mails versenden, kann es sinnvoll sein, lokal eine SMTP-Relay-Station zu betreiben. Sie bietet Ihrem Setup einen einzigen Endpunkt für die Kommunikation mit dem Mailserver.

Es gibt mehrere Docker-Container mit SMTP-Relay-Funktionalität. Dieses Tutorial konzentriert sich auf crazymax/msmtpd , da es unter den leichtgewichtigen Lösungen die beste Sicherheit bietet.

Relay über Docker Compose ausführen

Fügen Sie den folgenden Dienst zu Ihrer compose.yaml Datei hinzu:

  smtp_relay:
    container_name: smtp_relay
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"
    environment:
      TZ: Europe/Berlin # Ersetzen Sie dies durch Ihre bevorzugte Zeitzone
      SMTP_HOST: your.smtp.host # Ersetzen Sie dies durch den korrekten Endpunkt
      SMTP_PORT: 465
      SMTP_TLS: on
      SMTP_STARTTLS: off
      SMTP_TLS_CHECKCERT: on
      SMTP_AUTH: login
      SMTP_USER: you@yourdomain.com # Ersetzen Sie dies durch Ihren Benutzernamen
      SMTP_FROM: you@yourdomain.com # Ersetzen Sie dies durch Ihre E-Mail-Adresse
      SMTP_PASSWORD: ${SMTP_PASSWORD}
      SMTP_DOMAIN: localhost
    healthcheck:
      test: ["CMD", "msmtp", "--version"]
      interval: 30s
      timeout: 10s
      retries: 3
    image: crazymax/msmtpd
    logging:
      driver: local
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - smtp_network
    restart: unless-stopped

Dadurch wird der Container gestartet und verbindet sich mit Port 465 (dem Standard für das SMTPS-Protokoll) des SMTP-Hosts. Die Verschlüsselung erfolgt mit TLS und nicht mit STARTTLS. Der Server lauscht auf Port 2500. Dies ist zwar nicht aus der Eingabe ersichtlich, entspricht aber dem Standardverhalten von msmtp.

Die Änderung Ihrer Compose-Datei ist jedoch noch nicht abgeschlossen!

Unter „Netzwerke“ müssen Sie das SMTP-Netzwerk angeben:

  bomnipotent_server:
    container_name: bomnipotent_server
    depends_on:
      smtp_relay:
        condition: service_healthy
    ...
    networks:
      - smtp_network

Sie müssen das Netzwerk außerdem jedem Container hinzufügen, der es kontaktieren soll. Sie können diese Container auch vom SMTP-Relay abhängig machen, damit sie nicht gestartet werden, bevor die Relay Station bereit ist:

  bomnipotent_server:
    container_name: bomnipotent_server
    depends_on:
      smtp_relay:
        condition: service_healthy
    ...
    networks:
      - smtp_network

Neben den Änderungen an der Compose-Datei muss Ihre .env-Datei oder Ihre Umgebung das Geheimnis oder Passwort Ihres E-Mail-Anbieters enthalten:

SMTP_PASSWORD=eHD5B6S8Kze3

export SMTP_PASSWORD=eHD5B6S8Kze3

set SMTP_PASSWORD=eHD5B6S8Kze3

$env:SMTP_PASSWORD = "eHD5B6S8Kze3"

In Ihrer BOMnipotent Server-Konfigurationsdatei können Sie nun den SMTP-Abschnitt so anpassen, dass die Verbindung zum Relay über das Docker-Netzwerk hergestellt wird:

[smtp_config]
user = "you@yourdomain.com"
endpoint = "smtp://smtp_relay:2500"

Relay im eigenständigen Docker-Container ausführen

Wenn Ihr Setup keine Compose-Datei enthält, können Sie den Container stattdessen direkt mit Docker ausführen. Stellen Sie sicher, dass Ihre Umgebung einen Wert für SMTP_PASSWORD bereitstellt, und führen Sie anschließend Folgendes aus:

docker run --detach -p 2500:2500 --name smtp_relay \
    -e TZ=Europe/Berlin \
    -e SMTP_HOST=your.smtp.host \
    -e SMTP_PORT=465 \
    -e SMTP_TLS=on \
    -e SMTP_STARTTLS=off \
    -e SMTP_TLS_CHECKCERT=on \
    -e SMTP_AUTH=login \
    -e SMTP_USER=you@yourdomain.com \
    -e SMTP_FROM=you@yourdomain.com \
    -e SMTP_PASSWORD=${SMTP_PASSWORD} \
    -e SMTP_DOMAIN=localhost \
    crazymax/msmtpd

Dies funktioniert im Wesentlichen wie der für die compose Datei vorgeschlagene Abschnitt. Ersetzen Sie erneut die Werte für TZ, SMTP_HOST, SMTP_USER und SMTP_FROM durch die Werte Ihres E-Mail-Anbieters.

Der obige Befehl stellt Port 2500 für localhost bereit. Ihre BOMnipotent-Konfiguration muss daher wie folgt lauten:

[smtp_config]
user = "you@yourdomain.com"
endpoint = "smtp://localhost:2500"

Um den Container zu stoppen, führen Sie Folgendes aus:

docker stop smtp_relay

SBOMs mit Syft

Eine Software Bill of Materials (SBOM) ist eine Liste aller Softwarekomponenten, die in deinem Produkt verwendet werden. Im Kontext der Lieferkettensicherheit dient sie als maschinenlesbare Liste von Elementen, mit der neue Schwachstellen abgeglichen werden können, sobald sie bekannt werden.

Es gibt mehrere Tools zur automatischen Erstellung einer solchen SBOM. Dieses Tutorial konzentriert sich auf Syft von Anchore, einem Open-Source-Kommandozeilentool.

Einrichtung

Das offizielle Syft GitHub Repository enthält Installationsanweisungen. Die Installation ist über ein Shell-Skript oder verschiedene Paketmanager möglich.

Auf manchen Linux-Systemen sollten Sie den Installationspfad (das letzte Argument des Shell-Befehls) auf “~/.local/bin” ändern, da für Änderungen an “/usr/local/bin” Root-Rechte erforderlich sind.

curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b ~/.local/bin

[info] checking github for the current release tag 
[info] fetching release script for tag='v1.28.0' 
[info] checking github for the current release tag 
[info] using release tag='v1.28.0' version='1.28.0' os='linux' arch='amd64' 
[info] installed /root/.local/bin/syft 

Verwendung

Die grundlegende Verwendung von Syft lautet:

syft <Ziel> [Optionen]

Zusätzlich lassen sich einige Konfigurationen über Umgebungsvariablen vornehmen.

Syft unterstützt Lockfiles, Verzeichnisse, Container-Images und weitere Zieltypen.

Lockfile

Ein Beispielaufruf sieht folgendermaßen aus:

SYFT_FORMAT_PRETTY=1 syft /home/your_project/Cargo.lock --output cyclonedx-json=/home/your_project/sbom.cdx.json --source-name="Your Project" --source-version="1.0.0"

SYFT_FORMAT_PRETTY=1 syft /home/your_project/Cargo.lock -o cyclonedx-json=/home/your_project/sbom.cdx.json --source-name="Your Project" --source-version="1.0.0"

Erklärung:

• ‘SYFT_FORMAT_PRETTY=1’ setzt eine Umgebungsvariable, die Syft anweist, durch Menschen besser lesbare Ausgabe zu produzieren. Eine vollständige Liste der Konfigurationen befindet sich hier .
• ‘syft’ ruft das Syft-Programm auf.
• ‘Cargo.lock’ gibt an, dass Syft die Lockfile-Datei des Rust-Ökosystems analysieren soll.
• ‘–output cyclonedx-json=./sbom.cdx.json’ legt fest, dass die Ausgabe im CycloneDx JSON-Format in der Datei ‘./sbom.cdx.json’ gespeichert wird.
  • Beachten Sie, dass ‘.cdx.json’ die empfohlene Dateiendung ist.
• ‘–source-name=“BOMnipotent”’ gibt an, dass diese Quellen zu der Komponente BOMnipotent gehören, was Syft nicht in allen Fällen automatisch erkennen kann.
  • Das CycloneDX-Schema erfordert möglicherweise keinen Komponentennamen, aber BOMnipotent benötigt ihn.
• ‘–source-version=“1.0.0”’ gibt Syft die aktuelle Version des Projekts an.
  • Falls keine Version angegeben wird, versucht BOMnipotent, stattdessen den Zeitstempel als Versionszeichenkette zu verwenden.

Syft unterstützt eine Vielzahl von Ökosystemen, welche in Ihrem GitHub repo aufgelistet sind.

Verzeichnis

Syft kann auf ein ganzes Verzeichnis angewendet werden, allerdings ist das oft übertrieben. Es durchsucht alle Unterverzeichnisse und erfasst alles, was entfernt wie eine Lockfile aussieht, einschließlich aller Testabhängigkeiten, Entwicklungsskripte und GitHub Actions.

SYFT_FORMAT_PRETTY=1 syft /home/your_project/ --output cyclonedx-json=/home/your_project/dev_env_sbom.cdx.json --source-name="Your Development Environment" --source-version=1.2.3

SYFT_FORMAT_PRETTY=1 syft /home/your_project/ -o cyclonedx-json=/home/your_project/dev_env_sbom.cdx.json --source-name="Your Development Environment" --source-version=1.2.3

Container

Falls Sie einen Docker-Container als ‘.tar’-Datei exportiert haben, können Sie diesen ebenfalls als Ziel angeben:

syft container.tar --output cyclonedx-json=./container_sbom.cdx.json --source-name="BOMnipotent Container" --source-version=1.2.3

syft container.tar -o cyclonedx-json=./container_sbom.cdx.json --source-name="BOMnipotent Container" --source-version=1.2.3

Bei kompilierten Sprachen können die Ergebnisse stark abweichen, da die meisten Informationen über die Komponenten, die in die Kompilierung eingeflossen sind, verloren gehen. Andererseits enthält diese SBOM Informationen über die Umgebung, in der das Produkt später möglicherweise ausgeführt wird.

Abschließende Bemerkungen

Bei der Auswahl eines Ziels ist es wichtig, den Umfang der Anwendung zu berücksichtigen: Was wird an den Kunden ausgeliefert? In welchem Umfang sind Sie für die Lieferkette des Produkts verantwortlich? Bei Unentschlossenheit spricht nichts dagegen, mehrere Varianten einer SBOM hochzuladen – solange der Produktname oder die Version unterschiedlich ist.

Sobald die SBOM generiert ist, kann sie mit dem BOMnipotent Client auf dem BOMnipotent Server hochgeladen werden.

Danach können Sie Grype nutzen, um regelmäßig nach Sicherheitslücken zu scannen .

Sicherheitslücken mit Grype

Sobald Ihre SBOM (Software Bill of Materials) erstellt wurde, ist es an der Zeit, sie kontinuierlich auf Schwachstellen zu scannen. Beachten Sie, dass einige Gesetze, wie beispielsweise der Cyber Resilience Act der EU, vorschreiben, dass Produkte ohne bekannte Schwachstellen veröffentlicht werden. Der erste Scan sollte daher vor einer Veröffentlichung erfolgen.

Es gibt verschiedene Tools zur Überprüfung eines Produkts auf Schwachstellen in der Lieferkette. Dieses Tutorial verwendet Grype von Anchore, da es sich gut mit Syft von Anchore aus dem SBOM tutorial integriert. Genau wie Syft ist Grype ein Open-Source-Befehlszeilenprogramm.

Einrichtung

Das offizielle Grype GitHub Repository enthält Installationsanweisungen. Ähnlich wie bei Syft können Sie den Installationspfad (das letzte Argument des Shell-Befehls) auf ‘~/.local/bin’ ändern, da ‘/usr/local/bin’ Root-Berechtigungen zum Ändern erfordert.

curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b ~/.local/bin

[info] checking github for the current release tag 
[info] fetching release script for tag='v0.96.0' 
[info] checking github for the current release tag 
[info] using release tag='v0.96.0' version='0.96.0' os='linux' arch='amd64' 
[info] installed /root/.local/bin/grype 

Verwendung

Sobald eine SBOM vorliegt, ist das Scannen auf Schwachstellen sehr einfach:

grype sbom:/home/your_project/sbom.cdx.json --fail-on low

grype sbom:/home/your_project/sbom.cdx.json -f low

[0025] ERROR discovered vulnerabilities at or above the severity threshold
NAME    INSTALLED  FIXED IN  TYPE        VULNERABILITY        SEVERITY  EPSS  RISK  
rustls  0.23.15    0.23.18   rust-crate  GHSA-qg5g-gv98-5ffh  Medium    N/A   N/A

Beim Ausführen dieses Befehls überprüft Grype mehrere Schwachstellendatenbanken auf Übereinstimmungen mit den im SBOM angegebenen Komponenten. Die Option ‘fail-on’ sorgt dafür, dass das Programm mit einem Fehlercode ungleich null beendet wird, falls eine Schwachstelle mit mindestens der angegebenen Schwere ’low’ gefunden wird.

Die Syntax zum Exportieren eines Schwachstellenberichts, der von BOMnipotent verarbeitet werden kann, ist ähnlich wie bei Syft:

grype sbom:/home/your_project/sbom.cdx.json --output cyclonedx-json=/home/your_project/vuln.cdx.json

grype sbom:/home/your_project/sbom.cdx.json -o cyclonedx-json=/home/your_project/vuln.cdx.json

Grype lässt sich leicht mit BOMnipotent kombinieren. Sie können das “bom get” Kommando von BOMnipotent Client verwenden, um den Inhalt einer BOM direkt in die Konsole ausgeben zu lassen, und diesen dann an Grype weitergeben:

bomnipotent_client bom get "Your Project" "1.0.0" | grype --output cyclonedx-json=/home/vuln.cdx.json

bomnipotent_client bom get "Your Project" "1.0.0" | grype -o cyclonedx-json=/home/vuln.cdx.json

CI/CD

BOMnipotent wurde für die Automatisierung entwickelt. Es fordert den Nutzer nie zur interaktiven Eingabe auf und ist damit vollständig skriptbar.

Diese Seite beschreibt, wie Sie den BOMnipotent-Client in Ihrer CI/CD-Pipeline verwenden, um mit jedem Release BOMs hochzuladen und täglich auf Schwachstellen zu prüfen.

Weichwerke Heidrich Software hat mehrere einsatzbereite GitHub-Actions zur Integration von BOMnipotent in Ihre Pipeline entwickelt. Die meisten davon basieren auf Bash-Skripten, um die Übertragung in andere Pipeline-Umgebungen so einfach und nahtlos wie möglich zu gestalten.

Voraussetzungen

Dieses Setup setzt voraus, dass Sie eine BOMnipotent-Serverinstanz installiert haben. Falls dies noch nicht der Fall ist, lesen Sie die Setup-Anleitung .

Die Pipeline erfordert außerdem, dass der Server über ein genehmigtes Roboter-Benutzerkonto mit den Berechtigungen BOM_MANAGEMENT und VULN_MANAGEMENT verfügt. Die Abschnitte zur Kontoerstellung und Zugriffsverwaltung enthalten weitere Informationen zur Einrichtung.

BOMnipotent-Client einrichten

Die Bereitstellung ausführbarer Dateien ist der Bereich, in dem sich die verschiedenen Pipeline-Umgebungen am meisten unterscheiden. Glücklicherweise ist dies auch die Hürde, die DevOps-Ingenieure sehr früh überwinden. Daher wird diese Aufgabe derzeit nur für GitHub-Actions beschrieben, für die ein einsatzbereiter Schritt vorhanden ist.

GitHub-Action

Die Action zum Einrichten von BOMnipotent Client finden Sie im GitHub Marketplace .

Ein typischer Ausschnitt aus Ihrer Workflow-YAML-Datei sieht wie folgt aus (mit Ausnahme der Einrückung, weil YAML…):

- name: Installieren von BOMnipotent Client
  uses: Weichwerke-Heidrich-Software/setup-bomnipotent-action@v1
  with:
    domain: '<Ihre-Server-Domain>'
    user: '<Ihr-Roboter-Nutzer>'
    secret-key: ${{ secrets.CLIENT_SECRET_KEY }} 

Ein ausführlicheres Beispiel finden Sie auf GitHub .

Die drei Parameter sind optional, werden aber empfohlen:

• domain: Geben Sie die vollständige Domäne (einschließlich Subdomäne) für Ihre BOMnipotent-Serverinstanz an. Diese wird in einer Sitzung gespeichert, sodass Sie sie bei nachfolgenden Aufrufen nicht erneut angeben müssen.
• user: Speichern Sie den Benutzernamen Ihres Roboterbenutzers, den Sie im Abschnitt Voraussetzungen eingerichtet haben.
• secret-key: Geben Sie eine Referenz auf den geheimen Schlüssel an, der zur Authentifizierung des Roboterbenutzers verwendet wird. Sie können ihn Ihrer Pipeline über <your repo> → Einstellungen → Geheimnisse und Variablen → Aktionen → Neues Repository-Geheimnis zur Verfügung stellen. Im obigen Beispiel heißt er “CLIENT_SECRET_KEY”.

Achtung: Speichern Sie Ihren geheimen Schlüssel nicht direkt in der Pipeline oder einer anderen versionierten Datei. Genau dafür ist der GitHub-Secret-Mechanismus konzipiert.

Nach Ausführung dieser Aktion steht der Befehl “bomnipotent_client.exe” (Windows) bzw. “bomnipotent_client” (UNIX) für den Rest des Jobs zur Verfügung. Da verschiedene Jobs in unterschiedlichen Containern ausgeführt werden, kann es erforderlich sein, die Setup-Aktion im Laufe des Workflows mehrmals aufzurufen.

BOMs hochladen

Eine Stückliste / Bill of Material (BOM) ist eine Liste der Komponenten eines Produkts. Da es sich um ein statisches Dokument handelt, ist jede BOM eng mit einem bestimmten Release des Produkts verknüpft. Ändern sich die Komponenten des (veröffentlichten) Produkts, sollte dieses mit einer neuen Version versehen und einer neuen BOM zugeordnet werden.

Deshalb sollte das Hochladen einer BOM auf den Server als Teil der Release-Pipeline ausgeführt werden.

Gemäß dem Single Responisbility Prinzip sind für das Hochladen von Stücklisten einige Voraussetzungen erforderlich: – Der BOMnipotent Client Befehl muss verfügbar sein. Es gibt eine separate Action , die genau das sicherstellt. – Die Action benötigt als Eingabe eine BOM im CycloneDX-Format, die zuvor generiert werden muss.

Die Erstellung einer BOM ist sehr produktspezifisch. Das ideale Tool hängt vom jeweiligen Ökosystem und dessen Nutzung ab. Syft ist ein Tool, das Sie dabei unterstützen kann und eine einsatzbereite GitHub-Action bereitstellt. Es ist jedoch bei weitem nicht die einzige Option: Das CycloneDX Tool Center bietet zahlreiche Alternativen.

GitHub-Action

Ein häufiges Muster besteht darin, die Release-Pipeline durch das Pushen eines Tags auszulösen, welches einer semantischen Version entspricht:

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'

Nachdem der BOMnipotent-Client eingerichtet und die BOM generiert wurde, kann es mit dem folgenden Ausschnitt hochgeladen werden:

- name: BOM Hochladen
  uses: Weichwerke-Heidrich-Software/upload-bom-action@v1
  with:
    bom: './bom.cdx.json'
    name: '${{ github.event.repository.name }}'
    version: '${{ github.ref_name }}'
    tlp: 'amber'

Die Action akzeptiert mehrere Argumente:

• bom: Dies ist das einzige obligatorische Argument. Es muss auf eine vorhandene Datei verweisen, die eine BOM im CycloneDX-Format enthält. In diesem Beispiel wurde die Stückliste unter “./bom.cdx.json” gespeichert.
• name / version: Der CycloneDX-Standard erfordert für eine BOM keinen Namen und keine Version, BOMnipotent hingegen schon. Falls das zur Erstellung der Stückliste verwendete Tool die Festlegung von Name und/oder Version nicht ermöglicht, können Sie diese über Argumente überschreiben. Im obigen Beispiel wird der Repository-Name als Produktname und das auslösende Tag als Version verwendet. Alternativ können Sie auch einen Dateipfad angeben: Die Zeile version: './version.txt' weist die Aktion beispielsweise an, die Datei “./version.txt” zu lesen und den Inhalt als Versionszeichenfolge zu verwenden.
• tlp: Sie können ein TLP-Label angeben, um die hochgeladene Stückliste zu klassifizieren. Falls nicht angegeben, gilt das Default-TLP des Servers.

Eine vollständige Liste der Argumente finden Sie auf dem GitHub Marketplace .

Andere Pipeline

Die GitHub-Action ist lediglich ein Wrapper für ein Bash-Skript. Um eine BOM über Ihre Pipeline-Infrastruktur hochzuladen, können Sie das Skript aus dem Repository herunterladen und verwenden.

if [ ! -f ./upload_bom.sh ]; then
    curl https://raw.githubusercontent.com/Weichwerke-Heidrich-Software/upload-bom-action/refs/heads/main/upload_bom.sh > ./upload_bom.sh
    chmod +x ./upload_bom.sh
fi
./upload_bom.sh <bom.cdx.json> <optional args...>

Das Skript verwendet dieselben Argumente wie die Aktion, mit der Ausnahme, dass das Argument “bom” positionell ist und optionalen Argumenten ein doppelter Bindestrich vorangestellt werden muss:

./upload_bom.sh ./bom.cdx.json --name <product-name> --version <product-version> --tlp amber

Auf Sicherheitslücken prüfen

BOMs selbst sind zwar statische Objekte, die die Zusammensetzung eines Produkts dokumentieren, sie müssen aber regelmäßig auf Sicherheitslücken geprüft werden. Die meisten Datenbanken von Sicherheitslücken werden täglich aktualisiert, daher sollten Prüfungen ähnlich häufig durchgeführt werden.

Die BOMnipotent Vulnerability Action umfasst zwei Schritte: – Aktualisierung der bekannten Sicherheitslücken aller BOMs auf dem Server. – Überprüfung des Servers auf neue, noch nicht bewertete Sicherheitslücken.

Beide Schritte können einzeln übersprungen werden, falls sie für Ihren Anwendungsfall nicht relevant sind.

GitHub-Action

Um die Sicherheitslückenprüfung beispielsweise täglich um 3:00 Uhr morgens auszuführen, fügen Sie Ihrem Workflow-YAML-Dokument den folgenden Trigger hinzu:

on:
  schedule:
    - cron: '0 3 * * *' # Runs the workflow every day at 03:00 UTC

Sobald sie auf dem Agent BOMnipotent Client aufgesetzt haben , ist der Ausschnitt zur Handhabung der Sicherheitslücken sehr einfach:

- name: Update Vulnerabilities
  uses: Weichwerke-Heidrich-Software/vulnerability-action@v1

Ein vollständiges Beispiel finden Sie im GitHub Marketplace .

Das Skript lädt alle dem Robernutzer zugänglichen BOMs herunter, gleicht sie mit mehreren Datenbanken bekannter Sicherheitslücken ab, und aktualisiert sie auf dem Server.

Anschließend prüft es, ob noch nicht bewertete Sicherheitslücken vorhanden sind. Eine Sicherheitslücke gilt als nicht bewertet, wenn BOMnipotent-Server kein ihr zugeordnetes CSAF-Dokument enthält.

Andere Pipeline

Analog zum Upload-Schritt ist diese Action im Wesentlichen ein Wrapper für ein Bash-Skript. Sie können das Skript im Repository referenzieren oder direkt herunterladen und verwenden:

if [ ! -f ./upload_bom.sh ]; then
    curl https://raw.githubusercontent.com/Weichwerke-Heidrich-Software/vulnerability-action/refs/heads/main/update_vulns.sh > ./update_vulns.sh
    chmod +x ./update_vulns.sh
fi
./update_vulns.sh

Das Skript verwendet intern grype um auf Sicherheitslücken zu prüfen. Falls Sie das Skript direkt verwenden müssen Sie sicherstellen, dass das Programm installiert ist.

CSAF Docs mit Secvisogram

Das Common Security Advisory Framework (CSAF) ist ein maschinenlesbares Format und ein internationaler Standard für den Informationsaustausch über Cyber-Sicherheitslücken. Es informiert Nutzer Ihres Produkts über die richtige Reaktion: Müssen sie auf eine neuere Version aktualisieren? Müssen sie eine Konfiguration ändern? Ist Ihr Produkt überhaupt betroffen oder ruft es den betroffenen Teil der anfälligen Bibliothek möglicherweise nie auf?

Der CSAF-Standard von OASIS Open deckt ein sehr breites Spektrum an Szenarien ab. Aus diesem Grunde kann er zunächst sehr überwältigend sein. Diese Seite zeigt die wichtigsten Komponenten eines CSAF-Dokuments und bietet einen praktischen Leitfaden für den sofortigen Einstieg.

Secvisogram

CSAF-Dokumente sind Dateien im JSON-Format, die einem bestimmten Schema folgen. Daher können sie grundsätzlich mit jedem Texteditor erstellt werden. CSAF-Dokumente müssen jedoch eine Vielzahl von Regeln einhalten, die jeder CSAF-Anbieter (und das schließt BOMnipotent mit ein) überprüfen muss.

Stattdessen wird die Verwendung von Secvisogram empfohlen. Es handelt sich um eine Open-Source-Serveranwendung mit grafischer Benutzeroberfläche, die ursprünglich vom Bundesamt für Sicherheit in der Informationstechnik (BSI) entwickelt wurde.

Lokaler Editor

Der wohl bequemste Einstieg in das Schreiben von CSAF-Dokumenten ist das Forken des Repositorys local_csaf_editor der AUNOVIS GmbH . Es enthält ein kleines Bash-Skript zum lokalen Klonen und Ausführen von Secvisogram. Es ermuntert Sie weiterhin dazu, versionierte CSAF-Vorlagen zu speichern, da einige Eigenschaften von Advisory zu Advisory immer gleich bleiben.

Wichtige Einträge

Die Erstellung eines validen CSAF-Dokuments ist eine Reise, die Sie von sich selbst über Ihre Produkte bis hin zu den Sicherheitslücken führt, die sie plagen. Diese Seite ist Ihre Karte und Ihr Reisebegleiter.

Wichtige Dokument Einträge

Dokumenteigenschaften liefern Informationen über das CSAF-Dokument selbst. Sie geben unter anderem Aufschluss darüber, wie es identifiziert werden kann, wer es wann erstellt hat, und mit wem es geteilt werden darf.

Titel

Der Titel des Dokuments soll dem menschlichen Leser den Inhalt des Dokuments verdeutlichen. Es ist sinnvoll, den Produktnamen und die Art der Sicherheitslücke im Titel anzugeben, es gibt jedoch keine formalen Einschränkungen.

In Secvisogram finden Sie den Titel unter “Metadaten auf Dokumentebene”.

Publisher

Der Abschnitt Publisher dient Ihrer eindeutigen Identifizierung als Herausgeber des Dokuments.

Er enthält die Pflichtfelder “Name”, “Namespace” und “Category” sowie die optionalen Felder “Issuing Authority” und “Contact Details”. Die hier angegebenen Werte sollten mit den Werten in Ihrer Provider-Metadaten -Konfiguration übereinstimmen, die für das Hosten von CSAF-Dokumenten erforderlich ist. Die Dokumentationsseite enthält weitere Informationen zu den hier anzugebenden Werten.

Tracking

Der Abschnitt Tracking enthält wichtige Metadaten zum Dokument. Er soll in erster Linie maschinenlesbar sein. Der erforderlichen Felder gibt es viele:

• ID: Die ID dient zusammen mit Ihrem Herausgeber-Namespace zur Identifizierung eines Dokuments. Sie muss daher innerhalb Ihrer Organisation eindeutig sein. Darüber hinaus verlangt der Standard lediglich, dass die ID nicht mit einem Leerzeichen beginnt oder endet. Es wird jedoch empfohlen, nur Kleinbuchstaben, Ziffern sowie die Symbole “+”, “-” und “_” zu verwenden, denn der Standard empfiehlt, dass Dateinamen für CSAF-Dokumente diesem Muster folgen. Abweichungen davon können zu Verwirrung und sogar Konflikten führen. Es gibt keinen triftigen Grund dafür, dass eine ID nicht mit ihrem Dateinamen identisch sein sollte.
• Initial Release Date (Erstveröffentlichungsdatum) und Current Release Date (Aktuelles Veröffentlichungsdatum) sind wunderbar selbsterklärende Felder.
• Status: Dieser Status muss “draft” (“Entwurf”), “interim” (“Zwischenstand”) oder “final” (“Endstand”) sein. Der Status informiert Ihre Nutzer über die voraussichtliche Änderungsrate des Dokuments. Vor dem ursprünglichen Veröffentlichungsdatum muss der Status “draft” sein.
• Version: Sie können entweder die semantische Versionierung oder eine natürliche Zahl als Dokumentversion verwenden. Es wird empfohlen, mit 1 als (semantische) Major Version oder als natürliche Zahl zu beginnen. Bei jeder Änderung Ihres Dokuments müssen Sie die Version erhöhen. Bei semantischen Versionen bedeutet dies, dass mindestens die Patch-Version erhöht werden muss, während bei natürlichen Zahlenversionen die Zahl mindestens um 1 erhöht werden muss.
• Revisionsverlauf: Dieser muss für jede veröffentlichte Version einen Eintrag mit Zeitstempel, Version und Zusammenfassung enthalten.

Distribution - TLP

Obwohl Sie das CSAF-Dokument nicht klassifizieren müssen, möchten Sie dies wahrscheinlich. Dies geschieht mithilfe des Traffic Light Protocol (TLP) , mit dem Sie die Informationen auf eine einzelne Person, eine Organisation und ihre Kunden, eine ganze Community oder gar nicht beschränken können.

Diese Klassifizierung hat programmatische Konsequenzen: Ein als TLP:WHITE oder TLP:CLEAR klassifiziertes Dokument wird von BOMnipotent öffentlich freigegeben, während Dokumente mit einer anderen Klassifizierung eine explizite Authentifizierung und Zugriff erfordern, um angezeigt zu werden.

Wenn Sie im Dokument keine Klassifizierung angeben, verwendet der BOMnipotent-Server ein konfigurierbares Standard-TLP . Dies bedeutet jedoch, dass die TLP-Informationen verloren gehen, sobald das Dokument vom Server heruntergeladen wird. Daher wird eine Klassifizierung im Dokument empfohlen.

Bitte beachten Sie, dass der CSAF-Standard nur die Klassifizierung mit den veralteten TLP v1.0 Labels vorsieht. Sofern Sie sich strikt daran halten, sollte die URL im Dokument https://www.first.org/tlp/v1/ lauten (dies entspricht nicht der von Secvisogram angebotenen URL).

Viele CSAF-Herausgeber bevorzugen jedoch die Klassifizierung ihrer Dokumente mit dem TLP v2.0 Label TLP:AMBER+STRICT, welches nur die Verteilung innerhalb einer Organisation erlaubt. Sie können BOMnipotent so konfigurieren , dass auch CSAF-Dokumente akzeptiert werden, die mit TLP v2.0-Labels klassifiziert sind.

Wichtige Product Tree Einträge

Der Produktbaum enthält Informationen darüber, welche Produkte von dem Advisory abgedeckt sind. Diese sind in Zweige gruppiert, die, ähnlich wie Namespaces, zur Strukturierung Ihres Produktkatalogs dienen.

Erstellen Sie am besten eine Vorlage mit allen Ihren Produkten (oder Produktfamilien, falls dies Ihren Anforderungen besser entspricht). Das Löschen irrelevanter Produkte aus einem Dokument ist in Sekundenschnelle erledigt, das Hinzufügen fehlender Produkte birgt hingegen das Risiko, einige zu vergessen.

Branches

Branches (Zweige) bestehen immer aus genau drei Feldern: einem Namen , einer Kategorie und anschließend entweder einem Produkt oder weiterer Zweige.

Diese rekursive Definition sollte mit einem allgemeinen Überblick beginnen und dann bis zu den einzelnen Releases heruntergehen. Eine sehr plausible Struktur ist die folgende:

• Ein oberster Zweig mit der Kategorie “vendor” (“Anbieter”). Der Name entspricht dem Namen Ihrer Organisation.
• Der Zweig “vendor” enthält für jedes Ihrer Produkte einen Zweig mit der Kategorie “product_name” (“Produktname”). Sollten die Produkte zu zahlreich werden, können Sie sie zusätzlich in Zweigen mit der Kategorie “product_family” (“Produktfamilie”) gruppieren.
• Jeder Zweig “product_name” enthält einen Zweig für jede “product_version” (“Produktversion”). Wichtig ist, dass der Name des Zweigs tatsächlich eine Version und nicht einen Versionsbereich darstellt. Dafür gibt es eine separate Kategorie. Wenn Sie für verschiedene Architekturen entwickeln, empfiehlt sich die Einrichtung eines Unterzweigs mit der Kategorie “architecture”.

Für welche Zweigstruktur Sie sich auch entscheiden, die untersten Zweige müssen ein Produktfeld enthalten. Dieses muss die folgenden Felder enthalten:

• Name: Ein idealerweise eindeutiger Name, der menschlichen Lesern die Identifizierung des Produkts erleichtert. Dies kann auch die Verkettung aller Zweignamen sein, die zu diesem Punkt führen.
• Produkt-ID: Die Produkt-ID dient zur Referenzierung dieses Produkts im aktuellen Dokument. Es gelten keine besonderen Anforderungen, außer dass sie im Dokument eindeutig sein muss.

Das Produkt kann einen Produktidentifizierungshelfer enthalten. Dieser ist in erster Linie relevant, um anderen Personen die Identifizierung Ihres Produkts von außerhalb des aktuellen Dokuments zu erleichtern.

Zuordnung zu BOMs

BOMnipotent nutzt die product_name und product_version Einträge Ihrer Branches, um Produkt IDs von CSAF Dokumenten mit BOMs zu assoziieren. Dies befähigt es, zu prüfen , ob eine in einer BOM gefundene Sicherheitslücke von einem CSAF Dokument abgedeckt wird.

Wichtig: Falls der CSAF Branch, der zu einem Produkt führt, keinen product_name oder product_version Eintrag enthält, ist BOMnipotent nicht in der Lage, die Produkt ID mit einer BOM zu assoziieren.

Falls der Branch hingegen mehr als einen product_name oder product_version Eintrag hat, nutzt BOMnipotent jweils den spezifischsten Wert, welches der ist, der am weitesten unten in der Baumstruktur ist.

Als Beispiel betrachten Sie die folgende (schematische) Baumstruktur:

product_name: Umbrella
    product_version: 1.0.0
        product_id: umbrella_1.0.0
    product_version: 1.1.0
        product_name: Flowersheet
            product_id: umbrella_1.1.0_flowersheet
    architecture: linux
        product_id: umbrella_linux

Hier würde BOMnipotent die folgenden Zuordnungen machen:

• Die ID “umbrella_1.0.0” mit der BOM mit dem Namen “Umbrella” und der Version “1.0.0”.
• Die ID “umbrella_1.1.0_flowersheet” mit der BOM mit Namen “Flowersheet” und Version “1.1.0” (“Flowersheet” wird als Produktname bevorzugt, weil es weiter unten in der Baumstruktur ist als “Umbrella”).
• Die ID “umbrella_linux” mit gar keiner BOM, da sie keinen Eintrag für product_version hat.

Wichtige Vulnerabilities Einträge

Vulnerabilities sind Einträge, die Ihren Nutzern mitteilen, welche Produkte (nicht) von einer Sicherheitslücke betroffen sind und welche Maßnahmen ergriffen werden müssen.

Titel

Der Titel dient dazu, menschlichen Lesern zu zeigen, welche Sicherheitslücke in diesem CSAF-Dokument behandelt wird.

CVE und IDs

Diese wichtigen Felder werden von Maschinen zur Identifizierung einer Sicherheitslücke verwendet. Es gibt verschiedene Systeme zur Identifizierung von Sicherheitslücken. Das bekannteste ist die Common Vulnerabilities and Exposures (CVE) Trackingnummer. Wenn für die Sicherheitslücke eine CVE-Nummer vorhanden ist, können Sie diese in das entsprechende Feld eingeben.

Wird die Sicherheitslücke über ein anderes System verfolgt, können Sie deren ID im Feld IDs angeben. Jeder Eintrag enthält zwei Felder:

• Systemname: Dient zur Identifizierung des Tracking-Systems. Dies kann beispielsweise “GitHub Security Advisories” oder “GitHub Issue” sein. Nur “CVE” ist nicht zulässig, da CVEs über das dedizierte Feld angegeben werden.
• Text: Der tatsächliche Wert der ID, z. B. “GHSA-abcd-efgh-ijkl” oder “Weichwerke-Heidrich-Software/bomnipotent_doc#37”.

Hinweis: In Secvisogram müssen Sie die “Aktive Relevanzstufe” auf 4 setzen, um IDs eingeben zu können, die keine CVEs sind.

Notes

Jede Sicherheitslücke muss mindestens eine Notiz enthalten. Eine Notiz hat eine Kategorie und einen Inhalt. In den meisten Fällen reicht es aus, einen Hinweis mit der Kategorie “description” (“Beschreibung”) hinzuzufügen und die Beschreibung der Sicherheitslücke aus der offiziellen Quelle zu übernehmen.

Anders verhält es sich natürlich, falls die Sicherheitslücke keine offizielle Beschreibung hat, weil sie direkt aus Ihrem Produkt stammt. In diesem Fall sollten Sie eine weitere Notiz mit der Kategorie “details” hinzufügen.

Produktstatus

Die Listen mit den Produktstati können als das Herzstück des Advisorys verstanden werden. Sie sind maschinenlesbare Listen, die Informationen darüber enthalten, ob ein Produkt von einer Sicherheitslücke betroffen ist oder nicht. Es wird empfohlen, alle Ihre Product IDs (also alle Versionen aller Produkte) mindestens in die folgenden Kategorien zu sortieren:

• Known affected: Diese Versionen sind von der Sicherheitslücke betroffen.
• Fixed: Diese Versionen enthalten einen Fix und sind daher nicht von der Sicherheitslücke betroffen.
• Recommended: Dies ist die Version, die Sie zur Verwendung empfehlen. Sie sollte idealerweise auch in Ihrer Liste der behobenen Probleme aufgeführt sein.

Es kommt nicht selten vor, dass eine Sicherheitslücke in Ihrer Lieferkette Ihr Produkt nicht tatsächlich betrifft. Dies kann daran liegen, dass Ihr Produkt die anfälligen Pfade nie nutzt. In diesem Fall sollten Sie auch Einträge zu “known not affected” hinzufügen. Andernfalls werden Nutzer Ihres Produkts mit Zugriff auf Ihre SBOM möglicherweise über die Sicherheitslücke benachrichtigt und fragen nach, ob sie Maßnahmen ergreifen müssen.

Hinweis: Im Secvisogram müssen Sie die “Aktive Relevanzstufe” auf 4 setzen, um alle verfügbaren Stati anzuzeigen.

Remediations

Für jedes betroffene (oder aktuell untersuchte) Produkt müssen Sie mindestens einen Eintrag erstellen, der eine remediation (Abhilfemaßnahme) beschreibt. Der Eintrag muss Folgendes enthalten:

• eine Kategorie, zum Beispiel “mitigation”, “workaround” oder “no_fix_planned” (Risikoakzeptanz ist eine valide Strategie).
• Einzelheiten zur Anwendung der Abhilfemaßnahme oder warum keine Fehlerbehebung geplant ist.
• Ein Verweis auf mindestens eine Produkt-ID.