Estudo ferramenta SCA Trivy

[JerfesonGregorio]

Qual é o problema?

O APAE não tem análise de composição de software (SCA). Dependência de terceiro entra no
projeto sem que ninguém saiba se carrega vulnerabilidade conhecida, e continua lá até
alguém tropeçar nela por acaso.

Este repositório é o piloto. APAE-atendimento e APAE-gestao-escolar ficam de fora: o estudo
roda em um projeto só, e estender para os outros dois é decisão posterior, tomada com o
resultado deste na mão.

O quê: a superfície exposta nunca foi medida. Hoje ela é, no mínimo:

Alvo	Arquivo	Tamanho medido
Backend Java	apps/api/pom.xml	23 dependências diretas
Workspace e frontend	pnpm-lock.yaml	578 pacotes resolvidos
Workspace e frontend	package-lock.json	605 pacotes resolvidos
Imagens	apps/api/Dockerfile, apps/apae/Dockerfile	2 imagens, dois estágios cada

Duas linhas dessa tabela já são pergunta para o estudo. As 23 dependências de Maven são
apenas as declaradas — a árvore transitiva real, onde a maioria das CVE mora, não tem
medida nenhuma. E a raiz carrega dois lockfiles do mesmo ecossistema, pnpm-lock.yaml e
package-lock.json, com contagens diferentes. O Trivy vai ler os dois, e o estudo precisa
dizer qual deles é a verdade.

Por quê: o Renovate, já adotado, sobe versão de dependência. Isso é remediação, não
detecção. Ele atualiza o que tem versão nova disponível, e é cego para três coisas: a
dependência transitiva que ainda não tem correção publicada, o pacote de sistema operacional
dentro da imagem construída, e a pergunta "quantas vulnerabilidades existem aqui agora".
Sem alguém responder essa pergunta, não há linha de base, não há prioridade e não há como
saber se a situação melhora ou piora entre uma sprint e outra.

As imagens do APAE partem de gcr.io/distroless/java21-debian13 e
gcr.io/distroless/nodejs20-debian13, ambas presas por digest. A expectativa é de superfície
de sistema operacional quase nula — mas expectativa não é medida. Confirmar isso com número é
parte do estudo, e é o número que justifica manter a escolha de imagem base.

Como reproduzir

Tarefas Relacionadas

• PR relacionado: a definir, abre quando o estudo começar
• Renovate já foi estudado e adotado. Esta issue não reabre aquela decisão — ela define como
  as duas ferramentas convivem.
• APAE-atendimento e APAE-gestao-escolar estão fora desta issue. Se o piloto for aprovado,
  cada um vira issue própria, reaproveitando a configuração já validada aqui.

Objetivo da Solução

Entregar um documento de estudo que permita à equipe decidir
com números na mão se o Trivy entra no fluxo, e que deixe a implantação pronta para ser
escrita como issue seguinte. O estudo é de leitura e execução local — nada em CI muda nesta issue.

O documento tem quatro blocos obrigatórios, nesta ordem.

1. Objetivo

Responder que pergunta o Trivy responde que hoje
ninguém responde. Delimitar as duas ferramentas lado a lado:

Ferramenta	Pergunta que responde	Já existe?
Renovate	Existe versão mais nova desta dependência?	Sim
Trivy	As dependências e imagens de hoje têm vulnerabilidade conhecida?	Não

Explicar o que o Trivy não faz, com a mesma clareza: não corrige nada, não avalia se a
vulnerabilidade é alcançável pelo código da aplicação, e não substitui revisão de código.

2. Escopo no projeto

Definir e justificar, com o baseline medido como argumento:

• Quais alvos dentro do repositório. apps/api para Maven, apps/apae para npm, e os
  dois Dockerfiles. Decidir também o que fazer com os dois lockfiles da raiz — varrer os
  dois, varrer um só, ou tratar a duplicidade como problema à parte — e registrar a decisão.
• Qual tipo de varredura. Sistema de arquivos (scan-type: fs, lê lockfile e pom) e
  varredura de imagem (scan-type: image, lê pacote de sistema operacional). São coisas
  diferentes e acham coisas diferentes — o documento precisa mostrar a diferença com saída
  real das duas.
• Qual severidade bloqueia. Proposta a validar: HIGH e CRITICAL com
  ignore-unfixed, e LOW/MEDIUM apenas registrados. Justificar com a contagem medida:
  se HIGH sozinho já produz dezenas de achados sem correção disponível, o portão trava o
  time no primeiro dia.
• Baseline. Rodar no APAE e registrar, em tabela, a contagem por severidade, separando
  ecossistema Java, npm e sistema operacional. Esse número é o que a próxima issue vai usar
  para comparar.

3. Configuração

Testar localmente e documentar, com o comando exato e a saída obtida:

• trivy.yaml central, para não repetir flag em cada execução. Precisa incluir
  skip-dirs para node_modules, target e .next — sem isso o Trivy varre o
  node_modules inteiro e duplica cada achado que já veio do lockfile.
• .trivyignore com política. Toda linha exige justificativa escrita e data de
  expiração (CVE-XXXX-YYYY exp:AAAA-MM-DD). Exceção sem prazo vira dívida invisível.
