DockSec

KI-gestützter Docker-Sicherheitsscanner, der Schwachstellen in einfacher Sprache erklärt

Was ist DockSec?

DockSec ist ein OWASP-Laborprojekt, das die Lücke zwischen komplexen Sicherheits-Scanergebnissen und umsetzbaren Entwicklerlösungen schließt. Es integriert branchenübliche Scanner (Trivy, Hadolint, Docker Scout) mit KI, um kontextbezogene Sicherheitsanalysen zu liefern.

Statt Sie mit einer Liste von über 200 CVEs zu überfordern, bietet DockSec:

• Priorisierung dessen, was Ihre spezifische Container-Umgebung tatsächlich betrifft.
• Erklärungen von Schwachstellen in einfacher Sprache, nicht nur Sicherheits-Fachjargon.
• Konkrete Vorschläge zur Behebung für Ihre Dockerfile.
• Erstellung professioneller, interaktiver Sicherheitsberichte für Ihr Team.

Alle Scans finden lokal statt; das Einzige, was Ihr Gerät jemals verlässt, sind die (von Geheimnissen bereinigten) Dateiinhalte, die an den von Ihnen gewählten KI-Anbieter gesendet werden – und mit einem lokalen Modell oder im Nur-Scan-Modus verlässt nichts Ihr Gerät. Siehe Datenfluss und Datenschutz.

So funktioniert es

DockSec-Workflow: vom Scan zu umsetzbaren Erkenntnissen

DockSec durchläuft eine Pipeline mit vier Phasen:

1. Scannen: Führt Trivy, Hadolint und Docker Scout lokal in Ihrer Umgebung aus.
2. Analysieren: Die KI korreliert die Ergebnisse aller Scanner, um Rauschen zu entfernen und die tatsächlichen Auswirkungen zu bewerten.
3. Empfehlen: Erzeugt verständliche Erklärungen und konkrete Behebungsschritte.
4. Berichten: Exportiert umsetzbare Ergebnisse als HTML, PDF, JSON, CSV, SARIF und CycloneDX-SBOM.

Erste Schritte

1. Voraussetzungen

DockSec orchestriert lokale Scanner und benötigt daher:

Oder lassen Sie DockSec Trivy und Hadolint für Sie installieren:```bash python -m docksec.setup_external_tools

### 2. DockSec installieren```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. Führen Sie Ihren ersten Scan aus

Für das lokale Scannen ist kein API-Schlüssel erforderlich:```bash docksec Dockerfile --scan-only

Jeder Scan endet mit einer Ergebnisübersicht: einer Schweregradtabelle, einem Sicherheits-Score von 0–100 mit einer
Bewertung, einem „Quick take“-Aktionsblock, den generierten Berichten (standardmäßig gespeichert unter
`~/.docksec/results/`), und einem vorgeschlagenen nächsten Befehl.

### 4. KI-Analyse aktivieren

Die KI-Analyse erklärt Befunde und schlägt Korrekturen vor. Wählen Sie einen Anbieter, legen Sie dessen API-Schlüssel fest, und führen Sie aus:```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

Jeder Anbieter hat ein sinnvolles Standardmodell (OpenAI: gpt-4o, Anthropic: claude-haiku-4-5, Google: gemini-1.5-pro, Ollama: llama3.1), daher ist --model optional. Um Flags nicht zu wiederholen, setzen Sie Umgebungsvariablen (oder legen Sie sie in einer .env-Datei im Verzeichnis ab, aus dem Sie starten - DockSec lädt sie automatisch):```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile

Bevor Inhalte an einen KI-Anbieter gesendet werden, werden vertraulich aussehende Werte (Passwörter, Tokens, API-Schlüssel, private Schlüsselblöcke) automatisch maskiert. Siehe [Datenfluss und Datenschutz](#data-flow-and-privacy).

### 5. Oder nutze die GitHub Action```yaml
- name: Run DockSec AI Scanner
  uses: OWASP/[email protected]
  with:
    dockerfile: 'Dockerfile'
    openai_api_key: ${{ secrets.OPENAI_API_KEY }}

Häufige Befehle```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

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 --no-color # also honors NO_COLOR

---

## Konfigurationsdatei

Committet eine `.docksec.yml` an der Wurzel eures Repository und das ganze Team - und
jeder CI-Job - scannt unter derselben Richtlinie, anstatt dass jeder Entwickler seine eigenen
Flags übergibt.```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

