zero-touch-containment

Antigena (Darktrace) → Pont Aruba ClearPass CoA — quarantaine en temps réel des utilisateurs/appareils pilotée par modèles. Zéro clic SOC entre la détection et le confinement.

Implémentation de référence anonymisée d'un modèle d'intégration NDR↔NAC en production, exploité à l'échelle du secteur financier (plusieurs milliers de terminaux, SOC 24h/24). Les éléments spécifiques au client ont été remplacés par des données synthétiques ; l'architecture, le flux de décision et les schémas opérationnels sont réels.

Pourquoi cela existe

La promesse des NDR (Darktrace, ExtraHop, Vectra) est la détection en quelques secondes. La réalité dans la plupart des banques : détection en secondes, confinement en heures — car la transmission SOC vers les équipes NAC/pare-feu est manuelle.

Cet outil comble cet écart en faisant le pont entre Antigena (le module de réponse autonome de Darktrace) et Aruba ClearPass via l'API REST ClearPass. Lorsqu'un modèle Darktrace dépasse un seuil de sévérité configurable, l'outil :

Reçoit le webhook Antigena (validé HMAC).
Mappe le modèle + la sévérité à une action de confinement via une configuration YAML.
Appelle l'API REST ClearPass pour appliquer un nouveau rôle de terminal (VLAN de quarantaine), déconnecter la session, ou les deux.
Enregistre chaque décision dans un journal SQLite pour audit et libération automatique.
Notifie le SOC via Slack/Teams.
Transmet des événements d'audit structurés au SIEM (LogRhythm, Elastic).

Latence médiane de bout en bout entre le déclenchement du modèle et l'activation de la VLAN de quarantaine : moins de 5 secondes.

Ce qu'il contient

zero-touch-containment/
├── README.md                       ← Vous êtes ici
├── LICENSE
├── .gitignore
├── docs/
│   ├── architecture.md             ← Analyse approfondie de l'architecture + traçabilité SOLID
│   └── lessons-learned.md          ← 10 leçons tirées de l'exploitation en production
│
├── webhook/                        ← Couche HTTP entrante (divisée par SRP)
│   ├── app.py                      ← Routes FastAPI + cycle de vie uniquement
│   ├── auth.py                     ← verify_hmac() — validation HMAC-SHA1
│   ├── replay.py                   ← ReplayCache — protection LRU contre le rejeu
│   └── models.py                   ← Schéma pydantic AntigenaEvent
│
├── engine/                         ← Moteur de décision piloté par YAML
│   ├── decision.py                 ← DecisionEngine (dépend du protocole QuarantineReader)
│   ├── rules.py                    ← Chargeurs YAML pour mapping et liste blanche
│   └── models.py                   ← Action + MappingRule + ActionKind
│
├── clearpass/                      ← Adaptateur NAC (implémente le protocole CoAClient)
│   ├── client.py                   ← ClearPassClient — opérations REST de type CoA
│   ├── ports.py                    ← Protocole CoAClient — port pour tout backend NAC
│   └── auth.py                     ← OAuth2 TokenCache
│
├── ledger/                         ← Journal SQLite (implémente 5 ports — ISP appliqué)
│   ├── store.py                    ← SqliteLedger — implémentation tout-en-un
│   ├── ports.py                    ← EventStore + QuarantineWriter + QuarantineReader
│   │                                 + ReleaseManager + HealthChecker (séparés)
│   └── schema.py                   ← Constante SQL DDL
│
├── cli/                            ← CLI d'opérations SOC
│   └── soc.py                      ← `ztc release-expired` + commandes prévues
│
├── config/
│   ├── mapping.example.yaml        ← Mapping sévérité → action
│   └── allowlist.example.yaml      ← Liste VIP / jamais en quarantaine
│
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── .env.example
│
├── tests/                          ← 60 tests couvrant chaque couche
│   ├── test_decision.py
│   ├── test_ledger.py
│   ├── test_webhook_helpers.py
│   ├── test_clearpass_client.py
│   ├── test_protocols.py           ← Tests structurels de conformité ISP/DIP
│   └── fixtures/sample_event.json
│
├── requirements.txt
└── pyproject.toml

Démarrage rapide

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  # remplissez CLEARPASS_HOST, identifiants OAuth, secret HMAC

# Lancez le récepteur webhook
uvicorn webhook.app:app --host 0.0.0.0 --port 8080

# Dans un autre terminal : rejouez un événement exemple
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

Le webhook valide HMAC-SHA1, exécute le moteur de décision par rapport à mapping.yaml et soit :

mode dry-run (par défaut en dev) → enregistre l'action qui aurait été prise
mode live → appelle l'API REST ClearPass pour appliquer la mesure

