### 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

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

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

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

---

## 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

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

### 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.

### 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'

> `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

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

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

| `-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

server: http://localhost:8080
token: your-api-token
output: table
timeout: 30

# Abhängigkeiten installieren
make deps

# Binärdatei erstellen
make build

# Tests ausführen
make test

# Alle Plattformen erstellen
make release

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

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>