owasp/docksecScanner de sécurité Docker alimenté par l'IA qui explique les vulnérabilités en langage clair. Un projet de laboratoire OWASP.
<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/) **Scanner de sécurité Docker propulsé par l'IA qui explique les vulnérabilités en langage clair** </div> --- ## Qu'est-ce que DockSec ? DockSec est un **projet OWASP Lab** qui comble le fossé entre les résultats complexes des scanners de sécurité et les correctifs exploitables par les développeurs. Il intègre des scanners standards de l'industrie (Trivy, Hadolint, Docker Scout) avec l'IA pour fournir une **analyse de sécurité contextuelle**. Au lieu de vous submerger avec une liste de plus de 200 CVE, DockSec : - **Priorise** ce qui affecte réellement votre configuration de conteneur spécifique. - **Explique** les vulnérabilités en langage clair, pas seulement en 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 (secrets masqués) envoyé au fournisseur d'IA que vous choisissez - et avec un modèle local ou le mode scan-only, rien ne quitte votre machine. Voir [Flux de données et confidentialité](#data-flow-and-privacy). --- ## Comment ça fonctionne <div align="center"> <img src="https://assets.kitploit.com/production/public/readmes/39487/99b4247f599cc8f7a260f285815f8793ca4d2c050ea6656480818a846d590fb0.png" alt="DockSec Workflow" width="800"> <p><em>Flux de travail DockSec : de l'analyse aux informations exploitables</em></p> </div> DockSec suit un pipeline en cinq étapes : 1. **Scan** : Exécute Trivy (vulnérabilités d'images et mauvaise configuration de Dockerfile), Hadolint et Docker Scout localement sur votre environnement. 2. **Prioriser** : Classe chaque résultat CVE par gravité combinée à sa probabilité d'exploitation [EPSS](https://www.first.org/epss/), afin que la liste soit ordonnée par ce qu'il faut corriger en premier plutôt que par ce qui a été trouvé en premier. 3. **Corréler** : Détecte les [chaînes d'exploitation](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) où des résultats distincts se combinent en un seul chemin d'attaque - une base de données avec identifiants qu'un service exposé sur Internet peut atteindre est une chaîne, pas deux résultats sans rapport. Avec une clé API, une passe d'IA raisonne sur la sortie complète du scan pour classer, expliquer et étendre cela. 4. **Recommander** : Produit des commandes de correction à copier-coller et des modifications concrètes de Dockerfile ou de compose, et indique combien de résultats elles résolvent. 5. **Rapport** : Exporte les résultats exploitables en HTML, PDF, JSON, CSV, Markdown, SARIF et CycloneDX SBOM. --- ## Pour commencer ### 1. Prérequis DockSec orchestre des scanners locaux, il nécessite donc : | Exigence | Nécessaire pour | Installation | |---|---|---| | Python 3.12+ | DockSec lui-même | [python.org](https://www.python.org/downloads/) | | Trivy | Toutes les analyses (requis) | `brew install trivy` ou [Trivy docs](https://trivy.dev/latest/getting-started/installation/) | | Hadolint | Linting de Dockerfile | `brew install hadolint` ou [Hadolint docs](https://github.com/hadolint/hadolint#install) | | Docker | Analyses d'images (`-i`) | [Docker docs](https://docs.docker.com/get-docker/) | 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 n'est nécessaire pour un 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 commande suivante 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, et 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 pertinent (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 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 automatiquement masquées. Voir [Flux de données et confidentialité](#data-flow-and-privacy). ### 5. Ou exécuter l'image de conteneur (rien à installer) L'image publiée intègre des versions épinglées de Trivy et Hadolint, il n'y a donc rien à installer et rien à configurer :```bash docker run --rm -v "$PWD:/github/workspace" \ -e INPUT_DOCKERFILE=Dockerfile \ -e INPUT_SCAN_ONLY=true \ ghcr.io/owasp/docksec:latest ``` Publié en multi-arch (amd64 et arm64) à chaque release. Épinglez une version spécifique (`ghcr.io/owasp/docksec:2026.9.21`) ou une série mineure (`ghcr.io/owasp/docksec:2026.9`) plutôt que `latest` en CI. Chaque image porte une attestation de provenance de build :```bash gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec ``` L'image lit les mêmes variables `INPUT_*` que la GitHub Action, donc toute entrée d'Action fonctionne ici : `INPUT_IMAGE`, `INPUT_COMPOSE`, `INPUT_SEVERITY`, `INPUT_FAIL_ON`, `INPUT_FORMAT`, `INPUT_SARIF`, `INPUT_OUTPUT_DIR`. Écrivez les rapports quelque part sur le montage pour les conserver après la sortie du conteneur :```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. Ou utilisez la GitHub Action```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 # 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 ``` --- ## Fichier de configuration Validez un `.docksec.yml` à la racine de votre dépôt et toute l'équipe - ainsi que chaque job CI - analyse selon 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 est remplacé par la variable d'environnement puis par la valeur par défaut intégrée. Un exemple complet annoté se trouve dans [`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/examples/.docksec.yml). ### Priorité Priorité la plus élevée en premier :``` CLI flag > environment variable > .docksec.yml > built-in default ``` Un `severity: LOW` commité est donc toujours surchargé par `--severity CRITICAL` sur la ligne de commande, et par `DOCKSEC_DEFAULT_SEVERITY` dans l'environnement. ### Découverte DockSec recherche `.docksec.yml` (ou `.docksec.yaml`) dans le répertoire de travail puis remonte jusqu'à la racine du dépôt, de sorte qu'un service dans un sous-répertoire d'un monorepo hérite de la politique commitée au niveau supérieur. La recherche s'arrête au répertoire contenant `.git`, afin de ne jamais récupérer un fichier en dehors du dépôt. - `--config FILE` utilise un fichier spécifique au lieu de rechercher. - `--no-config` ignore tout fichier de configuration, pour des exécutions CI reproductibles. Le fichier de configuration en vigueur est affiché dans la bannière de scan, il est donc toujours clair quelle politique a été appliquée. ### Paramètres | Paramètre | Option équivalente | Notes | | --- | --- | --- | | `severity` | `--severity` | Niveaux de sévérité pour le scan de l'image | | `fail_on` | `--fail-on` | Seuil de déclenchement CI | | `formats` | `--format` | Forme 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` | Obsolète et ignoré ; le scoring est toujours déterministe | | `no_redact` | `--no-redact` | Ne pas masquer les secrets avant l'appel à l'IA | | `no_cache` | `--no-cache` | Contourner le cache de scan | | `ignore_file` | `--ignore-file` | Chemin du fichier de dérogation | | `baseline` | `--baseline` | Chemin du fichier de référence | | `rules.disabled` | - | ID de règles à désactiver entièrement | Un fichier de configuration invalide - une clé inconnue, une sévérité incorrecte - est une erreur fatale qui se termine avec le code `2` plutôt qu'un avertissement, afin qu'un fichier de politique défectueux ne puisse jamais provoquer l'exécution d'un scan sous des règles que l'équipe n'a pas commitées. ### Autocomplétion de l'éditeur Le commentaire `# yaml-language-server:` sur la première ligne fournit la complétion et la validation en ligne dans VS Code et les éditeurs JetBrains. Le schéma est publié à l'adresse [`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/main/docs/docksec-config-schema.json) et peut être régénéré avec `docksec --print-config-schema`. ### Désactivation de règles `rules.disabled` désactive entièrement une vérification, partout - elle est supprimée avant le scoring, les rapports, `--json` et le seuil `--fail-on`. Utilisez-la pour les vérifications qui ne s'appliquent pas à votre environnement. Pour les constats individuels que votre équipe a triés et acceptés, préférez le [fichier de dérogation](#ignoring-findings-waivers), dont les entrées portent une raison et une date d'expiration et restent donc auditables. --- ## Intégration CI/CD ### Codes de sortie DockSec utilise des codes de sortie adaptés à la CI afin que les builds et les shells puissent réagir aux résultats : | Code | Signification | |---|---| | `0` | Succès, aucun constat égal ou supérieur à `--fail-on` | | `1` | Constats égaux ou supérieurs au seuil `--fail-on` | | `2` | Erreur d'utilisation ou d'argument | | `3` | Erreur d'outil ou d'exécution (scan échoué, image introuvable, outils manquants) | `--fail-on` filtre sur chaque constat structuré : vulnérabilités d'image, erreurs de configuration du Dockerfile et erreurs de configuration de compose. Lorsque `--fail-on` est inférieur à la `--severity` demandée, la sévérité du scan est automatiquement élargie afin que le seuil puisse observer ces constats. ### Scans incomplets Si un scanner ne peut pas s'exécuter, les résultats peuvent manquer de constats plutôt que d'être réellement propres. DockSec le signale comme une lacune de détection dans le bloc Coverage et dans `--json` sous `scan_info.completeness`. Utilisez `--incomplete-policy fail` pour sortir avec le code `3` dans ce cas, afin que la CI ne puisse pas valider un scan qui ne s'est pas terminé :```bash docksec Dockerfile --incomplete-policy fail ``` ### Priorité : quoi corriger en premier Chaque résultat de CVE est évalué par rapport à [EPSS](https://www.first.org/epss/), qui estime la probabilité qu'il soit exploité dans les 30 prochains jours. En combinant cela avec la sévérité, on obtient quatre niveaux : | Niveau | Signification | |---|---| | **À corriger maintenant** | Sévérité critique ou élevée, et dans le top 10 % des CVE par probabilité d'exploitation | | **À corriger bientôt** | Sévérité critique ou élevée, mais l'exploitation est moins courante | | **À surveiller** | Sévérité plus faible, mais activement exploité | | **Priorité faible** | Sévérité plus faible, exploitation peu courante | C'est le seul appel réseau que DockSec effectue en dehors de la passe IA, et il est délibérément restreint : **seuls les identifiants CVE sont envoyés** - aucun nom d'image, aucun contenu de fichier, aucun chemin. Les scores sont mis en cache pendant 24 heures. `--offline` et `--no-epss` le désactivent, et toute défaillance revient à un classement par sévérité uniquement plutôt que de faire échouer l'analyse. ### Chaînes d'exploitation Une vue par service rapporte les résultats un par un. DockSec rapporte également les cas où des résultats distincts se combinent en un seul chemin d'attaque :```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. ``` La détection de chaînes est basée sur des règles, elle fonctionne donc avec `--scan-only`, hors ligne et sans clé API, et renvoie la même réponse à chaque exécution. La passe IA les classe et les étend plutôt que d'être nécessaire. Les chaînes apparaissent également dans `--json` sous `exploit_chains`. Consultez le [guide des chaînes d'exploitation](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) pour la liste complète et la [référence des règles de composition](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) pour chaque règle qu'elles combinent. ### Commandes de correction Les scans se terminent par des commandes concrètes plutôt qu'une liste d'identifiants, et par un énoncé clair du nombre de résultats qu'elles résolvent :```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. ``` ### Sortie lisible par machine `--json` affiche un seul objet JSON sur stdout (informations de scan, vulnérabilités, comptages de sévérité et toute découverte IA) au lieu du résumé lisible par l'humain, afin qu'il puisse être redirigé directement vers 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 redirigés vers stderr en mode `--json`, de sorte que stdout ne contient jamais que la charge utile JSON. ### Formats de rapport `--format` accepte une liste de sorties de fichiers séparées par des virgules : | Format | Ce que vous obtenez | |--------|----------------| | `json` | Un fichier `.json` avec les métadonnées du scan, le décompte des sévérités et la liste complète des vulnérabilités (même structure que la charge utile stdout de `--json`, mais écrite sur disque). | | `csv` | Un tableau `.csv` des résultats (ID, sévérité, paquet, version, titre et champs associés). | | `pdf` | Un résumé PDF imprimable avec les informations du scan, les scores et les détails des vulnérabilités. | | `html` | Un rapport HTML stylisé pour parcourir les résultats dans un navigateur. | | `markdown` | Un rapport `.md` qui s'affiche nativement dans les commentaires de pull request et les résumés de jobs CI. Optionnel : non écrit sauf si demandé. | `json`, `csv`, `pdf` et `html` sont écrits par défaut ; ajoutez `markdown` explicitement pour l'obtenir. **CSV sans aucun résultat :** si un scan ne signale aucune vulnérabilité mais que `csv` figure dans votre liste `--format`, DockSec écrit tout de même un fichier CSV ne contenant que les en-têtes de colonnes. C'est intentionnel (l'export est valide, ce n'est pas une écriture échouée) afin que les outils en aval puissent s'appuyer sur un schéma stable même sur des scans propres. Pour le JSON sur stdout et le piping vers d'autres outils, voir [Sortie lisible par machine](#machine-readable-output) ci-dessus. Pour la CI et GitHub Code Scanning, utilisez `--sarif` (voir la section suivante) ; SARIF est distinct de `--format` et est toujours émis lorsqu'il est demandé. ### Sortie SARIF pour GitHub Code Scanning `--sarif` écrit un rapport SARIF 2.1.0 aux côtés des autres formats de rapport. Téléversez-le avec l'action standard `github/codeql-action/upload-sarif` pour voir les résultats annotés directement sur les pull requests et dans l'onglet Security :```yaml - name: Run DockSec uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' sarif: 'true' - name: Upload SARIF to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: ~/.docksec/results ``` > `if: always()` est important : sans cela, l'étape d'upload est ignorée dès que > `--fail-on` fait sortir DockSec avec un code non nul, perdant les résultats exactement au moment > où ils comptent le plus. ### Mode baseline / ratchet `--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 une fois avec `--update-baseline` pour capturer les résultats actuels, puis committez le fichier de baseline ; à partir de là, `--fail-on` ne filtre que les 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 résultats sont mis en correspondance par ID de vulnérabilité, cible et nom de paquet, de sorte que la référence reste valide à mesure que des résultats non liés apparaissent et disparaissent. Relancez avec `--update-baseline` chaque fois que vous souhaitez accepter l'état actuel comme nouvelle référence. ### Ignorer des résultats (dérogations) `--ignore-file FILE` supprime des résultats individuels qu'une équipe a triés et acceptés. Contrairement à la référence (un instantané ponctuel), le fichier d'ignorance est une liste explicite et vérifiable où chaque entrée porte 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 résultats supprimés sont retirés avant la notation, les rapports, la sortie `--json` et le seuil `--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. Validez le fichier dans le contrôle de version pour que les suppressions soient examinées comme toute autre modification. --- ## Rapports ### Formats de rapport Par défaut, chaque analyse écrit quatre fichiers de rapport ; utilisez `--format` pour choisir un sous-ensemble : - **html** : Un rapport web interactif et visuellement épuré : cartes de gravité, évaluation du score, tableau complet des vulnérabilités avec versions corrigées, et l'intégralité des résultats 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 structure que la sortie stdout `--json`). - **csv** : Un tableau prêt pour tableur des vulnérabilités individuelles. - **markdown** : Un rapport léger et lisible (résumé de gravité + tableau des vulnérabilités avec versions corrigées) qui s'affiche nativement dans les commentaires de pull request et les résumés de jobs CI. Optionnel : ajoutez `markdown` à `--format` ; il n'est pas écrit par défaut. > Note sur le comportement CSV : avec zéro vulnérabilité, DockSec écrit tout de 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. ### SBOM CycloneDX `--sbom` écrit une nomenclature logicielle CycloneDX (`<image>.cdx.json`) de l'image analysée, listant chaque composant de paquet ainsi que les vulnérabilités connues. La BOM est produite par l'exportateur natif de Trivy (elle est donc conforme à la spécification) et DockSec s'inscrit lui-même dans les métadonnées de l'outil. Alimentez 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`), il est donc 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 téléversé où que ce soit par DockSec. - **L'analyse IA n'envoie que le fichier analysé.** Lorsque la passe IA s'exécute, le contenu du Dockerfile ou du fichier compose (plus un bref résumé du nombre de vulnérabilités pour le scoring) est envoyé au fournisseur LLM que vous avez configuré. Rien d'autre n'est transmis. - **Les secrets sont masqués avant de quitter la machine.** Les valeurs ressemblant à des secrets (mots de passe, jetons, clés API, blocs de clés privées) dans le fichier sont masquées avant que le contenu ne soit envoyé au fournisseur IA. Les noms de clés restent visibles afin que les identifiants exposés soient toujours signalés. Utilisez `--no-redact` pour désactiver ce comportement. - **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 communique avec rien. ### 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 ainsi que l'analyse avancée Docker Scout, qui nécessitent toutes deux un accès 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 (n'importe quelle 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, modifiable avec `DOCSEC_CACHE_TTL_HOURS`) et indexés par le digest du contenu de l'image, de sorte qu'un tag reconstruit tel qu'un `:latest` réutilisé obtient toujours une analyse fraîche. Utilisez `--no-cache` (ou `DOCSEC_USE_CACHE=false`) pour contourner le cache pendant une exécution. ### Récupération des images qui ne sont pas locales L'analyse d'une image qui n'est pas présente localement la récupère d'abord. Une pile compose nomme régulièrement des images que la machine n'a jamais récupérées, et sans cela chacun de ces services est signalé comme non analysé. Définissez `DOCSEC_PULL_MISSING_IMAGES=false` pour désactiver cela et échouer à la place, ce qui vaut la peine d'être fait sur une connexion limitée ou un runner partagé. `--offline` ne récupère jamais, quel que soit ce paramètre. --- ## Compétences d'assistant 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 ``` Cela 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) Les fichiers sont en texte brut, que vous pouvez consulter et committer ; rien n'est exécuté. Relancer la commande met à jour la section DockSec sur 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 des modèles locaux via Ollama. - **Confidentialité avant tout** : les valeurs des secrets sont masquées avant que tout contenu n'atteigne un fournisseur d'IA, l'analyse est entièrement locale, et il n'y a aucune télémétrie. - **Analyse de Docker Compose** : détectez les erreurs de configuration au niveau de l'orchestration et analysez tous les services d'un fichier compose. - **Intégration poussée** : combine Trivy (vulnérabilités), Hadolint (linting) et Docker Scout. - **Score de sécurité** : un score de 0 à 100 avec une note pour suivre votre posture de sécurité dans le temps. - **Formats riches** : HTML (interactif), PDF, JSON, CSV, SARIF et SBOM CycloneDX. - **Prêt pour la 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** : analysez entièrement en air-gapped (`--offline`) en utilisant la base de données Trivy locale. - **Compétences pour assistants IA** : `docksec install-skill` apprend à Claude Code, Cursor, Copilot et autres comment exécuter DockSec dans votre dépôt. --- ## Comparaison de DockSec | Capacité | DockSec | Trivy (autonome) | Snyk Container | Aikido | |---|---|---|---|---| | Licence et coût | Gratuit, open source (MIT) | Gratuit, open source (Apache 2.0) | Commercial (offre gratuite limitée) | Commercial (offre gratuite limitée) | | Gouvernance | Projet OWASP Lab, neutre vis-à-vis des fournisseurs | Open source, maintenu par Aqua | Fournisseur unique | Fournisseur unique | | Détecte les CVE et les erreurs de configuration des Dockerfile | Oui | Oui | Oui | Oui | | Explique les résultats en langage clair | Oui (contexte et impact rédigés par IA) | Non (données CVE brutes) | Partiel (indices de sévérité et de correction) | Partiel (résumés IA dans la plateforme) | | Remédiation contextuelle des Dockerfile | Oui (réécritures spécifiques avec explication) | Non (détection uniquement) | Oui (conseils de mise à niveau de l'image de base, PR de correction) | Oui (PR AutoFix par IA) | | Analyse de Docker Compose (multi-services) | Oui (vérifications d'orchestration et analyse par service) | Partiel (analyse de configuration, pas de répartition par service) | Partiel | Partiel | | Mode baseline / ratchet (échouer uniquement sur les nouveaux résultats) | Oui | Non | Partiel (politiques de plateforme) | Partiel (politiques de plateforme) | | Dérogations auditables par résultat avec raisons et expiration | Oui | Partiel (.trivyignore, aucune raison imposée) | Partiel (politiques de plateforme) | Partiel (politiques de plateforme) | | Sortie native CI (SARIF pour GitHub Code Scanning) | Oui | Oui | Oui | Oui | | Export SBOM (CycloneDX) | Oui (`--sbom`) | Oui | Oui | Oui | | Installation de compétence pour assistant IA (Claude Code, Cursor, Copilot) | Oui (`install-skill`) | Non | Non | Non | | Fonctionne entièrement hors ligne / air-gapped | Oui (LLM local via Ollama, mode analyse seule, aucune clé API) | Analyse uniquement (pas de couche de remédiation) | Non (plateforme cloud) | Non (plateforme hébergée) | | Les données de votre image restent sur votre réseau | Oui | Oui | Non | Non | | Apportez votre propre LLM / choix du modèle | Oui (OpenAI, Anthropic, Gemini, ou Ollama local) | Non applicable | Non (IA propriétaire) | Non (IA propriétaire) | | Auto-hébergeable, sans déploiement de plateforme | Oui | Oui | Non | Non | | Verrouillage fournisseur | Aucun | Aucun | Oui | Oui | | Score de sécurité (0-100) et rapports multi-formats | Oui | Partiel (formats machine, pas de rapport de remédiation) | Partiel (rapports de tableau de bord) | Partiel (rapports de tableau de bord) | DockSec est le seul de ces outils à associer une remédiation contextuelle des Dockerfile à une conception entièrement open source, gouvernée par l'OWASP et exécutable localement. Snyk et Aikido proposent une remédiation IA performante, mais uniquement en tant que 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 à rien corriger. DockSec comble le vide pour les développeurs et pour les équipes réglementées ou air-gapped qui ont besoin à la fois des conseils de correction et du contrôle total de leurs données, sans frais. --- ## Application automatique des corrections `--fix` applique le sous-ensemble mécanique des modifications de Dockerfile suggérées, relance l'analyse et rapporte le delta :```bash docksec Dockerfile --scan-only --fix --dry-run # print the diff, change nothing docksec Dockerfile --scan-only --fix # apply, keeping a .bak ``` ## Outils de sécurité - [**Nuclei**](https://github.com/projectdiscovery/nuclei) - Scanner de vulnérabilités rapide et personnalisable basé sur des modèles. - [**Amass**](https://github.com/OWASP/Amass) - Cartographie des surfaces d'attaque réseau et découverte de ressources externes. - [**httpx**](https://github.com/projectdiscovery/httpx) - Boîte à outils HTTP rapide et multi-usage. - [**Subfinder**](https://github.com/projectdiscovery/subfinder) - Outil de découverte de sous-domaines. - [**Naabu**](https://github.com/projectdiscovery/naabu) - Scanner de ports rapide axé sur la fiabilité. - [**Katana**](https://github.com/projectdiscovery/katana) - Framework de crawling et de spidering de nouvelle génération. - [**dnsx**](https://github.com/projectdiscovery/dnsx) - Boîte à outils DNS rapide et multi-usage. - [**tlsx**](https://github.com/projectdiscovery/tlsx) - Boîte à outils TLS rapide et multi-usage. - [**cloudlist**](https://github.com/projectdiscovery/cloudlist) - Outil de listage des ressources cloud multi-fournisseurs. - [**notify**](https://github.com/projectdiscovery/notify) - Utilitaire de distribution de sortie vers plusieurs plateformes. - [**interactsh**](https://github.com/projectdiscovery/interactsh) - Client OOB pour la collecte d'interactions. - [**proxify**](https://github.com/projectdiscovery/proxify) - Proxy HTTP/SOCKS5 multi-usage et enregistreur de trafic. - [**uncover**](https://github.com/projectdiscovery/uncover) - Découverte rapide d'hôtes exposés sur Internet via des moteurs de recherche. - [**shuffledns**](https://github.com/projectdiscovery/shuffledns) - Wrapper autour de massdns pour la résolution de noms de domaine. - [**mapcidr**](https://github.com/projectdiscovery/mapcidr) - Utilitaire pour effectuer des opérations sur des blocs CIDR. - [**cdncheck**](https://github.com/projectdiscovery/cdncheck) - Utilitaire pour identifier les technologies CDN et WAF. - [**asnmap**](https://github.com/projectdiscovery/asnmap) - Bibliothèque Go et CLI pour la cartographie des données ASN. - [**alterx**](https://github.com/projectdiscovery/alterx) - Générateur de noms de sous-domaines basé sur des modèles. - [**simplehttpserver**](https://github.com/projectdiscovery/simplehttpserver) - Serveur HTTP configurable en Go. - [**cvemap**](https://github.com/projectdiscovery/cvemap) - Navigateur de vulnérabilités et d'expositions courantes. - [**tldfinder**](https://github.com/projectdiscovery/tldfinder) - Découverte de domaines et de TLD. - [**urlfinder**](https://github.com/projectdiscovery/urlfinder) - Extraction d'URL à partir de sources passives. - [**chaos**](https://github.com/projectdiscovery/chaos-client) - Client Go pour accéder au jeu de données Chaos. - [**pdtm**](https://github.com/projectdiscovery/pdtm) - Gestionnaire d'outils ProjectDiscovery.```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) ``` Il est délibérément conservateur. Il ne choisira pas de version d'image de base, ne déplacera pas de secret, ne convertira pas un `ADD` qui récupère une URL ou décompresse une archive, et ne modifiera pas de fichier compose - ceux-ci sont signalés sous « Needs review » à la place. Il refuse également de modifier un fichier avec des changements non commités sauf si `--force` est fourni, afin que git soit toujours en mesure d'annuler la modification. ## Documentation | Guide | Ce qu'il couvre | | --- | --- | | [Guide d'évaluation](https://github.com/owasp/docksec/blob/main/docs/evaluation-guide.md) | Évaluation en 15 minutes, y compris ce que DockSec ne fait *pas* | | [Chaînes d'exploitation](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) | Chemins d'attaque inter-services, et leurs limites | | [Référence des règles Compose](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) | Les 17 règles : ce que chacune détecte, et quand la conserver est raisonnable | | [Intégration CI](https://github.com/owasp/docksec/blob/main/docs/ci/README.md) | Jenkins, GitLab, Azure Pipelines, pre-commit | | [Exemples](https://github.com/owasp/docksec/blob/main/examples/README.md) | Dix Dockerfiles et stacks compose avec leurs résultats attendus | | [Études de cas](https://github.com/owasp/docksec/blob/main/docs/case-studies/README.md) | Analyses réelles d'images officielles, avec les chiffres | ## Feuille de route Voir [ROADMAP.md](https://github.com/owasp/docksec/blob/main/ROADMAP.md) pour savoir où DockSec se dirige : analyse de registre sans démon Docker local, fichier de configuration de politique au niveau du dépôt, modèles Jenkins/GitLab/Azure DevOps, image de conteneur officielle, analyse Kubernetes et Helm, et plus encore. Les retours et votes sur les priorités sont les bienvenus dans les [issues](https://github.com/OWASP/DockSec/issues) et sur [OWASP Slack](https://owasp.slack.com/archives/C0APXGCUW7M). --- ## Contribuer 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 vous impliquer : - **Contributions au code** : Corrigez des bugs ou ajoutez de nouvelles fonctionnalités. - **Documentation** : Améliorez les guides ou créez des tutoriels. - **Signalement de problèmes** : Identifiez et signalez les bugs. - **Retours** : Partagez votre expérience et vos suggestions. Pour commencer, consultez nos [Directives de contribution](https://github.com/owasp/docksec/blob/main/CONTRIBUTING.md), notre [Code de conduite](https://github.com/owasp/docksec/blob/main/CODE_OF_CONDUCT.md) et notre [Guide de parrainage](https://github.com/owasp/docksec/blob/main/SPONSORSHIP.md). --- ## Responsables et communauté DockSec est dirigé par une équipe dédiée à rendre la sécurité des conteneurs accessible : - [Advait Patel](https://github.com/advaitpatel) - Responsable du projet - [Arkadii Yakovets](https://github.com/arkid15r) - Co-responsable du projet Retrouvez-nous ici : - **Page du projet OWASP** : [owasp.org/DockSec/](https://owasp.org/DockSec/) - **OWASP Slack** : [#project-docksec](https://owasp.slack.com/archives/C0APXGCUW7M) - **PyPI** : [pypi.org/project/docksec/](https://pypi.org/project/docksec/) - **Issues** : [Signaler un bug](https://github.com/OWASP/DockSec/issues) - **Changelog** : [CHANGELOG.md](https://github.com/owasp/docksec/blob/main/CHANGELOG.md) --- <div align="center"> <strong>Si DockSec vous aide, mettez une étoile au dépôt pour aider les autres à le découvrir.</strong><br> Créé par <a href="https://github.com/advaitpatel">Advait Patel</a> et la communauté OWASP. </div>
