layerleak – Der OCI-Image-Secret-Scanner

Siehe CONTRIBUTING.md für Richtlinien zur Mitarbeit.

• OCI-Image-Secret-Scanner, der mit jedem öffentlichen OCI-konformen Registry arbeitet (Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public, selbst gehostet). Er analysiert Image-Layer, Konfigurationsmetadaten und die Image-Historie und speichert deduplizierte Funde nach Manifest-Digest.
• Herkömmliche Secret-Scanner behandeln ein Container-Image oft als flachen Blob oder sind auf einen lokalen Docker-Daemon angewiesen. Dieses Projekt ist auf die OCI-Image-Interna ausgelegt.

Inhaltsverzeichnis

• Dokumentationsseite
• Aktuelle Fähigkeiten
• Installation
• Postgres-Persistenz
• So starten Sie
• HTTP-API
• Docker-Compose-Bereitstellung (Dockge / Komodo)
• Lizenz
• Unterstützen Sie dieses Projekt

Dokumentationsseite

• https://brumbelow.github.io/layerleak/docs

Die veröffentlichte Seite wird aus web/ im main-Branch von .github/workflows/pages.yml erstellt. Die Quellen der Dokumentation und die simulierte Browser-Demo befinden sich in diesem Verzeichnis.

Aktuelle Fähigkeiten:

• Öffentliche Images von jedem OCI-konformen Registry (Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public, selbst gehostet)
• Nur-Lese-Scanning
• Keine Secret-Überprüfung
• Keine Abhängigkeit von einem Docker-Daemon erforderlich
• Manifest- und Layer-bewusstes Scannen
• Scannt das endgültige Dateisystem und Artefakte aus gelöschten Layern
• Scannt Image-Konfigurationsmetadaten, Umgebungsvariablen, Labels und die Historie
• Dedupliziert Funde nach Secret-Fingerprint und fasst wiederholte identische Kontextausschnitte pro Manifest zusammen
• Native Detektoren für über 60 Secret-Typen plus TruffleHog-Standardeinstellungen als Fallback-Layer
• Unterdrückt Funde aus Test-/Fixture-/Spec-/e2e-/Acceptance-Pfaden, um Fehlalarme in Entwicklungs-Images zu reduzieren

Installation

Voraussetzungen:

• Go 1.25.7+

Installation mit Go:

go install github.com/brumbelow/layerleak@latest
layerleak --help

Das kanonische Installationsziel ist das Modul-Root. Um eine bestimmte Version festzulegen:

go install github.com/brumbelow/[email protected]

Ersetzen Sie v1.0.0 durch das gewünschte veröffentlichte v1.x.y-Tag. Stellen Sie sicher, dass Ihr GOBIN- oder GOPATH/bin-Verzeichnis in PATH enthalten ist.

Der Modulpfad ist github.com/brumbelow/layerleak, daher löst go install @latest das höchste veröffentlichte v1.x.y-Tag auf. Eine v2.x.y-Modulveröffentlichung würde erfordern, dass der Modulpfad zu github.com/brumbelow/layerleak/v2 geändert wird. Modul-installierte Binärdateien melden die aufgelöste Modulversion über layerleak --version; lokale Checkout-Builds melden die Version, die Go für den Checkout einbettet, und fallen auf dev zurück, wenn keine Modulversion verfügbar ist.

Build aus dem Quellcode:

git clone https://github.com/brumbelow/layerleak.git
cd layerleak
go build -o layerleak .
./layerleak --help

Die API mit einem Container-Image ausführen:

docker pull ghcr.io/brumbelow/layerleak:latest
docker run --rm \
  -p 8080:8080 \
  -e LAYERLEAK_DATABASE_URL='postgres://<user>:<password>@<host>:5432/layerleak?sslmode=disable' \
  ghcr.io/brumbelow/layerleak:latest

Das Container-Image führt standardmäßig die API aus und setzt LAYERLEAK_API_ADDR=0.0.0.0:8080.

Optionale Umgebungskonfiguration:

cp .env.example .env

Ergebnis- und Datenbankkonfiguration:

