lama-labs/zero-touch-containmentAntigena (Darktrace) → Aruba ClearPass CoA bridge — quarantena in tempo reale di utenti/dispositivi basata su modelli. Zero clic SOC. Architettura esagonale, copertura dei test all'82%.
Ponte Antigena (Darktrace) → Aruba ClearPass CoA — quarantena in tempo reale di utenti/dispositivi basata su modelli. Zero click SOC tra rilevamento e contenimento.
Implementazione di riferimento sanificata di un pattern di integrazione NDR↔NAC operato su scala finanziaria (migliaia di endpoint, SOC 24/7). Elementi specifici del cliente sono stati sostituiti con fixture sintetiche; l'architettura, il flusso decisionale e i pattern operativi sono quelli reali.
La promessa di NDR (Darktrace, ExtraHop, Vectra) è il rilevamento in secondi. La realtà nella maggior parte delle banche: rilevamento in secondi, contenimento in ore — perché il passaggio dal SOC ai team NAC/firewall è manuale.
Questo toolkit colma quel divario collegando Antigena (modulo di risposta autonoma di Darktrace) ad Aruba ClearPass tramite l'API REST di ClearPass. Quando un modello Darktrace si attiva superando una soglia di severità configurabile, il toolkit:
Latenza mediana end-to-end dall'attivazione del modello alla VLAN di quarantena attiva: sotto i 5 secondi.
zero-touch-containment/
├── README.md ← Sei qui
├── LICENSE
├── .gitignore
├── docs/
│ ├── architecture.md ← Approfondimento completo dell'architettura + tracciato SOLID
│ └── lessons-learned.md ← 10 lezioni apprese dall'esecuzione in produzione
│
├── webhook/ ← Livello HTTP in ingresso (diviso per SRP)
│ ├── app.py ← Solo route FastAPI + ciclo di vita
│ ├── auth.py ← verify_hmac() — convalida HMAC-SHA1
│ ├── replay.py ← ReplayCache — protezione replay LRU
│ └── models.py ← Schema pydantic AntigenaEvent
│
├── engine/ ← Motore decisionale basato su YAML
│ ├── decision.py ← DecisionEngine (dipende dal protocollo QuarantineReader)
│ ├── rules.py ← Caricatori YAML per mapping e allowlist
│ └── models.py ← Action + MappingRule + ActionKind
│
├── clearpass/ ← Adattatore NAC (implementa il protocollo CoAClient)
│ ├── client.py ← ClearPassClient — operazioni REST in stile CoA
│ ├── ports.py ← Protocollo CoAClient — interfaccia per qualsiasi backend NAC
│ └── auth.py ← TokenCache OAuth2
│
├── ledger/ ← Registro SQLite (implementa 5 porte — ISP applicato)
│ ├── store.py ← SqliteLedger — implementazione tutto-in-uno
│ ├── ports.py ← EventStore + QuarantineWriter + QuarantineReader
│ │ + ReleaseManager + HealthChecker (separati)
│ └── schema.py ← Costante DDL SQL
│
├── cli/ ← CLI per operazioni SOC
│ └── soc.py ← `ztc release-expired` + comandi pianificati
│
├── config/
│ ├── mapping.example.yaml ← Mapping severità → azione
│ └── allowlist.example.yaml ← Lista VIP / mai in quarantena
│
├── deploy/
│ ├── docker-compose.yml
│ ├── Dockerfile
│ └── .env.example
│
├── tests/ ← 60 test che coprono ogni livello
│ ├── test_decision.py
│ ├── test_ledger.py
│ ├── test_webhook_helpers.py
│ ├── test_clearpass_client.py
│ ├── test_protocols.py ← Test di conformità strutturale ISP/DIP
│ └── fixtures/sample_event.json
│
├── requirements.txt
└── pyproject.toml
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 # inserisci CLEARPASS_HOST, credenziali OAuth, segreto HMAC
# Avvia il ricevitore webhook
uvicorn webhook.app:app --host 0.0.0.0 --port 8080
# In un'altra shell: riproduci un evento di esempio
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
Il webhook convalida HMAC-SHA1, esegue il motore decisionale contro mapping.yaml e:
┌──────────────┐ 1. webhook ┌──────────────────┐ 2. convalida ┌──────────────────┐
│ Darktrace │ ──────────────▶ │ Ricevitore │ ───────────────▶ │ Motore │
│ Antigena │ HMAC-SHA1 │ webhook │ parse + auth │ decisionale │
│ attiva modello│ │ (FastAPI) │ │ (basato su YAML)│
└──────────────┘ └──────────────────┘ └─────────┬────────┘
│
▼
3. risolvi azione
(allowlist + rate limit)
│
┌───────────────────────┬───────────────────────┼────────────────────────┐
▼ ▼ ▼ ▼
┌──────────────┐ ┌────────────────┐ ┌──────────────┐ ┌─────────────┐
│ ClearPass │ │ Registro │ │ Notifica │ │ SIEM │
│ API REST │ │ SQLite │ │ Slack/Teams │ │ (log │
│ - cambio ruolo│ │ - stato │ │ │ │ strutturati)│
│ - disconnessione│ │ - rilascio auto │ │ │ │ │
└──────────────┘ └────────────────┘ └──────────────┘ └─────────────┘
Vedi docs/architecture.md per la ripartizione completa.