Trivy no Node.js

O Trivy no Node.js identifica vulnerabilidades em dependências, imagens de container, sistemas operacionais e configurações de infraestrutura. Ele pode analisar o repositório antes do build, a imagem final publicada e manifestos Kubernetes, criando várias camadas de verificação na pipeline.

Um scanner não prova que a aplicação está segura. Bases de vulnerabilidades mudam, alguns achados são falsos positivos e uma versão corrigida pode ainda não existir. Por isso, o resultado precisa de uma política clara, exceções com prazo e rastreabilidade do artefato analisado.

Neste guia, você aprenderá a instalar Trivy, escanear filesystem e imagens, filtrar severidade, usar ignore files, gerar SARIF, verificar IaC, integrar com GitHub Actions e evitar que scans inconsistentes bloqueiem ou liberem releases indevidamente.

O que é Trivy?

A documentação oficial do Trivy apresenta scanners para vulnerabilidades, misconfigurations, secrets, licenças e supply chain. Entre os alvos estão imagens, filesystem, repositórios, Kubernetes e SBOMs.

Instalação

Em ambientes locais, instale pelo método recomendado para seu sistema e fixe a versão no CI. Também é possível executar via container:

docker run --rm \
  -v "$PWD:/workspace" \
  aquasec/trivy:0.61.0 \
  fs /workspace

Evite usar apenas latest, porque regras, formatos e comportamento podem mudar.

Scan do repositório

trivy fs .

O comando analisa lockfiles, arquivos do sistema, IaC e outros alvos detectados. Para uma aplicação Node.js, mantenha package-lock.json, pnpm-lock.yaml ou yarn.lock versionado.

Somente vulnerabilidades

trivy fs \
  --scanners vuln \
  --severity HIGH,CRITICAL \
  .

Esse scan encontra dependências conhecidas pelo lockfile. Ele não substitui testes, análise de código e revisão de comportamento inseguro.

Falhando o CI

trivy fs \
  --scanners vuln \
  --severity CRITICAL,HIGH \
  --ignore-unfixed \
  --exit-code 1 \
  .

--exit-code 1 bloqueia a pipeline quando há achados. --ignore-unfixed reduz ruído, mas também esconde riscos sem correção. Decida conforme criticidade, exposição e mitigação.

Scan da imagem

trivy image \
  --severity HIGH,CRITICAL \
  --exit-code 1 \
  ghcr.io/acme/orders-api@sha256:abc123...

Analise por digest para garantir que o resultado corresponde ao artefato implantado. Veja GitHub Container Registry no Node.js.

Filesystem versus imagem

O scan do repositório detecta dependências antes do build. O scan da imagem também encontra pacotes do sistema operacional e confirma o conteúdo final. Execute ambos quando o risco justificar.

Imagem multi-stage

Uma imagem final pequena reduz superfície:

• não copie ferramentas de build;
• remova devDependencies;
• evite shells e utilitários desnecessários;
• fixe a imagem base;
• execute como não-root.

Consulte Docker Multi-stage para Node.js.

Scan de secrets

trivy fs \
  --scanners secret \
  .

O scanner busca padrões de chaves e tokens. Ele não deve ser a única barreira. Use proteção de branches, secret scanning do provedor e rotação imediata de qualquer credencial exposta.

Misconfiguration

trivy config .

Trivy avalia Dockerfiles, Kubernetes, Terraform, Helm e outros formatos. Ele pode detectar container privilegiado, ausência de limites, filesystem gravável e portas expostas.

Dockerfile

trivy config Dockerfile

Um scan útil verifica usuário não-root, secrets em ENV, imagens sem versão e práticas que ampliam a superfície. Nem toda recomendação se aplica a todos os serviços; documente exceções.

Kubernetes

kubectl kustomize k8s/overlays/production \
  | trivy config -

Analise o YAML renderizado, não apenas os templates. Assim, patches e values finais entram na avaliação. Veja Kustomize para Node.js e Helm para Node.js.

Configuração por arquivo

Crie trivy.yaml:

severity:
  - HIGH
  - CRITICAL
ignore-unfixed: true
exit-code: 1
scanners:
  - vuln
  - misconfig
  - secret

Versione a política junto com o código. Alterações devem passar por revisão.

.trivyignore

CVE-2026-12345
AVD-KSV-0014

Não adicione IDs sem contexto. Cada exceção precisa registrar:

• motivo;
• serviço afetado;
• mitigação;
• responsável;
• data de expiração;
• link para issue.

Ignore com YAML

