zero-touch-containment

Puente Antigena (Darktrace) → Aruba ClearPass CoA — cuarentena de usuario/dispositivo en tiempo real basada en modelos. Cero clics del SOC entre detección y contención.

Implementación de referencia sanitizada de un patrón de integración NDR↔NAC operado a escala del sector financiero (miles de endpoints, SOC 24/7). Los bits específicos del cliente se reemplazaron con accesorios sintéticos; la arquitectura, el flujo de decisión y los patrones operativos son los reales.

Por qué existe esto

La promesa de las soluciones NDR (Darktrace, ExtraHop, Vectra) es la detección en segundos. La realidad en la mayoría de los bancos: detección en segundos, contención en horas — porque la transferencia del SOC a los equipos de NAC/cortafuegos es manual.

Este conjunto de herramientas cierra esa brecha al conectar Antigena (módulo de Respuesta Autónoma de Darktrace) con Aruba ClearPass a través de la API REST de ClearPass. Cuando un modelo de Darktrace se activa por encima de un umbral de severidad configurable, la herramienta:

Recibe el webhook de Antigena (validado con HMAC).
Asigna el modelo + severidad a una acción de contención mediante configuración YAML.
Llama a la API REST de ClearPass para asignar un nuevo rol de endpoint (VLAN de cuarentena), desconectar la sesión, o ambas.
Registra cada decisión en un libro contable SQLite para auditoría + liberación automática.
Notifica al SOC a través de Slack/Teams.
Reenvía eventos de auditoría estructurados al SIEM (LogRhythm, Elastic).

Latencia media de extremo a extremo desde que se activa el modelo hasta que la VLAN de cuarentena está activa: menos de 5 segundos.

Contenido

zero-touch-containment/
├── README.md                       ← Estás aquí
├── LICENSE
├── .gitignore
├── docs/
│   ├── architecture.md             ← Inmersión profunda en arquitectura + trazabilidad SOLID
│   └── lessons-learned.md          ← 10 lecciones de ejecutarlo en producción
│
├── webhook/                        ← Capa HTTP entrante (dividida por SRP)
│   ├── app.py                      ← Solo rutas FastAPI + ciclo de vida
│   ├── auth.py                     ← verify_hmac() — validación HMAC-SHA1
│   ├── replay.py                   ← ReplayCache — protección LRU contra repetición
│   └── models.py                   ← Esquema pydantic AntigenaEvent
│
├── engine/                         ← Motor de decisión basado en YAML
│   ├── decision.py                 ← DecisionEngine (depende del Protocolo QuarantineReader)
│   ├── rules.py                    ← Cargadores YAML para mapeo + lista blanca
│   └── models.py                   ← Action + MappingRule + ActionKind
│
├── clearpass/                      ← Adaptador NAC (implementa el Protocolo CoAClient)
│   ├── client.py                   ← ClearPassClient — operaciones CoA vía REST
│   ├── ports.py                    ← Protocolo CoAClient — puerto para cualquier backend NAC
│   └── auth.py                     ← TokenCache OAuth2
│
├── ledger/                         ← Libro contable SQLite (implementa 5 puertos — ISP aplicado)
│   ├── store.py                    ← SqliteLedger — implementación integral
│   ├── ports.py                    ← EventStore + QuarantineWriter + QuarantineReader
│   │                                 + ReleaseManager + HealthChecker (segregados)
│   └── schema.py                   ← Constante DDL SQL
│
├── cli/                            ← CLI de operaciones SOC
│   └── soc.py                      ← `ztc release-expired` + comandos planificados
│
├── config/
│   ├── mapping.example.yaml        ← Mapeo severidad → acción
│   └── allowlist.example.yaml      ← Lista VIP / nunca en cuarentena
│
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── .env.example
│
├── tests/                          ← 60 pruebas que cubren cada capa
│   ├── test_decision.py
│   ├── test_ledger.py
│   ├── test_webhook_helpers.py
│   ├── test_clearpass_client.py
│   ├── test_protocols.py           ← Pruebas estructurales de cumplimiento ISP/DIP
│   └── fixtures/sample_event.json
│
├── requirements.txt
└── pyproject.toml