export LAYERLEAK_LOG_LEVEL=info
export LAYERLEAK_FINDINGS_DIR=findings
export LAYERLEAK_API_ADDR=127.0.0.1:8080
export LAYERLEAK_PERSIST_RAW_SECRETS=0
export LAYERLEAK_TAG_PAGE_SIZE=100
export LAYERLEAK_HTTP_TIMEOUT=30s
export LAYERLEAK_MAX_FILE_BYTES=1048576
export LAYERLEAK_MAX_LAYER_BYTES=536870912
export LAYERLEAK_MAX_LAYER_ENTRIES=50000
export LAYERLEAK_MAX_MANIFEST_BYTES=0
export LAYERLEAK_MAX_CONFIG_BYTES=0
export LAYERLEAK_MAX_TAG_RESPONSE_BYTES=8388608
export LAYERLEAK_MAX_REPOSITORY_TAGS=0
export LAYERLEAK_MAX_REPOSITORY_TARGETS=0
export LAYERLEAK_REGISTRY_REQUEST_ATTEMPTS=2
# Optionale Registry-Überschreibungen; normalerweise nicht gesetzt.
export LAYERLEAK_REGISTRY_BASE_URL=
export LAYERLEAK_REGISTRY_AUTH_URL=
export LAYERLEAK_DATABASE_URL=postgres://postgres:postgres@localhost:5432/layerleak?sslmode=disable

Dieselben Variablen und ihre Standardwerte befinden sich in .env.example, das die Quelle der Wahrheit für Standardwerte ist.

Wenn eines der MAX_*-Limits auf einen positiven Wert gesetzt ist, führt dessen Überschreitung zu einem Scann-Fehler mit einer klaren Fehlermeldung, anstatt die Arbeit stillschweigend abzuschneiden.

Ergebnisverhalten:

• Umsetzbare Funde bleiben in findings und bestimmen den Nicht-Null-Scan-Exit-Status.
• Wahrscheinliche Test-/Beispiel-/Demo-Platzhalter werden separat als unterdrückte Beispielfunde ausgegeben und zählen nicht zu total_findings.
• Funddatensätze enthalten disposition, disposition_reason und line_number, um Triage und Überprüfung von Fehlalarmen zu erleichtern.
• Wenn ein konfiguriertes Betriebslimit überschritten wird, schreibt layerleak dennoch die vor dem Fehler erzeugten Teilergebnisse und rendert sie, beendet sich dann mit Status 1, da der Scan unvollständig ist.

Postgres-Persistenz

Layerleak enthält versionierte SQL-Migrationen unter migrations/. Migrationen sind bewusst manuell. Der Scanner erstellt oder aktualisiert das Schema nicht automatisch. Layerleak erfordert PostgreSQL-Server >= 16.13 für DB-gestützte API- und Scanner-Persistenz.

Wenden Sie die Migrationen mit psql in der richtigen Reihenfolge an:

psql "$LAYERLEAK_DATABASE_URL" -f migrations/0001_initial.up.sql
psql "$LAYERLEAK_DATABASE_URL" -f migrations/0002_finding_occurrence_metadata.up.sql
psql "$LAYERLEAK_DATABASE_URL" -f migrations/0003_scan_runs.up.sql

Oder wenden Sie Migrationen mit dem Container-Hilfsbefehl an:

docker run --rm \
  -e LAYERLEAK_DATABASE_URL="$LAYERLEAK_DATABASE_URL" \
  ghcr.io/brumbelow/layerleak:latest \
  layerleak-migrate-up

layerleak-migrate-up kann sicher erneut ausgeführt werden, wenn Migrationen bereits angewendet sind. Wenn ein teilweiser Migrationszustand erkannt wird, wird mit einem Nicht-Null-Exit beendet und um manuelles Eingreifen gebeten. Der Helfer erzwingt auch die Serverversion >= 16.13 und überprüft, ob das gebündelte postgresql-client-16 das Ubuntu PGDG 24.04-Paket verwendet (.pgdg24.04+) in Version >= 16.13-1.pgdg24.04+1.

Rückgängigmachen der Migrationen in umgekehrter Reihenfolge:

psql "$LAYERLEAK_DATABASE_URL" -f migrations/0003_scan_runs.down.sql
psql "$LAYERLEAK_DATABASE_URL" -f migrations/0002_finding_occurrence_metadata.down.sql
psql "$LAYERLEAK_DATABASE_URL" -f migrations/0001_initial.down.sql

Betriebliche Standardeinstellungen:

