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 :

1. Reçoit le webhook Antigena (validé HMAC).
2. Mappe le modèle + la sévérité à une action de confinement via une configuration YAML.
3. Appelle l'API REST ClearPass pour appliquer un nouveau rôle de terminal (VLAN de quarantaine), déconnecter la session, ou les deux.
4. Enregistre chaque décision dans un journal SQLite pour audit et libération automatique.
5. Notifie le SOC via Slack/Teams.
6. 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)