Zuletzt aktualisiert: 11. September

Sichere CI/CD-Pipelines mit b2sum und CLI

Tim Koschützki

Mitgründer · Berlin, Deutschland ·

Die Sicherstellung der Dateiintegrität ist in der Softwareentwicklung entscheidend, insbesondere wenn Deployments über CI/CD-Pipelines automatisiert werden. Ein leistungsfähiges Werkzeug dafür ist b2sum, ein Hashing-Dienstprogramm auf Basis des BLAKE2-Algorithmus. Sehen wir uns an, wie Sie b2sum in Ihren Kommandozeilen-Workflows nutzen können, um Sicherheit und Zuverlässigkeit zu erhöhen.

Einführung in b2sum

b2sum ist ein Kommandozeilen-Dienstprogramm, das den Hash-Algorithmus BLAKE2 implementiert. Im Vergleich zu klassischen Hash-Algorithmen wie MD5 oder SHA-1 bietet BLAKE2 deutliche Vorteile:

Geschwindigkeit: Schneller als MD5, SHA-1, SHA-2 und SHA-3 auf 64-Bit-Plattformen.
Sicherheit: Bietet ein Sicherheitsniveau ähnlich wie SHA-3, einschließlich Immunität gegen Length-Extension-Angriffe und Ununterscheidbarkeit von einem Zufallsorakel.
Vielseitigkeit: Unterstützt sowohl die 256-Bit-Variante (BLAKE2s) als auch die 512-Bit-Variante (BLAKE2b).

BLAKE2-Varianten

BLAKE2 gibt es in zwei Hauptvarianten, die jeweils für unterschiedliche Anwendungsfälle optimiert sind:

BLAKE2b: Für 64-Bit-Plattformen optimiert, erzeugt Hashwerte mit bis zu 512 Bit. Dies ist die Variante, die das in GNU coreutils enthaltene Dienstprogramm b2sum implementiert, was sie ideal für moderne Serverumgebungen und CI/CD-Pipelines macht.
BLAKE2s: Für 32-Bit-Plattformen und ressourcenbeschränkte Umgebungen optimiert, erzeugt Hashwerte mit bis zu 256 Bit.

Installation

b2sum ist auf den meisten modernen Linux-Distributionen als Teil von GNU coreutils bereits vorinstalliert. So prüfen Sie, ob es verfügbar ist, und ermitteln die Version:

b2sum --version

Falls b2sum nicht installiert ist, können Sie es in der Regel als Teil des Pakets coreutils installieren:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install coreutils

CentOS/RHEL:
```
sudo yum install coreutils
```
macOS (mit Homebrew):
```
brew install coreutils
```
Hinweis: Unter macOS werden coreutils-Befehle häufig mit dem Präfix g versehen (z. B. gb2sum), um Konflikte mit den nativen BSD-Dienstprogrammen zu vermeiden. Möglicherweise müssen Sie Ihren PATH anpassen oder den Befehl mit Präfix verwenden.

b2sum in CI/CD-Pipelines integrieren

Um b2sum in Ihre CI/CD-Pipeline zu integrieren, erzeugen Sie Hashes für Build-Artefakte und überprüfen diese zum Zeitpunkt des Deployments. So gehen Sie in der Praxis vor:

Schritt 1: Hashes erzeugen

Nachdem Sie Ihre Artefakte erstellt haben (z. B. eine kompilierte Binärdatei oder ein ZIP-Archiv), erzeugen Sie einen BLAKE2b-Hash und speichern ihn in einer Datei:

# Example: generate hash for my-app.tar.gz
b2sum my-app.tar.gz > my-app.tar.gz.b2

Dieser Befehl berechnet den BLAKE2b-Hash von my-app.tar.gz und leitet die Ausgabe (den Hash und den Dateinamen) in my-app.tar.gz.b2 um. Bewahren Sie diese Datei mit der Endung .b2 sicher zusammen mit Ihrem Artefakt auf, etwa in einem Artefakt-Repository oder einem sicheren Speicherort.