• Migrationen sollen additiv bleiben.
• Das Schema behält den aktuellen deduplizierten Zustand mit first_seen_at und last_seen_at bei und speichert zusätzlich eine append-only Scan-Historie in scan_runs.
• Tag-Zuordnungen werden für Tags aktualisiert, die vom aktuellen Scan berührt werden.
• Funde werden kanonisch nach (manifest_digest, fingerprint) dedupliziert, und wiederholte identische Kontextausschnitte werden vor der Persistenz zusammengefasst.
• Die Scan-Historie speichert eine geschwärzte Momentaufnahme des öffentlichen Ergebnis-JSONs, keine Rohwerte oder rohen Ausschnitte.

Hinweis zur Secrets-Sicherheit:

• Die Postgres-Persistenz speichert standardmäßig geschwärzte Vorschauen.
• Wenn LAYERLEAK_PERSIST_RAW_SECRETS=1 gesetzt ist, speichert Postgres auch rohe Fundwerte und rohe Ausschnitte.
• Die scan_runs.result_json-Momentaufnahme bleibt geschwärzt.
• Verwenden Sie eine dedizierte Datenbank oder ein Schema für layerleak.
• Für den sichersten Löschpfad löschen Sie die dedizierte Datenbank oder das Schema, anstatt zu versuchen, einzelne Zeilen gezielt zu entfernen.

So starten Sie

CLI-Hilfe anzeigen:

layerleak --help
layerleak scan --help

Führen Sie einen Scan gegen ein öffentliches OCI-Image auf einer beliebigen unterstützten Registry aus:

./layerleak scan ubuntu
./layerleak scan library/nginx:latest --format json
./layerleak scan alpine:latest --platform linux/amd64
./layerleak scan mongo
./layerleak scan ghcr.io/homebrew/core/hello:latest
./layerleak scan quay.io/prometheus/busybox:latest
./layerleak scan gcr.io/distroless/static:nonroot
./layerleak scan public.ecr.aws/docker/library/alpine:3.20
./layerleak scan mcr.microsoft.com/hello-world:latest

Jeder Scan schreibt eine JSON-Ergebnisdatei in das Ausgabeverzeichnis für Funde. Wenn LAYERLEAK_FINDINGS_DIR nicht gesetzt ist, ist das Standardausgabeverzeichnis findings/ unter dem nächstgelegenen übergeordneten Verzeichnis, das go.mod enthält (normalerweise das Repository-Root), mit einem Fallback auf das aktuelle Arbeitsverzeichnis, wenn kein Repository-Root gefunden wird.

Diese gespeicherten Ergebnisdateien enthalten Funddatensätze mit redacted_value, geschwärztem context_snippet, genauer Quellposition, Dispositionsmetadaten und Zeilennummer für jeden Fund. Wenn LAYERLEAK_PERSIST_RAW_SECRETS=1 gesetzt ist, enthalten die gespeicherten Ergebnisdateien auch rohe value und raw_context_snippet. Wenn die Postgres-Persistenz aktiviert ist, bleiben rohe findings.value und finding_occurrences.raw_snippet leer, es sei denn, LAYERLEAK_PERSIST_RAW_SECRETS=1 ist gesetzt. Bei Multi-Architektur-Images überspringt layerleak Attestations- und Provenance-Manifeste wie application/vnd.in-toto+json, anstatt sie als fehlgeschlagene Plattform-Scans zu zählen.

Repositoryweite Scans:

• Die Übergabe eines reinen Repository-Namens wie mongo zählt jedes öffentliche Tag in diesem Repository auf, löst jedes Tag in einen Digest auf, gruppiert doppelte Digests und scannt die verschiedenen Ziele.
• layerleak gibt eine Warnung auf stderr aus, bevor der Scan beginnt, sodass der Umfang in CI-Protokollen und Automatisierungsausgaben offensichtlich ist.
• Wenn Sie nur ein einzelnes Image wünschen, übergeben Sie ein explizites Tag oder einen Digest wie mongo:latest oder mongo@sha256:....

Befehlsyntax:

layerleak [command]
layerleak scan <image-ref> [flags]

Gültigkeitsflags für Repository-Scans (jedes überschreibt die entsprechende Umgebungsvariable für einen einzelnen Befehl):

HTTP-API

