--- title: "Gitleaks mit Docker installieren: Schneller Secret-Scanner für Git-Repositories" date: 2026-08-12T22:03:22+02:00 modified: 2026-11-08T21:18:52+01:00 category: sicherheit type: how_to author: Marcel Schönfelder canonical: https://s-edv.com/anleitungen/gitleaks-docker-secret-scanner reading_time: 9 --- # Gitleaks mit Docker installieren: Schneller Secret-Scanner für Git-Repositories Ein versehentlich eingecheckter API-Key bleibt in der Git-History, auch wenn er im nächsten Commit gelöscht wird. Gitleaks ist ein quelloffenes SAST-Werkzeug (Static Application Security Testing), das Git-Historien, Branches und Verzeichnisse mit Regex-Regeln und Entropie-Analyse nach Secrets durchsucht: API-Keys, Passwörter, private Schlüssel, OAuth-Tokens. Das Projekt hat rund 29.500 GitHub-Stars, das Docker-Hub-Image über 30 Millionen Pulls. Diese Anleitung richtet Gitleaks per Docker Compose ein, auf einem Linux-Host, einer VM oder einem NAS mit Docker, und zeigt Scans auf Abruf, Reports und die Einbindung in CI/CD. **Kurzfassung:** Legen Sie einen Projektordner mit `compose.yaml` und `.env` an, setzen Sie den Pfad zum Repository per Umgebungsvariable und starten Sie `docker compose run --rm gitleaks`. Der Container scannt und beendet sich, ohne Webdienst, Datenbank oder offene Ports. Findings landen als JSON-, SARIF- oder JUnit-Report in `./reports/`. Seit Version 8.19 lautet der Aufruf `gitleaks git /repo`, die Option `--source` gibt es beim Unterbefehl `git` nicht. Bekannte False Positives ignorieren Sie per `.gitleaksignore`-Fingerprint oder Inline-Kommentar `#gitleaks:allow`. ## Voraussetzungen - [ ] **Docker Engine 20.10+** und **Docker Compose Plugin v2** (`docker compose`, nicht das alte `docker-compose`), Installation siehe [Docker und Docker Compose auf Linux installieren](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage). - [ ] Linux-Host, VM, NAS oder WSL2 mit amd64 oder arm64 (laut Image-Manifest v8.30.1). 1 CPU-Kern und 512 MB RAM genügen, ein Scan dauert in der Regel unter einer Sekunde. - [ ] Ein lokal ausgechecktes Git-Repository mit vollständiger History (`.git`-Verzeichnis muss im Mount-Root liegen). - [ ] Ausgabeverzeichnis `./reports/` auf dem Host. Fehlt es, legt Docker es beim Start als root an. - [ ] Keine Datenbank, kein API-Key, kein offener Port, Gitleaks ist zustandslos. ## Schritt 1: Eckdaten und Projektordner Die wichtigsten Parameter: | Parameter | Wert | | --- | --- | | Image (empfohlen) | `ghcr.io/gitleaks/gitleaks:v8.30.1` | | Alternatives Image | `zricethezav/gitleaks:v8.30.1` (Docker Hub) | | Aktueller stabiler Tag | `v8.30.1` (Release März 2026, aktuell im Oktober 2026) | | Image-Größe | ca. 25 MB | | Exponierter Port | keiner, Kommandozeilenwerkzeug | | Datenbank | keine | | Report-Formate | JSON, CSV, JUnit, SARIF, Go-Template | | Exit-Code bei Leaks | 1 (überschreibbar mit `--exit-code=0`) | | Exit-Code kein Fund | 0 | Legen Sie Projektordner und Report-Verzeichnis an: ```bash $ mkdir -p ~/gitleaks/reports $ cd ~/gitleaks ``` > **Prüfen:** `ls -la ~/gitleaks/` zeigt das Verzeichnis `reports/` mit Ihrem Benutzer als Besitzer. ## Schritt 2: .env-Datei anlegen Variable Pfade und Einstellungen stehen in der `.env`. So bleibt die `compose.yaml` unverändert, wenn Sie ein anderes Repository scannen. ```ini # Pfad zum zu scannenden Git-Repository (muss .git-Verzeichnis enthalten) REPO_PATH=/home/user/mein-projekt # Ausgabeverzeichnis für Reports (muss auf dem Host existieren) REPORT_PATH=./reports # Pfad zur optionalen Konfigurationsdatei (eigene Regeln, Allowlists) # Datei muss existieren, wenn der Mount aktiv ist! # Für die eingebauten Regeln Mount und GITLEAKS_CONFIG entfernen (Schritt 3). CONFIG_PATH=./.gitleaks.toml # Report-Format: json | csv | junit | sarif | template REPORT_FORMAT=json ``` Setzen Sie `REPO_PATH` auf den Repository-Root, also das Verzeichnis mit dem `.git`-Ordner, nicht auf ein Unterverzeichnis. > **Prüfen:** `cat ~/gitleaks/.env` zeigt die Variablen, `ls /home/user/mein-projekt/.git` listet den Inhalt des `.git`-Ordners. ## Schritt 3: compose.yaml anlegen Gitleaks ist ein Kommandozeilenwerkzeug, kein Dienst. Die Compose-Datei nutzt deshalb `restart: "no"` und ein Profil: Sie starten den Scan bewusst per `docker compose run`. ```yaml services: gitleaks: image: ghcr.io/gitleaks/gitleaks:v8.30.1 container_name: gitleaks-scanner restart: "no" volumes: - ${REPO_PATH:-./repo}:/repo:ro - ${REPORT_PATH:-./reports}:/reports - ${CONFIG_PATH:-./.gitleaks.toml}:/gitleaks.toml:ro environment: - GITLEAKS_CONFIG=/gitleaks.toml command: > git /repo --report-format=${REPORT_FORMAT:-json} --report-path=/reports/gitleaks-report.${REPORT_FORMAT:-json} --verbose --exit-code=0 profiles: - scan ``` Hinweise: 1. `git /repo`**statt**`detect --source`: Seit v8.19.0 sind `detect` und `protect` veraltet und durch `git` (Repositories) und `directory` (Verzeichnisse ohne Git, laut README Alias von `files`) ersetzt. Der Pfad folgt dem Unterbefehl direkt. Mit `git --source=/repo` bricht v8.30.1 mit `Error: unknown flag: --source` ab, es entsteht dann kein Report. `detect --source=/repo` funktioniert noch. 2. `:ro`**beim Repo-Mount**: Gitleaks liest das Repository nur. 3. `--exit-code=0`: Standardmäßig endet Gitleaks bei Findings mit Code 1 und bricht so Pipelines ab. Für reine Audits ist 0 sinnvoll. 4. **Ohne eigene Konfiguration**: Entfernen Sie den dritten Volume-Eintrag und `GITLEAKS_CONFIG`, dann gelten die eingebauten Regeln. > **Prüfen:** `docker compose config` gibt die aufgelöste Konfiguration ohne Fehler aus. Warnt Docker vor fehlenden Variablen, liegt die `.env` nicht neben der `compose.yaml`. ## Schritt 4: Optionale Gitleaks-Konfigurationsdatei anlegen Mit `CONFIG_PATH=./.gitleaks.toml` muss die Datei vor dem Start existieren. Fehlt sie, legt Docker an ihrer Stelle ein leeres Verzeichnis an, und Gitleaks bricht ab (siehe Typische Fehler). Eine minimale `.gitleaks.toml`: Datei: `.gitleaks.toml` ```ini # .gitleaks.toml, Minimalkonfiguration title = "Eigene Gitleaks-Konfiguration" [extend] # Standardregeln von Gitleaks einbinden useDefault = true # Beispiel: Bekanntes False-Positive-Muster ignorieren [[allowlists]] description = "Lokaler Testschlüssel" regexes = ['''test_secret_[a-z0-9]{8}'''] ``` Für den Einstieg reichen die Zeilen `[extend]` und `useDefault = true`. Eigene Regeln ergänzen Sie als `[[rules]]`-Blöcke. Seit v8.25.0 heißt der Abschnitt für Ausnahmen `[[allowlists]]` mit einer Liste `regexes`. Die ältere Schreibweise `[[allowlist.regexes]]` lehnt v8.30.1 mit `Failed to load config` ab. > **Prüfen:** `ls -la ~/gitleaks/.gitleaks.toml` zeigt eine Datei (kein Verzeichnis). ## Schritt 5: Ersten Scan ausführen Weil der Service in einem Profil liegt, starten Sie ihn mit `docker compose run` statt `docker compose up`: ```bash $ docker compose run --rm gitleaks ``` Gitleaks scannt das Repository und schreibt den Report nach `./reports/gitleaks-report.json`. Bei einem absichtlich eingecheckten GitHub-Token sieht die Ausgabe so aus (gekürzt): Datei: `./reports/gitleaks-report.json` ```json ○ │╲ │ ○ ○ ░ ░ gitleaks Finding: GITHUB_TOKEN = "ghp_tU...J9SW Secret: ghp_tU...J9SW RuleID: github-pat Entropy: 4.903056 File: config.py Line: 1 Commit: 70895cff11327dab437f560d12927532e4f67787 Author: Test Fingerprint: 70895cff11327dab437f560d12927532e4f67787:config.py:github-pat:1 11:44PM INF 2 commits scanned. 11:44PM INF scanned ~73 bytes (73 bytes) in 52.2ms 11:44PM WRN leaks found: 1 ``` > **Prüfen:** 1. Die Ausgabe endet mit `INF … commits scanned.` und `WRN leaks found: N` oder `INF no leaks found`. Steht dort `0 commits scanned`, zeigt der Mount nicht auf ein Git-Repository. > 2. `ls -lh ~/gitleaks/reports/` zeigt die Report-Datei. Sie gehört root, weil der Container als root läuft. > 3. `head -50 ~/gitleaks/reports/gitleaks-report.json` zeigt die ersten Findings. ## Schritt 6: Report auswerten und Findings verwalten Der JSON-Report enthält je Fund Datei, Zeile, Commit, Autor, Datum und einen eindeutigen **Fingerprint** der Form `Commit:Datei:Regel:Zeile`. Drei Wege, mit Findings umzugehen: ### Option A: Inline-Ausnahme im Code Ist ein Secret bewusst gesetzt (z. B. ein Testtoken in einer Unit-Test-Datei), schreiben Sie den Kommentar hinter die Zeile: ```bash TEST_API_KEY = "test_secret_abc12345" #gitleaks:allow ``` ### Option B: .gitleaksignore-Datei Für bekannte Findings in der Git-History, die sich nicht mehr entfernen lassen, tragen Sie den Fingerprint in eine `.gitleaksignore` ein: ```bash # .gitleaksignore, bekannte und akzeptierte Findings 70895cff11327dab437f560d12927532e4f67787:config.py:github-pat:1 ``` Die Datei liegt im Repository-Root. Gitleaks findet sie dort ohne weitere Option, der Scan meldet danach `no leaks found`. ### Option C: Baseline-Workflow Für ältere Repositories mit vielen historischen Findings speichern Sie zuerst einen vollständigen Scan als Baseline und lassen danach nur neue Findings melden: ```bash # Baseline erstellen docker compose run --rm gitleaks git /repo \ --report-format=json \ --report-path=/reports/baseline.json \ --exit-code=0 # Nur neue Findings (ab jetzt) melden docker compose run --rm gitleaks git /repo \ --baseline-path=/reports/baseline.json \ --report-format=json \ --report-path=/reports/new-findings.json ``` > **Prüfen:** `ls -lh ~/gitleaks/reports/` zeigt `baseline.json` und `new-findings.json`. Ohne neue Secrets meldet der zweite Lauf `no leaks found`, und `new-findings.json` enthält `[]`. ## Schritt 7: Image aktualisieren Gitleaks erhält weiterhin Sicherheitsupdates. Tragen Sie den neuen Tag in die `compose.yaml` ein und laden Sie das Image. Weil der Service in einem Profil liegt, braucht `pull` die Option `--profile scan`, ohne sie lädt `docker compose pull` nichts. Mehr zu Container-Updates: [Docker-Container automatisch aktualisieren nach dem Watchtower-Aus](https://s-edv.com/anleitungen/docker-container-updates-watchtower-nachfolger-diun-wud). ```bash $ docker compose --profile scan pull $ docker compose run --rm gitleaks --version ``` > **Prüfen:** Die Ausgabe zeigt die erwartete Version, zum Beispiel `gitleaks version v8.30.1`. ## Bonus: CI/CD-Integration Als Pipeline-Schritt prüft Gitleaks jeden Push, bevor Code in den Hauptbranch gelangt. Secrets gehören dabei in einen Secrets-Manager, nicht in Konfigurationsdateien (siehe [Docker Compose absichern](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root)). ### GitHub Actions ```yaml name: Secret Scan on: [push, pull_request] jobs: gitleaks: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 with: fetch-depth: 0 # vollständige History, kein Shallow Clone - uses: gitleaks/gitleaks-action@v3 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }} # nur für Organisationen ``` ### GitLab CI ```yaml gitleaks: image: name: ghcr.io/gitleaks/gitleaks:v8.30.1 entrypoint: [""] variables: GIT_DEPTH: 0 # vollständige History script: - gitleaks git . --report-path=gitleaks-report.json --exit-code=1 artifacts: reports: sast: gitleaks-report.json when: always ``` In beiden Fällen gilt: **vollständige Git-History** auschecken (`fetch-depth: 0` bzw. `GIT_DEPTH: 0`), sonst sieht Gitleaks nur den letzten Commit. `gitleaks-action@v2` läuft laut Projekt-README seit 16.09.2026 nicht mehr auf GitHub-gehosteten Runnern (Node 20 entfernt), nutzen Sie `@v3`. Für Repositories einer GitHub-Organisation verlangt die Action zusätzlich eine kostenlose Lizenz in `GITLEAKS_LICENSE`. ## Troubleshooting / Typische Fehler **„0 commits scanned“ und „no leaks found“ trotz vorhandener History** Der Mount zeigt nicht auf den Repository-Root. Gitleaks meldet dann `fatal: not a git repository` als Fehlerzeile, endet aber mit Exit-Code 0. Setzen Sie `REPO_PATH` auf das Verzeichnis, das `.git/` direkt enthält, z. B. `/home/user/mein-projekt` statt `/home/user/mein-projekt/src`. **„dubious ownership“** Git verweigert seit 2.35.2 Repositories eines anderen Besitzers. Im offiziellen Image ist `safe.directory = *` bereits gesetzt, der Fehler tritt dort nicht auf. Bei eigenen Images hilft `git config --global --add safe.directory /repo`. **Nur ein Commit gescannt** Das Repository ist ein Shallow Clone. In GitHub Actions `fetch-depth: 0`, in GitLab CI `GIT_DEPTH: 0` setzen. **Container startet ständig neu** In der `compose.yaml` steht `restart: always`. Nutzen Sie `restart: "no"` und `profiles: [scan]`. **Report-Datei fehlt nach dem Scan** Meist ist der Aufruf fehlgeschlagen, etwa mit `Error: unknown flag: --source` (siehe Schritt 3). Prüfen Sie die Ausgabe auf Fehlerzeilen. **„unable to load gitleaks config, err: read /gitleaks.toml: is a directory“** Die Datei aus `CONFIG_PATH` fehlte beim Start, Docker hat stattdessen ein Verzeichnis angelegt (in der Regel root-eigen). Löschen Sie es mit `sudo rmdir`, legen Sie die `.gitleaks.toml` an oder entfernen Sie Mount und `GITLEAKS_CONFIG`. **„Failed to load config … AllowList.Regexes[0]“** Die Konfiguration nutzt die alte Allowlist-Syntax. Stellen Sie auf `[[allowlists]]` mit `regexes = [...]` um (siehe Schritt 4). **Langer Scan oder Speichermangel bei großer History** `--max-target-megabytes` und `--timeout` nutzen oder den Bereich mit `--log-opts 'HEAD~50..HEAD'` eingrenzen. ## Häufige Fragen ### Brauche ich eine Datenbank oder weitere Container? Nein. Gitleaks läuft als einzelner zustandsloser Container ohne externe Abhängigkeiten und passt damit gut in schlanke CI/CD-Pipelines. ### Wie starte ich den Scan nach der Einrichtung? Mit `docker compose run --rm gitleaks`. `--rm` entfernt den Container nach dem Scan. ### Kann ich nur bestimmte Commits oder Branches scannen? Ja, mit `--log-opts`: `--log-opts='main..feature-branch'` scannt nur die Commits des Feature-Branches, `--log-opts='HEAD~10..HEAD'` die letzten zehn Commits. Ergänzen Sie die Option im `command`-Abschnitt hinter `git /repo`. ### Welches Report-Format eignet sich am besten für CI/CD? **SARIF** für GitHub Code Scanning (Upload in den Security-Tab), **JUnit** für Jenkins und GitLab-Testreports, **JSON** für eigene Auswertung oder SIEM-Anbindung. ### Wie ignoriere ich bekannte False-Positives dauerhaft? Per Fingerprint in der `.gitleaksignore` im Repository-Root oder per Inline-Kommentar `#gitleaks:allow`, der die Ausnahme sichtbar im Code dokumentiert (siehe Schritt 6). ### Ist Gitleaks noch aktiv gepflegt? Laut README ist Gitleaks „feature complete“: Neue Funktionen kommen nicht mehr hinzu, künftige Releases sind Sicherheitsupdates. Der Maintainer arbeitet am Nachfolger **Betterleaks**. Für das Aufspüren von Secrets reicht Gitleaks v8.x aus. ### Was ist der Unterschied zwischen den Unterbefehlen `git` und `directory`? `git` scannt ein Repository samt Commit-History, der Standardfall. `directory` (Alias `files`) scannt nur den aktuellen Dateistand eines beliebigen Verzeichnisses, etwa Konfigurationsordner ohne Git. ## Fazit Gitleaks findet eingecheckte Secrets schnell und ohne Infrastruktur. Das kleine Image und die fehlende Datenbank machen es zu einem einfachen Baustein für Scans auf Abruf und in Pipelines. Achten Sie auf die aktuelle Syntax (`git /repo`, `[[allowlists]]`) und prüfen Sie bei jedem Scan die Zahl der gescannten Commits. Neue Funktionen gibt es nicht mehr, Sicherheitsupdates weiterhin. Zur Härtung des Docker-Stacks: [Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root) und [Docker-Images auf Schwachstellen scannen mit Trivy](https://s-edv.com/anleitungen/docker-images-scannen-trivy-schwachstellen-sbom). Secrets zentral verwalten: [Infisical mit Docker: Open-Source Secrets Management](https://s-edv.com/anleitungen/infisical-docker-secrets-management). ## Weiterführende Anleitungen und Quellen 1. [Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root) 2. [Docker-Images auf Schwachstellen scannen mit Trivy: CVE-Check, SBOM und automatische Scans](https://s-edv.com/anleitungen/docker-images-scannen-trivy-schwachstellen-sbom) 3. [Infisical mit Docker: Open-Source Secrets Management](https://s-edv.com/anleitungen/infisical-docker-secrets-management) 4. [Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage) 5. [VPS absichern und härten: UFW, SSH-Keys und Fail2Ban](https://s-edv.com/anleitungen/vps-absichern-haerten-ufw-ssh-keys-fail2ban) **Offizielle Quellen:** [Gitleaks GitHub README](https://github.com/gitleaks/gitleaks#readme) · [Gitleaks GitHub Releases](https://github.com/gitleaks/gitleaks/releases) · [Gitleaks Docker Hub](https://hub.docker.com/r/zricethezav/gitleaks)