DockSec

Scanner de sécurité Docker propulsé par l'IA qui explique les vulnérabilités en langage clair

Qu'est-ce que DockSec ?

DockSec est un projet de laboratoire OWASP qui comble le fossé entre des résultats d'analyse de sécurité complexes et des correctifs exploitables pour les développeurs. Il intègre des scanners standard de l'industrie (Trivy, Hadolint, Docker Scout) avec l'IA pour fournir une analyse de sécurité contextuelle.

Plutôt que de vous submerger avec une liste de plus de 200 CVE, DockSec :

• Priorise ce qui affecte réellement votre configuration conteneurisée spécifique.
• Explique les vulnérabilités en langage clair, pas seulement avec du jargon de sécurité.
• Suggère des correctifs spécifiques pour votre Dockerfile.
• Génère des rapports de sécurité professionnels et interactifs pour votre équipe.

Tout est analysé localement ; la seule chose qui quitte votre machine est le contenu du fichier (avec secrets masqués) envoyé au fournisseur d'IA que vous choisissez – et avec un modèle local ou un mode analyse uniquement, rien ne sort du tout. Voir Flux de données et confidentialité.

Comment ça fonctionne

Workflow DockSec : de l'analyse aux informations actionnables

DockSec suit un pipeline en quatre étapes :

1. Analyser : exécute Trivy, Hadolint et Docker Scout localement sur votre environnement.
2. Analyser : l'IA croise les résultats de tous les scanners pour éliminer le bruit et évaluer l'impact réel.
3. Recommander : génère des explications lisibles par l'humain et des étapes de remédiation spécifiques.
4. Rapporter : exporte des résultats actionnables en HTML, PDF, JSON, CSV, SARIF et SBOM CycloneDX.

Pour commencer

1. Prérequis

DockSec orchestre les scanners locaux, il a donc besoin de :

Ou laissez DockSec installer Trivy et Hadolint pour vous :```bash python -m docksec.setup_external_tools

### 2. Installer 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. Lancez votre premier scan

Aucune clé API requise pour le scan local:```bash docksec Dockerfile --scan-only

Chaque scan se termine par un résumé des résultats : un tableau de gravité, un score de sécurité de 0 à 100 avec une évaluation, un bloc d'action "Quick take", les rapports générés (enregistrés dans `~/.docksec/results/` par défaut) et une prochaine commande suggérée.

### 4. Activer l'analyse IA

L'analyse IA explique les résultats et suggère des correctifs. Choisissez un fournisseur, définissez sa clé API, puis exécutez :```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

Chaque fournisseur dispose d’un modèle par défaut raisonnable (OpenAI : gpt-4o, Anthropic : claude-haiku-4-5, Google : gemini-1.5-pro, Ollama : llama3.1), donc --model est facultatif. Pour éviter de répéter les options, définissez des variables d’environnement (ou placez-les dans un fichier .env dans le répertoire depuis lequel vous exécutez DockSec – il le charge automatiquement) :```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile

Avant que tout contenu ne soit envoyé à un fournisseur d'IA, les valeurs ressemblant à des secrets (mots de passe, jetons,
clés API, blocs de clés privées) sont masquées automatiquement. Voir
[Flux de données et confidentialité](#data-flow-and-privacy).

### 5. Ou utilisez l'action GitHub```yaml
- name: Run DockSec AI Scanner
  uses: OWASP/[email protected]
  with:
    dockerfile: 'Dockerfile'
    openai_api_key: ${{ secrets.OPENAI_API_KEY }}

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

---

## Fichier de configuration

Commitez un `.docksec.yml` à la racine de votre dépôt et toute l'équipe - et
chaque tâche CI - analyse sous la même politique, au lieu que chaque développeur
passe ses propres options.```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

Chaque paramètre est optionnel ; tout ce que vous omettez revient à la variable d'environnement et ensuite à la valeur par défaut intégrée. Un exemple complet annoté se trouve dans examples/.docksec.yml.

Priorité

Priorité la plus élevée d'abord :``` CLI flag > environment variable > .docksec.yml > built-in default

Ainsi, une `severity: LOW` présente dans le dépôt est toujours remplacée par `--severity CRITICAL` en ligne de commande, et par `DOCKSEC_DEFAULT_SEVERITY` dans l'environnement.

### Découverte

DockSec cherche `.docksec.yml` (ou `.docksec.yaml`) dans le répertoire de travail, puis remonte jusqu'à la racine du dépôt, afin qu'un service dans un sous-répertoire d'un monorepo hérite de la politique définie au niveau racine. La recherche s'arrête au répertoire contenant `.git`, et ne récupère donc jamais un fichier situé en dehors du dépôt.

