Git-Secrets-Leaks vermeiden und aufräumen

1. Warum das Löschen einer Datei den Secret nicht aus der Git-Historie entfernt

Jeder Git-Commit ist durch seinen Hash eindeutig identifiziert, und dieser Hash hängt vom Inhalt des Commits sowie von allen Eltern-Commits ab. Wird eine Datei mit einem darin enthaltenen Secret gelöscht und der neue Zustand committet, entsteht lediglich ein weiterer Commit in der Historie. Der vorherige Commit, der die Datei mit dem Secret noch enthielt, bleibt vollständig erhalten und über seinen Hash jederzeit erreichbar. Git ist als Historie konzipiert, nicht als reiner Zustand: Löschen bedeutet in Git fast immer, einen neuen Zustand hinzuzufügen, nicht einen alten Zustand zu entfernen.

Technisch liegt jede Dateiversion als eigenständiges Blob-Objekt in der Objektdatenbank des Repositories, referenziert über seinen Inhalts-Hash. Solange irgendein Commit, irgendein Branch, ein Tag oder sogar nur der Reflog auf dieses Blob verweist, gilt es als erreichbar und wird von git gc niemals entfernt. Wer git log --all durchsucht oder direkt git show auf den alten Commit anwendet, bekommt das Secret im Klartext zurück, unabhängig davon, wie viele Commits seitdem vergangen sind.

Noch gravierender: Sobald das Repository geklont, geforkt oder in einer CI-Pipeline zwischengespeichert wurde, existiert die vollständige Historie inklusive Secret bereits an mehreren Orten außerhalb der eigenen Kontrolle. Ein nachträgliches Löschen im eigenen Remote-Repository ändert nichts an diesen Kopien. Das folgende Beispiel zeigt, wie einfach ein vermeintlich gelöschtes Secret wiederhergestellt werden kann.

#!/usr/bin/env bash
# demo-recover-deleted-secret.sh - zeigt, dass eine geloeschte Datei
# weiterhin vollstaendig wiederherstellbar ist
set -euo pipefail

# Den Commit finden, der app/etc/env.php geloescht hat
git log --all --diff-filter=D --summary -- app/etc/env.php

# Den exakten Dateiinhalt aus dem Eltern-Commit dieses Loesch-Commits wiederherstellen
git show <loesch-commit-sha>^:app/etc/env.php > recovered-env.php

# Jedes Blob, auf das IRGENDEIN Commit auf IRGENDEINEM Branch verweist,
# bleibt in der Objektdatenbank, bis es unerreichbar wird UND git gc --prune greift
git cat-file -p <blob-sha> | head -n 5

2. Wie Secret-Scanner technisch funktionieren: Pattern-Matching und Entropie

Secret-Scanner wie gitleaks und trufflehog verlassen sich im Kern auf zwei komplementäre Erkennungsstrategien. Die erste ist Pattern-Matching mit regulären Ausdrücken gegen bekannte Formate: ein AWS Access Key beginnt zuverlässig mit AKIA, ein GitHub-Token mit ghp_, ein Magento-Marketplace-Token folgt einem festen Hex-Format. Diese Regeln sind präzise, aber blind für alles, was kein bekanntes Format hat, etwa selbst vergebene Datenbankpasswörter oder interne API-Keys.

Die zweite Strategie ist Entropie-Analyse: Zufällig generierte Strings, wie sie für Passwörter und Tokens typisch sind, haben eine deutlich höhere Shannon-Entropie als natürliche Sprache oder gewöhnlicher Quellcode. trufflehog nutzt diesen Ansatz, um auch unbekannte Secret-Formate zu erkennen, akzeptiert dafür aber eine höhere Rate an False Positives, etwa bei Hash-Werten oder harmlosen Base64-kodierten Daten. gitleaks kombiniert eigene Entropie-Heuristiken mit einer umfangreichen, community-gepflegten Regel-Bibliothek für gängige Provider.