Jede Einstellung ist optional; alles, was du weglässt, greift auf die Umgebungsvariable und dann auf den eingebauten Standardwert zurück. Ein vollständiges, annotiertes Beispiel ist in examples/.docksec.yml.

Rangfolge

Höchste Priorität zuerst:``` CLI flag > environment variable > .docksec.yml > built-in default

Ein committetes `severity: LOW` wird also weiterhin durch `--severity CRITICAL` in der Befehlszeile und durch `DOCKSEC_DEFAULT_SEVERITY` in der Umgebung überschrieben.

### Discovery

DockSec sucht in der Arbeitsumgebung nach `.docksec.yml` (oder `.docksec.yaml`) und läuft dann bis zum Repository-Root nach oben, sodass ein Dienst in einem Monorepo-Unterverzeichnis die auf der obersten Ebene committete Richtlinie erbt. Die Suche endet in dem Verzeichnis, das `.git` enthält, sodass niemals eine Datei von außerhalb des Repositorys aufgenommen wird.

- `--config FILE` verwendet eine bestimmte Datei, anstatt zu suchen.
- `--no-config` ignoriert jede Konfigurationsdatei für reproduzierbare CI-Läufe.

Die aktive Konfigurationsdatei wird im Scan-Banner angezeigt, sodass immer klar ist, welche Richtlinie angewendet wurde.

### Einstellungen

| Einstellung | Äquivalentes Flag | Hinweise |
| --- | --- | --- |
| `severity` | `--severity` | Schweregradstufen für den Image-Scan |
| `fail_on` | `--fail-on` | CI-Gate-Schwelle |
| `formats` | `--format` | Listenform: `[json, html]` |
| `output_dir` | `--output-dir` | Ziel für Berichte |
| `provider` | `--provider` | `openai`, `anthropic`, `google`, `ollama` |
| `model` | `--model` | Modellname des Anbieters |
| `offline` | `--offline` | Kein Netzwerk; überspringt KI und Docker Scout |
| `skip_ai_scoring` | `--skip-ai-scoring` | Nur lokale Bewertung |
| `no_redact` | `--no-redact` | Maskiert keine Geheimnisse vor dem KI-Aufruf |
| `no_cache` | `--no-cache` | Scan-Cache umgehen |
| `ignore_file` | `--ignore-file` | Pfad zur Waiver-Datei |
| `baseline` | `--baseline` | Pfad zur Baseline-Datei |
| `rules.disabled` | - | Regel-IDs, die vollständig deaktiviert werden |

Eine ungültige Konfigurationsdatei – ein unbekannter Schlüssel, ein ungültiger Schweregrad – ist ein harter Fehler, der mit Code `2` endet und nicht nur eine Warnung erzeugt. Eine fehlerhafte Richtliniendatei kann also niemals dazu führen, dass ein Scan mit Regeln läuft, die das Team nicht committet hat.

### Editor-Autovervollständigung

Der Kommentar `# yaml-language-server:` in der ersten Zeile bietet Vervollständigung und Inline-Validierung in VS Code und JetBrains-Editoren. Das Schema ist unter [`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/HEAD/docs/docksec-config-schema.json) veröffentlicht und kann mit `docksec --print-config-schema` neu erzeugt werden.

### Regeln deaktivieren