- `--config FILE` utilise un fichier spécifique au lieu de chercher.
- `--no-config` ignore tout fichier de configuration, pour des exécutions CI reproductibles.

Le fichier de configuration en vigueur est affiché dans le bandeau d'analyse, afin qu'il soit toujours clair quelle politique a été appliquée.

### Paramètres

| Paramètre | Option équivalente | Notes |
| --- | --- | --- |
| `severity` | `--severity` | Niveaux de gravité pour l'analyse d'image |
| `fail_on` | `--fail-on` | Seuil CI |
| `formats` | `--format` | Forme de liste : `[json, html]` |
| `output_dir` | `--output-dir` | Destination du rapport |
| `provider` | `--provider` | `openai`, `anthropic`, `google`, `ollama` |
| `model` | `--model` | Nom du modèle pour le fournisseur |
| `offline` | `--offline` | Pas de réseau ; ignore l'IA et Docker Scout |
| `skip_ai_scoring` | `--skip-ai-scoring` | Évaluation locale uniquement |
| `no_redact` | `--no-redact` | Ne pas masquer les secrets avant l'appel à l'IA |
| `no_cache` | `--no-cache` | Ignorer le cache d'analyse |
| `ignore_file` | `--ignore-file` | Chemin du fichier de dérogation |
| `baseline` | `--baseline` | Chemin du fichier de référence |
| `rules.disabled` | - | Identifiants de règle à désactiver entièrement |

Un fichier de configuration invalide - une clé inconnue, une gravité invalide - est une erreur bloquante entraînant la sortie avec le code `2`, plutôt qu'un simple avertissement. Ainsi, un fichier de politique cassé ne peut jamais faire exécuter une analyse avec des règles que l'équipe n'a pas définies.

### Autocomplétion de l'éditeur

