DockSec

Escáner de seguridad de Docker impulsado por IA que explica las vulnerabilidades en lenguaje sencillo

¿Qué es DockSec?

DockSec es un Proyecto de Laboratorio de OWASP que cierra la brecha entre los resultados complejos 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 contextual.

En lugar de abrumarte con una lista de más de 200 CVEs, 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 los secretos redactados) que se envía 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.

Cómo funciona

DockSec sigue un proceso de cuatro etapas:

1. Escaneo: Ejecuta Trivy, Hadolint y Docker Scout localmente en tu entorno.
2. Análisis: La IA correlaciona los hallazgos de todos los escáneres para eliminar el ruido y evaluar el impacto en el mundo real.
3. Recomendación: Genera explicaciones legibles para humanos y pasos de remediación específicos.
4. Informe: Exporta resultados prácticos como HTML, PDF, JSON, CSV, SARIF y SBOM de CycloneDX.

Primeros pasos

1. Requisitos previos

DockSec orquesta escáneres locales, por lo que necesita:

O deja que DockSec instale Trivy y Hadolint por ti:```bash python -m docksec.setup_external_tools

3. Ejecuta tu primer escaneo

No se necesita clave API para el escaneo local:```bash docksec Dockerfile --scan-only

Cada proveedor tiene un modelo predeterminado sensato (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 banderas, 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

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

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

Cada ajuste es opcional; cualquier cosa que omitas recurre a la variable de entorno y luego al valor predeterminado integrado. Un ejemplo completo anotado está en examples/.docksec.yml.

Precedencia

Mayor prioridad primero:``` CLI flag > environment variable > .docksec.yml > built-in default

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 para humanos se mueven a stderr en el modo --json, por lo que stdout solo contiene la carga útil JSON.

Salida SARIF para GitHub Code Scanning

--sarif escribe un informe SARIF 2.1.0 junto con los otros formatos de informe. Súbelo con la acción estándar github/codeql-action/upload-sarif para ver los hallazgos anotados directamente en las 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

Los hallazgos se comparan por ID de vulnerabilidad, objetivo y nombre de paquete, por lo que la línea base sigue siendo válida a medida que aparecen y desaparecen hallazgos no relacionados. Vuelve a ejecutar con --update-baseline siempre que quieras aceptar el estado actual como la nueva línea base.

Ignorar hallazgos (exenciones)

--ignore-file FILE suprime hallazgos individuales que un equipo ha clasificado y aceptado. A diferencia de la línea base (una instantánea en un momento dado), el archivo de ignorados es una lista explícita y revisable donde cada entrada incluye un motivo y una fecha de caducidad opcional. Si existe un archivo .docksec-ignore.yml en el directorio actual, se recoge 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"

--sbom necesita una única 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 de IA envía solo el archivo escaneado. Cuando se ejecuta el paso 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 con aspecto de secreto (contraseñas, tokens, claves de API, bloques de claves privadas) del archivo se enmascaran antes de enviar el contenido al proveedor de IA. Los nombres de las claves permanecen visibles para que las credenciales expuestas sigan marcándose. Usa --no-redact para optar por no hacerlo.
• 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 y no se comunica con nada.

Modo sin conexión

--offline ejecuta un escaneo sin acceso a la red. Usa la base de datos de vulnerabilidades de Trivy ya presente en el disco (sin actualización de la base de datos) y omite el análisis de IA y el escaneo avanzado de Docker Scout, ambos 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

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 lugar de duplicarla.

Características

• Análisis inteligente: la IA explica qué significan las vulnerabilidades para tu configuración específica.
• Soporte multi-LLM: OpenAI, Anthropic Claude, Google Gemini o modelos locales mediante Ollama.
• Privacidad primero: los valores 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 incorrectas a nivel de orquestación y escanea todos los servicios en 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 enriquecidos: HTML (interactivo), PDF, JSON, CSV, SARIF y CycloneDX SBOM.
• Listo para CI/CD: códigos de salida --fail-on, modo de línea base/trinquete, exenciones auditables, JSON a stdout y una GitHub Action en el Marketplace.
• Modo sin conexión: escanea completamente aislado (--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.

Comparativa de DockSec

DockSec es el único de estos que combina la corrección contextual de Dockerfile con un diseño totalmente de código abierto, gobernado por OWASP y ejecutable localmente. Snyk y Aikido ofrecen corrección con IA capaz, pero solo como plataformas comerciales en la nube que envían tus datos a su servicio. Trivy es de código abierto y local, pero se detiene en la detección y no te ayuda a corregir nada. DockSec llena ese vacío para desarrolladores y para equipos regulados o aislados que necesitan tanto la guía de corrección como el control total de sus datos, sin costo alguno.

Hoja de ruta

Consulta ROADMAP.md para ver hacia dónde se dirige DockSec: escaneo de registros sin un demonio Docker local, un archivo de configuración de políticas a nivel de repositorio, plantillas para Jenkins/GitLab/Azure DevOps, una imagen de contenedor oficial, escaneo de Kubernetes y Helm, y más. Los comentarios y votos sobre prioridades son bienvenidos en issues y en OWASP Slack.

Contribuciones

DockSec prospera gracias a las contribuciones de la comunidad. Ya seas desarrollador, diseñador o entusiasta de la seguridad, hay muchas formas de participar:

• Contribuciones de código: corrige errores o añade nuevas funciones.
• Documentación: mejora las guías o crea tutoriales.
• Reporte de problemas: identifica y reporta errores.
• Comentarios: comparte tu experiencia y sugerencias.

Para empezar, consulta nuestras Guías de contribución, Código de conducta y Guía de patrocinio.

Líderes y comunidad

DockSec está liderado por un equipo dedicado comprometido con hacer accesible la seguridad de contenedores:

• Advait Patel - Líder del proyecto
• Arkadii Yakovets - Colíder del proyecto

Encuéntranos aquí:

• Página del proyecto OWASP: owasp.org/DockSec/
• OWASP Slack: #project-docksec
• PyPI: pypi.org/project/docksec/
• Issues: Reportar un error
• Registro de cambios: CHANGELOG.md