Schritt 2: Hashes überprüfen

Bevor Sie das Artefakt deployen oder verwenden, überprüfen Sie seine Integrität mithilfe der erzeugten Hash-Datei:

# Example: verify the integrity of my-app.tar.gz using its hash file
b2sum -c my-app.tar.gz.b2

Die Option -c (oder --check) weist b2sum an, Hashsummen aus der angegebenen Datei zu lesen und zu prüfen. Stimmt die Datei my-app.tar.gz mit dem in my-app.tar.gz.b2 gespeicherten Hash überein, gibt b2sum Folgendes aus:

my-app.tar.gz: OK

Wurde die Datei manipuliert, ist sie beschädigt oder fehlt sie, meldet b2sum einen Fehler und beendet sich mit einem Statuscode ungleich null, mit dem sich die CI/CD-Pipeline anhalten lässt.

Beispiel für eine CI/CD-Integration

Hier ein praktisches Beispiel, das b2sum mithilfe von GitHub Actions in Ihren Workflow integriert:

name: Verify Build Artifacts

on: [push, pull_request]

jobs:
  build_and_verify:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4 # Use the latest major version

      - name: Set up environment
        # Add steps to set up your build environment (e.g., install Node.js, Java, etc.)
        run: echo "Setting up build environment..."

      - name: Build artifact
        run: |
          echo "Building application..."
          # Replace with your actual build commands
          mkdir -p dist
          echo "Build output" > dist/app.txt
          # Create an archive of the build output
          tar -czf artifact.tar.gz ./dist

      - name: Generate hash
        id: generate_hash # Give the step an ID to reference its output
        run: |
          b2sum artifact.tar.gz > artifact.tar.gz.b2
          echo "Generated hash file artifact.tar.gz.b2"
          # Optionally, output the hash value itself for logging
          HASH_VALUE=$(cut -d' ' -f1 artifact.tar.gz.b2)
          echo "hash_value=$HASH_VALUE" >> $GITHUB_OUTPUT

      - name: Verify hash
        run: |
          echo "Verifying hash for artifact.tar.gz..."
          b2sum -c artifact.tar.gz.b2
          echo "Verification successful!"

      - name: Upload artifact and hash
        uses: actions/upload-artifact@v4 # Use the latest major version
        with:
          name: build-artifact
          path: |
            artifact.tar.gz
            artifact.tar.gz.b2
          retention-days: 7 # Optional: Adjust artifact retention period

Dieser Workflow:

Checkt den Quellcode aus.
Richtet die Build-Umgebung ein (Platzhalter).
Baut die Anwendung und erstellt ein Archiv im Format tar.gz.
Erzeugt einen BLAKE2-Hash des Archivs und speichert ihn in einer Datei mit der Endung .b2. Zusätzlich wird der Hashwert selbst ausgegeben.
Überprüft den Hash unmittelbar danach, um sicherzustellen, dass das Artefakt während des Vorgangs nicht beschädigt wurde.
Lädt sowohl das Artefakt (artifact.tar.gz) als auch dessen Hash-Datei (artifact.tar.gz.b2) hoch, damit sie später in den Deployment-Phasen verwendet werden können.

Integritätsprüfungen automatisieren

Für komplexere Szenarien oder die Wiederverwendung in verschiedenen Pipelines können Sie ein robustes Shell-Skript für die Integritätsprüfung erstellen:

#!/bin/bash

# verify-integrity.sh: checks the integrity of a file using its corresponding .b2 hash file.

set -euo pipefail # Exit on error, undefined variable, or pipe failure

ARTIFACT_PATH="${1:-}"
HASH_FILE="${ARTIFACT_PATH}.b2"

# Check if artifact path is provided
if [ -z "$ARTIFACT_PATH" ]; then
  echo "Usage: $0 <path/to/artifact>"
  exit 1
fi

