Agente DepAlert

CTWall

Esta herramienta forma parte de la plataforma CTWall. Ver: CTWall

Descripción

DepAlert es una puerta de seguridad de código abierto para tu pipeline CI/CD. Analiza SBOMs contra datos de inteligencia de malware y te dice rápidamente si tu compilación incluye paquetes maliciosos conocidos.

DepAlert resuelve problemas fundamentales de la cadena de suministro de software que impactan directamente en la velocidad de lanzamiento, el riesgo y el costo:

• Evita que el malware llegue a producción convirtiendo el análisis de SBOM en una puerta de lanzamiento automática en el CI/CD.
• Reduce los cuellos de botella de seguridad al dar a los equipos un veredicto rápido y determinista (MALWARE, CLEAN, UNKNOWN) en cada ejecución del pipeline.
• Estandariza las decisiones de riesgo entre equipos con un modelo de políticas consistente (fail-on) y un flujo de trabajo de excepciones auditable.
• Reduce la exposición a incidentes y cumplimiento normativo al aplicar comprobaciones con ámbito de proyecto antes del despliegue, no después.
• Mejora la productividad de los desarrolladores reemplazando los traspasos manuales de seguridad con un solo paso de CLI que puede reutilizarse en cualquier pipeline.

Inicio rápido

Consulta 00_quick_start.md para obtener instrucciones paso a paso.

Propósito de la herramienta

depalert es una CLI de CI/CD que:

1. Sube un SBOM a CTWall (POST /api/v1/ingest)
2. Espera sincrónicamente el veredicto de la revisión (GET /api/v1/tests/{testId}/revisions/{revisionId}/depalert-verdict)
3. Devuelve un resultado amigable para el pipeline y un código de salida

La herramienta está limitada al ámbito del proyecto. Puedes seleccionar el proyecto objetivo mediante:

• project-id (UUID), o
• project-name (resuelto a través de la API).

Si se proporcionan ambos, project-id tiene prioridad.

Resultados de Depalert

DepAlert devuelve un resultado por revisión:

• CLEAN - no se detectó ningún hallazgo de malware - salida 0
• MALWARE - se detectó al menos un hallazgo de malware en la revisión - salida 1
• UNKNOWN - el análisis aún no está completo - salida 2 (o salida 0 con fail-on=NONE)

Formato de salida de la CLI:

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

El modo JSON está disponible mediante --format json (o CTWALL_OUTPUT=json).

Ejemplo de salida 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 salida 0 = aprobado
• código de salida 1 = fallo de política o error en tiempo de ejecución
• código de salida 2 = el veredicto final es UNKNOWN y fail-on no es NONE

Configuración de CLI y entorno

Flag	ENV	Requerido	Predeterminado	Descripción
--url	CTWALL_API_URL	sí	http://localhost:8080	URL de la API de CTWall
--key	CTWALL_API_KEY	no	vacío	Token de API (Authorization: Bearer ...)
--project-id	CTWALL_PROJECT_ID	condicional	ninguno	UUID del proyecto objetivo (tiene prioridad sobre project-name)
--project-name	CTWALL_PROJECT_NAME	condicional	ninguno	Nombre del proyecto objetivo (resuelto a UUID a través de la API)
--file	CTWALL_SBOM_FILE (o legacy SBOM_FILE)	sí	ninguno	Ruta del archivo SBOM
--product	CTWALL_PRODUCT	sí	ninguno	Nombre del producto
--scope	CTWALL_SCOPE	sí	ninguno	Nombre del ámbito
--test	CTWALL_TEST	sí	ninguno	Nombre de la prueba
--fail-on	CTWALL_FAIL_ON	no	MALWARE	Lista CSV de veredictos: MALWARE,CLEAN,UNKNOWN o NONE
--ignore-file	CTWALL_IGNORE_FILE	no	depalert.ignore	Archivo YAML opcional de excepciones para anulación local de veredicto + actualizaciones de triaje
--format	CTWALL_OUTPUT	no	text	Formato de salida: text o json
--timeout-seconds	CTWALL_WAIT_TIMEOUT_SECONDS	no	180	Tiempo de espera de sincronización en segundos
--allow-insecure	CTWALL_ALLOW_INSECURE	no	false	Permitir HTTP para hosts no locales
--skip-tls-verify	CTWALL_SKIP_TLS_VERIFY	no	false	Omitir verificación del certificado TLS para HTTPS (inseguro, solo pruebas)

Reglas de selección de proyecto

• Se requiere al menos uno de project-id o project-name.
• project-name se resuelve usando GET /api/v1/projects.
• La coincidencia de nombres es exacta y no distingue mayúsculas/minúsculas.
• Si más de un proyecto activo coincide con el mismo nombre, la ejecución falla con un error de ambigüedad.
• Los valores requeridos pueden proporcionarse mediante flags o variables de entorno; los flags tienen prioridad.

Conexión

• Se requiere https para hosts no locales.
• Para entornos de prueba/no producción puedes usar:
  • --allow-insecure, o
  • CTWALL_ALLOW_INSECURE=true.
• Para certificados HTTPS autofirmados (solo prueba/no producción) puedes usar:
  • --skip-tls-verify, o
  • CTWALL_SKIP_TLS_VERIFY=true.

Seguridad

Por favor, consulta

Licencia

DepAlert está licenciado bajo la Licencia BSD de 3 Cláusulas