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:

Empfängt den Antigena-Webhook (HMAC-validiert).
Ordnet das Modell + den Schweregrad über eine YAML-Konfiguration einer Eindämmungsaktion zu.
Ruft die ClearPass REST API auf, um eine neue Endpunktrolle (Quarantäne-VLAN) zu setzen, die Sitzung zu trennen oder beides.
Protokolliert jede Entscheidung in einem SQLite-Ledger für Audit + automatische Freigabe.
Benachrichtigt das SOC via Slack/Teams.
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

Was das NICHT ist

❌ Kein Darktrace-Ersatz — es verarbeitet Antigena-Ausgabe, erzeugt sie nicht.
❌ Kein ClearPass-Ersatz — es ist eine dünne Orchestrierungsschicht über der ClearPass-REST-API.
❌ Kein SIEM — es liefert strukturierte Ereignisse an Ihr SIEM, fragt nicht ab/korreliert nicht.
❌ Nicht für jeden — nur nützlich, wenn Sie sowohl Darktrace NDR als auch Aruba ClearPass NAC betreiben. Anbieterspezifisch von Grund auf.

Praxis-Hintergrund

Die Muster hier stammen aus einem mehrjährigen NDR+NAC-Engagement bei einem Tier-1-Finanzinstitut in Lateinamerika:

Mehrere tausend Endpunkte unter kombinierter NAC+NDR-Abdeckung
500+ vSensoren über Filial-, Kernrechenzentrums- und Unternehmensendpunktumgebungen
6 MITRE ATT&CK-Bedrohungskategorien unter Autonomous Response: C2-Beaconing, laterale Bewegung, Datenexfiltration, UEBA-Anomalien, Schatten-IT-Geräte, Protokollangriffe
60% MTTR-Reduzierung durch diese bidirektionale Brücke (vs. manuelle SOC-Übergabe)
40% Reduzierung von Sicherheitsvorfällen durch Autonomous Response-Abdeckung

Das Toolkit ist die destillierte, bereinigte Version dieser Integration. Modellnamen, Mandanten-IDs, ClearPass-Endpunkte, IP-Pläne wurden durch synthetische Äquivalente ersetzt.

Was Sie aus `docs/lessons-learned.md` lernen

10 Dinge, von denen ich mir gewünscht hätte, sie wären mir vor dem ersten Tag einer Antigena↔ClearPass-Produktionsbereitstellung gesagt worden – über Webhook-Zuverlässigkeit, ClearPass-REST-API-Eigenheiten, den Unterschied zwischen Rollenwechsel und Sitzungstrennung, False-Positive-Eindämmungsstürme und Operator-Übergabe-Design.

Architektur (SOLID-konform)

Hexagonale Schichtung mit expliziten Protocol-Ports zwischen konkreten Adaptern und Orchestrierungscode:

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

Testsuite ausführen

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

60 Tests, die Entscheidungsengine, SQLite-Ledger, HMAC-Validierung, Replay-Cache, ClearPass-Client (async, respx-gemockt) und strukturelle Protocol-Compliance abdecken.

Roadmap

Webhook-Empfänger + HMAC-Validierung
YAML-gesteuerte Entscheidungsengine
ClearPass REST-Client (Rollenwechsel + Sitzungstrennung)
SQLite-Ledger + automatische Freigabe
Protocol-Ports + SOLID-Compliance-Refactoring
60-Test-Suite, die jede Schicht abdeckt
SOC-Override-CLI — list, release, quarantine, audit (Tier-2)
Slack/Teams-Benachrichtigungsschicht (Tier-2)
SIEM-strukturierter Weiterleiter (Tier-2)

Über den Autor

Leonardo Mejía — Senior Cybersecurity & SD-WAN Architect · 15+ Jahre Zero Trust · Hybrid Cloud · NDR · Enterprise SD-WAN

LinkedIn: linkedin.com/in/leonardomejia
GitHub: github.com/zimlama
Schwester-Portfolio-Repo: sdwan-automation-toolkit

Lizenz

MIT — siehe LICENSE.

Die Muster in diesem Repo sind bereinigte Abstraktionen, kein proprietärer Client-Code. Frei verwendbar; Quellenangabe erwünscht.

Sprache	Python 3.11+
Web	FastAPI + Uvicorn (Webhook-Empfänger)
HTTP-Client	`httpx` (async) + `tenacity` (Wiederholung mit Backoff)
Auth	HMAC-SHA1 eingehend (Darktrace) · OAuth2 client_credentials ausgehend (ClearPass)
Konfiguration	YAML — Schweregrad → Aktions-Mapping + Allowlist
Zustand	SQLite + WAL — Quarantäne-Ledger + automatische Freigabe
Logging	`structlog` — JSON-Ausgabe für SIEM-Aufnahme
Testen	`pytest` + `respx` (httpx-Mock) + aufgezeichnete Fixtures
Bereitstellung	Docker Compose, einfach auf einem einzelnen VM

SRP	`webhook/` aufgeteilt in `auth` + `replay` + `models` + Routing. `clearpass/` aufgeteilt in `client` + `auth` + `ports`. `ledger/` aufgeteilt in `store` + `ports` + `schema`.
OCP	Neue NAC-Backends implementieren `CoAClient` Protocol – keine Änderungen an Webhook oder Engine.
LSP	Tests verwenden In-Memory-Fakes, die dieselben Protocols erfüllen. Pipeline-Verhalten unverändert.
ISP	Ledger aufgeteilt in 5 getrennte Ports (`EventStore`, `QuarantineWriter`, `QuarantineReader`, `ReleaseManager`, `HealthChecker`). Webhook hängt nur von den ersten beiden ab; Engine nur von `QuarantineReader`.
DIP	`webhook/app.py` und `engine/decision.py` hängen von Protocols ab, niemals von konkreten Klassen.

zero-touch-containment

Beliebteste

zero-touch-containment

Warum es das gibt

Was drin ist

Schnellstart

Architektur (Auf-einen-Blick)

Technologie-Stack

Was das NICHT ist

Praxis-Hintergrund

Was Sie aus docs/lessons-learned.md lernen

Architektur (SOLID-konform)

Testsuite ausführen

Roadmap

Über den Autor

Lizenz

Was Sie aus `docs/lessons-learned.md` lernen