# Check if artifact file exists
if [ ! -f "$ARTIFACT_PATH" ]; then
  echo "Error: Artifact file '$ARTIFACT_PATH' not found."
  exit 1
fi

# Check if hash file exists
if [ ! -f "$HASH_FILE" ]; then
  echo "Error: Hash file '$HASH_FILE' not found."
  exit 1
fi

echo "Verifying integrity of '$ARTIFACT_PATH' using '$HASH_FILE'..."

# Perform the check
if b2sum --quiet -c "$HASH_FILE"; then
  echo "Integrity check PASSED for '$ARTIFACT_PATH'."
  exit 0
else
  echo "Integrity check FAILED for '$ARTIFACT_PATH'!"
  # b2sum already prints detailed error messages when check fails
  exit 1
fi

Speichern Sie es als verify-integrity.sh, machen Sie es mit chmod +x verify-integrity.sh ausführbar und verwenden Sie es in Ihren Pipeline-Skripten:

# Example usage in a CI/CD script after downloading the artifact and hash file
./verify-integrity.sh path/to/downloaded/my-app.tar.gz
# The script will exit with 0 on success, non-zero on failure

Bewährte Verfahren für die Fehlerbehandlung

Wenn Sie die Hash-Prüfung in Ihrer CI/CD-Pipeline umsetzen, beachten Sie diese bewährten Verfahren zur Fehlerbehandlung:

Fail Fast: Konfigurieren Sie Ihre Pipeline so, dass sie sofort stoppt, wenn eine Hash-Prüfung fehlschlägt. So verhindern Sie, dass möglicherweise beschädigte oder manipulierte Artefakte deployt werden.
Ausführliches Logging: Protokollieren Sie den Prüfversuch, den erwarteten Hash (sofern leicht verfügbar) und das Ergebnis. b2sum -c gibt im Fehlerfall nützliche Fehlermeldungen aus; stellen Sie sicher, dass diese in Ihren CI/CD-Logs erfasst werden.
Benachrichtigungssystem: Binden Sie Ihr Benachrichtigungssystem an (z. B. Slack, E-Mail), um das zuständige Team sofort zu alarmieren, wenn eine Integritätsprüfung fehlschlägt.
Sichere Aufbewahrung der Hashes: Stellen Sie sicher, dass die Hash-Dateien .b2 sicher gespeichert werden und nicht ohne Weiteres manipuliert werden können. Es hat sich bewährt, sie zusammen mit den Artefakten in einem Repository abzulegen, das Versionen nachverfolgt oder Unveränderlichkeit bietet. Erwägen Sie, die Hash-Dateien zu signieren, wenn zusätzliche Sicherheit erforderlich ist.
Fehlende Dateien behandeln: Sorgen Sie dafür, dass Ihre Skripte Fälle, in denen entweder das Artefakt oder die Hash-Datei fehlt, sauber abfangen und dabei klare Fehlermeldungen ausgeben.

Häufige Probleme beheben