Le commentaire `# yaml-language-server:` sur la première ligne fournit l'autocomplétion et la validation dans l'éditeur dans VS Code et les éditeurs JetBrains. Le schéma est disponible dans [`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/HEAD/docs/docksec-config-schema.json) et peut être régénéré avec `docksec --print-config-schema`.

### Désactivation des règles

`rules.disabled` désactive entièrement une vérification, partout - elle est retirée avant l'évaluation, les rapports, `--json` et le critère `--fail-on`. Utilisez-la pour les vérifications qui ne s'appliquent pas à votre environnement. Pour des constatations individuelles que votre équipe a triées et acceptées, préférez le [fichier de dérogation](#ignoring-findings-waivers), dont les entrées comportent une raison et une date d'expiration et restent ainsi auditables.

---

## Intégration CI/CD

### Codes de sortie

DockSec utilise des codes de sortie adaptés au CI afin que les builds et les shells puissent réagir aux résultats :

| Code | Signification |
|---|---|
| `0` | Succès, aucune constatation de gravité égale ou supérieure à `--fail-on` |
| `1` | Constatations de gravité égale ou supérieure au seuil `--fail-on` |
| `2` | Erreur d'utilisation ou d'argument |
| `3` | Erreur d'outil ou d'exécution (échec de l'analyse, image introuvable, outils manquants) |

`--fail-on` se déclenche en fonction des constatations structurées (vulnérabilités d'image et mauvaises configurations de Compose). Lorsque `--fail-on` est inférieur au `--severity` demandé, la gravité de l'analyse est élargie automatiquement afin que le seuil puisse détecter ces constatations.

### Sortie lisible par machine

`--json` affiche un objet JSON unique sur stdout (informations d'analyse, vulnérabilités, compteurs de gravité et éventuelles constatations de l'IA) au lieu du résumé lisible par un humain, afin de pouvoir être directement transmis à d'autres outils :```bash
docksec -i myapp:latest --image-only --json | jq '.severity_counts'

Avec --json seul, aucun fichier de rapport n'est écrit ; combinez-le avec --format pour écrire des fichiers et afficher le JSON dans la même exécution. Tous les messages lisibles par l'humain sont déplacés vers stderr en mode --json, de sorte que stdout ne contient que la charge utile JSON.

Sortie SARIF pour l'analyse de code GitHub

--sarif écrit un rapport SARIF 2.1.0 en plus des autres formats de rapport. Téléversez-le avec l'action standard github/codeql-action/upload-sarif pour voir les constatations annotées directement sur les pull requests et dans l'onglet Sécurité :```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()` est important : sans lui, l'étape d'upload est ignorée chaque fois que
> `--fail-on` fait sortir DockSec avec un code non nul, perdant les résultats exactement quand ils
> comptent le plus.

### Mode baseline / cliquet

`--baseline FILE` vous permet d'adopter `--fail-on` sur un projet existant sans qu'un mur de
résultats préexistants ne bloque chaque build. Exécutez-le une fois avec `--update-baseline` pour prendre
un instantané des résultats actuels, puis validez le fichier baseline ; à partir de là, `--fail-on` ne s'applique qu'aux
résultats qui ne sont pas déjà dans la 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

Les findings sont appariés par identifiant de vulnérabilité, cible et nom de package, donc la ligne de base reste valide à mesure que des findings sans rapport apparaissent et disparaissent. Relancez avec --update-baseline dès que vous souhaitez accepter l'état actuel comme nouvelle ligne de base.

Ignorer les findings (dérogations)

--ignore-file FILE supprime les findings individuels qu'une équipe a triés et acceptés. Contrairement à la ligne de base (un instantané à un moment donné), le fichier d'ignorance est une liste explicite, consultable où chaque entrée comporte une raison et une date d'expiration facultative. Si un fichier .docksec-ignore.yml existe dans le répertoire courant, il est pris en compte automatiquement.```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"

Les constatations supprimées sont retirées avant le calcul du score, les rapports, la sortie `--json` et la
porte `--fail-on`. Les entrées expirées cessent de s’appliquer automatiquement (avec un avertissement), et
les entrées sans motif sont signalées afin que les dérogations restent auditables. Commitez le fichier dans
le contrôle de version afin que les suppressions soient examinées comme tout autre changement.

---

## Rapports

### Formats de rapport

Par défaut, chaque analyse écrit quatre fichiers de rapport ; utilisez `--format` pour en choisir un sous-ensemble :

- **html** : Un rapport web interactif et visuellement propre : cartes de sévérité, évaluation du score, tableau complet des vulnérabilités avec les versions corrigées, et l’intégralité des constatations de l’IA.
- **pdf** : Un document portable, prêt pour la présentation.
- **json** : Données d’analyse complètes et lisibles par machine (même forme que la sortie stdout de `--json`).
- **csv** : Un tableau de vulnérabilités individuelles prêt pour un tableur.

> Remarque sur le comportement du CSV : en cas de zéro vulnérabilité, DockSec écrit quand même un CSV
> avec uniquement l’en-tête (noms de colonnes, aucune ligne) afin que l’automatisation en aval ne casse
> jamais sur un fichier manquant ou vide. C’est intentionnel.

### CycloneDX SBOM

`--sbom` écrit une nomenclature logicielle CycloneDX (`<image>.cdx.json`) de
l’image analysée, répertoriant chaque composant de paquet ainsi que les vulnérabilités connues. La nomenclature est
produite par l’exportateur natif de Trivy (donc conforme à la spécification) et DockSec s’inscrit lui-même
dans les métadonnées de l’outil. Intégrez-la dans Dependency-Track, le graphe de dépendances de GitHub, ou
tout autre consommateur de SBOM :```bash
docksec --image-only -i myapp:latest --sbom

--sbom nécessite une seule image (-i), donc il est ignoré pour les exécutions compose. Comme --sarif, il est indépendant de --format.

Flux de données et confidentialité

DockSec est conçu pour que vous sachiez toujours ce qui quitte votre machine :

• L'analyse est entièrement locale. Trivy, Hadolint et le score de sécurité s'exécutent sur votre machine. Le contenu des images n'est jamais envoyé nulle part par DockSec.
• L'analyse IA n'envoie que le fichier analysé. Lorsque l'étape IA s'exécute, le contenu du Dockerfile ou du fichier compose (plus un court résumé du nombre de vulnérabilités pour le score) est envoyé au fournisseur de LLM que vous avez configuré. Rien d'autre n'est transmis.
• Les secrets sont masqués avant de quitter votre machine. Les valeurs ressemblant à des secrets (mots de passe, jetons, clés API, blocs de clés privées) du fichier sont masquées avant que le contenu soit envoyé au fournisseur IA. Les noms des clés restent visibles afin que les identifiants exposés soient toujours signalés. Utilisez --no-redact pour désactiver le masquage.
• L'IA entièrement locale est prise en charge. Utilisez --provider ollama pour garder l'analyse IA sur votre propre matériel, ou --scan-only / --offline pour ignorer complètement l'IA.
• Aucune télémétrie. DockSec ne collecte aucune donnée d'utilisation et ne contacte aucun serveur.

Mode hors ligne

--offline exécute une analyse sans accès réseau. Il utilise la base de données de vulnérabilités Trivy déjà présente sur le disque (aucune mise à jour de la base) et ignore l'analyse IA et l'analyse avancée Docker Scout, qui nécessitent toutes deux un réseau. C'est la façon la plus simple d'analyser dans un environnement isolé ou verrouillé :```bash docksec --image-only -i myapp:latest --offline

Assurez-vous que la base de données Trivy a été téléchargée au moins une fois (toute analyse en ligne antérieure le fait
avant de vous fier à `--offline`).

### Cache des résultats d'analyse

Les résultats d'analyse d'image sont mis en cache (par défaut : 24 heures, remplacez avec
`DOCKSEC_CACHE_TTL_HOURS`) et indexés par le condensé de contenu de l'image, de sorte qu'une balise reconstruite
telle qu'un `:latest` réutilisé obtienne toujours une nouvelle analyse. Utilisez `--no-cache` (ou
`DOCKSEC_USE_CACHE=false`) pour contourner le cache lors d'une exécution.

