DockSec

Scanner de segurança Docker com IA que explica vulnerabilidades em linguagem simples

O que é o DockSec?

O DockSec é um Projeto de Laboratório OWASP que preenche a lacuna entre resultados complexos de varreduras de segurança e correções acionáveis para desenvolvedores. Ele integra scanners padrão do setor (Trivy, Hadolint, Docker Scout) com IA para fornecer análise de segurança sensível ao contexto.

Em vez de sobrecarregar você com uma lista de 200+ CVEs, o DockSec:

• Prioriza o que realmente afeta a configuração específica do seu contêiner.
• Explica vulnerabilidades em linguagem simples, não apenas jargão de segurança.
• Sugere correções específicas para o seu Dockerfile.
• Gera relatórios de segurança profissionais e interativos para a sua equipe.

Tudo é verificado localmente; a única coisa que sai da sua máquina é o conteúdo do arquivo (com segredos removidos) enviado ao provedor de IA que você escolher - e, com um modelo local ou o modo somente verificação, nada sai. Consulte Fluxo de dados e privacidade.

Como Funciona

Fluxo de trabalho do DockSec: da varredura a insights acionáveis

O DockSec segue um pipeline de quatro etapas:

1. Scan: Executa Trivy, Hadolint e Docker Scout localmente no seu ambiente.
2. Analyze: A IA correlaciona as descobertas de todos os scanners para remover ruído e avaliar o impacto no mundo real.
3. Recommend: Gera explicações legíveis por humanos e etapas específicas de remediação.
4. Report: Exporta resultados acionáveis como HTML, PDF, JSON, CSV, SARIF e CycloneDX SBOM.

Primeiros Passos

1. Pré-requisitos

O DockSec orquestra scanners locais, portanto precisa de:

Ou deixe o DockSec instalar o Trivy e o Hadolint para você:```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. Execute sua primeira varredura

Não é necessária chave de API para varredura local:```bash docksec Dockerfile --scan-only

Toda varredura termina com um resumo de resultados: uma tabela de severidade, uma pontuação de segurança de 0 a 100 com uma classificação, um bloco de ação "Quick take", os relatórios gerados (salvos em `~/.docksec/results/` por padrão) e um próximo comando sugerido.

### 4. Ativar análise de IA

A análise de IA explica os achados e sugere correções. Escolha um provedor, defina sua chave de API e execute:```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 provedor tem um modelo padrão razoável (OpenAI: gpt-4o, Anthropic: claude-haiku-4-5, Google: gemini-1.5-pro, Ollama: llama3.1), então --model é opcional. Para evitar repetir flags, defina variáveis de ambiente (ou coloque-as em um arquivo .env no diretório de onde você executa - o DockSec o carrega automaticamente):```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile

