owasp/docksecEscáner de seguridad de Docker impulsado por IA que explica las vulnerabilidades en un lenguaje sencillo. Un proyecto de laboratorio de 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/) **Escáner de seguridad Docker impulsado por IA que explica las vulnerabilidades en lenguaje sencillo** </div> --- ## ¿Qué es DockSec? DockSec es un **Proyecto de Laboratorio de OWASP** que tiende un puente entre los complejos resultados de los escaneos de seguridad y las correcciones prácticas para los desarrolladores. Integra escáneres estándar de la industria (Trivy, Hadolint, Docker Scout) con IA para proporcionar **análisis de seguridad consciente del contexto**. En lugar de abrumarte con una lista de más de 200 CVE, DockSec: - **Prioriza** lo que realmente afecta a tu configuración específica de contenedores. - **Explica** las vulnerabilidades en lenguaje sencillo, no solo con jerga de seguridad. - **Sugiere** correcciones específicas para tu Dockerfile. - **Genera** informes de seguridad profesionales e interactivos para tu equipo. Todo se escanea localmente; lo único que sale de tu máquina es el contenido del archivo (con secretos censurados) enviado al proveedor de IA que elijas, y con un modelo local o el modo de solo escaneo, no sale nada en absoluto. Consulta [Flujo de datos y privacidad](#data-flow-and-privacy). --- ## Cómo funciona <div align="center"> <img src="https://assets.kitploit.com/production/public/readmes/39487/99b4247f599cc8f7a260f285815f8793ca4d2c050ea6656480818a846d590fb0.png" alt="DockSec Workflow" width="800"> <p><em>Flujo de trabajo de DockSec: del escaneo a información procesable</em></p> </div> DockSec sigue un flujo de cinco etapas: 1. **Escanear**: Ejecuta Trivy (vulnerabilidades de imágenes y configuraciones incorrectas de Dockerfile), Hadolint y Docker Scout localmente en tu entorno. 2. **Priorizar**: Clasifica cada hallazgo de CVE por gravedad combinada con su probabilidad de explotación [EPSS](https://www.first.org/epss/), de modo que la lista se ordena por lo que hay que corregir primero en lugar de por lo que se encontró primero. 3. **Correlacionar**: Detecta [cadenas de explotación](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) donde hallazgos separados se combinan en una única ruta de ataque: una base de datos con credenciales a la que puede acceder un servicio expuesto a internet es una cadena, no dos hallazgos no relacionados. Con una clave de API, una pasada de IA razona sobre la salida completa del escaneo para clasificar, explicar y ampliar esto. 4. **Recomendar**: Produce comandos de corrección para copiar y ejecutar y cambios concretos en el Dockerfile o en el compose, e indica cuántos hallazgos resuelven. 5. **Informar**: Exporta resultados procesables como HTML, PDF, JSON, CSV, Markdown, SARIF y CycloneDX SBOM. --- ## Primeros pasos ### 1. Requisitos previos DockSec orquesta escáneres locales, por lo que necesita: | Requisito | Necesario para | Instalación | |---|---|---| | Python 3.12+ | DockSec en sí | [python.org](https://www.python.org/downloads/) | | Trivy | Todos los escaneos (obligatorio) | `brew install trivy` o [Trivy docs](https://trivy.dev/latest/getting-started/installation/) | | Hadolint | Linting de Dockerfile | `brew install hadolint` o [Hadolint docs](https://github.com/hadolint/hadolint#install) | | Docker | Escaneos de imágenes (`-i`) | [Docker docs](https://docs.docker.com/get-docker/) | O deja que DockSec instale Trivy y Hadolint por ti:```bash python -m docksec.setup_external_tools ``` ### 2. Instalar 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. Ejecuta tu primer escaneo No se necesita clave API para el escaneo local:```bash docksec Dockerfile --scan-only ``` Cada escaneo termina con un resumen de resultados: una tabla de severidad, una puntuación de seguridad de 0 a 100 con una calificación, un bloque de acción "Quick take", los informes generados (guardados en `~/.docksec/results/` por defecto), y un comando siguiente sugerido. ### 4. Habilitar el análisis de IA El análisis de IA explica los hallazgos y sugiere correcciones. Elige un proveedor, configura su clave de API y ejecuta:```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 ``` Cada proveedor tiene un modelo predeterminado razonable (OpenAI: `gpt-4o`, Anthropic: `claude-haiku-4-5`, Google: `gemini-1.5-pro`, Ollama: `llama3.1`), por lo que `--model` es opcional. Para evitar repetir flags, establece variables de entorno (o colócalas en un archivo `.env` en el directorio desde el que ejecutas - DockSec lo carga automáticamente):```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile ``` Antes de que se envíe cualquier contenido a un proveedor de IA, los valores que parecen secretos (contraseñas, tokens, claves de API, bloques de claves privadas) se enmascaran automáticamente. Consulta [Flujo de datos y privacidad](#data-flow-and-privacy). ### 5. O ejecuta la imagen del contenedor (nada que instalar) La imagen publicada incluye versiones fijadas de Trivy y Hadolint, por lo que no hay nada que instalar ni nada que configurar:```bash docker run --rm -v "$PWD:/github/workspace" \ -e INPUT_DOCKERFILE=Dockerfile \ -e INPUT_SCAN_ONLY=true \ ghcr.io/owasp/docksec:latest ``` Publicado multi-arquitectura (amd64 y arm64) en cada release. Fija una versión específica (`ghcr.io/owasp/docksec:2026.9.21`) o una serie menor (`ghcr.io/owasp/docksec:2026.9`) en lugar de `latest` en CI. Cada imagen incluye una atestación de procedencia de compilación:```bash gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec ``` La imagen lee las mismas variables `INPUT_*` que la GitHub Action, por lo que cualquier entrada de la Action funciona aquí: `INPUT_IMAGE`, `INPUT_COMPOSE`, `INPUT_SEVERITY`, `INPUT_FAIL_ON`, `INPUT_FORMAT`, `INPUT_SARIF`, `INPUT_OUTPUT_DIR`. Escribe los informes en algún lugar del montaje para conservarlos después de que el contenedor finalice:```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. O usa la GitHub Action```yaml - name: Run DockSec AI Scanner uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' openai_api_key: ${{ secrets.OPENAI_API_KEY }} ``` --- ## Comandos comunes```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 ``` --- ## Archivo de configuración Confirma un `.docksec.yml` en la raíz de tu repositorio y todo el equipo - y cada trabajo de CI - escanea bajo la misma política, en lugar de que cada desarrollador pase sus propias banderas.```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 ``` Cada ajuste es opcional; cualquier valor que omita recurre a la variable de entorno y luego al valor predeterminado integrado. En [`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/examples/.docksec.yml) se encuentra un ejemplo completo anotado. ### Precedencia Mayor prioridad primero:``` CLI flag > environment variable > .docksec.yml > built-in default ``` Así, un `severity: LOW` confirmado sigue siendo anulado por `--severity CRITICAL` en la línea de comandos, y por `DOCKSEC_DEFAULT_SEVERITY` en el entorno. ### Descubrimiento DockSec busca `.docksec.yml` (o `.docksec.yaml`) en el directorio de trabajo y luego sube hasta la raíz del repositorio, de modo que un servicio en un subdirectorio de un monorepo hereda la política confirmada en el nivel superior. La búsqueda se detiene en el directorio que contiene `.git`, por lo que nunca toma un archivo de fuera del repositorio. - `--config FILE` usa un archivo específico en lugar de buscar. - `--no-config` ignora cualquier archivo de configuración, para ejecuciones de CI reproducibles. El archivo de configuración en vigor se muestra en el banner del escaneo, por lo que siempre queda claro qué política se aplicó. ### Ajustes | Ajuste | Bandera equivalente | Notas | | --- | --- | --- | | `severity` | `--severity` | Niveles de severidad para el escaneo de la imagen | | `fail_on` | `--fail-on` | Umbral de la compuerta de CI | | `formats` | `--format` | Forma de lista: `[json, html]` | | `output_dir` | `--output-dir` | Destino del informe | | `provider` | `--provider` | `openai`, `anthropic`, `google`, `ollama` | | `model` | `--model` | Nombre del modelo para el proveedor | | `offline` | `--offline` | Sin red; omite la IA y Docker Scout | | `skip_ai_scoring` | `--skip-ai-scoring` | Obsoleto e ignorado; la puntuación siempre es determinista | | `no_redact` | `--no-redact` | No enmascarar secretos antes de la llamada a la IA | | `no_cache` | `--no-cache` | Omitir la caché de escaneo | | `ignore_file` | `--ignore-file` | Ruta del archivo de exenciones | | `baseline` | `--baseline` | Ruta del archivo de línea base | | `rules.disabled` | - | IDs de reglas para desactivar por completo | Un archivo de configuración inválido - una clave desconocida, una severidad incorrecta - es un error grave que sale con `2` en lugar de una advertencia, por lo que un archivo de política roto nunca puede provocar que un escaneo se ejecute bajo reglas que el equipo no confirmó. ### Autocompletado del editor El comentario `# yaml-language-server:` en la primera línea proporciona autocompletado y validación en línea en los editores VS Code y JetBrains. El esquema se publica en [`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/main/docs/docksec-config-schema.json) y se puede regenerar con `docksec --print-config-schema`. ### Desactivación de reglas `rules.disabled` desactiva una comprobación por completo, en todas partes - se elimina antes de la puntuación, los informes, `--json` y la compuerta `--fail-on`. Úsalo para comprobaciones que no se aplican a tu entorno. Para hallazgos individuales que tu equipo ha triado y aceptado, prefiere el [archivo de exenciones](#ignoring-findings-waivers), cuyas entradas llevan un motivo y una fecha de caducidad y por lo tanto siguen siendo auditables. --- ## Integración CI/CD ### Códigos de salida DockSec usa códigos de salida compatibles con CI para que las compilaciones y los shells puedan reaccionar a los resultados: | Código | Significado | |---|---| | `0` | Éxito, sin hallazgos en o por encima de `--fail-on` | | `1` | Hallazgos en o por encima del umbral `--fail-on` | | `2` | Error de uso o de argumentos | | `3` | Error de herramienta o de tiempo de ejecución (escaneo fallido, imagen no encontrada, herramientas faltantes) | `--fail-on` controla cada hallazgo estructurado: vulnerabilidades de la imagen, malas configuraciones del Dockerfile y malas configuraciones de compose. Cuando `--fail-on` está por debajo de la `--severity` solicitada, la severidad del escaneo se amplía automáticamente para que la compuerta pueda observar esos hallazgos. ### Escaneos incompletos Si un escáner no puede ejecutarse, los resultados pueden carecer de hallazgos en lugar de estar genuinamente limpios. DockSec informa eso como una brecha de detección en el bloque Coverage y en `--json` bajo `scan_info.completeness`. Usa `--incomplete-policy fail` para salir con `3` en ese caso, para que CI no pueda pasar en un escaneo que no terminó:```bash docksec Dockerfile --incomplete-policy fail ``` ### Prioridad: qué corregir primero Cada hallazgo de CVE se puntúa según [EPSS](https://www.first.org/epss/), que estima la probabilidad de que se explote en los próximos 30 días. Combinando eso con la severidad se obtienen cuatro niveles: | Nivel | Significado | |---|---| | **Corregir ahora** | Severidad crítica o alta, y en el top 10% de CVE por probabilidad de explotación | | **Corregir pronto** | Severidad crítica o alta, pero la explotación es menos común | | **Monitorizar** | Severidad más baja, pero explotado activamente | | **Baja prioridad** | Severidad más baja, explotación poco común | Esta es la única llamada de red que hace DockSec fuera de la pasada de IA, y es deliberadamente limitada: **solo se envían los ID de CVE** - sin nombres de imágenes, sin contenido de archivos, sin rutas. Las puntuaciones se almacenan en caché durante 24 horas. `--offline` y `--no-epss` lo desactivan, y cualquier fallo recurre a una clasificación basada solo en la severidad en lugar de hacer fallar el escaneo. ### Cadenas de explotación Una vista por servicio informa los hallazgos uno a uno. DockSec también informa dónde se combinan hallazgos separados en una única ruta de ataque:```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 detección de cadenas está basada en reglas, por lo que funciona con `--scan-only`, sin conexión y sin clave de API, y devuelve la misma respuesta en cada ejecución. La pasada de IA las clasifica y las amplía en lugar de ser necesaria para ello. Las cadenas también aparecen en `--json` bajo `exploit_chains`. Consulta la [guía de cadenas de explotación](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) para ver la lista completa y la [referencia de reglas de composición](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) para cada regla que combinan. ### Comandos de corrección Los escaneos terminan con comandos concretos en lugar de una lista de identificadores, y una declaración simple de cuántos hallazgos resuelven:```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. ``` ### Salida legible por máquina `--json` imprime un único objeto JSON en stdout (información del escaneo, vulnerabilidades, recuentos de severidad y cualquier hallazgo de IA) en lugar del resumen legible por humanos, por lo que puede canalizarse directamente a otras herramientas:```bash docksec -i myapp:latest --image-only --json | jq '.severity_counts' ``` Con `--json` solo, no se escriben archivos de informe; combínalo con `--format` para escribir archivos e imprimir JSON en la misma ejecución. Todos los mensajes legibles por humanos se mueven a stderr en modo `--json`, por lo que stdout solo contiene la carga útil JSON. ### Formatos de informe `--format` acepta una lista separada por comas de salidas de archivo: | Formato | Qué obtienes | |--------|----------------| | `json` | Un archivo `.json` con metadatos del escaneo, recuentos de severidad y la lista completa de vulnerabilidades (misma estructura que la carga útil de stdout de `--json`, pero escrita en disco). | | `csv` | Una tabla `.csv` de hallazgos (ID, severidad, paquete, versión, título y campos relacionados). | | `pdf` | Un resumen en PDF imprimible con información del escaneo, puntuaciones y detalles de vulnerabilidades. | | `html` | Un informe HTML con estilos para explorar los resultados en un navegador. | | `markdown` | Un informe `.md` que se renderiza de forma nativa en comentarios de pull request y resúmenes de trabajos de CI. Opcional: no se escribe a menos que se solicite. | `json`, `csv`, `pdf` y `html` se escriben por defecto; añade `markdown` explícitamente para obtenerlo. **CSV con cero hallazgos:** si un escaneo no reporta vulnerabilidades pero `csv` está en tu lista de `--format`, DockSec igualmente escribe un archivo CSV que contiene solo los encabezados de columna. Eso es intencional (la exportación es válida, no una escritura fallida) para que las herramientas posteriores puedan confiar en un esquema estable incluso en escaneos limpios. Para JSON en stdout y canalización a otras herramientas, consulta [Salida legible por máquina](#machine-readable-output) arriba. Para CI y GitHub Code Scanning, usa `--sarif` (consulta la siguiente sección); SARIF es independiente de `--format` y siempre se emite cuando se solicita. ### Salida SARIF para GitHub Code Scanning `--sarif` escribe un informe SARIF 2.1.0 junto con los demás formatos de informe. Súbelo con la acción estándar `github/codeql-action/upload-sarif` para ver los hallazgos anotados directamente en pull requests y en la pestaña 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()` es importante: sin él, el paso de subida se omite siempre que > `--fail-on` hace que DockSec salga con un código distinto de cero, perdiendo los hallazgos exactamente cuando > más importan. ### Modo baseline / ratchet `--baseline FILE` te permite adoptar `--fail-on` en un proyecto existente sin un muro de hallazgos preexistentes que bloqueen cada compilación. Ejecuta una vez con `--update-baseline` para capturar los hallazgos actuales, luego confirma el archivo baseline; a partir de entonces, `--fail-on` solo bloquea los hallazgos que no estén ya en el 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 ``` Los hallazgos se emparejan por ID de vulnerabilidad, objetivo y nombre de paquete, por lo que la línea base se mantiene válida a medida que aparecen y desaparecen hallazgos no relacionados. Vuelva a ejecutar con `--update-baseline` siempre que desee aceptar el estado actual como la nueva línea base. ### Ignorar hallazgos (exenciones) `--ignore-file FILE` suprime hallazgos individuales que un equipo ha triado y aceptado. A diferencia de la línea base (una instantánea puntual), el archivo de ignorados es una lista explícita y revisable donde cada entrada lleva un motivo y una fecha de caducidad opcional. Si existe un archivo `.docksec-ignore.yml` en el directorio actual, se detecta automáticamente.```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" ``` Los hallazgos suprimidos se eliminan antes del scoring, los informes, la salida `--json` y la puerta `--fail-on`. Las entradas caducadas dejan de aplicarse automáticamente (con una advertencia), y las entradas sin un motivo se marcan para que las exenciones sigan siendo auditables. Confirma el archivo en el control de versiones para que las supresiones se revisen como cualquier otro cambio. --- ## Informes ### Formatos de informe Por defecto, cada escaneo escribe cuatro archivos de informe; usa `--format` para elegir un subconjunto: - **html**: Un informe web interactivo y visualmente limpio: tarjetas de severidad, calificación de puntuación, tabla completa de vulnerabilidades con versiones corregidas y los hallazgos completos de la IA. - **pdf**: Un documento portátil y listo para presentaciones. - **json**: Datos de escaneo completos y legibles por máquina (misma estructura que la salida de `--json` por stdout). - **csv**: Una tabla de vulnerabilidades individuales lista para hoja de cálculo. - **markdown**: Un informe ligero y legible (resumen de severidad + tabla de vulnerabilidades con versiones corregidas) que se renderiza de forma nativa en los comentarios de pull requests y en los resúmenes de trabajos de CI. Opcional: añade `markdown` a `--format`; no se escribe por defecto. > Nota sobre el comportamiento de CSV: con cero vulnerabilidades, DockSec sigue escribiendo un > CSV solo con encabezado (nombres de columnas, sin filas) para que la automatización posterior nunca se rompa por un archivo > ausente o vacío. Esto es intencional. ### CycloneDX SBOM `--sbom` escribe un software bill of materials de CycloneDX (`<image>.cdx.json`) de la imagen escaneada, listando cada componente de paquete más las vulnerabilidades conocidas. El BOM es producido por el exportador nativo de Trivy (por lo que cumple con la especificación) y DockSec se registra a sí mismo en los metadatos de la herramienta. Aliméntalo a Dependency-Track, al gráfico de dependencias de GitHub o a cualquier otro consumidor de SBOM:```bash docksec --image-only -i myapp:latest --sbom ``` `--sbom` necesita una sola imagen (`-i`), por lo que se omite en las ejecuciones de compose. Al igual que `--sarif`, es independiente de `--format`. --- ## Flujo de datos y privacidad DockSec está diseñado para que siempre sepas qué sale de tu máquina: - **El escaneo es totalmente local.** Trivy, Hadolint y la puntuación de seguridad se ejecutan en tu máquina. DockSec nunca sube el contenido de las imágenes a ningún sitio. - **El análisis con IA solo envía el archivo escaneado.** Cuando se ejecuta la pasada de IA, el contenido del Dockerfile o del archivo compose (más un breve resumen de los recuentos de vulnerabilidades para la puntuación) se envía al proveedor de LLM que hayas configurado. No se transmite nada más. - **Los secretos se redactan antes de salir.** Los valores que parecen secretos (contraseñas, tokens, claves de API, bloques de claves privadas) en el archivo se enmascaran antes de que el contenido se envíe al proveedor de IA. Los nombres de las claves permanecen visibles para que las credenciales expuestas sigan siendo señaladas. Usa `--no-redact` para desactivar esto. - **Se admite IA totalmente local.** Usa `--provider ollama` para mantener el análisis de IA en tu propio hardware, o `--scan-only` / `--offline` para omitir la IA por completo. - **Sin telemetría.** DockSec no recopila datos de uso ni se conecta a nada. ### Modo sin conexión `--offline` ejecuta un escaneo sin acceso a la red. Usa la base de datos de vulnerabilidades de Trivy que ya está en disco (sin actualización de la BD) y omite el análisis de IA y el escaneo avanzado de Docker Scout, ambos de los cuales requieren red. Esta es la forma más sencilla de escanear en un entorno aislado o restringido:```bash docksec --image-only -i myapp:latest --offline ``` Asegúrate de que la base de datos de Trivy se haya descargado al menos una vez (cualquier escaneo en línea previo lo hace) antes de confiar en `--offline`. ### Caché de resultados de escaneo Los resultados de escaneo de imágenes se almacenan en caché (predeterminado: 24 horas, se puede sobrescribir con `DOCKSEC_CACHE_TTL_HOURS`) y se indexan por el digest del contenido de la imagen, por lo que una etiqueta reconstruida como un `:latest` reutilizado siempre obtiene un escaneo nuevo. Usa `--no-cache` (o `DOCKSEC_USE_CACHE=false`) para omitir la caché durante una ejecución. ### Descarga de imágenes que no son locales Escanear una imagen que no está presente localmente la descarga primero. Un stack de compose habitualmente nombra imágenes que la máquina nunca ha descargado, y sin esto cada uno de esos servicios se reporta como no escaneado. Establece `DOCKSEC_PULL_MISSING_IMAGES=false` para desactivar esto y fallar en su lugar, lo cual vale la pena hacer en una conexión medida o en un runner compartido. `--offline` nunca descarga, independientemente de esta configuración. --- ## Habilidades de asistente de IA (`install-skill`) `docksec install-skill` escribe las instrucciones de uso de DockSec en los archivos de contexto conocidos de los asistentes de codificación con IA más populares, para que un asistente que trabaje en tu repositorio sepa cómo invocar DockSec:```bash docksec install-skill ``` Esto crea o actualiza: - `.claude/commands/docksec.md` (comando de barra `/docksec` de Claude Code) - `.cursor/rules/docksec.mdc` (Cursor) - `AGENTS.md` (Codex CLI), `GEMINI.md` (Gemini CLI) - `.github/copilot-instructions.md` (GitHub Copilot) Los archivos son texto plano que puedes revisar y confirmar; no se ejecuta nada. Volver a ejecutar el comando actualiza la sección de DockSec en su lugar en vez de duplicarla. --- ## Características - **Análisis inteligente**: la IA explica qué significan las vulnerabilidades para *tu* configuración específica. - **Compatibilidad con múltiples LLM**: OpenAI, Anthropic Claude, Google Gemini o modelos locales mediante Ollama. - **Privacidad ante todo**: los valores de los secretos se redactan antes de que cualquier contenido llegue a un proveedor de IA, el escaneo es totalmente local y no hay telemetría. - **Escaneo de Docker Compose**: detecta configuraciones erróneas a nivel de orquestación y escanea todos los servicios de un archivo compose. - **Integración profunda**: combina Trivy (vulnerabilidades), Hadolint (linting) y Docker Scout. - **Puntuación de seguridad**: una puntuación de 0 a 100 con una calificación para hacer seguimiento de tu postura de seguridad a lo largo del tiempo. - **Formatos variados**: HTML (interactivo), PDF, JSON, CSV, SARIF y CycloneDX SBOM. - **Listo para CI/CD**: códigos de salida con `--fail-on`, modo baseline/ratchet, exenciones auditables, JSON a stdout y una GitHub Action en el Marketplace. - **Modo sin conexión**: escanea totalmente aislado de la red (`--offline`) usando la base de datos local de Trivy. - **Habilidades para asistentes de IA**: `docksec install-skill` enseña a Claude Code, Cursor, Copilot y otros cómo ejecutar DockSec en tu repositorio. --- ## Cómo se compara DockSec | Capacidad | DockSec | Trivy (independiente) | Snyk Container | Aikido | |---|---|---|---|---| | Licencia y coste | Gratis, código abierto (MIT) | Gratis, código abierto (Apache 2.0) | Comercial (nivel gratuito limitado) | Comercial (nivel gratuito limitado) | --- [Read more](https://github.com/owasp/docksec)