Inicio rápido

git clone https://gitlab.com/zimlama/zero-touch-containment.git
cd zero-touch-containment

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp config/mapping.example.yaml config/mapping.yaml
cp config/allowlist.example.yaml config/allowlist.yaml
cp deploy/.env.example .env  # rellena CLEARPASS_HOST, credenciales OAUTH, secreto HMAC

# Ejecuta el receptor webhook
uvicorn webhook.app:app --host 0.0.0.0 --port 8080

# En otra terminal: reproduce un evento de ejemplo
curl -X POST http://localhost:8080/antigena \
  -H "Content-Type: application/json" \
  -H "X-Darktrace-Signature: sha1=$(echo -n @tests/fixtures/sample_event.json | openssl dgst -sha1 -hmac "$HMAC_SECRET" | awk '{print $2}')" \
  --data @tests/fixtures/sample_event.json

El webhook valida HMAC-SHA1, ejecuta el motor de decisión contra mapping.yaml y:

modo de prueba (predeterminado en desarrollo) → registra la acción que se habría tomado.
modo en vivo → llama a la API REST de ClearPass para aplicar.

Arquitectura (vista de una pantalla)

┌──────────────┐   1. webhook    ┌──────────────────┐   2. validar   ┌──────────────────┐
│  Darktrace   │ ──────────────▶ │  Receptor        │ ─────────────▶│  Motor de        │
│  Antigena    │  HMAC-SHA1      │  de webhook      │  analizar +    │  decisión        │
│  activa modelo│                 │  (FastAPI)       │  autenticar    │  (basado en YAML)│
└──────────────┘                 └──────────────────┘                └─────────┬────────┘
                                                                               │
                                                                               ▼
                                                                    3. resolver acción
                                                                    (lista blanca + límite de tasa)
                                                                               │
                                  ┌───────────────────────┬───────────────────────┼────────────────────────┐
                                  ▼                       ▼                       ▼                        ▼
                          ┌──────────────┐       ┌────────────────┐      ┌──────────────┐         ┌─────────────┐
                          │ ClearPass    │       │ Libro contable │      │ Notificación │         │ SIEM        │
                          │ API REST     │       │ SQLite         │      │ Slack/Teams  │         │ (registros  │
                          │ - cambio de  │       │ - estado       │      │              │         │  estructurados)│
                          │   rol        │       │ - liberación   │      │              │         │             │
                          │ - desconectar│       │   automática   │      │              │         │             │
                          └──────────────┘       └────────────────┘      └──────────────┘         └─────────────┘

Consulta docs/architecture.md para el desglose completo.

Stack tecnológico

Lo que esto NO es

❌ No es un reemplazo de Darktrace — consume la salida de Antigena, no la produce.
❌ No es un reemplazo de ClearPass — es una capa de orquestación ligera sobre la API REST de ClearPass.
❌ No es un SIEM — envía eventos estructurados a tu SIEM, no consulta ni correlaciona.
❌ No es para todos — solo es útil si ejecutas tanto Darktrace NDR como Aruba ClearPass NAC. Específico del proveedor por diseño.

Contexto del mundo real

Los patrones aquí surgieron de un compromiso de varios años de NDR + NAC en una institución financiera Tier-1 de LATAM:

Miles de endpoints bajo cobertura combinada NAC + NDR
Más de 500 vSensors en sucursales, centro de datos principal y entornos de endpoint corporativos
6 categorías de amenazas MITRE ATT&CK bajo Respuesta Autónoma: C2 beaconing, movimiento lateral, exfiltración de datos, anomalías UEBA, dispositivos no autorizados, ataques de protocolo
Reducción del 60 % en MTTR gracias a este puente bidireccional (vs. transferencia manual al SOC)
Reducción del 40 % en incidentes de seguridad mediante la cobertura de Respuesta Autónoma

El conjunto de herramientas es la versión destilada y sanitizada de esa integración. Los nombres de modelos, IDs de inquilinos, endpoints de ClearPass y planes de IP se reemplazaron con equivalentes sintéticos.

