DockSec v2026.9.21
Escáner de seguridad de Docker impulsado por IA que explica las vulnerabilidades en un lenguaje sencillo. Un proyecto de laboratorio de OWASP.
DockSec
Escáner de seguridad Docker impulsado por IA que explica las vulnerabilidades en lenguaje sencillo
¿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.
Cómo funciona
Flujo de trabajo de DockSec: del escaneo a información procesable
DockSec sigue un flujo de cinco etapas:
- Escanear: Ejecuta Trivy (vulnerabilidades de imágenes y configuraciones incorrectas de Dockerfile), Hadolint y Docker Scout localmente en tu entorno.
- Priorizar: Clasifica cada hallazgo de CVE por gravedad combinada con su probabilidad de explotación EPSS, de modo que la lista se ordena por lo que hay que corregir primero en lugar de por lo que se encontró primero.
- Correlacionar: Detecta cadenas de explotación 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.
- 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.
- 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 |
| Trivy | Todos los escaneos (obligatorio) | brew install trivy o Trivy docs |
| Hadolint | Linting de Dockerfile | brew install hadolint o Hadolint docs |
| Docker | Escaneos de imágenes (-i) | Docker docs |
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 FILEusa un archivo específico en lugar de buscar.--no-configignora 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 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,
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 para ver la lista completa y la referencia de reglas de composición 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
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-redactpara desactivar esto. - Se admite IA totalmente local. Usa
--provider ollamapara mantener el análisis de IA en tu propio hardware, o--scan-only/--offlinepara 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/docksecde 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-skillenseñ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) |
| Gobernanza | Proyecto de laboratorio de OWASP, neutral respecto a proveedores | Código abierto, mantenido por Aqua | Proveedor único | Proveedor único |
| Detecta CVE y configuraciones erróneas de Dockerfile | Sí | Sí | Sí | Sí |
| Explica los hallazgos en lenguaje sencillo | Sí (contexto e impacto redactados por IA) | No (datos de CVE sin procesar) | Parcial (indicaciones de severidad y corrección) | Parcial (resúmenes de IA en la plataforma) |
| Remediación contextual del Dockerfile | Sí (reescrituras específicas con explicación) | No (solo detección) | Sí (consejos de actualización de imagen base, PRs de corrección) | Sí (PRs de AutoFix con IA) |
| Escaneo de Docker Compose (multiservicio) | Sí (comprobaciones de orquestación y escaneo por servicio) | Parcial (escaneo de configuración, sin despliegue por servicio) | Parcial | Parcial |
| Modo baseline / ratchet (fallar solo ante hallazgos nuevos) | Sí | No | Parcial (políticas de plataforma) | Parcial (políticas de plataforma) |
| Exenciones auditables por hallazgo con motivos y caducidad | Sí | Parcial (.trivyignore, sin motivos exigidos) | Parcial (políticas de plataforma) | Parcial (políticas de plataforma) |
| Salida nativa para CI (SARIF para GitHub Code Scanning) | Sí | Sí | Sí | Sí |
| Exportación de SBOM (CycloneDX) | Sí (--sbom) | Sí | Sí | Sí |
| Instalación de habilidad para asistentes de IA (Claude Code, Cursor, Copilot) | Sí (install-skill) | No | No | No |
| Se ejecuta totalmente sin conexión / aislado de la red | Sí (LLM local mediante Ollama, modo solo escaneo, sin clave de API) | Solo escaneo (sin capa de remediación) | No (plataforma en la nube) | No (plataforma alojada) |
| Los datos de tu imagen permanecen en tu red | Sí | Sí | No | No |
| Trae tu propio LLM / elección de modelo | Sí (OpenAI, Anthropic, Gemini u Ollama local) | No aplicable | No (IA propietaria) | No (IA propietaria) |
| Autoalojable, sin despliegue de plataforma | Sí | Sí | No | No |
| Dependencia de proveedor | Ninguna | Ninguna | Sí | Sí |
| Puntuación de seguridad (0-100) e informes multiformato | Sí | Parcial (formatos de máquina, sin informe de remediación) | Parcial (informes de panel) | Parcial (informes de panel) |
DockSec es el único de estos que combina la remediación contextual del Dockerfile con un diseño totalmente de código abierto, gobernado por OWASP y ejecutable localmente. Snyk y Aikido ofrecen una remediació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 cubre la brecha para desarrolladores y para equipos regulados o aislados de la red que necesitan tanto la guía de corrección como el control total de sus datos, sin coste alguno.
Aplicar correcciones automáticamente
--fix aplica el subconjunto mecánico de los cambios sugeridos en el Dockerfile,
vuelve a escanear e informa del delta:```bash
docksec Dockerfile --scan-only --fix --dry-run # print the diff, change nothing
docksec Dockerfile --scan-only --fix # apply, keeping a .bak
| `--no-color` | Desactiva la salida en color |
| `--verbose` | Muestra información detallada de depuración |
| `--quiet` | Suprime toda la salida excepto los errores |
| `--json` | Genera la salida en formato JSON |
| `--config <path>` | Especifica una ruta de archivo de configuración personalizada |
| `--timeout <seconds>` | Establece el tiempo de espera de la solicitud en segundos |
| `--retry <count>` | Número de reintentos para solicitudes fallidas |
| `--proxy <url>` | Usa el proxy especificado para las solicitudes |
| `--user-agent <string>` | Establece una cadena de User-Agent personalizada |
| `--header <header>` | Añade una cabecera HTTP personalizada a las solicitudes |
| `--cookie <cookie>` | Incluye una cookie en las solicitudes |
| `--output <file>` | Escribe la salida en el archivo especificado |
| `--input <file>` | Lee la entrada desde el archivo especificado |
| `--threads <count>` | Número de hilos concurrentes a usar |
| `--rate-limit <rps>` | Limita las solicitudes por segundo |
| `--follow-redirects` | Sigue las redirecciones HTTP automáticamente |
| `--insecure` | Omite la verificación del certificado TLS |
| `--debug` | Habilita el registro de depuración |
### Ejemplos
```bash
# Ejecución básica
tool --target example.com
# Salida detallada con formato JSON
tool --target example.com --verbose --json
# Usar un archivo de configuración personalizado
tool --config /path/to/config.yaml
# Establecer tiempo de espera y reintentos
tool --target example.com --timeout 30 --retry 3
# Usar un proxy y un User-Agent personalizado
tool --target example.com --proxy http://127.0.0.1:8080 --user-agent "CustomAgent/1.0"
# Limitar la tasa de solicitudes y usar múltiples hilos
tool --target example.com --rate-limit 10 --threads 5
# Escribir la salida en un archivo
tool --target example.com --output results.txt
# Leer objetivos desde un archivo
tool --input targets.txt --threads 10
Configuración
La herramienta se puede configurar mediante un archivo de configuración YAML o variables de entorno.
Archivo de configuración
# config.yaml
target: example.com
verbose: true
timeout: 30
retry: 3
threads: 5
rate_limit: 10
follow_redirects: true
insecure: false
output: results.txt
Variables de entorno
| Variable | Descripción |
|---|---|
TOOL_TARGET | Objetivo predeterminado |
TOOL_VERBOSE | Habilita la salida detallada |
TOOL_TIMEOUT | Tiempo de espera de la solicitud en segundos |
TOOL_RETRY | Número de reintentos |
TOOL_THREADS | Número de hilos concurrentes |
TOOL_RATE_LIMIT | Límite de solicitudes por segundo |
TOOL_OUTPUT | Ruta del archivo de salida |
TOOL_PROXY | URL del proxy |
TOOL_USER_AGENT | Cadena de User-Agent personalizada |
Solución de problemas
Problemas comunes
Error: Conexión rechazada
- Verifica que el objetivo sea accesible y que el puerto esté abierto.
- Comprueba la configuración del proxy y del cortafuegos.
Error: Tiempo de espera agotado
- Aumenta el valor de
--timeout. - Reduce el número de hilos concurrentes.
Error: Permiso denegado
- Ejecuta la herramienta con privilegios elevados si es necesario.
- Verifica los permisos del archivo de salida.
Error: Certificado TLS no válido
- Usa
--insecurepara omitir la verificación del certificado (solo para pruebas).
Registro de depuración
Habilita el registro de depuración con la opción --debug o estableciendo la variable de entorno TOOL_DEBUG=true.
tool --target example.com --debug
Contribuir
¡Agradecemos las contribuciones! Por favor, sigue estos pasos:
- Haz un fork del repositorio.
- Crea una rama de funcionalidad (
git checkout -b feature/nueva-funcionalidad). - Realiza tus cambios y añade pruebas.
- Ejecuta la suite de pruebas (
make test). - Envía una solicitud de extracción.
Licencia
Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.
Descargo de responsabilidad
Esta herramienta está destinada únicamente a pruebas de seguridad autorizadas y fines educativos. Los autores no se hacen responsables del uso indebido o de los daños causados por esta herramienta. Asegúrate siempre de tener la autorización adecuada antes de realizar pruebas en cualquier sistema.```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)
Es deliberadamente conservador. No elegirá una versión de imagen base, moverá un secreto, convertirá un `ADD` que obtiene una URL o descomprime un archivo, ni editará un archivo compose; esos casos se reportan en "Needs review" en su lugar. También se niega a editar un archivo con cambios sin confirmar a menos que se proporcione `--force`, por lo que git siempre está en posición de deshacer el cambio.
## Documentación
| Guía | Qué cubre |
| --- | --- |
| [Guía de evaluación](https://github.com/owasp/docksec/blob/main/docs/evaluation-guide.md) | Evaluación de 15 minutos, incluyendo lo que DockSec *no* hace |
| [Cadenas de explotación](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) | Rutas de ataque entre servicios, y sus límites |
| [Referencia de reglas de Compose](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) | Las 17 reglas: qué detecta cada una, y cuándo es razonable mantenerla |
| [Integración de CI](https://github.com/owasp/docksec/blob/main/docs/ci/README.md) | Jenkins, GitLab, Azure Pipelines, pre-commit |
| [Ejemplos](https://github.com/owasp/docksec/blob/main/examples/README.md) | Diez Dockerfiles y stacks de compose con sus hallazgos esperados |
| [Casos de estudio](https://github.com/owasp/docksec/blob/main/docs/case-studies/README.md) | Escaneos reales de imágenes oficiales, con las cifras |
## Hoja de ruta
Consulta [ROADMAP.md](https://github.com/owasp/docksec/blob/main/ROADMAP.md) para saber hacia dónde se dirige DockSec: escaneo de registros sin un daemon de Docker local, un archivo de configuración de políticas a nivel de repositorio, plantillas de 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](https://github.com/OWASP/DockSec/issues) y en
[OWASP Slack](https://owasp.slack.com/archives/C0APXGCUW7M).
---
## Contribuir
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 funcionalidades.
- **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 [Directrices de contribución](https://github.com/owasp/docksec/blob/main/CONTRIBUTING.md), [Código de conducta](https://github.com/owasp/docksec/blob/main/CODE_OF_CONDUCT.md) y [Guía de patrocinio](https://github.com/owasp/docksec/blob/main/SPONSORSHIP.md).
---
## Líderes y comunidad
DockSec está liderado por un equipo dedicado a hacer accesible la seguridad de contenedores:
- [Advait Patel](https://github.com/advaitpatel) - Líder del proyecto
- [Arkadii Yakovets](https://github.com/arkid15r) - Co-líder del proyecto
Encuéntranos aquí:
- **Página del proyecto 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**: [Reportar un error](https://github.com/OWASP/DockSec/issues)
- **Changelog**: [CHANGELOG.md](https://github.com/owasp/docksec/blob/main/CHANGELOG.md)
---
<div align="center">
<strong>Si DockSec te ayuda, dale una estrella al repositorio para que otros lo descubran.</strong><br>
Creado por <a href="https://github.com/advaitpatel">Advait Patel</a> y la comunidad OWASP.
</div>