Antes que qualquer conteúdo seja enviado a um provedor de IA, valores com aparência de segredo (senhas, tokens,
chaves de API, blocos de chaves privadas) são mascarados automaticamente. Consulte
[Fluxo de dados e privacidade](#data-flow-and-privacy).

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

Comandos Comuns```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

---

## Configuration file

Faça commit de um `.docksec.yml` na raiz do seu repositório e toda a equipe - e cada job de CI - fará a varredura sob a mesma política, em vez de cada desenvolvedor passar seus próprios flags.```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 configuração é opcional; o que você deixar de fora recorre à variável de ambiente e depois ao padrão interno. Um exemplo completo anotado está em examples/.docksec.yml.

Precedência

Maior prioridade primeiro:``` CLI flag > environment variable > .docksec.yml > built-in default

Portanto, um valor `severity: LOW` commitado ainda é substituído por `--severity CRITICAL` na
linha de comando e por `DOCKSEC_DEFAULT_SEVERITY` no ambiente.

### Descoberta

DockSec procura por `.docksec.yml` (ou `.docksec.yaml`) no diretório de trabalho
e então sobe até a raiz do repositório, de modo que um serviço em um subdiretório
de um monorepo herda a política commitada no nível superior. A busca para no
diretório que contém `.git`, portanto nunca captura um arquivo de fora do
repositório.

- `--config FILE` usa um arquivo específico em vez de procurar.
- `--no-config` ignora qualquer arquivo de configuração, para execuções de CI reproduzíveis.

O arquivo de configuração em vigor é exibido no banner da varredura, portanto fica sempre claro
qual política foi aplicada.

### Configurações

| Configuração | Flag equivalente | Notas |
| --- | --- | --- |
| `severity` | `--severity` | Níveis de gravidade para a varredura de imagem |
| `fail_on` | `--fail-on` | Limite do gate de CI |
| `formats` | `--format` | Formato de lista: `[json, html]` |
| `output_dir` | `--output-dir` | Destino do relatório |
| `provider` | `--provider` | `openai`, `anthropic`, `google`, `ollama` |
| `model` | `--model` | Nome do modelo para o provedor |
| `offline` | `--offline` | Sem rede; pula IA e Docker Scout |
| `skip_ai_scoring` | `--skip-ai-scoring` | Apenas pontuação local |
| `no_redact` | `--no-redact` | Não mascarar segredos antes da chamada de IA |
| `no_cache` | `--no-cache` | Ignorar o cache da varredura |
| `ignore_file` | `--ignore-file` | Caminho do arquivo de dispensa |
| `baseline` | `--baseline` | Caminho do arquivo de baseline |
| `rules.disabled` | - | IDs de regras para desativar completamente |

Um arquivo de configuração inválido - uma chave desconhecida, uma gravidade inválida - é um erro
grave que sai com o código `2` em vez de um aviso, de modo que um arquivo de política quebrado
nunca pode fazer uma varredura rodar sob regras que a equipe não commitou.

### Autocompletar no editor

O comentário `# yaml-language-server:` na primeira linha fornece autocompletar e
validação inline nos editores VS Code e JetBrains. O schema está publicado em
[`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/HEAD/docs/docksec-config-schema.json) e pode ser
regenerado com `docksec --print-config-schema`.

### Desabilitando regras

`rules.disabled` desativa uma verificação completamente, em todos os lugares - ela é removida
antes da pontuação, dos relatórios, do `--json` e do gate `--fail-on`. Use para verificações
que não se aplicam ao seu ambiente. Para achados individuais que sua equipe já fez triagem e
aceitou, prefira o [arquivo de dispensa](#ignoring-findings-waivers), cujas entradas contêm
um motivo e uma data de expiração e, portanto, permanecem auditáveis.

---

## Integração CI/CD

### Códigos de saída

DockSec usa códigos de saída amigáveis para CI, para que builds e shells possam reagir aos resultados:

| Código | Significado |
|---|---|
| `0` | Sucesso, sem achados no nível igual ou acima de `--fail-on` |
| `1` | Achados no nível igual ou acima do limite de `--fail-on` |
| `2` | Erro de uso ou de argumento |
| `3` | Erro de ferramenta ou de execução (varredura falhou, imagem não encontrada, ferramentas ausentes) |

O `--fail-on` atua como gate sobre os achados estruturados (vulnerabilidades de imagem e
configurações incorretas do compose). Quando `--fail-on` está abaixo da `--severity` solicitada,
a gravidade da varredura é ampliada automaticamente para que o gate possa observar esses achados.

### Saída legível por máquina

`--json` imprime um único objeto JSON na stdout (informações da varredura, vulnerabilidades,
contagens de gravidade e quaisquer achados de IA) em vez do resumo legível por humanos,
portanto pode ser canalizado diretamente para outras ferramentas:```bash
docksec -i myapp:latest --image-only --json | jq '.severity_counts'

Com --json sozinho, nenhum arquivo de relatório é gravado; combine-o com --format para gravar arquivos e imprimir JSON na mesma execução. Todas as mensagens legíveis por humanos vão para stderr em modo --json, então o stdout contém apenas o payload JSON.

Saída SARIF para o GitHub Code Scanning

--sarif grava um relatório SARIF 2.1.0 junto com os outros formatos de relatório. Envie-o com a ação padrão github/codeql-action/upload-sarif para ver as descobertas anotadas diretamente em pull requests e na aba 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()` é importante: sem ele, a etapa de upload é ignorada sempre que
> `--fail-on` faz o DockSec sair com código diferente de zero, perdendo as descobertas exatamente quando
> mais importam.

### Modo baseline / catraca

`--baseline FILE` permite adotar o `--fail-on` em um projeto existente sem uma parede de
descobertas pré-existentes bloqueando cada build. Execute uma vez com `--update-baseline` para
criar um snapshot das descobertas de hoje e depois faça commit do arquivo de baseline; a partir de então, o `--fail-on` só
bloqueia descobertas que ainda não estão no 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

Findings are matched by vulnerability ID, target, and package name, so the baseline stays valid as unrelated findings come and go. Re-run with --update-baseline whenever you want to accept the current state as the new baseline.

Ignoring findings (waivers)

--ignore-file FILE suppresses individual findings a team has triaged and accepted. Unlike the baseline (a point-in-time snapshot), the ignore file is an explicit, reviewable list where every entry carries a reason and an optional expiry date. If a .docksec-ignore.yml file exists in the current directory, it is picked up automatically.```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"

Descobertas suprimidas são removidas antes da pontuação, dos relatórios, da saída `--json` e do gate `--fail-on`. Entradas expiradas param de ser aplicadas automaticamente (com um aviso), e entradas sem um motivo são sinalizadas para que as isenções permaneçam auditáveis. Faça commit do arquivo no controle de versão para que as supressões sejam revisadas como qualquer outra alteração.

---

## Relatórios

### Formatos de relatório

Por padrão, cada varredura gera quatro arquivos de relatório; use `--format` para escolher um subconjunto:

- **html**: Um relatório web interativo e visualmente limpo: cartões de gravidade, classificação de pontuação, tabela completa de vulnerabilidades com versões corrigidas e todas as descobertas de IA.
- **pdf**: Um documento portátil e pronto para apresentação.
- **json**: Dados completos de varredura legíveis por máquina (mesma forma que a saída `--json` no stdout).
- **csv**: Uma tabela pronta para planilhas com vulnerabilidades individuais.

> Nota sobre o comportamento do CSV: com zero vulnerabilidades, o DockSec ainda escreve um CSV
> apenas com cabeçalho (nomes de colunas, sem linhas) para que a automação a jusante nunca quebre por arquivo ausente ou
> vazio. Isso é intencional.

### CycloneDX SBOM

`--sbom` escreve uma lista de materiais de software CycloneDX (`<image>.cdx.json`) da
imagem varrida, listando cada componente de pacote e as vulnerabilidades conhecidas. O BOM é
produzido pelo exportador nativo do Trivy (portanto, em conformidade com a especificação) e o DockSec se insere
nos metadados da ferramenta. Envie-o para o Dependency-Track, o gráfico de dependências do GitHub ou qualquer
outro consumidor de SBOM:```bash
docksec --image-only -i myapp:latest --sbom

--sbom precisa de uma única imagem (-i), então é ignorado nas execuções de compose. Como --sarif, é independente de --format.

Fluxo de dados e privacidade

O DockSec foi projetado para que você sempre saiba o que sai da sua máquina:

• A verificação é totalmente local. O Trivy, o Hadolint e a pontuação de segurança são executados na sua máquina. O conteúdo das imagens nunca é enviado para lugar algum pelo DockSec.
• A análise de IA envia apenas o arquivo verificado. Quando a etapa de IA é executada, o Dockerfile ou o conteúdo do arquivo compose (além de um breve resumo das contagens de vulnerabilidades para a pontuação) é enviado ao provedor de LLM que você configurou. Nada mais é transmitido.
• Os segredos são mascarados antes de saírem. Valores com aparência de segredo (senhas, tokens, chaves de API, blocos de chave privada) no arquivo são mascarados antes que o conteúdo seja enviado ao provedor de IA. Os nomes das chaves permanecem visíveis para que credenciais expostas ainda sejam sinalizadas. Use --no-redact para desativar o mascaramento.
• IA totalmente local é suportada. Use --provider ollama para manter a análise de IA em seu próprio hardware, ou --scan-only / --offline para pular a IA completamente.
• Sem telemetria. O DockSec não coleta dados de uso e não se comunica com nenhum servidor externo.

Modo offline

--offline executa uma verificação sem acesso à rede. Ele usa o banco de dados de vulnerabilidades do Trivy já presente no disco (sem atualização de banco de dados) e ignora a análise de IA e a verificação avançada do Docker Scout, que exigem rede. Essa é a maneira mais simples de verificar em um ambiente isolado ou restrito:```bash docksec --image-only -i myapp:latest --offline

Certifique-se de que o banco de dados do Trivy foi baixado pelo menos uma vez (qualquer varredura on-line anterior faz
isso) antes de confiar em `--offline`.

### Cache de resultados de varredura

Os resultados da varredura de imagens são armazenados em cache (padrão: 24 horas, substituível com
`DOCKSEC_CACHE_TTL_HOURS`) e indexados pelo digest de conteúdo da imagem, de modo que uma tag reconstruída
como um `:latest` reutilizado sempre recebe uma nova varredura. Use `--no-cache` (ou
`DOCKSEC_USE_CACHE=false`) para ignorar o cache em uma execução.

---

## Habilidades para assistentes de IA (`install-skill`)

`docksec install-skill` grava as instruções de uso do DockSec nos arquivos de contexto bem conhecidos
para assistentes de codificação de IA populares, para que um assistente que trabalhe no seu repositório saiba como
invocar o DockSec:```bash
docksec install-skill

Isso cria ou atualiza:

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

Os arquivos são texto simples que você pode revisar e commitar; nada é executado. Executar o comando novamente atualiza a seção do DockSec no lugar, em vez de duplicá-la.

Funcionalidades

• Análise Inteligente: a IA explica o que as vulnerabilidades significam para a sua configuração específica.
• Suporte Multi-LLM: OpenAI, Anthropic Claude, Google Gemini ou modelos locais via Ollama.
• Privacidade em Primeiro Lugar: valores secretos são ocultados antes que qualquer conteúdo chegue a um provedor de IA, a varredura é totalmente local e não há telemetria.
• Varredura de Docker Compose: detecta configurações incorretas no nível de orquestração e varre todos os serviços em um arquivo compose.
• Integração Profunda: combina Trivy (vulnerabilidades), Hadolint (linting) e Docker Scout.
• Pontuação de Segurança: uma pontuação de 0 a 100 com uma classificação para acompanhar sua postura de segurança ao longo do tempo.
• Formatos Ricos: HTML (interativo), PDF, JSON, CSV, SARIF e SBOM CycloneDX.
• Pronto para CI/CD: códigos de saída --fail-on, modo baseline/ratchet, isenções auditáveis, JSON para stdout e uma GitHub Action no Marketplace.
• Modo Offline: varredura totalmente isolada (--offline) usando o banco de dados local do Trivy.
• Habilidades para Assistentes de IA: docksec install-skill ensina ao Claude Code, Cursor, Copilot e outros como executar o DockSec no seu repositório.

Como o DockSec se Compara

O DockSec é o único entre essas ferramentas que combina correção contextual de Dockerfile com um design totalmente open source, governado pela OWASP e executável localmente. Snyk e Aikido oferecem correção por IA competente, mas apenas como plataformas comerciais em nuvem que enviam seus dados para o serviço delas. O Trivy é open source e local, mas para na detecção e não ajuda você a corrigir nada. O DockSec preenche essa lacuna para desenvolvedores e para equipes em setores regulamentados ou em redes isoladas que precisam tanto da orientação de correção quanto do controle total dos seus dados, sem nenhum custo.

Roadmap

Veja ROADMAP.md para saber para onde o DockSec está caminhando: varredura de registries sem um daemon Docker local, um arquivo de configuração de políticas no nível do repositório, templates para Jenkins/GitLab/Azure DevOps, uma imagem de contêiner oficial, varredura de Kubernetes e Helm e muito mais. Comentários e votos sobre prioridades são bem-vindos em issues e no Slack da OWASP.

Contribuindo

O DockSec prospera com contribuições da comunidade. Seja você um desenvolvedor, designer ou entusiasta de segurança, há muitas maneiras de se envolver:

• Contribuições de Código: corrija bugs ou adicione novos recursos.
• Documentação: melhore guias ou crie tutoriais.
• Relato de Issues: identifique e relate bugs.
• Feedback: compartilhe sua experiência e sugestões.

Para começar, consulte as nossas Diretrizes de Contribuição, o nosso Código de Conduta e o nosso Guia de Patrocínio.

Líderes e Comunidade

O DockSec é liderado por uma equipe dedicada e comprometida em tornar a segurança de contêineres acessível:

• Advait Patel - Líder do Projeto
• Arkadii Yakovets - Colíder do Projeto

Encontre-nos aqui:

• Página do Projeto OWASP: owasp.org/DockSec/
• Slack da OWASP: #project-docksec
• PyPI: pypi.org/project/docksec/
• Issues: Relate um bug
• Changelog: CHANGELOG.md