Formatos estruturados permitem políticas mais detalhadas conforme a versão do Trivy. Prefira exceções com expiração quando suportado e valide periodicamente se ainda são necessárias.

VEX

Vulnerability Exploitability eXchange registra se uma vulnerabilidade realmente afeta o produto. Um pacote pode estar presente, mas o código vulnerável pode não ser executável. VEX melhora contexto, porém exige evidência confiável.

SBOM

Trivy gera SBOM:

trivy image \
  --format cyclonedx \
  --output sbom.cdx.json \
  ghcr.io/acme/orders-api@sha256:abc123...

Também pode analisar um SBOM existente. Consulte SBOM no Node.js.

Cache e base de dados

O primeiro scan baixa bases de vulnerabilidades. Em CI, use cache para reduzir tempo, mas permita atualização frequente. Uma base antiga produz um resultado antigo, mesmo que o comando passe.

Ambiente sem internet

Espelhe as bases e imagens necessárias conforme a documentação. Registre a data da última atualização e alerte quando o cache exceder o limite aceitável.

GitHub Actions

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v4

  - name: Build image
    run: docker build -t orders-api:${{ github.sha }} .

  - name: Trivy image scan
    uses: aquasecurity/trivy-action@master
    with:
      image-ref: orders-api:${{ github.sha }}
      format: sarif
      output: trivy-results.sarif
      severity: CRITICAL,HIGH
      ignore-unfixed: true

  - name: Upload SARIF
    uses: github/codeql-action/upload-sarif@v3
    with:
      sarif_file: trivy-results.sarif

Em produção, fixe actions por commit em vez de branches móveis. Consulte CI para Node.js com GitHub Actions.

Scan antes e depois do push

Uma estratégia eficiente:

1. scan do filesystem;
2. testes e build;
3. scan da imagem local;
4. push por digest;
5. scan periódico no registry;
6. novo alerta quando a base encontra CVE posterior.

Scan periódico

Uma imagem que passou hoje pode receber uma CVE amanhã. Execute scans agendados para imagens ainda implantadas e abra issues automaticamente.

Política por ambiente

Pull requests podem produzir relatório sem bloquear achados antigos. Releases podem bloquear novas vulnerabilidades críticas. Produção pode exigir aprovação para exceções. Evite uma política única que todos aprendem a ignorar.

Baseline

Em sistemas legados, registre um baseline e bloqueie regressões. O objetivo é reduzir dívida sem impedir qualquer alteração. Baseline não deve virar permissão eterna.

Comparando resultados

Armazene SARIF, JSON ou tabela como artefato. Compare por digest, versão do Trivy e data da base. Sem essas informações, relatórios diferentes não são diretamente comparáveis.

Licenças

Trivy pode detectar licenças conforme configuração e versão. Defina uma política com jurídico e produto. Uma licença desconhecida exige revisão, não rejeição automática sem contexto.

Segurança do próprio scanner

• fixe a versão do Trivy;
• verifique assinatura e checksum;
• restrinja rede e credenciais do job;
• não monte o Docker socket sem necessidade;
• não execute código do repositório durante um scan de PR não confiável;
• proteja relatórios que contêm caminhos internos.

Supply chain

Trivy é uma etapa, não a supply chain completa. Combine lockfiles, builds reproduzíveis, SBOM, assinatura, provenance, registry e deploy por digest. Veja Supply Chain no Node.js.

Observabilidade

Monitore:

• achados por severidade;
• tempo médio de correção;
• exceções ativas e expiradas;
• idade da base;
• imagens sem scan;
• digests implantados vulneráveis;
• falhas de download;
• tempo da pipeline.

Erros comuns

• Scan só do package.json: o lockfile e a imagem final ficam ausentes.
• Ignore sem prazo: riscos nunca voltam à revisão.
• Base antiga: o relatório parece limpo por falta de dados.
• Bloquear tudo: equipes desativam o scanner.
• Ignorar tudo sem fix: vulnerabilidades exploráveis permanecem.
• Scan por tag móvel: o resultado não identifica o conteúdo.
• Sem scan periódico: CVEs novas não são detectadas.
• Confiar apenas no scanner: falhas de lógica e autorização passam.

Conclusão

O Trivy no Node.js analisa dependências, imagens, secrets e infraestrutura como código. Executar scans no repositório e no digest final oferece visibilidade sobre o conteúdo que realmente será implantado.

Fixe versões, mantenha a base atualizada e crie uma política com exceções temporárias. Gere relatórios, scans periódicos e contexto VEX quando necessário. Com SBOM, assinatura e deploy por digest, Trivy se torna uma barreira útil da supply chain sem ser tratado como garantia absoluta.