Artefakt-Signierung, Checksums und Integrität für Releases

1. Warum Artefakt-Integrität ein echtes Risiko ist

Ein Release-Artefakt durchläuft auf dem Weg von der Pipeline zum Produktionsserver mehrere Stationen: GitLab-Speicher, Netzwerkübertragung, temporäre Verzeichnisse auf dem Server. An jeder dieser Stationen kann theoretisch eine unbemerkte Veränderung stattfinden – durch Fehler, durch Angriffe auf die Supply Chain oder durch einen fehlerhaften Übertragungsvorgang. Ein beschädigtes oder manipuliertes Artefakt, das ohne Prüfung deployed wird, ist gefährlicher als ein fehlgeschlagener Build, weil es keinen sichtbaren Fehler erzeugt.

Für Magento-Shops ist das Risiko konkret: vendor/ enthält PHP-Bibliotheken, die direkt im Produktionsbetrieb ausgeführt werden. Wenn eine Bibliothek zwischen Build und Deploy verändert wurde, wird dieser Schadcode mit jedem Request ausgeführt. Supply-Chain-Angriffe auf npm und Composer-Pakete sind keine Theorie mehr – sie passieren in der Realität. Die Gegenmaßnahme ist keine Paranoia, sondern eine einfache technische Kontrolle: SHA256-Checksums, die im Build-Job erzeugt und vor dem Deploy verifiziert werden.

2. Checksums: SHA256 und wie sie entstehen

Eine Checksum ist ein kryptografischer Hash einer Datei, der sich ändert, wenn auch nur ein Byte der Datei geändert wird. SHA256 ist der aktuelle Standard – MD5 und SHA1 sind für Integritätsprüfungen nicht mehr ausreichend, weil Kollisionen theoretisch möglich sind. Ein SHA256-Hash ist 64 Zeichen lang und eindeutig für den genauen Inhalt der Datei. Auf Linux-Systemen wird sha256sum verwendet, auf macOS shasum -a 256.

Für ein Release-Artefakt wird der Hash nach der Erstellung berechnet und in einer separaten Datei gespeichert. Die Konvention ist dabei eine .sha256-Datei neben dem Artefakt: release-v1.2.3.tar.gz und release-v1.2.3.tar.gz.sha256. Beide Dateien werden als GitLab-Artefakte gespeichert. Vor dem Deploy liest der Deployment-Job die .sha256-Datei, berechnet den Hash des tatsächlichen Artefakts und vergleicht die beiden Werte. Stimmen sie überein, ist die Integrität gesichert. Stimmen sie nicht überein, bricht die Pipeline sofort ab.

package:release:
  stage: package
  dependencies:
    - build:magento
    - build:frontend
  script:
    # Create timestamped release archive
    - export RELEASE_TAG="${CI_COMMIT_TAG:-${CI_COMMIT_SHORT_SHA}}"
    - tar -czf "release-${RELEASE_TAG}.tar.gz" vendor/ generated/ app/ pub/static/
    # Generate SHA256 checksum — stored alongside the archive
    - sha256sum "release-${RELEASE_TAG}.tar.gz" > "release-${RELEASE_TAG}.tar.gz.sha256"
    # Display checksum for pipeline log transparency
    - cat "release-${RELEASE_TAG}.tar.gz.sha256"
    - echo "RELEASE_TAG=${RELEASE_TAG}" >> release.env
  artifacts:
    name: "release-${CI_COMMIT_SHORT_SHA}"
    paths:
      - release-*.tar.gz
      - release-*.tar.gz.sha256
      - release.env
    reports:
      dotenv: release.env
    expire_in: 14 days

3. Checksums automatisch in der Pipeline erzeugen

Der Checksum-Schritt muss Teil des Package-Jobs sein, nicht ein nachträglicher Zusatz. Nur wenn Hash und Artefakt im selben Job entstehen, ist sichergestellt, dass der Hash tatsächlich das Artefakt beschreibt, das gebaut wurde – und nicht eine spätere, möglicherweise veränderte Version. Die Checksum-Datei wird gemeinsam mit dem Artefakt in artifacts.paths aufgeführt und hat damit denselben Lebenszyklus.