Layerleak enthält auch eine minimale JSON-API unter cmd/api. Die API ist Postgres-gestützt und erfordert LAYERLEAK_DATABASE_URL; sie bedient nicht aus den Ergebnisdateien auf der Festplatte.

Starten Sie sie mit:

go run ./cmd/api

Oder führen Sie den API-Container aus:

docker run --rm \
  -p 8080:8080 \
  -e LAYERLEAK_DATABASE_URL='postgres://<user>:<password>@<host>:5432/layerleak?sslmode=disable' \
  ghcr.io/brumbelow/layerleak:latest

Aktuelle Endpunkte:

• GET /health
• POST /api/v1/scans
• GET /api/v1/scans/{id}
• GET /api/v1/repositories
• GET /api/v1/repositories/{repository}/scans
• GET /api/v1/repositories/{repository}/findings
• GET /api/v1/findings/{id}

GET /health gibt {"status":"ok"} zurück und benötigt keinen konfigurierten Store oder Scanner. Er eignet sich für Kubernetes-Readiness-Probes und Docker-Compose-healthcheck-Ziele.

POST /api/v1/scans bleibt synchron. Er akzeptiert einen JSON-Body mit reference und optionalem platform und gibt scan_run_id zurück, wenn die Postgres-Persistenz aktiviert ist. API-Scan-Antworten verwenden dasselbe geschwärzte Ergebnisschema wie die CLI-JSON-Ausgabe. GET /api/v1/scans/{id} gibt die persistierten Lauf-Metadaten sowie die gespeicherte geschwärzte Ergebnismomentaufnahme zurück. Repository- und Finding-Endpunkte bleiben ebenfalls geschwärzt: Sie geben redacted_value und geschwärztes context_snippet zurück, niemals rohe Secret-Werte oder rohe Ausschnitte aus Postgres.

GET /api/v1/repositories/{repository}/scans und GET /api/v1/repositories/{repository}/findings akzeptieren einen optionalen registry-Abfrageparameter (z.B. ?registry=ghcr.io). Wenn er weggelassen wird, standardmäßig docker.io aus Gründen der Abwärtskompatibilität. Verwenden Sie dies, um Scans von Repositories auf GHCR, Quay, GCR, MCR, Amazon ECR Public oder einem selbst gehosteten Registry abzurufen.

List-Endpunkte (/repositories, /repositories/{repository}/scans, /repositories/{repository}/findings) akzeptieren ?limit= und ?offset= für Paginierung. limit standardmäßig 50 und ist auf 200 begrenzt. /repositories/{repository}/findings akzeptiert auch ?disposition=actionable|suppressed|all; wenn weggelassen, enthält die Antwort nur umsetzbare Funde.

Die API enthält keine Authentifizierung. Für Organisationsbereitstellungen halten Sie sie in einem privaten Netzwerk und stellen Sie ihr ein eigenes Authn/Authz-Gateway oder Reverse-Proxy-Richtlinie voran.

Docker-Compose-Bereitstellung (Dockge / Komodo)

Dieses Repository enthält einen Compose-Stack in docker-compose.yml mit den Diensten db, migrate und api. Der db-Dienst-Baseline ist auf postgres:16.13-alpine festgelegt. Wenn Sie ein anderes Postgres-Image verwenden, halten Sie die Serverversion auf 16.13 oder neuer.

Setzen Sie Bereitstellungsvariablen (in der Shell exportieren oder in einer .env-Datei neben docker-compose.yml ablegen):

export LAYERLEAK_IMAGE=ghcr.io/brumbelow/layerleak:latest
export LAYERLEAK_DB_NAME=layerleak
export LAYERLEAK_DB_USER=layerleak
export LAYERLEAK_DB_PASSWORD=replace-me
export LAYERLEAK_API_PORT=8080

Überprüfen Sie die gerenderte Compose-Konfiguration vor der Bereitstellung:

docker compose config

Führen Sie Migrationen einmalig aus, bevor Sie die API starten:

docker compose --profile manual run --rm migrate

Starten Sie den API-Dienst:

docker compose up -d api

In Dockge oder Komodo importieren Sie dieselbe Compose-Datei und führen Sie den migrate-Dienst einmalig aus, bevor Sie den langlebigen api-Dienst aktivieren.

Lizenz

Veröffentlicht unter der MIT-Lizenz – siehe LICENSE.

Unterstützen Sie dieses Projekt