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:

1. Recibe el webhook de Antigena (validado con HMAC).
2. Asigna el modelo + severidad a una acción de contención mediante configuración YAML.
3. Llama a la API REST de ClearPass para asignar un nuevo rol de endpoint (VLAN de cuarentena), desconectar la sesión, o ambas.
4. Registra cada decisión en un libro contable SQLite para auditoría + liberación automática.
5. Notifica al SOC a través de Slack/Teams.
6. 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   │      │              │         │             │
                          └──────────────┘       └────────────────┘      └──────────────┘         └─────────────┘