owasp/docksecKI-gestützter Docker-Sicherheitsscanner, der Schwachstellen in einfachem Englisch erklärt. Ein OWASP-Lab-Projekt.
<div align="center"> [](https://owasp.org/DockSec/) [](https://owasp.org/DockSec/) [](https://owasp.slack.com/archives/C0APXGCUW7M) [](https://github.com/OWASP/DockSec/actions) <br>[](https://www.bestpractices.dev/projects/12939) [](https://github.com/OWASP/DockSec/blob/main/LICENSE) [](https://github.com/OWASP/DockSec/commits/main/) [](https://github.com/OWASP/DockSec/graphs/contributors) [](https://github.com/OWASP/DockSec/network/members) [](https://github.com/OWASP/DockSec/stargazers)  [](https://github.com/OWASP/DockSec/issues) [](https://github.com/OWASP/DockSec/pulls) [](https://github.com/OWASP/DockSec/commit/80664db8935e4b5ab44df5867913e) <picture> <source srcset="https://raw.githubusercontent.com/OWASP/DockSec/main/images/docksec-logo-for-github.png" media="(prefers-color-scheme: dark)"> <img src="https://assets.kitploit.com/production/public/readmes/39487/d30ee74abf3ad22a447ed36ba3010acab606147bc21702a1fb428b8633298caf.png" alt="DockSec Logo" width="600"> </picture><br> <img src="https://assets.kitploit.com/production/public/readmes/39487/009ae678c48ab2738e17c17c238c83cb2481510fbc2bf9d7284ea80ec487feda.png" alt="OWASP Logo" width="300"> # [DockSec](https://owasp.org/DockSec/) **KI-gestützter Docker-Sicherheitsscanner, der Schwachstellen in verständlichem Deutsch erklärt** </div> --- ## Was ist DockSec? DockSec ist ein **OWASP Lab Project**, das die Lücke zwischen komplexen Sicherheitsscan-Ergebnissen und umsetzbaren Entwicklerkorrekturen schließt. Es integriert branchenübliche Scanner (Trivy, Hadolint, Docker Scout) mit KI, um **kontextbezogene Sicherheitsanalysen** bereitzustellen. Anstatt Sie mit einer Liste von über 200 CVEs zu überfordern, tut DockSec Folgendes: - **Priorisiert**, was tatsächlich Ihr spezifisches Container-Setup betrifft. - **Erklärt** Schwachstellen in verständlicher Sprache, nicht nur in Sicherheitsjargon. - **Schlägt** konkrete Korrekturen für Ihr Dockerfile vor. - **Erstellt** professionelle, interaktive Sicherheitsberichte für Ihr Team. Alles wird lokal gescannt; das Einzige, was Ihren Rechner jemals verlässt, ist der (um Geheimnisse bereinigte) Dateiinhalt, der an den von Ihnen gewählten KI-Anbieter gesendet wird – und mit einem lokalen Modell oder dem Nur-Scan-Modus verlässt überhaupt nichts Ihren Rechner. Siehe [Datenfluss und Datenschutz](#data-flow-and-privacy). --- ## Wie es funktioniert <div align="center"> <img src="https://assets.kitploit.com/production/public/readmes/39487/99b4247f599cc8f7a260f285815f8793ca4d2c050ea6656480818a846d590fb0.png" alt="DockSec Workflow" width="800"> <p><em>DockSec-Workflow: vom Scannen zu umsetzbaren Erkenntnissen</em></p> </div> DockSec folgt einer fünfstufigen Pipeline: 1. **Scannen**: Führt Trivy (Image-Schwachstellen und Dockerfile-Fehlkonfigurationen), Hadolint und Docker Scout lokal in Ihrer Umgebung aus. 2. **Priorisieren**: Ordnet jeden CVE-Befund nach Schweregrad in Kombination mit seiner [EPSS](https://www.first.org/epss/)-Ausnutzungswahrscheinlichkeit ein, sodass die Liste danach sortiert ist, was zuerst behoben werden sollte, und nicht danach, was zuerst gefunden wurde. 3. **Korrelieren**: Erkennt [Exploit-Ketten](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md), bei denen separate Befunde zu einem einzigen Angriffspfad kombiniert werden – eine Datenbank mit Anmeldedaten, die ein internetzugewandter Dienst erreichen kann, ist eine Kette und nicht zwei unabhängige Befunde. Mit einem API-Schlüssel analysiert ein KI-Durchlauf die vollständige Scan-Ausgabe, um dies zu bewerten, zu erklären und zu erweitern. 4. **Empfehlen**: Erzeugt kopier- und ausführbare Korrekturbefehle und konkrete Dockerfile- oder Compose-Änderungen und gibt an, wie viele Befunde sie beheben. 5. **Berichten**: Exportiert umsetzbare Ergebnisse als HTML, PDF, JSON, CSV, Markdown, SARIF und CycloneDX SBOM. --- ## Erste Schritte ### 1. Voraussetzungen DockSec orchestriert lokale Scanner und benötigt daher: | Anforderung | Benötigt für | Installation | |---|---|---| | Python 3.12+ | DockSec selbst | [python.org](https://www.python.org/downloads/) | | Trivy | Alle Scans (erforderlich) | `brew install trivy` oder [Trivy-Dokumentation](https://trivy.dev/latest/getting-started/installation/) | | Hadolint | Dockerfile-Linting | `brew install hadolint` oder [Hadolint-Dokumentation](https://github.com/hadolint/hadolint#install) | | Docker | Image-Scans (`-i`) | [Docker-Dokumentation](https://docs.docker.com/get-docker/) | 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 durch Für lokales Scannen ist kein API-Schlüssel erforderlich:```bash docksec Dockerfile --scan-only ``` Jeder Scan endet mit einer Ergebniszusammenfassung: einer Schweregradtabelle, einem Sicherheitswert 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ähle einen Anbieter, setze dessen API-Schlüssel und führe 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 wiederholte Flags zu vermeiden, setzen Sie Umgebungsvariablen (oder legen Sie sie in einer `.env`-Datei im Verzeichnis ab, aus dem Sie ausführen - 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 geheimnisvoll wirkende Werte (Passwörter, Tokens, API-Schlüssel, private Schlüsselblöcke) automatisch maskiert. Siehe [Datenfluss und Datenschutz](#data-flow-and-privacy). ### 5. Oder das Container-Image ausführen (nichts zu installieren) Das veröffentlichte Image bündelt festgelegte Versionen von Trivy und Hadolint, sodass es nichts zu installieren und nichts zu konfigurieren gibt:```bash docker run --rm -v "$PWD:/github/workspace" \ -e INPUT_DOCKERFILE=Dockerfile \ -e INPUT_SCAN_ONLY=true \ ghcr.io/owasp/docksec:latest ``` Veröffentlicht multi-arch (amd64 und arm64) bei jedem Release. Pinne auf eine bestimmte Version (`ghcr.io/owasp/docksec:2026.9.21`) oder eine Minor-Serie (`ghcr.io/owasp/docksec:2026.9`) statt auf `latest` in CI. Jedes Image trägt eine Build-Provenance-Attestierung:```bash gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec ``` Das Image liest dieselben `INPUT_*`-Variablen wie die GitHub Action, daher funktioniert jede Action-Eingabe hier: `INPUT_IMAGE`, `INPUT_COMPOSE`, `INPUT_SEVERITY`, `INPUT_FAIL_ON`, `INPUT_FORMAT`, `INPUT_SARIF`, `INPUT_OUTPUT_DIR`. Schreiben Sie Berichte irgendwo auf das Mount, um sie nach dem Beenden des Containers zu behalten:```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. Oder verwenden Sie 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 # 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 ``` --- ## Konfigurationsdatei Committen Sie eine `.docksec.yml` im Stammverzeichnis Ihres Repositorys, und das gesamte 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 Sie weglassen, fällt auf die Umgebungsvariable und dann auf den integrierten Standardwert zurück. Ein vollständiges kommentiertes Beispiel finden Sie in [`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/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` auf der Kommandozeile und durch `DOCKSEC_DEFAULT_SEVERITY` in der Umgebung überschrieben. ### Discovery DockSec sucht nach `.docksec.yml` (oder `.docksec.yaml`) im Arbeitsverzeichnis und geht dann bis zum Repository-Root nach oben, sodass ein Dienst in einem Monorepo-Unterverzeichnis die auf oberster Ebene committete Policy erbt. Die Suche endet bei dem Verzeichnis, das `.git` enthält, sodass sie niemals eine Datei von außerhalb des Repositorys aufnimmt. - `--config FILE` verwendet eine bestimmte Datei anstelle der Suche. - `--no-config` ignoriert jede Konfigurationsdatei, für reproduzierbare CI-Läufe. Die aktive Konfigurationsdatei wird im Scan-Banner angezeigt, sodass immer klar ist, welche Policy angewendet wurde. ### Einstellungen | Einstellung | Äquivalentes Flag | Hinweise | | --- | --- | --- | | `severity` | `--severity` | Schweregrade für den Image-Scan | | `fail_on` | `--fail-on` | CI-Gate-Schwellenwert | | `formats` | `--format` | Listenform: `[json, html]` | | `output_dir` | `--output-dir` | Ziel für Berichte | | `provider` | `--provider` | `openai`, `anthropic`, `google`, `ollama` | | `model` | `--model` | Modellname für den Provider | | `offline` | `--offline` | Kein Netzwerk; überspringt KI und Docker Scout | | `skip_ai_scoring` | `--skip-ai-scoring` | Veraltet und ignoriert; Scoring ist immer deterministisch | | `no_redact` | `--no-redact` | Secrets vor dem KI-Aufruf nicht maskieren | | `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 `2` beendet wird, statt einer Warnung, sodass eine fehlerhafte Policy-Datei niemals dazu führen kann, dass ein Scan unter Regeln läuft, die das Team nicht committet hat. ### Editor-Autovervollständigung Der `# yaml-language-server:`-Kommentar in der ersten Zeile ermöglicht Vervollständigung und Inline-Validierung in VS Code- und JetBrains-Editoren. Das Schema wird unter [`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/main/docs/docksec-config-schema.json) veröffentlicht und kann mit `docksec --print-config-schema` neu generiert werden. ### Regeln deaktivieren `rules.disabled` schaltet eine Prüfung vollständig ab, überall - sie wird vor dem Scoring, den Berichten, `--json` und dem `--fail-on`-Gate entfernt. Verwende es für Prüfungen, die nicht auf deine Umgebung zutreffen. Für einzelne Findings, die dein Team triagiert und akzeptiert hat, bevorzuge die [Waiver-Datei](#ignoring-findings-waivers), deren Einträge einen Grund und ein Ablaufdatum tragen und somit auditierbar 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 Findings bei oder über `--fail-on` | | `1` | Findings bei oder über dem `--fail-on`-Schwellenwert | | `2` | Verwendungs- oder Argumentfehler | | `3` | Werkzeug- oder Laufzeitfehler (Scan fehlgeschlagen, Image nicht gefunden, fehlende Werkzeuge) | `--fail-on` prüft jedes strukturierte Finding: Image-Schwachstellen, Dockerfile-Fehlkonfigurationen und Compose-Fehlkonfigurationen. Wenn `--fail-on` unter dem angeforderten `--severity` liegt, wird die Scan-Schwere automatisch erweitert, damit das Gate diese Findings erfassen kann. ### Unvollständige Scans Wenn ein Scanner nicht ausgeführt werden kann, können in den Ergebnissen Findings fehlen, statt dass sie wirklich sauber sind. DockSec meldet dies als Erkennungslücke im Coverage-Block und in `--json` unter `scan_info.completeness`. Verwende `--incomplete-policy fail`, um in diesem Fall mit `3` zu beenden, sodass CI nicht mit einem Scan durchlaufen kann, der nicht abgeschlossen wurde:```bash docksec Dockerfile --incomplete-policy fail ``` ### Priorität: Was zuerst behoben werden sollte Jeder CVE-Fund wird gegen [EPSS](https://www.first.org/epss/) bewertet, das die Wahrscheinlichkeit schätzt, dass er in den nächsten 30 Tagen ausgenutzt wird. Kombiniert mit dem Schweregrad ergibt das vier Stufen: | Stufe | Bedeutung | |---|---| | **Sofort beheben** | Kritischer oder hoher Schweregrad und unter den Top 10 % der CVEs nach Ausnutzungswahrscheinlichkeit | | **Bald beheben** | Kritischer oder hoher Schweregrad, aber Ausnutzung ist weniger verbreitet | | **Überwachen** | Geringerer Schweregrad, aber aktiv ausgenutzt | | **Niedrige Priorität** | Geringerer Schweregrad, Ausnutzung ungewöhnlich | Dies ist der einzige Netzwerkaufruf, den DockSec außerhalb des KI-Durchlaufs macht, und er ist bewusst eng gefasst: **Es werden nur CVE-IDs gesendet** – keine Image-Namen, keine Dateiinhalte, keine Pfade. Bewertungen werden 24 Stunden lang zwischengespeichert. `--offline` und `--no-epss` deaktivieren ihn, und jeder Fehler fällt auf eine reine Schweregrad-basierte Rangfolge zurück, anstatt den Scan fehlschlagen zu lassen. ### Exploit-Ketten Eine Ansicht pro Dienst meldet Befunde einzeln. DockSec meldet auch, wo separate Befunde zu einem einzigen Angriffspfad kombiniert werden:```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. ``` Die Chain-Erkennung ist regelbasiert und funktioniert daher mit `--scan-only`, offline und ohne API-Schlüssel und liefert bei jedem Durchlauf dasselbe Ergebnis. Der AI-Durchlauf rankt und erweitert sie, statt für sie erforderlich zu sein. Chains erscheinen ebenfalls in `--json` unter `exploit_chains`. Siehe den [exploit chains guide](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) für die vollständige Liste und die [compose rule reference](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) für jede Regel, die sie kombinieren. ### Fix commands Scans enden mit konkreten Befehlen statt mit einer Liste von Identifikatoren und einer einfachen Angabe, wie viele Findings sie beheben:```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. ``` ### Maschinenlesbare Ausgabe `--json` gibt ein einzelnes JSON-Objekt an stdout aus (Scan-Informationen, Schwachstellen, Schweregrad-Zählungen und alle KI-Funde) anstelle der menschenlesbaren Zusammenfassung, sodass es direkt in andere Tools weitergeleitet werden kann:```bash docksec -i myapp:latest --image-only --json | jq '.severity_counts' ``` Mit `--json` allein werden keine Report-Dateien geschrieben; kombiniere es mit `--format`, um Dateien zu schreiben und JSON im selben Lauf auszugeben. Alle für Menschen lesbaren Meldungen wandern im `--json`-Modus nach stderr, sodass stdout ausschließlich die JSON-Nutzlast enthält. ### Report-Formate `--format` akzeptiert eine kommagetrennte Liste von Dateiausgaben: | Format | Was du bekommst | |--------|----------------| | `json` | Eine `.json`-Datei mit Scan-Metadaten, Schweregrad-Zählungen und der vollständigen Schwachstellenliste (gleiche Struktur wie die `--json`-stdout-Nutzlast, aber auf die Festplatte geschrieben). | | `csv` | Eine `.csv`-Tabelle der Befunde (ID, Schweregrad, Paket, Version, Titel und verwandte Felder). | | `pdf` | Eine druckbare PDF-Zusammenfassung mit Scan-Infos, Bewertungen und Schwachstellendetails. | | `html` | Ein gestylter HTML-Report zum Durchsuchen der Ergebnisse im Browser. | | `markdown` | Ein `.md`-Report, der nativ in Pull-Request-Kommentaren und CI-Job-Zusammenfassungen gerendert wird. Opt-in: wird nur geschrieben, wenn angefordert. | `json`, `csv`, `pdf` und `html` werden standardmäßig geschrieben; füge `markdown` explizit hinzu, um es zu erhalten. **CSV mit null Befunden:** Wenn ein Scan keine Schwachstellen meldet, aber `csv` in deiner `--format`-Liste steht, schreibt DockSec trotzdem eine CSV-Datei, die nur die Spaltenüberschriften enthält. Das ist beabsichtigt (der Export ist gültig, kein fehlgeschlagener Schreibvorgang), damit nachgelagerte Tools sich auch bei sauberen Scans auf ein stabiles Schema verlassen können. Für stdout-JSON und das Weiterleiten in andere Tools siehe [Maschinenlesbare Ausgabe](#machine-readable-output) oben. Für CI und GitHub Code Scanning verwende `--sarif` (siehe den nächsten Abschnitt); SARIF ist getrennt von `--format` und wird immer ausgegeben, wenn es angefordert wird. ### SARIF-Ausgabe für GitHub Code Scanning `--sarif` schreibt einen SARIF 2.1.0-Report zusammen mit den anderen Report-Formaten. Lade ihn mit der Standard-Action `github/codeql-action/upload-sarif` hoch, um Befunde direkt in Pull Requests und im Security-Tab annotiert zu sehen:```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 es wird der Upload-Schritt übersprungen, wann immer > `--fail-on` dazu führt, dass DockSec mit einem Nicht-Null-Code beendet wird, wodurch die Findings genau dann verloren gehen, wenn sie am wichtigsten sind. ### Baseline- / Ratchet-Modus `--baseline FILE` ermöglicht es dir, `--fail-on` in einem bestehenden Projekt zu übernehmen, ohne dass eine Wand von bereits vorhandenen Findings jeden Build blockiert. Führe einmal `--update-baseline` aus, um die heutigen Findings zu erfassen, und committe dann die Baseline-Datei; von da an beschränkt `--fail-on` nur noch auf Findings, die nicht bereits 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 werden anhand von Schwachstellen-ID, Ziel und Paketname abgeglichen, sodass die Baseline gültig bleibt, wenn nicht zusammenhängende Findings auftauchen und wieder verschwinden. Führen Sie die Ausführung mit `--update-baseline` erneut aus, wann immer Sie den aktuellen Zustand als neue Baseline akzeptieren möchten. ### Ignorieren von Findings (Waiver) `--ignore-file FILE` unterdrückt einzelne Findings, die ein Team triagiert und akzeptiert hat. Anders als die Baseline (eine Momentaufnahme) ist die Ignore-Datei eine explizite, überprüfbare Liste, in der jeder Eintrag einen Grund und ein optionales Ablaufdatum enthält. Wenn eine `.docksec-ignore.yml`-Datei im aktuellen Verzeichnis existiert, wird sie automatisch übernommen.```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 Begründung werden markiert, damit Ausnahmen nachvollziehbar 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, visuell ansprechender Web-Bericht: Schweregrad-Karten, Score-Bewertung, vollständige Schwachstellentabelle mit behobenen Versionen und die vollständigen KI-Befunde. - **pdf**: Ein portables, präsentationsfertiges Dokument. - **json**: Vollständige, maschinenlesbare Scan-Daten (gleiche Struktur wie die `--json`-stdout-Ausgabe). - **csv**: Eine tabellenkalkulationsfertige Tabelle einzelner Schwachstellen. - **markdown**: Ein leichtgewichtiger, lesbarer Bericht (Schweregrad-Zusammenfassung + Schwachstellentabelle mit behobenen Versionen), der nativ in Pull-Request-Kommentaren und CI-Job-Zusammenfassungen gerendert wird. Opt-in: Fügen Sie `markdown` zu `--format` hinzu; standardmäßig wird es nicht geschrieben. > Hinweis zum CSV-Verhalten: Bei null Schwachstellen schreibt DockSec dennoch eine CSV mit > nur Kopfzeile (Spaltennamen, keine Zeilen), damit nachgelagerte Automatisierung niemals > aufgrund einer fehlenden oder leeren Datei abbricht. Dies ist beabsichtigt. ### CycloneDX SBOM `--sbom` schreibt eine CycloneDX-Software-Stückliste (`<image>.cdx.json`) des gescannten Images, die jede Paketkomponente sowie bekannte Schwachstellen auflistet. Die BOM wird vom nativen Exporter von Trivy erzeugt (ist also spezifikationskonform) und DockSec stempelt sich selbst in die Tool-Metadaten ein. Speisen Sie sie in Dependency-Track, den Dependency-Graph von GitHub oder jeden anderen SBOM-Konsumenten ein:```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 Ihren Rechner verlässt: - **Das Scannen ist vollständig lokal.** Trivy, Hadolint und die Sicherheitsbewertung laufen auf Ihrem Rechner. Image-Inhalte werden von DockSec niemals irgendwohin hochgeladen. - **Die KI-Analyse sendet nur die gescannte Datei.** Wenn der KI-Durchlauf ausgeführt wird, wird der Inhalt der Dockerfile- oder Compose-Datei (plus einer kurzen Zusammenfassung der Schwachstellenanzahl für die Bewertung) an den von Ihnen konfigurierten LLM-Anbieter gesendet. Nichts anderes wird übertragen. - **Secrets werden vor dem Versenden unkenntlich gemacht.** Werte, die wie Secrets aussehen (Passwörter, Tokens, API-Schlüssel, Private-Key-Blöcke), werden in der Datei maskiert, bevor der Inhalt an den KI-Anbieter gesendet wird. Schlüsselnamen bleiben sichtbar, damit offengelegte Anmeldedaten weiterhin gekennzeichnet werden. Verwenden Sie `--no-redact`, um dies zu deaktivieren. - **Vollständig lokale KI wird unterstützt.** Verwenden Sie `--provider ollama`, um die KI-Analyse auf Ihrer eigenen Hardware zu belassen, oder `--scan-only` / `--offline`, um die KI vollständig zu überspringen. - **Keine Telemetrie.** DockSec sammelt keine Nutzungsdaten und telefoniert nach Hause zu nichts. ### Offline-Modus `--offline` führt einen Scan ohne Netzwerkzugriff aus. Es verwendet die Trivy-Schwachstellendatenbank, die bereits auf der Festplatte liegt (kein DB-Update), und überspringt die KI-Analyse sowie den erweiterten Docker-Scout-Scan, die beide Netzwerk erfordern. Dies ist die einfachste Möglichkeit, in einer air-gapped oder abgeschotteten Umgebung zu scannen:```bash docksec --image-only -i myapp:latest --offline ``` Stelle sicher, dass die Trivy-DB mindestens einmal heruntergeladen wurde (jeder vorherige Online-Scan erledigt dies), bevor du dich auf `--offline` verlässt. ### Scan-Ergebnis-Cache Image-Scan-Ergebnisse werden zwischengespeichert (Standard: 24 Stunden, überschreibbar mit `DOCSEC_CACHE_TTL_HOURS`) und nach dem Content-Digest des Images verschlüsselt, sodass ein neu gebauter Tag wie ein wiederverwendetes `:latest` immer einen frischen Scan erhält. Verwende `--no-cache` (oder `DOCSEC_USE_CACHE=false`), um den Cache für einen Lauf zu umgehen. ### Images pullen, die nicht lokal vorhanden sind Beim Scannen eines Images, das nicht lokal vorhanden ist, wird es zuerst gepullt. Ein Compose-Stack benennt routinemäßig Images, die die Maschine noch nie gepullt hat, und ohne dies wird jeder dieser Dienste als nicht gescannt gemeldet. Setze `DOCSEC_PULL_MISSING_IMAGES=false`, um dies zu deaktivieren und stattdessen fehlzuschlagen, was sich bei einer getakteten Verbindung oder einem gemeinsam genutzten Runner lohnt. `--offline` pullt niemals, unabhängig von dieser Einstellung. --- ## KI-Assistenten-Skills (`install-skill`) `docksec install-skill` schreibt DockSec-Nutzungsanweisungen in die bekannten Kontextdateien für beliebte KI-Coding-Assistenten, damit ein Assistent, der in deinem Repo arbeitet, weiß, wie DockSec aufgerufen wird:```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 reiner Text, den du überprüfen und committen kannst; es wird nichts ausgeführt. Ein erneutes Ausführen des Befehls aktualisiert den DockSec-Abschnitt an Ort und Stelle, anstatt ihn zu duplizieren. --- ## Funktionen - **Intelligente 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**: Geheimwerte 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. - **Sicherheitsbewertung**: Eine Punktzahl von 0-100 mit einer Bewertung, um deine Sicherheitslage im Laufe der Zeit zu verfolgen. - **Umfangreiche Formate**: HTML (interaktiv), PDF, JSON, CSV, SARIF und CycloneDX SBOM. - **CI/CD-bereit**: `--fail-on`-Exit-Codes, Baseline-/Ratchet-Modus, auditierbare Waiver, JSON-to-stdout und eine GitHub Action im Marketplace. - **Offline-Modus**: Vollständig air-gapped scannen (`--offline`) unter Verwendung der lokalen Trivy-Datenbank. - **KI-Assistenten-Skills**: `docksec install-skill` bringt Claude Code, Cursor, Copilot und anderen bei, wie sie DockSec in deinem Repo ausführen. --- ## Wie DockSec abschneidet | Fähigkeit | DockSec | Trivy (eigenständig) | Snyk Container | Aikido | |---|---|---|---|---| | Lizenz und Kosten | Kostenlos, Open Source (MIT) | Kostenlos, Open Source (Apache 2.0) | Kommerziell (begrenzter kostenloser Tarif) | Kommerziell (begrenzter kostenloser Tarif) | | Governance | OWASP Lab Project, anbieterneutral | Open Source, gepflegt von Aqua | Einzelner Anbieter | Einzelner Anbieter | | Erkennt CVEs und Dockerfile-Fehlkonfigurationen | Ja | Ja | Ja | Ja | | Erklärt Befunde in verständlichem Englisch | Ja (KI-verfasster Kontext und Auswirkung) | Nein (rohe CVE-Daten) | Teilweise (Schweregrad und Fix-Hinweise) | Teilweise (KI-Zusammenfassungen in der Plattform) | | Kontextbezogene Dockerfile-Behebung | Ja (spezifische Umschreibungen mit Erklärung) | Nein (nur Erkennung) | Ja (Empfehlung zum Basis-Image-Upgrade, Fix-PRs) | Ja (KI-AutoFix-PRs) | | Docker Compose (Multi-Service) Scanning | Ja (Orchestrierungsprüfungen und Scan pro Dienst) | Teilweise (Konfigurationsscan, kein Fan-out pro Dienst) | Teilweise | Teilweise | | Baseline-/Ratchet-Modus (nur bei neuen Befunden fehlschlagen) | Ja | Nein | Teilweise (Plattformrichtlinien) | Teilweise (Plattformrichtlinien) | | Auditierbare Waiver pro Befund mit Begründungen und Ablauf | Ja | Teilweise (.trivyignore, keine Begründungen erzwungen) | Teilweise (Plattformrichtlinien) | Teilweise (Plattformrichtlinien) | | CI-native Ausgabe (SARIF für GitHub Code Scanning) | Ja | Ja | Ja | Ja | | SBOM-Export (CycloneDX) | Ja (`--sbom`) | Ja | Ja | Ja | | Installation von KI-Assistenten-Skills (Claude Code, Cursor, Copilot) | Ja (`install-skill`) | Nein | Nein | Nein | | Läuft vollständig offline / air-gapped | Ja (lokales LLM über Ollama, Scan-Only-Modus, kein API-Schlüssel) | Nur Scannen (keine Behebungsebene) | Nein (Cloud-Plattform) | Nein (gehostete Plattform) | | Deine Image-Daten bleiben in deinem Netzwerk | Ja | Ja | Nein | Nein | | Eigenes LLM / Modellwahl mitbringen | Ja (OpenAI, Anthropic, Gemini oder lokales Ollama) | Nicht zutreffend | Nein (proprietäre KI) | Nein (proprietäre KI) | | Selbst hostbar, kein Plattform-Deployment | Ja | Ja | Nein | Nein | | Anbieterbindung | Keine | Keine | Ja | Ja | | Sicherheitsbewertung (0-100) und Berichte in mehreren Formaten | Ja | Teilweise (Maschinenformate, kein Behebungsbericht) | Teilweise (Dashboard-Berichte) | Teilweise (Dashboard-Berichte) | DockSec ist das einzige dieser Tools, das kontextbezogene Dockerfile-Behebung mit einem vollständig quelloffenen, von OWASP verwalteten und lokal ausführbaren Design kombiniert. Snyk und Aikido bieten fähige KI-Behebung, aber nur als kommerzielle Cloud-Plattformen, die deine Daten an ihren Dienst senden. Trivy ist Open Source und lokal, bleibt aber bei der Erkennung stehen und hilft dir nicht, etwas zu beheben. DockSec schließt die Lücke für Entwickler und für regulierte oder air-gapped Teams, die sowohl die Fix-Anleitung als auch die volle Kontrolle über ihre Daten benötigen, und das kostenlos. --- ## Fixes automatisch anwenden `--fix` wendet die mechanische Teilmenge der vorgeschlagenen Dockerfile-Änderungen an, scannt erneut und meldet das Delta:```bash docksec Dockerfile --scan-only --fix --dry-run # print the diff, change nothing docksec Dockerfile --scan-only --fix # apply, keeping a .bak ``` | `-s` | `--server` | Server URL (default: `http://localhost:8080`) | | `-t` | `--token` | API token for authentication | | `-o` | `--output` | Output format: `json`, `yaml`, `table` (default: `table`) | | `-v` | `--verbose` | Enable verbose output | | `-q` | `--quiet` | Suppress non-essential output | | `--no-color` | | Disable colored output | | `--timeout` | | Request timeout in seconds (default: `30`) | ### Beispiele ```bash # Standardverbindung kitploit-cli scan --target example.com # Mit Authentifizierung kitploit-cli scan --target example.com --token $API_TOKEN # JSON-Ausgabe kitploit-cli scan --target example.com --output json # Ausführlicher Modus kitploit-cli scan --target example.com --verbose ``` ## Konfiguration Die Konfigurationsdatei befindet sich unter `~/.config/kitploit/config.yaml`: ```yaml server: http://localhost:8080 token: your-api-token output: table timeout: 30 ``` ### Umgebungsvariablen | Variable | Beschreibung | |----------|-------------| | `KITPLOIT_SERVER` | Server-URL | | `KITPLOIT_TOKEN` | API-Token | | `KITPLOIT_OUTPUT` | Ausgabeformat | | `KITPLOIT_TIMEOUT` | Timeout in Sekunden | ## Exit-Codes | Code | Beschreibung | |------|-------------| | `0` | Erfolg | | `1` | Allgemeiner Fehler | | `2` | Ungültige Argumente | | `3` | Authentifizierungsfehler | | `4` | Verbindungsfehler | | `5` | Timeout | ## Entwicklung ### Voraussetzungen - Go 1.21 oder höher - Make - Docker (optional) ### Build ```bash # Abhängigkeiten installieren make deps # Binärdatei erstellen make build # Tests ausführen make test # Alle Plattformen erstellen make release ``` ### Projektstruktur ``` kitploit-cli/ ├── cmd/ │ ├── root.go │ ├── scan.go │ └── version.go ├── internal/ │ ├── api/ │ │ ├── client.go │ │ └── types.go │ ├── config/ │ │ └── config.go │ └── output/ │ ├── json.go │ ├── table.go │ └── yaml.go ├── main.go ├── go.mod ├── go.sum ├── Makefile └── README.md ``` ## Beitragen 1. Repository forken 2. Feature-Branch erstellen (`git checkout -b feature/amazing-feature`) 3. Änderungen committen (`git commit -m 'Add amazing feature'`) 4. Branch pushen (`git push origin feature/amazing-feature`) 5. Pull Request öffnen ## Lizenz Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe [LICENSE](https://github.com/owasp/docksec/blob/main/LICENSE) für Details. ## Danksagungen - [Kitploit](https://www.kitploit.com/) für die Bereitstellung der Plattform - Alle Mitwirkenden und Tester ## Support - Dokumentation: [https://docs.kitploit.com](https://docs.kitploit.com) - Issues: [https://github.com/kitploit/kitploit-cli/issues](https://github.com/kitploit/kitploit-cli/issues) - Diskussionen: [https://github.com/kitploit/kitploit-cli/discussions](https://github.com/kitploit/kitploit-cli/discussions)```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) ``` Es ist bewusst konservativ. Es wird keine Basis-Image-Version auswählen, kein Secret verschieben, kein `ADD`, das eine URL abruft oder ein Archiv entpackt, umwandeln oder eine Compose-Datei bearbeiten – diese werden stattdessen unter „Needs review“ gemeldet. Es weigert sich außerdem, eine Datei mit nicht committeten Änderungen zu bearbeiten, es sei denn, `--force` wird angegeben, sodass git stets in der Lage ist, die Änderung rückgängig zu machen. ## Dokumentation | Leitfaden | Was er abdeckt | | --- | --- | | [Evaluierungsleitfaden](https://github.com/owasp/docksec/blob/main/docs/evaluation-guide.md) | 15-minütige Bewertung, einschließlich dessen, was DockSec *nicht* tut | | [Exploit-Ketten](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) | Dienstübergreifende Angriffspfade und ihre Grenzen | | [Compose-Regelreferenz](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) | Alle 17 Regeln: was jede erkennt und wann es sinnvoll ist, sie beizubehalten | | [CI-Integration](https://github.com/owasp/docksec/blob/main/docs/ci/README.md) | Jenkins, GitLab, Azure Pipelines, pre-commit | | [Beispiele](https://github.com/owasp/docksec/blob/main/examples/README.md) | Zehn Dockerfiles und Compose-Stacks mit ihren erwarteten Befunden | | [Fallstudien](https://github.com/owasp/docksec/blob/main/docs/case-studies/README.md) | Echte Scans offizieller Images, mit den Zahlen | ## Roadmap Siehe [ROADMAP.md](https://github.com/owasp/docksec/blob/main/ROADMAP.md) für die Richtung, in die sich DockSec entwickelt: Registry-Scanning ohne lokalen Docker-Daemon, eine Policy-Konfigurationsdatei auf Repo-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 den [Issues](https://github.com/OWASP/DockSec/issues) und auf [OWASP Slack](https://owasp.slack.com/archives/C0APXGCUW7M). --- ## Mitwirken DockSec lebt von Beiträgen aus der Community. Ob Sie Entwickler, Designer oder Sicherheitsenthusiast sind, es gibt viele Möglichkeiten, sich einzubringen: - **Code-Beiträge**: Fehler beheben oder neue Funktionen hinzufügen. - **Dokumentation**: Leitfäden verbessern oder Tutorials erstellen. - **Issue-Meldungen**: Fehler identifizieren und melden. - **Feedback**: Teilen Sie Ihre Erfahrungen und Vorschläge. Um loszulegen, schauen Sie sich unsere [Contributing Guidelines](https://github.com/owasp/docksec/blob/main/CONTRIBUTING.md), den [Code of Conduct](https://github.com/owasp/docksec/blob/main/CODE_OF_CONDUCT.md) und den [Sponsorship Guide](https://github.com/owasp/docksec/blob/main/SPONSORSHIP.md) an. --- ## Leitung und Community DockSec wird von einem engagierten Team geleitet, das sich dafür einsetzt, Container-Sicherheit zugänglich zu machen: - [Advait Patel](https://github.com/advaitpatel) - Projektleitung - [Arkadii Yakovets](https://github.com/arkid15r) - Co-Projektleitung Hier finden Sie uns: - **OWASP-Projektseite**: [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/) - **Issues**: [Fehler melden](https://github.com/OWASP/DockSec/issues) - **Changelog**: [CHANGELOG.md](https://github.com/owasp/docksec/blob/main/CHANGELOG.md) --- <div align="center"> <strong>Wenn DockSec Ihnen hilft, geben Sie dem Repo einen Stern, damit andere es entdecken können.</strong><br> Entwickelt von <a href="https://github.com/advaitpatel">Advait Patel</a> und der OWASP-Community. </div>