In der Praxis bedeutet das: Ein guter Scan-Aufbau nutzt beide Werkzeuge oder zumindest beide Strategien, prüft nicht nur den aktuellen Arbeitsstand, sondern beim Erstinstallieren in einem bestehenden Repository optional auch die gesamte Historie, und erlaubt projektspezifische Allowlists für bekannte False Positives, statt Entwickler mit ständigen Fehlalarmen zu ermüden.

3. Pre-Commit-Hooks: gitleaks und trufflehog mit husky oder pre-commit verdrahten

Ein Pre-Commit-Hook läuft lokal auf der Entwickler-Maschine, bevor ein Commit überhaupt erstellt wird, und ist damit die früheste mögliche Verteidigungslinie. Das Python-basierte pre-commit Framework verwaltet Hooks projektübergreifend über eine einzige .pre-commit-config.yaml, installiert die benötigten Werkzeuge automatisch in isolierten Umgebungen und wird mit pre-commit install einmalig pro Klon aktiviert. gitleaks bringt eine offizielle pre-commit-Hook-Definition mit, die ohne zusätzliche Konfiguration funktioniert.

In Node.js-lastigen Frontend-Setups, wie sie beim Hyvä-Tailwind-Build ohnehin vorhanden sind, bietet sich husky als Alternative an: Es verdrahtet Git-Hooks über package.json und ruft in .husky/pre-commit typischerweise gitleaks protect --staged auf, also einen Scan ausschließlich der zum Commit vorgemerkten Änderungen. Das hält den Hook schnell, weil nicht bei jedem Commit die komplette Historie erneut gescannt wird.

Wichtig ist, dass ein Pre-Commit-Hook niemals der einzige Schutzmechanismus sein darf. Er kann mit --no-verify umgangen werden, läuft nur auf Maschinen, auf denen er installiert wurde, und schützt nicht vor Commits, die über die GitHub-Weboberfläche oder von einem Kollegen ohne aktivierten Hook erstellt werden. Er ist eine schnelle erste Hürde, kein vollständiger Schutz, weshalb Abschnitt 6 den serverseitigen Schutz ergänzt.

# .pre-commit-config.yaml - scannt jeden Commit vor der Erstellung auf Secrets
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.4
    hooks:
      - id: gitleaks

  - repo: https://github.com/trufflesecurity/trufflehog
    rev: v3.74.0
    hooks:
      - id: trufflehog
        entry: trufflehog git file://. --since-commit HEAD --fail

# Alternative fuer Node.js-lastige Setups (z.B. Hyva Tailwind Build) via husky:
# package.json: "prepare": "husky install"
# .husky/pre-commit: gitleaks protect --staged --redact

4. Nach einem echten Leak: Zuerst rotieren, dann die Historie bereinigen

Wird ein echtes Secret in einem gepushten Commit entdeckt, zählt die Reihenfolge der Reaktion mehr als deren Perfektion. Der erste und einzig wirklich dringende Schritt ist, die betroffene Zugangsdaten sofort zu rotieren, also ungültig zu machen und durch eine neue zu ersetzen. Das gilt unabhängig davon, ob der Commit erst vor einer Minute oder vor einem Jahr gepusht wurde, und unabhängig davon, wie schnell danach die Git-Historie bereinigt wird.

Der Grund ist einfach: Sobald ein Commit auf einen öffentlich oder auch nur teamweit erreichbaren Remote gepusht wurde, kann er bereits geklont, von einem Bot indexiert oder von automatisierten Scannern erfasst worden sein, die kontinuierlich öffentliche Repositories nach Secrets durchsuchen. Dokumentierte Fälle zeigen, dass solche Scans gepushte Secrets innerhalb weniger Minuten finden und missbrauchen können. Eine History-Rewrite Stunden oder Tage später kommt für diesen Zeitraum zu spät.

History-Rewrite ist trotzdem sinnvoll, aber als zweiter Schritt: Er verhindert, dass zukünftige Klone oder ein erneuter Blick in die Historie das Secret wieder sichtbar machen, und ist Teil einer sauberen Aufräumarbeit. Wer die Reihenfolge umdreht, also erst die Historie umschreibt und danach rotiert, verschwendet wertvolle Zeit, in der das eigentliche Risiko, die weiterhin gültige Zugangsdaten, unverändert fortbesteht.

