zero-touch-containment

Antigena (Darktrace) → Aruba ClearPass CoA-Brücke — modellgetriebene, Echtzeit-Quarantäne von Benutzern/Geräten. Null SOC-Klicks zwischen Erkennung und Eindämmung.

Bereinigte Referenzimplementierung eines Produktions-NDR↔NAC-Integrationsmusters, betrieben im Finanzsektor (mehrere tausend Endpunkte, 24/7 SOC). Kundenspezifische Teile durch synthetische Fixtures ersetzt; die Architektur, der Entscheidungsfluss und die Betriebsmuster sind die echten.

---

Warum es das gibt

Die Verheißung von NDR (Darktrace, ExtraHop, Vectra) ist Erkennung in Sekunden. Die Realität in den meisten Banken: Erkennung in Sekunden, Eindämmung in Stunden – weil die SOC-Übergabe an NAC/Firewall-Teams manuell ist.

Dieses Toolkit schließt diese Lücke, indem es Antigena (Darktraces Autonomous Response-Modul) mit Aruba ClearPass über die ClearPass REST API verbindet. Wenn ein Darktrace-Modell oberhalb eines konfigurierbaren Schweregradschwellenwerts auslöst, führt das Toolkit Folgendes aus:

1. Empfängt den Antigena-Webhook (HMAC-validiert).
2. Ordnet das Modell + den Schweregrad über eine YAML-Konfiguration einer Eindämmungsaktion zu.
3. Ruft die ClearPass REST API auf, um eine neue Endpunktrolle (Quarantäne-VLAN) zu setzen, die Sitzung zu trennen oder beides.
4. Protokolliert jede Entscheidung in einem SQLite-Ledger für Audit + automatische Freigabe.
5. Benachrichtigt das SOC via Slack/Teams.
6. Leitet strukturierte Audit-Ereignisse an das SIEM (LogRhythm, Elastic) weiter.

Durchschnittliche Ende-zu-Ende-Latenz von Modellauslösung zu aktivem Quarantäne-VLAN: unter 5 Sekunden.

---

Was drin ist

zero-touch-containment/
├── README.md                       ← Du bist hier
├── LICENSE
├── .gitignore
├── docs/
│   ├── architecture.md             ← Ausführlicher Architektur-Deep-Dive + SOLID-Trace
│   └── lessons-learned.md          ← 10 Lektionen aus dem Betrieb in der Produktion
│
├── webhook/                        ← Eingehende HTTP-Ebene (nach SRP aufgeteilt)
│   ├── app.py                      ← FastAPI-Routen + nur Lebenszyklus
│   ├── auth.py                     ← verify_hmac() — HMAC-SHA1-Validierung
│   ├── replay.py                   ← ReplayCache — LRU-Replay-Schutz
│   └── models.py                   ← AntigenaEvent pydantic-Schema
│
├── engine/                         ← YAML-gesteuerte Entscheidungsengine
│   ├── decision.py                 ← DecisionEngine (abhängig von QuarantineReader Protocol)
│   ├── rules.py                    ← YAML-Lader für Mapping + Allowlist
│   └── models.py                   ← Action + MappingRule + ActionKind
│
├── clearpass/                      ← NAC-Adapter (implementiert CoAClient Protocol)
│   ├── client.py                   ← ClearPassClient — REST CoA-artige Operationen
│   ├── ports.py                    ← CoAClient Protocol — Schnittstelle für beliebiges NAC-Backend
│   └── auth.py                     ← OAuth2 TokenCache
│
├── ledger/                         ← SQLite-Ledger (implementiert 5 Ports — ISP angewendet)
│   ├── store.py                    ← SqliteLedger — All-in-One-Implementierung
│   ├── ports.py                    ← EventStore + QuarantineWriter + QuarantineReader
│   │                                 + ReleaseManager + HealthChecker (getrennt)
│   └── schema.py                   ← SQL-DDL-Konstante
│
├── cli/                            ← SOC-Betriebs-CLI
│   └── soc.py                      ← `ztc release-expired` + geplante Befehle
│
├── config/
│   ├── mapping.example.yaml        ← Schweregrad → Aktions-Mapping
│   └── allowlist.example.yaml      ← VIP/Nie-quarantäne-Liste
│
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── .env.example
│
├── tests/                          ← 60 Tests, die jede Schicht abdecken
│   ├── test_decision.py
│   ├── test_ledger.py
│   ├── test_webhook_helpers.py
│   ├── test_clearpass_client.py
│   ├── test_protocols.py           ← Strukturelle ISP/DIP-Compliance-Tests
│   └── fixtures/sample_event.json
│
├── requirements.txt
└── pyproject.toml

---

Schnellstart

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  # CLEARPASS_HOST, OAUTH-Anmeldedaten, HMAC-Secret eintragen

# Webhook-Empfänger starten
uvicorn webhook.app:app --host 0.0.0.0 --port 8080

# In einer anderen Shell: Beispielereignis abspielen
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

Der Webhook validiert HMAC-SHA1, führt die Entscheidungsengine gegen mapping.yaml aus und führt entweder:

• Dry-Run-Modus (Standard in der Entwicklung) → protokolliert die Aktion, die ergriffen worden wäre
• Live-Modus → ruft die ClearPass REST API auf, um die Maßnahme durchzusetzen

---

Architektur (Auf-einen-Blick)

┌──────────────┐   1. Webhook   ┌──────────────────┐   2. validieren  ┌──────────────────┐
│  Darktrace   │ ──────────────▶ │  Webhook         │ ───────────────▶ │  Entscheidungs-  │
│  Antigena    │  HMAC-SHA1     │  Empfänger       │  parsen + auth  │  engine          │
│  löst Modell │                │  (FastAPI)       │                 │  (YAML-gesteuert)│
└──────────────┘                └──────────────────┘                 └─────────┬────────┘
                                                                                │
                                                                                ▼
                                                                    3. Aktion auflösen
                                                                    (Allowlist + Ratenbegrenzung)
                                                                                │
                                  ┌───────────────────────┬─────────────────────┼────────────────────────┐
                                  ▼                       ▼                     ▼                        ▼
                          ┌──────────────┐       ┌────────────────┐      ┌──────────────┐         ┌─────────────┐
                          │ ClearPass    │       │ SQLite         │      │ Slack/Teams  │         │ SIEM        │
                          │ REST API     │       │ Ledger         │      │ Benachrichti-│         │ (strukturier-│
                          │ - Rollenwechsel│      │ - Zustand      │      │ gung         │         │ te Logs)    │
                          │ - Trennung   │       │ - auto. Freigabe│      │              │         │             │
                          └──────────────┘       └────────────────┘      └──────────────┘         └─────────────┘

Siehe docs/architecture.md für die vollständige Aufschlüsselung.

---

Technologie-Stack