brumbelow/layerleaklayerleak lo scanner di segreti di Docker Hub
# layerleak lo scanner di segreti per immagini OCI [](https://go.dev/) Consulta [CONTRIBUTING.md](https://github.com/brumbelow/layerleak/blob/main/CONTRIBUTING.md) per le linee guida sui contributi. - Scanner di segreti per immagini OCI che funziona con qualsiasi registro pubblico conforme a OCI (Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public, self-hosted). Analizza i layer delle immagini, i metadati di configurazione e la cronologia dell'immagine, quindi memorizza i risultati deduplicati per digest del manifest. - I tradizionali scanner di segreti spesso trattano un'immagine contenitore come un blob piatto o dipendono da un daemon Docker locale. Questo progetto è progettato attorno ai meccanismi interni delle immagini OCI. ## Sommario - [Pagina della documentazione](#pagina-della-documentazione) - [Funzionalità attuali](#funzionalità-attuali) - [Installazione](#installazione) - [Persistenza Postgres](#persistenza-postgres) - [Come iniziare](#come-iniziare) - [API HTTP](#api-http) - [Deploy con Docker Compose (Dockge / Komodo)](#deploy-con-docker-compose-dockge--komodo) - [Licenza](#licenza) - [Supporta questo progetto](#supporta-questo-progetto) ## Pagina della documentazione - https://brumbelow.github.io/layerleak/docs Il sito pubblicato è costruito da `web/` su `main` tramite `.github/workflows/pages.yml`. La sorgente della documentazione e la demo simulata del browser risiedono entrambe in quella directory. ## Funzionalità attuali: - Immagini pubbliche da qualsiasi registro conforme a OCI (Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public, self-hosted) - Scansione in sola lettura - Nessuna verifica dei segreti - Nessuna dipendenza dal daemon Docker - Scansione consapevole dei manifest e dei layer - Scansiona il filesystem finale e gli artefatti dei layer eliminati - Scansiona i metadati di configurazione dell'immagine, le variabili d'ambiente, le etichette e la cronologia - Deduplica i risultati per impronta digitale del segreto e comprime i frammenti di contesto identici ripetuti per manifest - Rilevatori nativi per oltre 60 tipi di segreti più i valori predefiniti di TruffleHog come layer di fallback - Sopprime i risultati provenienti da percorsi test/fixture/spec/e2e/acceptance per ridurre i falsi positivi nelle immagini di sviluppo ## Installazione Prerequisiti: - Go 1.25.7+ Installa con Go: ```bash go install github.com/brumbelow/layerleak@latest layerleak --help ``` La destinazione di installazione canonica è la radice del modulo. Per fissare una release esplicitamente: ```bash go install github.com/brumbelow/[email protected] ``` Sostituisci `v1.0.0` con il tag `v1.x.y` pubblicato che desideri. Assicurati che la directory `GOBIN` o `GOPATH/bin` sia nel `PATH`. Il percorso del modulo è `github.com/brumbelow/layerleak`, quindi `go install @latest` risolve al tag `v1.x.y` pubblicato più alto. Una release del modulo `v2.x.y` richiederebbe che il percorso del modulo cambi in `github.com/brumbelow/layerleak/v2`. I binari installati come modulo riportano la versione del modulo risolta tramite `layerleak --version`; le build da checkout locale riportano la versione che Go incorpora per il checkout, con fallback a `dev` quando nessuna versione del modulo è disponibile. Compila dal sorgente: ```bash git clone https://github.com/brumbelow/layerleak.git cd layerleak go build -o layerleak . ./layerleak --help ``` Esegui l'API con un'immagine contenitore: ```bash 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 ``` L'immagine contenitore esegue l'API per impostazione predefinita e imposta `LAYERLEAK_API_ADDR=0.0.0.0:8080`. Configurazione ambientale opzionale: ```bash cp .env.example .env ``` Configurazione dei risultati e del database: ```bash 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 # Override opzionali del registro; di solito lasciare non impostati. export LAYERLEAK_REGISTRY_BASE_URL= export LAYERLEAK_REGISTRY_AUTH_URL= export LAYERLEAK_DATABASE_URL=postgres://postgres:postgres@localhost:5432/layerleak?sslmode=disable ``` Le stesse variabili e i loro valori predefiniti risiedono in [`.env.example`](https://github.com/brumbelow/layerleak/blob/main/.env.example), che è la fonte di verità per i valori predefiniti. | Variabile | Predefinito | Scopo | | --- | --- | --- | | `LAYERLEAK_LOG_LEVEL` | `info` | Livello di log: `debug`, `info`, `warn` o `error`. | | `LAYERLEAK_FINDINGS_DIR` | _non impostato_ | Dove scrivere i file JSON dei risultati. Se non impostato, il valore predefinito è `findings/` sotto il genitore più vicino contenente `go.mod`, con fallback alla directory di lavoro corrente. | | `LAYERLEAK_API_ADDR` | `127.0.0.1:8080` | Indirizzo di binding per il server API. L'immagine contenitore lo sovrascrive a `0.0.0.0:8080`. | | `LAYERLEAK_PERSIST_RAW_SECRETS` | `0` | Imposta a `1` per scrivere i valori segreti grezzi e i frammenti di contesto grezzi su disco e Postgres. I risultati rimangono oscurati per impostazione predefinita. | | `LAYERLEAK_HTTP_TIMEOUT` | `30s` | Timeout per richiesta per ogni chiamata al registro (manifest, blob, pagine di tag, token di autenticazione). Accetta qualsiasi durata Go (`30s`, `2m`, `1h`). | | `LAYERLEAK_MAX_FILE_BYTES` | `1048576` (1 MiB) | Massimo di byte decompressi bufferizzati per file all'interno di un layer. I file più grandi vengono saltati in quanto troppo grandi. Deve essere maggiore di zero. | | `LAYERLEAK_MAX_LAYER_BYTES` | `536870912` (512 MiB) | Massimo di byte del flusso del layer decompresso per layer. `0` disabilita il limite. | | `LAYERLEAK_MAX_LAYER_ENTRIES` | `50000` | Massimo di voci tar per layer. `0` disabilita il limite. | | `LAYERLEAK_MAX_MANIFEST_BYTES` | `0` | Massimo di byte del corpo del manifest. `0` disabilita il limite. | | `LAYERLEAK_MAX_CONFIG_BYTES` | `0` | Massimo di byte del corpo della configurazione dell'immagine. `0` disabilita il limite. | | `LAYERLEAK_MAX_TAG_RESPONSE_BYTES` | `8388608` (8 MiB) | Massimo di byte per pagina di risposta dell'elenco di tag del registro. `0` disabilita il limite. | | `LAYERLEAK_TAG_PAGE_SIZE` | `100` | Dimensione della pagina dell'elenco di tag del registro per scansioni a livello di repository. | | `LAYERLEAK_MAX_REPOSITORY_TAGS` | `0` | Massimo di tag enumerati per scansione del repository. `0` disabilita il limite. | | `LAYERLEAK_MAX_REPOSITORY_TARGETS` | `0` | Massimo di destinazioni distinte risolte per scansione del repository. `0` disabilita il limite. | | `LAYERLEAK_REGISTRY_REQUEST_ATTEMPTS` | `2` | Numero di tentativi (incluso il primo) per ogni richiesta al registro. | | `LAYERLEAK_REGISTRY_BASE_URL` | _non impostato_ | Override opzionale. Normalmente layerleak lo deriva da ogni riferimento all'immagine; impostalo solo per forzare le scansioni attraverso un proxy o un endpoint alternativo. | | `LAYERLEAK_REGISTRY_AUTH_URL` | _non impostato_ | Override opzionale. Normalmente scoperto dalla sfida `WWW-Authenticate` del registro. | | `LAYERLEAK_DATABASE_URL` | _non impostato_ | Se impostato, layerleak scrive le scansioni su Postgres e fa fallire il comando se la persistenza non riesce. | Quando uno qualsiasi dei limiti `MAX_*` è impostato a un valore positivo, superarlo fa fallire la scansione con un errore chiaro invece di troncare silenziosamente il lavoro. Comportamento dei risultati: - I risultati utilizzabili rimangono in `findings` e determinano lo stato di uscita della scansione diverso da zero. - I probabili segnaposto di test/esempio/demo vengono emessi separatamente come risultati di esempio soppressi e non contano per `total_findings`. - I record dei risultati includono `disposition`, `disposition_reason` e `line_number` per facilitare il triage e la revisione dei falsi positivi. - Se un limite operativo configurato viene superato, layerleak scrive e mostra comunque i risultati parziali prodotti prima del fallimento, quindi esce con stato `1` perché la scansione è incompleta. ## Persistenza Postgres Layerleak fornisce migrazioni SQL versionate sotto `migrations/`. Le migrazioni sono intenzionalmente manuali. Lo scanner non crea né aggiorna automaticamente lo schema. Layerleak richiede PostgreSQL server `>= 16.13` per l'API basata su DB e la persistenza dello scanner. Applica le migrazioni con `psql` in ordine: ```bash 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 ``` Oppure applica le migrazioni usando il comando helper del contenitore: ```bash docker run --rm \ -e LAYERLEAK_DATABASE_URL="$LAYERLEAK_DATABASE_URL" \ ghcr.io/brumbelow/layerleak:latest \ layerleak-migrate-up ``` `layerleak-migrate-up` può essere eseguito di nuovo senza problemi quando le migrazioni sono già state applicate. Se rileva uno stato di migrazione parziale, esce con codice diverso da zero e richiede un intervento manuale. L'helper impone anche la versione del server `>= 16.13` e verifica che il `postgresql-client-16` in bundle utilizzi il pacchetto Ubuntu PGDG `24.04` (`.pgdg24.04+`) alla versione `>= 16.13-1.pgdg24.04+1`. Ripristina le migrazioni in ordine inverso: ```bash 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 ``` Valori predefiniti operativi: - Le migrazioni dovrebbero rimanere additive. - Lo schema mantiene lo stato deduplicato corrente con `first_seen_at` e `last_seen_at`, e memorizza anche la cronologia delle scansioni append-only in `scan_runs`. - Le mappature dei tag vengono aggiornate per i tag toccati dalla scansione corrente. - I risultati vengono deduplicati canonicamente per `(manifest_digest, fingerprint)` e i frammenti di contesto identici ripetuti vengono compressi prima della persistenza. - La cronologia delle scansioni memorizza un'istantanea oscurata del JSON dei risultati pubblici, non valori grezzi o frammenti grezzi. Nota sulla sicurezza dei segreti: - La persistenza Postgres memorizza anteprime oscurate per impostazione predefinita. - Se `LAYERLEAK_PERSIST_RAW_SECRETS=1`, Postgres memorizza anche i valori dei risultati grezzi e i frammenti grezzi. - L'istantanea `scan_runs.result_json` rimane oscurata. - Utilizza un database o schema dedicato per layerleak. - Per il percorso di eliminazione più sicuro, elimina il database o schema dedicato invece di provare a rimuovere chirurgicamente singole righe. ## Come iniziare Mostra l'aiuto della CLI: ```bash layerleak --help layerleak scan --help ```  Esegui una scansione contro un'immagine OCI pubblica su qualsiasi registro supportato: ```bash ./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 ```  Ogni scansione scrive un file JSON dei risultati nella directory di output dei risultati. Se `LAYERLEAK_FINDINGS_DIR` non è impostato, la directory di output predefinita è `findings/` sotto il genitore più vicino contenente `go.mod` (tipicamente la radice del repository), con fallback alla directory di lavoro corrente quando non viene trovata alcuna radice del repository. Quei file dei risultati salvati contengono record di risultati con `redacted_value`, `context_snippet` oscurato, posizione esatta della fonte, metadati di disposizione e numero di riga per ogni risultato. Se `LAYERLEAK_PERSIST_RAW_SECRETS=1`, i file dei risultati salvati includono anche `value` grezzo e `raw_context_snippet`. Se la persistenza Postgres è abilitata, `findings.value` grezzo e `finding_occurrences.raw_snippet` rimangono vuoti a meno che `LAYERLEAK_PERSIST_RAW_SECRETS=1`. Per le immagini multi-architettura, layerleak salta i manifest di attestazione e provenienza come `application/vnd.in-toto+json` invece di contarli come scansioni di piattaforma fallite. Spazzate di repository nudi: - Passare un nome di repository nudo come `mongo` enumera ogni tag pubblico in quel repository, risolve ogni tag in un digest, raggruppa i digest duplicati e scansiona le destinazioni distinte. - layerleak stampa un avviso su stderr prima di iniziare la spazzata in modo che l'ambito sia ovvio nei log CI e nell'output di automazione. - Se desideri una sola immagine, passa un tag o digest esplicito come `mongo:latest` o `mongo@sha256:...`. Sintassi del comando: ```text layerleak [command] layerleak scan <image-ref> [flags] ``` Flag di ambito per spazzate di repository (ognuna sovrascrive la variabile d'ambiente corrispondente per un singolo comando): | Flag | Scopo | | --- | --- | | `--tag-page-size` | Dimensione della pagina dell'elenco di tag del registro per spazzate di repository. Deve essere maggiore di zero. Sovrascrive `LAYERLEAK_TAG_PAGE_SIZE`. | | `--max-repository-tags` | Massimo di tag enumerati per spazzata del repository. `0` disabilita il limite. Sovrascrive `LAYERLEAK_MAX_REPOSITORY_TAGS`. | | `--max-repository-targets` | Massimo di destinazioni distinte risolte per spazzata del repository. `0` disabilita il limite. Sovrascrive `LAYERLEAK_MAX_REPOSITORY_TARGETS`. | ## API HTTP Layerleak fornisce anche un'API JSON minima sotto `cmd/api`. L'API è basata su Postgres e richiede `LAYERLEAK_DATABASE_URL`; non serve dai file dei risultati su disco. Avviala con: ```bash go run ./cmd/api ``` Oppure esegui il contenitore API: ```bash docker run --rm \ -p 8080:8080 \ -e LAYERLEAK_DATABASE_URL='postgres://<user>:<password>@<host>:5432/layerleak?sslmode=disable' \ ghcr.io/brumbelow/layerleak:latest ``` Endpoint correnti: - `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` restituisce `{"status":"ok"}` e non richiede uno store o scanner configurato. È adatto per readiness probe di Kubernetes e target `healthcheck` di Docker Compose. `POST /api/v1/scans` rimane sincrono. Accetta un corpo JSON con `reference` e `platform` opzionale, e restituisce `scan_run_id` ogni volta che la persistenza Postgres è abilitata. Le risposte delle scansioni API riutilizzano lo stesso schema di risultati oscurato dell'output JSON della CLI. `GET /api/v1/scans/{id}` restituisce i metadati dell'esecuzione persistita più l'istantanea del risultato oscurato memorizzata. Anche gli endpoint per repository e risultati rimangono oscurati: restituiscono `redacted_value` e `context_snippet` oscurato, mai valori segreti grezzi o frammenti grezzi da Postgres. `GET /api/v1/repositories/{repository}/scans` e `GET /api/v1/repositories/{repository}/findings` accettano un parametro di query `registry` opzionale (ad esempio `?registry=ghcr.io`). Se omesso, il registro predefinito è `docker.io` per compatibilità con le versioni precedenti. Usalo per ottenere scansioni di repository su GHCR, Quay, GCR, MCR, Amazon ECR Public o qualsiasi registro self-hosted. Gli endpoint di elenco (`/repositories`, `/repositories/{repository}/scans`, `/repositories/{repository}/findings`) accettano `?limit=` e `?offset=` per la paginazione. `limit` predefinito a `50` e limitato a `200`. `/repositories/{repository}/findings` accetta anche `?disposition=actionable|suppressed|all`; se omesso, la risposta include solo i risultati utilizzabili. L'API non include autenticazione. Per deployment organizzativi, mantienila su una rete privata e mettila davanti al tuo gateway di autenticazione/autorizzazione o alla tua politica di reverse proxy. ## Deploy con Docker Compose (Dockge / Komodo) Questo repository fornisce uno stack Compose in `docker-compose.yml` con i servizi `db`, `migrate` e `api`. Il servizio `db` è fissato a `postgres:16.13-alpine` come baseline. Se usi un'immagine Postgres diversa, mantieni la versione del server a `16.13` o successiva. Imposta le variabili di deployment (esporta in shell o inseriscile in un file `.env` accanto a `docker-compose.yml`): ```bash 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 ``` Convalida la configurazione Compose renderizzata prima del deployment: ```bash docker compose config ``` Esegui le migrazioni una volta prima di avviare l'API: ```bash docker compose --profile manual run --rm migrate ``` Avvia il servizio API: ```bash docker compose up -d api ``` In Dockge o Komodo, importa lo stesso file Compose ed esegui il servizio `migrate` una volta prima di abilitare il servizio `api` a lunga esecuzione. ## Licenza Rilasciato sotto la licenza MIT — vedi [LICENSE](https://github.com/brumbelow/layerleak/blob/main/LICENSE). ## Supporta questo progetto <details open> <summary><strong>☕ Ti piace questo progetto? Clicca qui per supportarlo</strong></summary> <br> Se questo repository ti ha fatto risparmiare tempo o ti è stato d'aiuto, puoi supportare gli aggiornamenti futuri qui: **[Buy me a coffee](https://ko-fi.com/brumbelow)** Grazie :) aiuta davvero a mantenere il progetto aggiornato. </details>