5. .gitignore-Disziplin für Magento- und PHP-Projekte

Die wirksamste Maßnahme gegen Git-Secret-Leaks ist, dass das Secret niemals in den Commit gelangt. In Magento-Projekten sind drei Dateien besonders gefährdet: app/etc/env.php enthält Datenbank-Zugangsdaten, den Crypt-Key und teils Cache-Backend-Credentials im Klartext. .env-Dateien, wie sie in begleitenden Node- oder PHP-Tools verwendet werden, enthalten häufig API-Keys und Zugangsdaten für externe Dienste. auth.json enthält die Composer-Repository-Zugangsdaten für den Magento Marketplace, deren Kompromittierung Zugriff auf kommerzielle Lizenzcode-Repositories ermöglicht.

Alle drei gehören von Projektbeginn an in .gitignore, nicht erst, nachdem ein Leak passiert ist. Magento liefert seit einigen Versionen eine sinnvolle Standard-.gitignore mit, die app/etc/env.php bereits ausschließt, aber projektspezifische Ergänzungen wie zusätzliche .env-Dateien oder lokale Docker-Overrides müssen manuell nachgezogen werden. Ein guter Test: git status nach einer frischen Installation darf niemals eine dieser Dateien als untracked oder gar als staged anzeigen.

Wichtig ist der Unterschied zwischen .gitignore und bereits getrackten Dateien: Steht eine Datei einmal unter Versionskontrolle, verhindert ein nachträglicher .gitignore-Eintrag nicht, dass sie weiterhin committet wird. In diesem Fall muss sie zunächst explizit mit git rm --cached aus dem Index entfernt werden, bevor der .gitignore-Eintrag greift, und selbst dann bleibt sie in der bisherigen Historie sichtbar, siehe Abschnitt 1.

6. CI-seitiges Secret-Scanning: GitHub und GitLab

Pre-Commit-Hooks schützen nur, wenn sie lokal installiert und nicht umgangen wurden. CI-seitiges Secret-Scanning schließt genau diese Lücke, weil es serverseitig läuft und nicht von der Konfiguration der einzelnen Entwickler-Maschine abhängt. GitHub Secret Scanning ist für öffentliche Repositories automatisch aktiv und erkennt Secrets bekannter Provider anhand von Partnerprogrammen, die Formate wie AWS-, Stripe- oder Slack-Tokens direkt beim jeweiligen Anbieter validieren können, oft bevor überhaupt ein Mensch reagiert.

Für private Repositories ist GitHub Advanced Security beziehungsweise Push Protection erforderlich, die einen Push mit erkanntem Secret bereits serverseitig blockieren kann, bevor er überhaupt im Remote landet. GitLab bietet mit Secret Detection einen vergleichbaren Mechanismus als Teil der CI/CD-Pipeline, der als eigener Job läuft und Merge Requests mit gefundenen Secrets markiert oder blockiert, je nach Konfiguration der Projekt-Policy.

Für selbstgehostete GitLab-Instanzen oder reine Bitbucket-Setups ohne native Lösung lässt sich dieselbe Funktionalität mit gitleaks oder trufflehog als eigenständiger CI-Job nachbauen, der bei einem Fund den Build fehlschlagen lässt und einen strukturierten Report als Artefakt ablegt. Das folgende Beispiel zeigt, wie ein solcher Fund typischerweise im Report eines CI-Jobs aussieht.

{
  "Description": "AWS Access Key",
  "StartLine": 42,
  "EndLine": 42,
  "StartColumn": 15,
  "EndColumn": 55,
  "Match": "AKIA************************",
  "Secret": "AKIA************************",
  "File": "app/etc/env.php",
  "SymlinkFile": "",
  "Commit": "a3f9c21e8b7d4f5a6c9e1b2d3f4a5b6c7d8e9f01",
  "Entropy": 3.95,
  "Author": "ci-bot@mironsoft.de",
  "Date": "2026-06-02T09:14:33Z",
  "RuleID": "aws-access-token"
}