• pom.xml contra JAR. Comparar trivy fs sobre o pom.xml com trivy fs sobre o JAR
  gerado por mvn package. Com spring-boot-starter-parent, a maioria das versões vem do
  BOM e não está escrita no pom; o JAR carrega a árvore já resolvida em BOOT-INF/lib/.
  Registrar a diferença de contagem entre os dois — é ela que decide o que a implantação vai
  escanear.
• Cache da base de dados. A base vem do ghcr.io e tem limite de requisição. Em CI sem
  cache o job falha por erro de download, não por achado. Documentar o caminho do cache e a
  configuração de repositório da base.
• SARIF. upload-sarif alimenta a aba Security, mas só é gratuito em repositório
  público. Verificar e registrar a visibilidade do APAE — se for privado sem GitHub Advanced
  Security, o documento precisa dizer qual é a alternativa (saída em tabela no log do job).
• SBOM. Gerar CycloneDX e dizer para que serve. É subproduto barato e tem valor de
  documentação para o projeto.

4. Integração com o Renovate

Esta é a parte que o documento não pode entregar pela metade. Precisa responder:

• Divisão de papéis. Trivy detecta e barra; Renovate corrige. Nenhum faz o trabalho do
  outro. Descrever o fluxo fim a fim em uma frase por etapa: Trivy acha na varredura
  agendada, Renovate abre o PR de correção, Trivy revalida naquele PR, o portão libera o
  merge.
• Onde a configuração do Renovate vive hoje. Não existe renovate.json no clone do
  APAE. Descobrir e registrar: é o aplicativo hospedado (Mend) com
  configuração pelo painel, é uma configuração central em outro repositório, ou é
  auto-descoberta com o preset padrão? Sem essa resposta nada do resto é aplicável.
• vulnerabilityAlerts e osvVulnerabilityAlerts. O Renovate consegue priorizar
  correção de segurança e abrir PR fora do cronograma normal, mas vulnerabilityAlerts lê
  os alertas do GitHub — ou seja, exige Dependabot alerts habilitado em
  Settings › Code security. Verificar se está ligado no APAE e registrar o estado atual.
• Não ligar Dependabot security updates. Só os alertas. Se os updates forem ligados,
  Dependabot e Renovate abrem PR para a mesma dependência e a fila de PR duplica.
• Coerência do ignore-unfixed. O portão do Trivy só deve barrar o que o Renovate
  consegue corrigir. Vulnerabilidade sem patch publicado trava o merge de todo mundo sem
  oferecer saída — e não há nada que o desenvolvedor do PR possa fazer a respeito.
• O que sobra para o Trivy que o Renovate nunca vai pegar. Listar explicitamente:
  dependência transitiva sem versão corrigida, vulnerabilidade na imagem base, portão de
  merge, e varredura agendada de dependência que ninguém tocou.

Não fazer nesta issue: não criar, alterar ou remover nenhum workflow — nem sca.yml,
nem os existentes. Não alterar pom.xml, package.json, lockfile, Dockerfile ou imagem
base. Não corrigir nenhuma vulnerabilidade que o estudo encontrar; o baseline é o
entregável, a correção vem em issue própria. Não alterar a configuração do Renovate — esta
issue só descobre e documenta o estado atual dela. Não configurar portão de bloqueio de
merge. Não instalar nada na organização IFPBEsp. Não estender o estudo, a configuração ou a
documentação a APAE-atendimento e APAE-gestao-escolar — os dois estão fora do piloto por
decisão, não por esquecimento.

Critérios de Aceite

• O documento traz os quatro blocos obrigatórios, na ordem: objetivo, escopo, configuração, integração com o Renovate
• A tabela comparando Renovate e Trivy está no documento, com a pergunta que cada um responde
• O que o Trivy não faz está escrito de forma explícita
• A versão exata do Trivy usada no estudo está registrada
• O baseline foi medido no APAE e está em tabela, com contagem por severidade separada em Java, npm e sistema operacional
• A diferença de contagem entre varrer pom.xml e varrer o JAR gerado está medida e registrada, com os dois comandos
• A diferença entre scan-type: fs e scan-type: image está demonstrada com saída real, e não apenas descrita
• trivy.yaml e .trivyignore aparecem no documento como exemplo, com skip-dirs e com a política de expiração de exceção
• O fluxo Trivy-Renovate fim a fim está descrito etapa por etapa
• A lista do que sobra para o Trivy e o Renovate nunca vai pegar está no documento
• O que fazer com os dois lockfiles da raiz está decidido e registrado
• O documento recomenda se o Trivy entra no fluxo do APAE, e justifica com número medido
• Nenhum workflow, pom.xml, package.json, lockfile ou Dockerfile foi alterado no PR
• Nenhuma vulnerabilidade foi corrigida neste PR
• Nenhum token, senha ou credencial aparece no documento

Artefatos

Anexe ao PR:

Baseline. Saída de trivy fs no APAE, em texto, com o resumo por severidade.

Comparação pom contra JAR. As duas execuções lado a lado, mostrando a diferença de
contagem de dependências analisadas.

Varredura de imagem. Saída de trivy image nas duas imagens do APAE, apps/api e
apps/apae, construídas localmente. Se o resultado confirmar superfície de sistema
operacional quase nula, isso precisa aparecer como número — é o que sustenta a escolha de
imagem base distroless.