Für mehrere Artefakte empfiehlt sich eine gemeinsame SHA256SUMS-Datei nach Linux-Konvention: Alle Hashes in einer Datei, ein Hash pro Zeile, mit Dateiname. Diese Datei lässt sich mit einem einzigen Befehl verifizieren: sha256sum -c SHA256SUMS. Das prüft alle Artefakte gleichzeitig und gibt für jede Datei entweder OK oder einen Fehler aus. In GitLab CI bedeutet ein Fehler in diesem Schritt automatisch einen Job-Fehler und einen Pipeline-Stopp – genau das gewünschte Verhalten.

4. Checksums vor dem Deploy verifizieren

Die Verifizierung muss als expliziter Schritt im Deploy-Job oder als separater Verify-Job vor dem Deploy erfolgen. Der Ablauf ist immer gleich: Artefakt und Checksum-Datei herunterladen, Hash des Artefakts berechnen, mit dem gespeicherten Hash vergleichen. Nur bei Übereinstimmung läuft das Deployment weiter. Dieser Schritt dauert Sekunden, verhindert aber das Deployen von beschädigten oder manipulierten Paketen.

Ein wichtiger Aspekt: Die Checksum-Datei selbst muss ebenfalls geschützt sein. Wenn ein Angreifer sowohl das Artefakt als auch die Checksum-Datei ersetzen kann, ist der Schutz wirkungslos. Hier kommt GPG-Signierung ins Spiel: Die Checksum-Datei wird mit einem privaten Schlüssel signiert, der nur dem CI-System bekannt ist. Vor dem Deploy wird die Signatur mit dem öffentlichen Schlüssel verifiziert. Damit kann keine unbemerkte Manipulation stattfinden – weder am Artefakt noch an der Checksum.

5. GPG-Signierung für Release-Pakete

GPG (GNU Privacy Guard) ermöglicht kryptografische Signaturen, die beweisen, dass ein Artefakt aus einer bestimmten Quelle stammt und seit der Signierung nicht verändert wurde. Im GitLab-CI-Kontext wird ein GPG-Schlüsselpaar erzeugt, der private Schlüssel als geschützte CI/CD-Variable gespeichert, und der öffentliche Schlüssel ist für alle Deployments zugänglich. Der Build-Job signiert das Release-Paket, der Deploy-Job verifiziert die Signatur vor dem Auspacken.

Die Einrichtung erfordert einmaligen Aufwand: Schlüsselpaar generieren, privaten Schlüssel base64-codiert als GitLab-Variable speichern, öffentlichen Schlüssel auf dem Deployment-Server importieren. Im laufenden Betrieb passiert die Signierung und Verifizierung vollautomatisch. Für Magento-Shops, die in regulierten Umgebungen betrieben werden oder bestimmte Compliance-Anforderungen haben, ist GPG-Signierung keine optionale Maßnahme, sondern ein dokumentiertes Sicherheitsmerkmal des Deployment-Prozesses.

sign:release:
  stage: package
  dependencies:
    - package:release
  script:
    # Import GPG private key from CI variable (base64-encoded)
    - echo "${GPG_PRIVATE_KEY}" | base64 -d | gpg --batch --import
    # Sign the release archive — creates .asc detached signature
    - gpg --batch --yes --armor --detach-sign
        --local-user "${GPG_KEY_ID}"
        release-*.tar.gz
    # Verify signature immediately to confirm signing worked
    - gpg --verify release-*.tar.gz.asc release-*.tar.gz
  artifacts:
    paths:
      - release-*.tar.gz.asc
    expire_in: 14 days

verify:signature:
  stage: verify
  dependencies:
    - package:release
    - sign:release
  script:
    # Import public key on verification side
    - echo "${GPG_PUBLIC_KEY}" | gpg --batch --import
    # Verify GPG signature before any deployment step
    - gpg --verify release-*.tar.gz.asc release-*.tar.gz
    - echo "Signature verified — safe to deploy"

6. GitLab Release API und Checksum-Anhang

GitLab bietet eine Release API, über die bei jedem Git-Tag automatisch ein Release-Eintrag mit angehängten Assets erstellt werden kann. Checksum-Dateien lassen sich als Release-Assets anhängen und sind damit dauerhaft mit dem Tag verknüpft – auch nach dem Ablauf des CI-Artefakts. Das ist besonders nützlich für langfristige Nachvollziehbarkeit: Welche Version wurde deployed, und wie lautet der Hash des deploytes Pakets?