Architecture (vue d'ensemble)

┌──────────────────┐   1. webhook    ┌────────────────────────┐   2. valider    ┌─────────────────────────────┐
│  Darktrace       │ ──────────────▶ │  Récepteur Webhook     │ ───────────────▶ │  Moteur de décision        │
│  Antigena        │  HMAC-SHA1      │  (FastAPI)             │  analyser + auth│  (piloté par YAML)           │
│  déclenche modèle │                 │                        │                  │                              │
└──────────────────┘                 └────────────────────────┘                  └──────────┬──────────────────┘
                                                                                             │
                                                                                             ▼
                                                                                  3. résoudre l'action
                                                                                   (liste blanche + limite de débit)
                                                                                             │
                         ┌────────────────────────┬──────────────────────────────────────────┼─────────────────────────────────┐
                         ▼                        ▼                                          ▼                                 ▼
                 ┌──────────────────┐    ┌──────────────────────┐              ┌──────────────────┐            ┌────────────────┐
                 │ API REST         │    │ Journal SQLite       │              │ Notification     │            │ SIEM           │
                 │ ClearPass        │    │ - état               │              │ Slack/Teams      │            │ (journaux      │
                 │ - changement     │    │ - libération         │              │                  │            │  structurés)   │
                 │   de rôle        │    │   automatique        │              │                  │            │                │
                 │ - déconnexion    │    │                      │              │                  │            │                │
                 └──────────────────┘    └──────────────────────┘              └──────────────────┘            └────────────────┘

Voir docs/architecture.md pour le détail complet.

Pile technologique

Ce que ce n'est PAS

❌ Pas un remplacement de Darktrace — il consomme la sortie d'Antigena, ne la produit pas.
❌ Pas un remplacement de ClearPass — c'est une fine couche d'orchestration au-dessus de l'API REST de ClearPass.
❌ Pas un SIEM — il envoie des événements structurés à votre SIEM, il n'interroge ni ne corréle.
❌ Pas pour tout le monde — utile uniquement si vous utilisez à la fois Darktrace NDR et Aruba ClearPass NAC. Spécifique au fournisseur par conception.

Contexte réel

Les modèles ici proviennent d'une intégration NDR + NAC de plusieurs années dans une institution financière de premier plan en Amérique latine :

Plusieurs milliers de terminaux sous couverture combinée NAC + NDR
500+ vSensors répartis dans les succursales, le centre de données principal et les environnements de postes de travail corporatifs
6 catégories de menaces MITRE ATT&CK sous réponse autonome : beaconing C2, mouvement latéral, exfiltration de données, anomalies UEBA, appareils non autorisés, attaques de protocole
Réduction de 60 % du MTTR grâce à ce pont bidirectionnel (vs transmission manuelle SOC)
Réduction de 40 % des incidents de sécurité grâce à la couverture de réponse autonome

L'outil est la version distillée et anonymisée de cette intégration. Les noms de modèles, ID de locataires, endpoints ClearPass, plans IP ont été remplacés par des équivalents synthétiques.

Ce que vous apprendrez de `docs/lessons-learned.md`

10 choses que j'aurais aimé qu'on me dise avant le premier jour d'un déploiement en production Antigena↔ClearPass — couvrant la fiabilité des webhooks, les bizarreries de l'API REST ClearPass, la différence entre changement de rôle et déconnexion, les orages de faux positifs de confinement, et la conception de la transmission opérateur.

Architecture (conforme SOLID)

Couches hexagonales avec des ports de protocole explicites entre les adaptateurs concrets et le code d'orchestration :

Voir docs/architecture.md pour le détail complet.

Exécution de la suite de tests

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

60 tests couvrant le moteur de décision, le journal SQLite, la validation HMAC, le cache anti-rejeu, le client ClearPass (asynchrone, mocké avec respx), et la conformité structurelle aux protocoles.

Feuille de route

Récepteur webhook + validation HMAC
Moteur de décision piloté par YAML
Client REST ClearPass (changement de rôle + déconnexion)
Journal SQLite + libération automatique
Ports de protocole + refactoring conforme SOLID
Suite de 60 tests couvrant chaque couche
CLI d'intervention SOC — list, release, quarantine, audit (Tier-2)
Couche de notification Slack/Teams (Tier-2)
Transmetteur structuré vers le SIEM (Tier-2)

À propos de l'auteur

Leonardo Mejía — Architecte Senior en Cybersécurité & SD-WAN · 15+ ans Zero Trust · Cloud Hybride · NDR · SD-WAN Entreprise

LinkedIn : linkedin.com/in/leonardomejia
GitHub : github.com/zimlama
Dépôt de portefeuille associé : sdwan-automation-toolkit

Licence

MIT — voir LICENSE.

Les modèles de ce dépôt sont des abstractions anonymisées, pas du code client propriétaire. Utilisez librement ; une attribution est appréciée.

Langage	Python 3.11+
Web	FastAPI + Uvicorn (récepteur webhook)
Client HTTP	`httpx` (asynchrone) + `tenacity` (réessai avec backoff)
Authentification	HMAC-SHA1 entrant (Darktrace) · OAuth2 client_credentials sortant (ClearPass)
Configuration	YAML — mapping sévérité → action + liste blanche
État	SQLite + WAL — journal de quarantaine + libération automatique
Journalisation	`structlog` — sortie JSON pour ingestion SIEM
Tests	`pytest` + `respx` (mock httpx) + fixtures enregistrées
Déploiement	Docker Compose, compatible VM unique

SRP	`webhook/` divisé en `auth` + `replay` + `models` + routage. `clearpass/` divisé en `client` + `auth` + `ports`. `ledger/` divisé en `store` + `ports` + `schema`.
OCP	Les nouveaux backends NAC implémentent le protocole `CoAClient` — aucune modification du webhook ou du moteur.
LSP	Les tests utilisent des faux en mémoire qui satisfont les mêmes protocoles. Comportement du pipeline inchangé.
ISP	Le journal divisé en 5 ports séparés (`EventStore`, `QuarantineWriter`, `QuarantineReader`, `ReleaseManager`, `HealthChecker`). Le webhook ne dépend que des deux premiers ; le moteur seulement de `QuarantineReader`.
DIP	`webhook/app.py` et `engine/decision.py` dépendent des protocoles, jamais des classes concrètes.

zero-touch-containment

Populaires

zero-touch-containment

Pourquoi cela existe

Ce qu'il contient

Démarrage rapide

Architecture (vue d'ensemble)

Pile technologique

Ce que ce n'est PAS

Contexte réel

Ce que vous apprendrez de docs/lessons-learned.md

Architecture (conforme SOLID)

Exécution de la suite de tests

Feuille de route

À propos de l'auteur

Licence

Ce que vous apprendrez de `docs/lessons-learned.md`