---

## Compétences pour assistants IA (`install-skill`)

`docksec install-skill` écrit les instructions d'utilisation de DockSec dans les fichiers de contexte bien connus
des assistants de codage IA populaires, afin qu'un assistant travaillant dans votre dépôt sache comment
invoquer DockSec :```bash
docksec install-skill

Ceci crée ou met à jour :

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

Ces fichiers sont en texte brut que vous pouvez relire et valider ; rien n'est exécuté. Relancer la commande met à jour la section DockSec en place au lieu de la dupliquer.

Fonctionnalités

• Analyse intelligente : l'IA explique ce que les vulnérabilités signifient pour votre configuration spécifique.
• Prise en charge multi-LLM : OpenAI, Anthropic Claude, Google Gemini, ou modèles locaux via Ollama.
• Confidentialité d'abord : les valeurs secrètes sont masquées avant que tout contenu n'atteigne un fournisseur d'IA, l'analyse est entièrement locale et il n'y a pas de télémétrie.
• Analyse Docker Compose : détecte les mauvaises configurations au niveau de l'orchestration et analyse tous les services d'un fichier compose.
• Intégration approfondie : combine Trivy (vulnérabilités), Hadolint (linting) et Docker Scout.
• Score de sécurité : un score de 0 à 100 avec une évaluation pour suivre votre posture de sécurité au fil du temps.
• Formats riches : HTML (interactif), PDF, JSON, CSV, SARIF et SBOM CycloneDX.
• Prêt pour CI/CD : codes de sortie --fail-on, mode baseline/ratchet, dérogations auditables, JSON vers stdout, et une GitHub Action sur le Marketplace.
• Mode hors ligne : analyse entièrement en environnement isolé (--offline) à l'aide de la base de données Trivy locale.
• Compétences pour assistants IA : docksec install-skill apprend à Claude Code, Cursor, Copilot et d'autres comment exécuter DockSec dans votre dépôt.

Comment DockSec se compare

DockSec est le seul de ces outils à associer une remédiation contextuelle des Dockerfile à une conception entièrement open source, régie par l'OWASP et exécutable localement. Snyk et Aikido proposent une remédiation IA efficace, mais uniquement sous forme de plateformes cloud commerciales qui envoient vos données à leur service. Trivy est open source et local mais s'arrête à la détection et ne vous aide pas à corriger quoi que ce soit. DockSec comble cette lacune pour les développeurs et pour les équipes réglementées ou en environnement isolé qui ont besoin à la fois de conseils de correction et d'un contrôle total de leurs données, sans aucun coût.

Feuille de route

Consultez ROADMAP.md pour voir où DockSec se dirige : analyse de registres sans démon Docker local, fichier de configuration de politiques au niveau du dépôt, modèles Jenkins/GitLab/Azure DevOps, image conteneur officielle, analyse Kubernetes et Helm, et plus encore. Les retours et les votes sur les priorités sont les bienvenus dans les issues et sur OWASP Slack.

Contribution

DockSec prospère grâce aux contributions de la communauté. Que vous soyez développeur, designer ou passionné de sécurité, il existe de nombreuses façons de participer :

• Contributions de code : corrigez des bogues ou ajoutez de nouvelles fonctionnalités.
• Documentation : améliorez les guides ou créez des tutoriels.
• Signalement de problèmes : identifiez et signalez des bogues.
• Retours : partagez votre expérience et vos suggestions.

Pour commencer, consultez nos Directives de contribution, notre Code de conduite et notre Guide de sponsoring.

Responsables et communauté

DockSec est dirigé par une équipe dévouée qui s'engage à rendre la sécurité des conteneurs accessible :

• Advait Patel - Responsable de projet
• Arkadii Yakovets - Co-responsable de projet

Retrouvez-nous ici :

• Page du projet OWASP: owasp.org/DockSec/
• OWASP Slack: #project-docksec
• PyPI: pypi.org/project/docksec/
• Issues: Signaler un bogue
• Changelog: CHANGELOG.md