Agente DepAlert

CTWall

Esta ferramenta faz parte da plataforma CTWall. Veja: CTWall

Descrição

O DepAlert é uma gate de segurança de código aberto para seu pipeline CI/CD. Ele analisa SBOMs contra dados de inteligência de malware e informa rapidamente se sua construção inclui pacotes maliciosos conhecidos.

O DepAlert resolve problemas essenciais da cadeia de suprimentos de software que impactam diretamente a velocidade de lançamento, risco e custo:

• Impede que malware chegue à produção ao transformar a análise de SBOM em uma gate automática de lançamento CI/CD.
• Reduz gargalos de segurança ao fornecer às equipes um veredito rápido e determinístico (MALWARE, CLEAN, UNKNOWN) em cada execução do pipeline.
• Padroniza decisões de risco entre equipes com um modelo de política consistente (fail-on) e um fluxo de exceção auditável.
• Diminui a exposição a incidentes e conformidade ao impor verificações com escopo de projeto antes da implantação, e não depois.
• Melhora a produtividade do desenvolvedor ao substituir transferências manuais de segurança por uma única etapa CLI que pode ser reutilizada em qualquer pipeline.

Início rápido

Veja 00_quick_start.md para instruções passo a passo.

Propósito da ferramenta

depalert é uma CLI de CI/CD que:

1. Envia um SBOM para o CTWall (POST /api/v1/ingest)
2. Aguarda sincronamente pelo veredito da revisão (GET /api/v1/tests/{testId}/revisions/{revisionId}/depalert-verdict)
3. Retorna um resultado e código de saída amigáveis ao pipeline

A ferramenta é com escopo de projeto. Você pode selecionar o projeto alvo por:

• project-id (UUID), ou
• project-name (resolvido através da API).

Se ambos forem fornecidos, project-id tem precedência.

Resultados do Depalert

O DepAlert retorna um resultado por revisão:

• CLEAN - nenhuma detecção de malware encontrada - saída 0
• MALWARE - pelo menos uma detecção de malware foi encontrada na revisão - saída 1
• UNKNOWN - a análise ainda não está completa - saída 2 (ou saída 0 com fail-on=NONE)

Formato de saída CLI:

VERDICT: <MALWARE|CLEAN|UNKNOWN> (malware=<n> clean=<n> unknown=<n> total=<n>, elapsed=<t>)

O modo JSON está disponível via --format json (ou CTWALL_OUTPUT=json).

Exemplo de saída JSON:

{
  "version": "1.1.0",
  "status": "success",
  "exitCode": 0,
  "projectId": "28e241e3-b924-4e1a-abc2-d592e8dd811c",
  "testId": "13271a70-cf47-4f3b-9e33-cb41ed0c793e",
  "revisionId": "c4d1f1a4-c018-488e-9dd0-6cfdbed83bf3",
  "verdict": "CLEAN",
  "malwareComponents": 0,
  "cleanComponents": 12,
  "unknownComponents": 0,
  "totalComponents": 12,
  "elapsedMs": 1842,
  "timedOut": false,
  "failOn": "MALWARE",
  "message": "depalert completed"
}

Resultado esperado

VERDICT: <MALWARE|CLEAN|UNKNOWN> (malware=<n> clean=<n> unknown=<n> total=<n>, elapsed=<t>)

• código de saída 0 = aprovado
• código de saída 1 = falha de política ou erro de execução
• código de saída 2 = veredito final é UNKNOWN e fail-on não é NONE

Configuração CLI e ambiente

Bandeira	Variável de ambiente	Obrigatório	Padrão	Descrição
--url	CTWALL_API_URL	sim	http://localhost:8080	URL da API CTWall
--key	CTWALL_API_KEY	não	vazio	Token da API (Authorization: Bearer ...)
--project-id	CTWALL_PROJECT_ID	condicional	nenhum	UUID do projeto alvo (tem prioridade sobre project-name)
--project-name	CTWALL_PROJECT_NAME	condicional	nenhum	Nome do projeto alvo (resolvido para UUID através da API)
--file	CTWALL_SBOM_FILE (ou legado SBOM_FILE)	sim	nenhum	Caminho do arquivo SBOM
--product	CTWALL_PRODUCT	sim	nenhum	Nome do produto
--scope	CTWALL_SCOPE	sim	nenhum	Nome do escopo
--test	CTWALL_TEST	sim	nenhum	Nome do teste
--fail-on	CTWALL_FAIL_ON	não	MALWARE	Lista CSV de vereditos: MALWARE,CLEAN,UNKNOWN ou NONE
--ignore-file	CTWALL_IGNORE_FILE	não	depalert.ignore	Arquivo opcional de exceções YAML para substituição local de veredito e atualizações de triagem
--format	CTWALL_OUTPUT	não	text	Formato de saída: text ou json
--timeout-seconds	CTWALL_WAIT_TIMEOUT_SECONDS	não	180	Tempo limite de espera síncrona em segundos
--allow-insecure	CTWALL_ALLOW_INSECURE	não	false	Permitir HTTP para hosts não locais
--skip-tls-verify	CTWALL_SKIP_TLS_VERIFY	não	false	Ignorar verificação de certificado TLS para HTTPS (inseguro, apenas teste)

Regras de segmentação de projeto

• Pelo menos um de project-id ou project-name é obrigatório.
• project-name é resolvido usando GET /api/v1/projects.
• A correspondência de nome é exata e insensível a maiúsculas/minúsculas.
• Se mais de um projeto ativo corresponder ao mesmo nome, a execução falha com um erro de ambiguidade.
• Valores obrigatórios podem ser fornecidos por bandeiras ou variáveis de ambiente; bandeiras têm precedência.

Conexão

• https é obrigatório para hosts não locais.
• Para ambientes de teste/não produção você pode usar:
  • --allow-insecure, ou
  • CTWALL_ALLOW_INSECURE=true.
• Para certificados HTTPS autoassinados (apenas teste/não produção) você pode usar:
  • --skip-tls-verify, ou
  • CTWALL_SKIP_TLS_VERIFY=true.

Segurança

Por favor, veja

Licença

O DepAlert está licenciado sob a Licença BSD 3-Clause