Die GitLab Release CLI oder die API ermöglicht, Checksum-Dateien als Links zu hinterlegen. Im einfachsten Fall speichert man die SHA256SUMS-Datei in einem S3-kompatiblen Object Storage und hängt die URL an das GitLab-Release. Für interne Deployments ohne externe Storage-Lösung reicht es, die Checksum-Datei im GitLab-Release als herunterladbares Asset zu hinterlegen. Wichtig ist die Konsequenz: Jedes tagged Release hat eine dokumentierte, nachprüfbare Checksumme.

7. SLSA und Provenance: woher kommt das Artefakt?

SLSA (Supply chain Levels for Software Artifacts) ist ein Framework, das beschreibt, unter welchen Bedingungen ein Artefakt gebaut wurde. Die Kernidee ist die Provenance: ein maschinenlesbares Dokument, das festhält, welcher Commit als Input diente, welche Pipeline den Build ausgeführt hat und welcher Runner dabei verwendet wurde. GitLab unterstützt Provenance-Erzeugung über den generate_provenance-Mechanismus bei Releases.

Für Magento-Deployments auf SLSA Level 1 reicht es, die Build-Umgebung zu dokumentieren: Git-Commit-SHA, Pipeline-ID, Runner-ID, Timestamp und Artefakt-Hash. Diese Informationen lassen sich als JSON-Datei im Package-Job erzeugen und als Artefakt speichern. Damit kann jeder Produktionsstand nachvollziehbar auf einen exakten Git-Commit zurückgeführt werden – eine Grundvoraussetzung für Incident-Response und Compliance-Nachweise in regulierten Branchen.

8. Composer-Integrität und composer.lock als Basis

Die Grundlage aller PHP-seitigen Integritätsprüfungen ist die composer.lock-Datei. Sie fixiert für jedes Paket die genaue Version und den SHA-Hash der heruntergeladenen Datei. composer install mit einer gültigen composer.lock verifiziert automatisch, dass die installierten Pakete exakt den erwarteten Hashes entsprechen. Das schützt gegen kompromittierte Paket-Mirror und Downgrade-Angriffe auf Composer-Pakete.

Im GitLab-CI-Build-Job muss daher composer.lock immer committed sein und composer install (nicht composer update) verwendet werden. Ein zusätzlicher Check: composer validate --strict prüft, ob composer.json und composer.lock konsistent sind. Wer composer install --no-dev im Build-Job verwendet, stellt sicher, dass keine Entwicklungsabhängigkeiten in das Produktions-Artefakt gelangen – eine weitere Angriffsfläche wird damit eliminiert.

9. Vergleich: ohne vs. mit Integritätssicherung

Die folgende Tabelle zeigt, welche Risiken ohne Integritätsprüfungen bestehen und wie jede Maßnahme sie adressiert.

Die Tabelle macht deutlich: Die ersten drei Maßnahmen – SHA256-Checksums, composer.lock committen und ein Verify-Job – erfordern minimalen Aufwand und decken die häufigsten Risiken ab. GPG-Signierung und Provenance-Dokumente sind sinnvoll für höhere Sicherheitsanforderungen oder regulierte Umgebungen, aber keine Grundvoraussetzung für einen sicheren Deployment-Prozess.

10. Zusammenfassung

Artefakt-Signierung, Checksums und Integritätsprüfungen sind keine übertriebenen Sicherheitsmaßnahmen, sondern die logische Konsequenz aus der Tatsache, dass Release-Artefakte durch externe Systeme fließen. SHA256-Checksums entstehen im Package-Job und werden vor dem Deploy verifiziert. GPG-Signaturen beweisen die Herkunft des Pakets kryptografisch. Die composer.lock-Datei stellt sicher, dass alle PHP-Abhängigkeiten versionsfest und hash-verifiziert installiert werden. Provenance-Dokumente liefern Rückverfolgbarkeit für Compliance und Incident-Response.

Der Gesamtaufwand für die grundlegende Integritätssicherung ist gering: ein zusätzlicher Checksum-Schritt im Package-Job und ein Verify-Job vor dem Deploy. Diese zwei Ergänzungen verwandeln einen Deployment-Prozess, der auf Hoffnung basiert, in einen, der auf Verifikation basiert. Für Magento-Shops mit Kundendaten und Zahlungsabwicklung ist dieser Unterschied nicht trivial.

11. FAQ: Artefakt-Signierung und Checksums in GitLab