`rules.disabled` schaltet eine Prüfung überall vollständig ab – sie wird vor der Bewertung, vor Berichten, vor `--json` und vor dem `--fail-on`-Gate entfernt. Verwenden Sie es für Prüfungen, die in Ihrer Umgebung nicht zutreffen. Für einzelne Befunde, die Ihr Team triagiert und akzeptiert hat, bevorzugen Sie die [Waiver-Datei](#ignoring-findings-waivers), deren Einträge einen Grund und ein Ablaufdatum enthalten und so prüfbar bleiben.

---

## CI/CD-Integration

### Exit-Codes

DockSec verwendet CI-freundliche Exit-Codes, damit Builds und Shells auf Ergebnisse reagieren können:

| Code | Bedeutung |
|---|---|
| `0` | Erfolg, keine Befunde bei oder über `--fail-on` |
| `1` | Befunde bei oder über dem `--fail-on`-Schwellenwert |
| `2` | Nutzungs- oder Argumentfehler |
| `3` | Tool- oder Laufzeitfehler (Scan fehlgeschlagen, Image nicht gefunden, fehlende Tools) |

`--fail-on` greift als Gate auf die strukturierten Befunde (Image-Schwachstellen und Compose-Fehlkonfigurationen). Wenn `--fail-on` unter dem angeforderten `--severity` liegt, wird der Scan-Schweregrad automatisch erweitert, damit das Gate diese Befunde erkennen kann.

### Maschinenlesbare Ausgabe

`--json` gibt ein einzelnes JSON-Objekt auf stdout aus (Scan-Informationen, Schwachstellen, Schweregrad-Anzahl und etwaige KI-Befunde) anstelle der menschenlesbaren Zusammenfassung, sodass es direkt an andere Werkzeuge weitergeleitet werden kann:```bash
docksec -i myapp:latest --image-only --json | jq '.severity_counts'

Mit --json allein werden keine Berichtsdateien geschrieben; kombinieren Sie es mit --format, um Dateien zu schreiben und JSON im selben Lauf auszugeben. Alle menschenlesbaren Meldungen werden im --json-Modus nach stderr verschoben, sodass stdout nur die JSON-Nutzlast enthält.

SARIF output for GitHub Code Scanning

--sarif schreibt einen SARIF-2.1.0-Bericht neben den anderen Berichtsformaten. Laden Sie ihn mit der Standardaktion github/codeql-action/upload-sarif hoch, um Ergebnisse direkt in Pull Requests und auf dem Security-Tab angezeigt zu bekommen:```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()` ist wichtig: Ohne sie wird der Upload-Schritt übersprungen, wenn
> `--fail-on` DockSec mit einem Exit-Code ungleich Null beendet, wodurch die Befunde genau dann verloren gehen,
> wenn sie am wichtigsten sind.

### Baseline / Ratschenmodus

`--baseline FILE` ermöglicht es dir, `--fail-on` in einem bestehenden Projekt einzuführen, ohne dass eine Wand
bereits vorhandener Befunde jeden Build blockiert. Führe es einmal mit `--update-baseline` aus, um
die heutigen Befunde zu erfassen, und committe dann die Baseline-Datei; von da an greift `--fail-on` nur noch bei
Befunden, die noch nicht in der Baseline enthalten sind:```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

Findings are matched by vulnerability ID, target, and package name, so the baseline stays valid as unrelated findings come and go. Re-run with --update-baseline whenever you want to accept the current state as the new baseline.

Ignoring findings (Ausnahmen)

--ignore-file FILE suppresses individual findings a team has triaged and accepted. Unlike the baseline (a point-in-time snapshot), the ignore file is an explicit, reviewable list where every entry carries a reason and an optional expiry date. If a .docksec-ignore.yml file exists in the current directory, it is picked up automatically.```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"

Unterdrückte Befunde werden vor der Bewertung, den Berichten, der `--json`-Ausgabe und dem `--fail-on`-Gate entfernt. Abgelaufene Einträge werden automatisch nicht mehr angewendet (mit einer Warnung), und Einträge ohne Grund werden markiert, damit Ausnahmen prüfbar bleiben. Committen Sie die Datei in die Versionskontrolle, damit Unterdrückungen wie jede andere Änderung überprüft werden.

---

## Berichte

### Berichtsformate

Standardmäßig schreibt jeder Scan vier Berichtsdateien; verwenden Sie `--format`, um eine Teilmenge auszuwählen:

- **html**: Ein interaktiver, optisch aufgeräumter Web-Bericht: Schweregrad-Karten, Bewertung, vollständige Schwachstellentabelle mit behobenen Versionen und die vollständigen KI-Befunde.
- **pdf**: Ein portables, präsentationsfertiges Dokument.
- **json**: Vollständige, maschinenlesbare Scandaten (gleiche Struktur wie die `--json`-Standardausgabe).
- **csv**: Eine tabellenkalkulationsbereite Tabelle einzelner Schwachstellen.

> Hinweis zum CSV-Verhalten: Bei null Schwachstellen schreibt DockSec dennoch eine CSV-Datei, die nur den Header enthält
> (Spaltennamen, keine Zeilen), damit nachgelagerte Automatisierung nie an einer fehlenden oder
> leeren Datei scheitert. Dies ist beabsichtigt.

### CycloneDX SBOM

`--sbom` schreibt eine CycloneDX-Software-Stückliste (`<image>.cdx.json`) des gescannten Images, die jede Paketkomponente plus bekannte Schwachstellen auflistet. Die BOM wird vom nativen Exporter von Trivy erzeugt (also spezifikationskonform), und DockSec trägt sich selbst in die Tool-Metadaten ein. Übergeben Sie sie an Dependency-Track, den GitHub-Abhängigkeitsgraphen oder einen beliebigen anderen SBOM-Konsumenten:```bash
docksec --image-only -i myapp:latest --sbom

--sbom benötigt ein einzelnes Image (-i), daher wird es bei Compose-Läufen übersprungen. Wie --sarif ist es unabhängig von --format.

Datenfluss und Datenschutz

DockSec ist so konzipiert, dass Sie immer wissen, was Ihre Maschine verlässt:

• Der Scan läuft vollständig lokal ab. Trivy, Hadolint und der Sicherheits-Score laufen auf Ihrem Rechner. Bildinhalte werden von DockSec niemals irgendwohin hochgeladen.
• Die KI-Analyse sendet nur die gescannte Datei. Wenn der KI-Durchlauf ausgeführt wird, werden der Inhalt der Dockerfile oder Compose-Datei (plus eine kurze Zusammenfassung der Schwachstellenanzahlen für die Bewertung) an den von Ihnen konfigurierten LLM-Anbieter gesendet. Sonst wird nichts übertragen.
• Geheimnisse werden geschwärzt, bevor sie die Maschine verlassen. Geheimnisartige Werte (Passwörter, Tokens, API-Schlüssel, private Schlüsselblöcke) in der Datei werden maskiert, bevor der Inhalt an den KI-Anbieter gesendet wird. Schlüsselnamen bleiben sichtbar, sodass offengelegte Anmeldedaten weiterhin markiert werden. Mit --no-redact können Sie dies deaktivieren.
• Vollständig lokale KI wird unterstützt. Verwenden Sie --provider ollama, um die KI-Analyse auf Ihrer eigenen Hardware zu halten, oder --scan-only / --offline, um die KI vollständig zu überspringen.
• Keine Telemetrie. DockSec erfasst keine Nutzungsdaten und nimmt zu keinerlei externen Diensten Kontakt auf.

Offline-Modus

--offline führt einen Scan ohne Netzwerkzugriff durch. Es verwendet die bereits auf der Festplatte vorhandene Trivy-Schwachstellendatenbank (kein DB-Update) und überspringt die KI-Analyse sowie den erweiterten Docker-Scout-Scan, die beide ein Netzwerk erfordern. Dies ist der einfachste Weg, um in einer abgeschotteten oder restriktiven Umgebung zu scannen:```bash docksec --image-only -i myapp:latest --offline

Stellen Sie sicher, dass die Trivy-Datenbank mindestens einmal heruntergeladen wurde (jeder frühere Online-Scan erledigt
dies), bevor Sie sich auf `--offline` verlassen.

### Cache für Scan-Ergebnisse

Scan-Ergebnisse von Images werden zwischengespeichert (Standard: 24 Stunden, überschreibbar mit
`DOCKSEC_CACHE_TTL_HOURS`) und anhand des Inhalts-Digests des Images referenziert, sodass ein neu erstellter Tag
wie ein wiederverwendetes `:latest` immer einen frischen Scan erhält. Verwenden Sie `--no-cache` (oder
`DOCKSEC_USE_CACHE=false`), um den Cache für einen Lauf zu umgehen.

---

## KI-Assistent-Fähigkeiten (`install-skill`)

`docksec install-skill` schreibt die DockSec-Nutzungsanweisungen in die bekannten Kontextdateien
für gängige KI-Codierungs-Assistenten, sodass ein Assistent, der in Ihrem Repository arbeitet, weiß, wie er
DockSec aufrufen kann:```bash
docksec install-skill

Dies erstellt oder aktualisiert:

• .claude/commands/docksec.md (Claude-Code-Slash-Befehl /docksec)
• .cursor/rules/docksec.mdc (Cursor)
• AGENTS.md (Codex CLI), GEMINI.md (Gemini CLI)
• .github/copilot-instructions.md (GitHub Copilot)

Die Dateien sind einfacher Text, den du überprüfen und committen kannst; nichts wird ausgeführt. Das erneute Ausführen des Befehls aktualisiert den DockSec-Abschnitt an Ort und Stelle, anstatt ihn zu duplizieren.

Funktionen

• Smarte Analyse: KI erklärt, was Schwachstellen für dein spezifisches Setup bedeuten.
• Multi-LLM-Unterstützung: OpenAI, Anthropic Claude, Google Gemini oder lokale Modelle über Ollama.
• Datenschutz zuerst: Geheime Werte werden redigiert, bevor Inhalte einen KI-Anbieter erreichen, das Scannen erfolgt vollständig lokal, und es gibt keine Telemetrie.
• Docker-Compose-Scanning: Erkennt Fehlkonfigurationen auf Orchestrierungsebene und scannt alle Dienste in einer Compose-Datei.
• Tiefe Integration: Kombiniert Trivy (Schwachstellen), Hadolint (Linting) und Docker Scout.
• Sicherheits-Scoring: Ein Punktwert von 0–100 mit einer Einstufung, um deine Sicherheitslage im Zeitverlauf zu verfolgen.
• Vielfältige Formate: HTML (interaktiv), PDF, JSON, CSV, SARIF und CycloneDX-SBOM.
• CI/CD-bereit: --fail-on-Exit-Codes, Baseline-/Ratchet-Modus, prüfbare Ausnahmegenehmigungen, JSON-to-stdout und eine GitHub Action im Marketplace.
• Offline-Modus: Scannt vollständig netzwerkisoliert (--offline) mithilfe der lokalen Trivy-Datenbank.
• KI-Assistenten-Skills: docksec install-skill bringt Claude Code, Cursor, Copilot und anderen bei, wie DockSec in deinem Repository ausgeführt wird.

DockSec im Vergleich

DockSec ist das einzige dieser Tools, das kontextbezogene Dockerfile-Behebung mit einem vollständig quelloffenen, OWASP-verwalteten und lokal ausführbaren Design kombiniert. Snyk und Aikido bieten leistungsfähige KI-Behebung, aber nur als kommerzielle Cloud-Plattformen, die deine Daten an ihren Dienst senden. Trivy ist quelloffen und lokal, endet jedoch bei der Erkennung und hilft nicht bei der Behebung. DockSec schließt diese Lücke für Entwickler und für regulierte oder netzwerkisolierte Teams, die sowohl die Behebungsanleitung als auch die volle Kontrolle über ihre Daten benötigen – und das kostenlos.

Roadmap

In ROADMAP.md erfährst du, wohin die Reise für DockSec geht: Registry-Scanning ohne lokalen Docker-Daemon, eine Richtlinien-Konfigurationsdatei auf Repository-Ebene, Jenkins-/GitLab-/Azure-DevOps-Vorlagen, ein offizielles Container-Image, Kubernetes- und Helm-Scanning und mehr. Feedback und Stimmen zu Prioritäten sind willkommen in Issues und auf OWASP Slack.

Mitwirken

DockSec lebt von den Beiträgen der Community. Ob du Entwickler, Designer oder Sicherheitsbegeisterter bist, es gibt viele Möglichkeiten, dich einzubringen:

• Code-Beiträge: Behebe Fehler oder füge neue Funktionen hinzu.
• Dokumentation: Verbessere Anleitungen oder erstelle Tutorials.
• Problemberichte: Identifiziere und melde Fehler.
• Feedback: Teile deine Erfahrungen und Vorschläge.

Um loszulegen, wirf einen Blick auf unsere Mitwirkungsrichtlinien, unseren Verhaltenskodex und die Sponsoring-Anleitung.

Leitung und Community

DockSec wird von einem engagierten Team geleitet, das sich dafür einsetzt, Containersicherheit zugänglich zu machen:

• Advait Patel – Projektleitung
• Arkadii Yakovets – Co-Projektleitung

Hier findest du uns:

• OWASP-Projektseite: owasp.org/DockSec/
• OWASP-Slack: #project-docksec
• PyPI: pypi.org/project/docksec/
• Issues: Fehler melden
• Changelog: CHANGELOG.md