zero-touch-containment

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.

Perché esiste

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:

Riceve il webhook Antigena (convalidato con HMAC).
Mappa il modello + la severità a un'azione di contenimento tramite configurazione YAML.
Chiama l'API REST di ClearPass per assegnare un nuovo ruolo endpoint (VLAN di quarantena), disconnettere la sessione, o entrambi.
Registra ogni decisione in un registro SQLite per audit e rilascio automatico.
Notifica il SOC tramite Slack/Teams.
Inoltra eventi di audit strutturati al SIEM (LogRhythm, Elastic).

Latenza mediana end-to-end dall'attivazione del modello alla VLAN di quarantena attiva: sotto i 5 secondi.

Cosa contiene

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

Avvio rapido

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:

modalità dry-run (predefinita in sviluppo) → registra l'azione che sarebbe stata eseguita
modalità live → chiama l'API REST di ClearPass per applicare

Architettura (vista a schermo singolo)

┌──────────────┐   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.

Stack tecnologico

Cosa NON è

❌ Non è un sostituto di Darktrace — consuma l'output di Antigena, non lo produce.
❌ Non è un sostituto di ClearPass — è un sottile strato di orchestrazione sopra l'API REST di ClearPass.
❌ Non è un SIEM — invia eventi strutturati al tuo SIEM, non esegue query/correlazioni.
❌ Non per tutti — utile solo se utilizzi sia Darktrace NDR che Aruba ClearPass NAC. Specifico per vendor per progettazione.

Contesto reale

I pattern qui provengono da un impegno pluriennale NDR + NAC presso un istituto finanziario Tier-1 in America Latina:

Migliaia di endpoint sotto copertura combinata NAC + NDR
Oltre 500 vSensors tra filiali, DC core e ambienti endpoint aziendali
6 categorie di minacce MITRE ATT&CK sotto Risposta Autonoma: beaconing C2, movimento laterale, esfiltrazione dati, anomalie UEBA, dispositivi rogue, attacchi di protocollo
Riduzione del 60% dell'MTTR grazie a questo ponte bidirezionale (rispetto al passaggio manuale del SOC)
Riduzione del 40% degli incidenti di sicurezza grazie alla copertura della Risposta Autonoma

Il toolkit è la versione distillata e sanificata di quell'integrazione. Nomi di modelli, ID tenant, endpoint ClearPass, piani IP sostituiti con equivalenti sintetici.

Cosa imparerai da `docs/lessons-learned.md`

10 cose che avrei voluto sapere prima del primo giorno di una distribuzione Antigena↔ClearPass in produzione — che coprono affidabilità del webhook, stranezze dell'API REST di ClearPass, la differenza tra cambio ruolo e disconnessione, tempeste di falsi positivi di contenimento e progettazione del passaggio operatore.

Architettura (conforme SOLID)

Layering esagonale con porte Protocollo esplicite tra adattatori concreti e codice di orchestrazione:

Vedi docs/architecture.md per la ripartizione completa.

Esecuzione della suite di test

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

60 test che coprono il motore decisionale, il registro SQLite, la convalida HMAC, la cache replay, il client ClearPass (asincrono, mock con respx) e la conformità strutturale ai Protocolli.

Roadmap

Ricevitore webhook + convalida HMAC
Motore decisionale basato su YAML
Client REST ClearPass (cambio ruolo + disconnessione)
Registro SQLite + rilascio automatico
Porte protocollo + refactoring conforme SOLID
Suite di 60 test che copre ogni livello
CLI per override SOC — list, release, quarantine, audit (Tier-2)
Livello di notifica Slack/Teams (Tier-2)
Inoltro strutturato al SIEM (Tier-2)

Informazioni sull'autore

Leonardo Mejía — Architetto senior di cybersecurity e SD-WAN · 15+ anni Zero Trust · Hybrid Cloud · NDR · Enterprise SD-WAN

LinkedIn: linkedin.com/in/leonardomejia
GitHub: github.com/zimlama
Repository portfolio gemello: sdwan-automation-toolkit

Licenza

MIT — vedi LICENSE.

I pattern in questo repository sono astrazioni sanificate, non codice cliente proprietario. Usa liberamente; l'attribuzione è gradita.

Linguaggio	Python 3.11+
Web	FastAPI + Uvicorn (ricevitore webhook)
Client HTTP	`httpx` (async) + `tenacity` (retry con backoff)
Autenticazione	HMAC-SHA1 in ingresso (Darktrace) · OAuth2 client_credentials in uscita (ClearPass)
Configurazione	YAML — mapping severità → azione + allowlist
Stato	SQLite + WAL — registro quarantene + rilascio automatico
Logging	`structlog` — output JSON per ingestione SIEM
Testing	`pytest` + `respx` (mock httpx) + fixture registrate
Deploy	Docker Compose, adatto a singola VM

SRP	`webhook/` suddiviso in `auth` + `replay` + `models` + routing. `clearpass/` suddiviso in `client` + `auth` + `ports`. `ledger/` suddiviso in `store` + `ports` + `schema`.
OCP	Nuovi backend NAC implementano il protocollo `CoAClient` — nessuna modifica a webhook o motore.
LSP	I test utilizzano finti in-memory che soddisfano gli stessi Protocolli. Comportamento della pipeline invariato.
ISP	Ledger suddiviso in 5 porte separate (`EventStore`, `QuarantineWriter`, `QuarantineReader`, `ReleaseManager`, `HealthChecker`). Il webhook dipende solo dalle prime due; il motore solo da `QuarantineReader`.
DIP	`webhook/app.py` e `engine/decision.py` dipendono dai Protocolli, mai da classi concrete.

zero-touch-containment

Più Popolari

zero-touch-containment

Perché esiste

Cosa contiene

Avvio rapido

Architettura (vista a schermo singolo)

Stack tecnologico

Cosa NON è

Contesto reale

Cosa imparerai da docs/lessons-learned.md

Architettura (conforme SOLID)

Esecuzione della suite di test

Roadmap

Informazioni sull'autore

Licenza

Cosa imparerai da `docs/lessons-learned.md`