7. Git-Historie bereinigen: git filter-repo, BFG Repo-Cleaner und ihre Grenzen

Wenn eine History-Rewrite tatsächlich notwendig ist, etwa weil das Secret in vielen Commits über einen langen Zeitraum verstreut vorkommt oder aus Compliance-Gründen keine Spur mehr existieren darf, sind git filter-repo und BFG Repo-Cleaner die beiden gängigen Werkzeuge. git filter-repo ist der offiziell empfohlene Nachfolger von git filter-branch, deutlich schneller und mit einer sichereren Standardkonfiguration. Es erlaubt das gezielte Entfernen einzelner Pfade über die gesamte Historie in einem einzigen Durchlauf.

BFG Repo-Cleaner ist auf den spezifischen Anwendungsfall Secret-Entfernung zugeschnitten und dadurch einfacher zu bedienen: --delete-files entfernt Dateien nach Namensmuster, --replace-text ersetzt konkrete Textmuster wie ein bekanntes Passwort durch einen Platzhalter, über die komplette Historie hinweg. Beide Werkzeuge schreiben effektiv jeden betroffenen Commit-Hash neu, was bedeutet, dass die komplette nachfolgende Historie ebenfalls neue Hashes erhält.

Die Grenzen sind entscheidend: Nach der Rewrite ist ein Force-Push zwingend erforderlich, weil alte und neue Historie inkompatibel sind. Jeder existierende Klon, jeder Fork, jede lokale Kopie eines Kollegen enthält weiterhin die alte Historie mit dem Secret, bis diese Kopien explizit neu geklont werden. GitHub cached zudem alte Commit-Ansichten teils noch eine Zeit lang über direkte Commit-URLs, selbst nach einem Force-Push. Eine History-Rewrite bereinigt das eigene Remote-Repository, nicht das gesamte Ökosystem, das bereits Zugriff hatte.

8. Praxis-Checkliste: Ein geleaktes Magento-, AWS- oder Datenbank-Credential

Ein strukturierter Ablaufplan verkürzt die Reaktionszeit im Ernstfall erheblich gegenüber einer improvisierten Reaktion unter Stress. Die Reihenfolge aus Abschnitt 4 gilt uneingeschränkt: Rotation vor Historie. Für ein Magento-spezifisches Szenario bedeutet das konkret: Datenbank-Zugangsdaten in app/etc/env.php über den Hosting-Provider oder die Cloud-Konsole neu setzen, den Crypt-Key rotieren, was unter Umständen eine erneute Verschlüsselung gespeicherter sensibler Daten erfordert, und ein kompromittiertes auth.json-Token sofort im Magento-Marketplace-Account widerrufen und neu generieren.

Bei AWS-Zugangsdaten ist die Reihenfolge create-then-delete wichtig: zuerst einen neuen Access Key erzeugen, die Anwendung darauf umstellen, erst danach den alten Key löschen, um keine Ausfallzeit zu erzeugen. Parallel dazu sollten CloudTrail-Logs auf ungewöhnliche API-Aufrufe im Zeitraum seit dem vermuteten Leak geprüft werden, um festzustellen, ob der Schlüssel bereits missbraucht wurde.

Nach der Rotation folgt die Kommunikation: alle Teammitglieder informieren, dass ein Force-Push bevorsteht und ein Re-Clone des Repositories notwendig ist, den Vorfall dokumentieren, und wo gesetzlich relevant prüfen, ob eine Meldepflicht nach Datenschutzrecht besteht, falls personenbezogene Daten betroffen waren. Das folgende Skript und das anschließende PHP-Beispiel zeigen eine praktische Umsetzung der Reihenfolge sowie eine automatisierte Absicherung gegen künftige Vorfälle.

#!/usr/bin/env bash
# incident-response.sh - die Reihenfolge zaehlt: zuerst rotieren, danach die Historie umschreiben
set -euo pipefail