Hash-Abweichung: Dies ist der häufigste Fehlerfall und zeigt an, dass sich der Dateiinhalt seit der Erzeugung des Hashes geändert hat. Mögliche Ursachen:
- Beschädigung der Datei bei Übertragung oder Speicherung.
- Absichtliche oder unabsichtliche Änderung des Artefakts nach dem Hashing.
- Erzeugung des Hashes für eine andere Version der Datei als die geprüfte.
- Lösung: Laden Sie das ursprüngliche Artefakt und die Hash-Datei erneut herunter oder beschaffen Sie sie neu. Besteht das Problem weiterhin, untersuchen Sie mögliche Ursachen für eine Beschädigung oder bauen Sie das Artefakt aus dem Quellcode neu.
b2sum: command not found: Das Dienstprogramm b2sum ist nicht installiert oder in der CI/CD-Ausführungsumgebung nicht im PATH des Systems enthalten.
- Lösung: Stellen Sie sicher, dass das Paket coreutils (oder ein Äquivalent) in Ihrer CI/CD-Runner-Umgebung installiert ist (z. B. Docker-Image, VM). Siehe den Abschnitt „Installation“.
Berechtigungsprobleme: Dem CI/CD-Prozess fehlen möglicherweise die nötigen Dateisystemberechtigungen, um das Artefakt oder die Hash-Datei zu lesen.
- Lösung: Prüfen Sie die Berechtigungen und Eigentümer der Dateien sowie den Ausführungskontext des Befehls b2sum.
Unterschiedliche Zeilenenden: Bei Textdateien können Unterschiede bei den Zeilenenden (CRLF vs. LF) zwischen der Umgebung, in der der Hash erzeugt wurde, und der Umgebung, in der er geprüft wird, zu Abweichungen führen.
- Lösung: Sorgen Sie für einheitliche Zeilenenden, häufig durch eine passende Konfiguration von Git (core.autocrlf) oder der Build-Werkzeuge. Wenn Sie Binärarchive hashen (etwa im Format .zip oder .tar.gz), tritt dieses Problem in der Regel nicht auf.
Falsches Format der Hash-Datei: Die Datei .b2 sollte die Hash-Ausgabe exakt so enthalten, wie b2sum sie erzeugt (Hash gefolgt vom Dateinamen). Manuelles Bearbeiten kann dieses Format zerstören.
- Lösung: Erzeugen Sie die Hash-Datei mit dem Standardbefehl b2sum artifact > artifact.b2 neu.

Integration mit Transloadit

Der Robot /file/hash von Transloadit unterstützt mehrere Hash-Algorithmen, darunter BLAKE2b (b2). Sie können Hashing direkt in Ihre Workflows zur Dateiverarbeitung integrieren. Hier ein Beispiel für eine Assembly mit BLAKE2:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "hashed": {
      "use": ":original",
      "robot": "/file/hash",
      "algorithm": "b2"
    }
  }
}

Nachdem die Assembly ausgeführt wurde, steht der BLAKE2b-Hashwert der verarbeiteten Datei im Ergebnis-JSON der Assembly zur Verfügung, üblicherweise im Objekt results für den Step hashed, im Feld file.meta.hash. So können Sie Hashes als Teil automatisierter Upload- und Verarbeitungspipelines erzeugen.

Fazit und bewährte Verfahren

Der Einsatz von b2sum in Ihrer CI/CD-Pipeline erhöht Sicherheit und Zuverlässigkeit erheblich, da er starke Garantien für die Dateiintegrität bietet. Indem Sie BLAKE2-Hashes erzeugen und überprüfen, erkennen Sie versehentliche Beschädigungen oder böswillige Manipulationen Ihrer Build-Artefakte, bevor diese in die Produktion gelangen.

Zu den wichtigsten bewährten Verfahren zählen:

Erzeugen Sie Hashes unmittelbar nach der Erstellung eines Artefakts.
Speichern Sie Hash-Dateien sicher zusammen mit den zugehörigen Artefakten oder mit ihnen verknüpft.
Automatisieren Sie die Hash-Prüfung als verpflichtenden Schritt vor dem Deployment oder der Verwendung eines Artefakts.
Verwenden Sie BLAKE2b (b2sum) wegen seiner Geschwindigkeits- und Sicherheitsvorteile auf modernen Systemen.
Implementieren Sie eine robuste Fehlerbehandlung und Benachrichtigungen bei fehlgeschlagenen Prüfungen.
Erwägen Sie für kritische Anwendungen signierte Hashes oder Prüfsummen, die in sicheren Manifesten gespeichert sind.

Mit diesen Verfahren bauen Sie eine vertrauenswürdigere und sicherere Deployment-Pipeline auf.

Bei Transloadit setzen wir in unserem Robot-Ökosystem robuste Hash-Algorithmen wie BLAKE2 als Teil unserer Dateiverarbeitungsdienste ein und tragen so dazu bei, die Dateiintegrität für unsere Nutzerinnen und Nutzer sicherzustellen.