Lo que aprenderás de `docs/lessons-learned.md`

10 cosas que desearía que alguien me hubiera dicho antes del día uno de un despliegue en producción de Antigena↔ClearPass: fiabilidad del webhook, peculiaridades de la API REST de ClearPass, la diferencia entre cambio de rol y desconexión, tormentas de contención por falsos positivos y diseño de transferencia al operador.

Arquitectura (cumplimiento SOLID)

Capas hexagonales con puertos de Protocolo explícitos entre adaptadores concretos y código de orquestación:

Consulta docs/architecture.md para el desglose completo.

Ejecución de la suite de pruebas

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"
HMAC_SECRET=test-secret python -m pytest tests/ -v

60 pruebas que cubren el motor de decisión, el libro contable SQLite, la validación HMAC, la caché de repetición, el cliente ClearPass (asíncrono, simulado con respx) y el cumplimiento estructural del Protocolo.

Hoja de ruta

Receptor webhook + validación HMAC
Motor de decisión basado en YAML
Cliente REST ClearPass (cambio de rol + desconexión)
Libro contable SQLite + liberación automática
Puertos de Protocolo + refactorización de cumplimiento SOLID
Suite de 60 pruebas que cubren todas las capas
CLI de anulación del SOC — list, release, quarantine, audit (Nivel 2)
Capa de notificación Slack/Teams (Nivel 2)
Reenviador estructurado al SIEM (Nivel 2)

Acerca del autor

Leonardo Mejía — Arquitecto Senior de Ciberseguridad y SD-WAN · 15+ años Confianza Cero · Nube Híbrida · NDR · SD-WAN Empresarial

LinkedIn: linkedin.com/in/leonardomejia
GitHub: github.com/zimlama
Repositorio hermano: sdwan-automation-toolkit

Licencia

MIT — consulta LICENSE.

Los patrones en este repositorio son abstracciones sanitizadas, no código propietario de clientes. Úsalo libremente; se agradece la atribución.

Lenguaje	Python 3.11+
Web	FastAPI + Uvicorn (receptor webhook)
Cliente HTTP	`httpx` (asíncrono) + `tenacity` (reintento con backoff)
Autenticación	HMAC-SHA1 entrante (Darktrace) · OAuth2 client_credentials saliente (ClearPass)
Configuración	YAML — mapeo severidad → acción + lista blanca
Estado	SQLite + WAL — libro contable de cuarentena + liberación automática
Registro	`structlog` — salida JSON para ingesta del SIEM
Pruebas	`pytest` + `respx` (simulación httpx) + accesorios grabados
Despliegue	Docker Compose, amigable para VM única

SRP	`webhook/` dividido en `auth` + `replay` + `models` + enrutamiento. `clearpass/` dividido en `client` + `auth` + `ports`. `ledger/` dividido en `store` + `ports` + `schema`.
OCP	Nuevos backends NAC implementan el Protocolo `CoAClient` — sin cambios en webhook ni motor.
LSP	Las pruebas usan simulaciones en memoria que satisfacen los mismos Protocolos. El comportamiento del pipeline no cambia.
ISP	Libro contable dividido en 5 puertos segregados (`EventStore`, `QuarantineWriter`, `QuarantineReader`, `ReleaseManager`, `HealthChecker`). El webhook solo depende de los dos primeros; el motor solo de `QuarantineReader`.
DIP	`webhook/app.py` y `engine/decision.py` dependen de Protocolos, nunca de clases concretas.

zero-touch-containment

Más Populares

zero-touch-containment

Por qué existe esto

Contenido

Inicio rápido

Arquitectura (vista de una pantalla)

Stack tecnológico

Lo que esto NO es

Contexto del mundo real

Lo que aprenderás de docs/lessons-learned.md

Arquitectura (cumplimiento SOLID)

Ejecución de la suite de pruebas

Hoja de ruta

Acerca del autor

Licencia

Lo que aprenderás de `docs/lessons-learned.md`