echo "SCHRITT 1: Die geleakte Zugangsdaten SOFORT rotieren (immer zuerst)"
# Beispiel: ein AWS Access Key wird rotiert
aws iam create-access-key --user-name deploy-bot
aws iam delete-access-key --user-name deploy-bot --access-key-id <ALTER_KEY_ID>

echo "SCHRITT 2: Bestaetigen, dass die alte Zugangsdaten wirklich tot ist"
aws iam list-access-keys --user-name deploy-bot

echo "SCHRITT 3: Erst jetzt die Historie umschreiben und das Secret entfernen"
git filter-repo --path app/etc/env.php --invert-paths --force

echo "SCHRITT 4: Force-Push ausfuehren und alle Mitarbeitenden zum Re-Clone auffordern"
git push origin --force --all
git push origin --force --tags
echo "HINWEIS: alle Klone und Forks enthalten das alte Secret weiterhin in ihrer lokalen Historie"

<?php

declare(strict_types=1);

namespace Mironsoft\SecuritySuite\Console;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Process\Process;

/**
 * CLI command that fails a deployment if secret-bearing files are tracked by git.
 */
class VerifyNoTrackedSecretsCommand extends Command
{
    private const FORBIDDEN_FILES = ['env.php', 'auth.json', '.env'];

    /**
     * Checks whether any forbidden file is present in the current git index.
     *
     * @param InputInterface $input Console input, unused in this command.
     * @param OutputInterface $output Console output for reporting results.
     * @return int Exit code, 0 if clean, 1 if a forbidden file is tracked.
     */
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $process = new Process(['git', 'ls-files']);
        $process->mustRun();
        $trackedFiles = explode("\n", trim($process->getOutput()));

        $violations = array_filter(
            $trackedFiles,
            static fn (string $file): bool => in_array(basename($file), self::FORBIDDEN_FILES, true)
        );

        if ($violations !== []) {
            $output->writeln('<error>Forbidden secret file(s) tracked by git: ' . implode(', ', $violations) . '</error>');
            return Command::FAILURE;
        }

        $output->writeln('<info>No forbidden secret files found in the git index.</info>');
        return Command::SUCCESS;
    }
}

9. Git-Secrets-Management im direkten Vergleich

Die folgende Übersicht stellt unsicheres Verhalten im Umgang mit Git-Secrets dem jeweils sicheren Gegenstück gegenüber, mit Fokus auf die Reihenfolge und die Werkzeuge, die in der Praxis den Unterschied machen.

Die einzelnen Zeilen zeigen ein wiederkehrendes Muster: Prävention über .gitignore und automatisiertes Scanning ist immer günstiger als Aufräumarbeit nach einem Leak, und innerhalb der Reaktion auf einen echten Leak zählt strikt die Reihenfolge Rotation vor Historie. Werkzeuge wie git filter-repo lösen nur die technische Seite des Problems, nicht die organisatorische Kommunikation im Team.

10. Zusammenfassung

Eine Git-Historie ist unveränderlich, und genau das macht das Löschen einer Datei mit einem Secret wirkungslos, solange die Historie nicht aktiv umgeschrieben wird. Pre-Commit-Hooks mit gitleaks oder trufflehog stoppen die meisten Leaks, bevor sie überhaupt entstehen, ersetzen aber nicht das serverseitige CI-Secret-Scanning, das nicht umgangen werden kann. Eine konsequente .gitignore-Disziplin für env.php, .env und auth.json verhindert den Großteil der Vorfälle bereits präventiv.

Passiert dennoch ein echter Leak, zählt die Reihenfolge mehr als die Perfektion der Reaktion: Zuerst die betroffene Zugangsdaten rotieren, danach die Historie mit git filter-repo oder BFG Repo-Cleaner bereinigen. Ein Force-Push macht das eigene Repository sauber, ändert aber nichts an bereits existierenden Klonen, Forks oder zwischengespeicherten Ansichten, weshalb koordinierte Team-Kommunikation ein fester Bestandteil jeder Bereinigung sein muss.

11. FAQ: Git-Secrets-Leaks vermeiden und aufräumen