zero-touch-containment

Antigena (Darktrace) → Aruba ClearPass CoA bridge — model-driven, real-time user/device quarantine. Zero SOC clicks between detection and containment.

Sanitized reference implementation of a production NDR↔NAC integration pattern operated at financial-sector scale (multi-thousand endpoints, 24/7 SOC). Customer-specific bits replaced with synthetic fixtures; the architecture, decision flow, and operational patterns are the real ones.

Why this exists

The promise of NDR (Darktrace, ExtraHop, Vectra) is detection in seconds. The reality in most banks: detection in seconds, containment in hours — because the SOC handoff to NAC/firewall teams is manual.

This toolkit closes that gap by bridging Antigena (Darktrace's Autonomous Response module) to Aruba ClearPass via the ClearPass REST API. When a Darktrace model fires above a configurable severity threshold, the toolkit:

Receives the Antigena webhook (HMAC-validated).
Maps the model + severity to a containment action via YAML config.
Calls ClearPass REST API to push a new endpoint role (quarantine VLAN), disconnect the session, or both.
Logs every decision to a SQLite ledger for audit + auto-release.
Notifies SOC via Slack/Teams.
Forwards structured audit events to SIEM (LogRhythm, Elastic).

End-to-end median latency from model fire → quarantine VLAN active: under 5 seconds.

What's inside

zero-touch-containment/
├── README.md                       ← You are here
├── LICENSE
├── .gitignore
├── docs/
│   ├── architecture.md             ← Full architecture deep-dive + SOLID trace
│   └── lessons-learned.md          ← 10 lessons from running this in prod
│
├── webhook/                        ← Inbound HTTP layer (split by SRP)
│   ├── app.py                      ← FastAPI routes + lifespan only
│   ├── auth.py                     ← verify_hmac() — HMAC-SHA1 validation
│   ├── replay.py                   ← ReplayCache — LRU replay protection
│   └── models.py                   ← AntigenaEvent pydantic schema
│
├── engine/                         ← YAML-driven decision engine
│   ├── decision.py                 ← DecisionEngine (depends on QuarantineReader Protocol)
│   ├── rules.py                    ← YAML loaders for mapping + allowlist
│   └── models.py                   ← Action + MappingRule + ActionKind
│
├── clearpass/                      ← NAC adapter (implements CoAClient Protocol)
│   ├── client.py                   ← ClearPassClient — REST CoA-style ops
│   ├── ports.py                    ← CoAClient Protocol — port for any NAC backend
│   └── auth.py                     ← OAuth2 TokenCache
│
├── ledger/                         ← SQLite ledger (implements 5 ports — ISP applied)
│   ├── store.py                    ← SqliteLedger — all-in-one implementation
│   ├── ports.py                    ← EventStore + QuarantineWriter + QuarantineReader
│   │                                 + ReleaseManager + HealthChecker (segregated)
│   └── schema.py                   ← SQL DDL constant
│
├── cli/                            ← SOC operations CLI
│   └── soc.py                      ← `ztc release-expired` + planned commands
│
├── config/
│   ├── mapping.example.yaml        ← Severity → action mapping
│   └── allowlist.example.yaml      ← VIP / never-quarantine list
│
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── .env.example
│
├── tests/                          ← 60 tests covering every layer
│   ├── test_decision.py
│   ├── test_ledger.py
│   ├── test_webhook_helpers.py
│   ├── test_clearpass_client.py
│   ├── test_protocols.py           ← Structural ISP/DIP compliance tests
│   └── fixtures/sample_event.json
│
├── requirements.txt
└── pyproject.toml

Quick start

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  # fill in CLEARPASS_HOST, OAUTH creds, HMAC secret

# Run the webhook receiver
uvicorn webhook.app:app --host 0.0.0.0 --port 8080

# In another shell: replay a sample event
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

The webhook validates HMAC-SHA1, runs the decision engine against mapping.yaml, and either:

dry-run mode (default in dev) → logs the action that would have been taken
live mode → calls ClearPass REST API to enforce

Architecture (one-screen view)

┌──────────────┐   1. webhook    ┌──────────────────┐   2. validate    ┌──────────────────┐
│  Darktrace   │ ──────────────▶ │  Webhook         │ ───────────────▶ │  Decision        │
│  Antigena    │  HMAC-SHA1      │  receiver        │  parse + auth    │  engine          │
│  fires model │                 │  (FastAPI)       │                  │  (YAML-driven)   │
└──────────────┘                 └──────────────────┘                  └─────────┬────────┘
                                                                                  │
                                                                                  ▼
                                                                       3. resolve action
                                                                       (allowlist + rate limit)
                                                                                  │
                                  ┌───────────────────────┬───────────────────────┼────────────────────────┐
                                  ▼                       ▼                       ▼                        ▼
                          ┌──────────────┐       ┌────────────────┐      ┌──────────────┐         ┌─────────────┐
                          │ ClearPass    │       │ SQLite         │      │ Slack/Teams  │         │ SIEM        │
                          │ REST API     │       │ ledger         │      │ notification │         │ (structured │
                          │ - role swap  │       │ - state        │      │              │         │  logs)      │
                          │ - disconnect │       │ - auto-release │      │              │         │             │
                          └──────────────┘       └────────────────┘      └──────────────┘         └─────────────┘

See docs/architecture.md for the full breakdown.

Tech stack

What this is NOT

❌ Not a Darktrace replacement — it consumes Antigena output, doesn't produce it.
❌ Not a ClearPass replacement — it's a thin orchestration layer above ClearPass's REST API.
❌ Not a SIEM — it ships structured events to your SIEM, doesn't query/correlate.
❌ Not for everyone — only useful if you run both Darktrace NDR and Aruba ClearPass NAC. Vendor-specific by design.

Real-world context

The patterns here came out of a multi-year NDR + NAC engagement at a Tier-1 LATAM financial institution:

Multi-thousand endpoints under combined NAC + NDR coverage
500+ vSensors across branch + core DC + corporate endpoint environments
6 MITRE ATT&CK threat categories under Autonomous Response: C2 beaconing, lateral movement, data exfiltration, UEBA anomalies, rogue devices, protocol attacks
60% MTTR reduction via this bidirectional bridge (vs manual SOC handoff)
40% reduction in security incidents via Autonomous Response coverage

The toolkit is the distilled, sanitized version of that integration. Model names, tenant IDs, ClearPass endpoints, IP plans replaced with synthetic equivalents.

What you'll learn from `docs/lessons-learned.md`

10 things I wish someone had told me before day one of an Antigena↔ClearPass production deployment — covering webhook reliability, ClearPass REST API quirks, the difference between role swap and disconnect, false-positive containment storms, and operator handoff design.

Architecture (SOLID-compliant)

Hexagonal layering with explicit Protocol ports between concrete adapters and orchestration code:

See docs/architecture.md for the full breakdown.

Running the test suite

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

60 tests covering the decision engine, SQLite ledger, HMAC validation, replay cache, ClearPass client (async, respx-mocked), and structural Protocol compliance.

Roadmap

Webhook receiver + HMAC validation
YAML-driven decision engine
ClearPass REST client (role swap + disconnect)
SQLite ledger + auto-release
Protocol ports + SOLID compliance refactor
60-test suite covering every layer
SOC override CLI — list, release, quarantine, audit (Tier-2)
Slack/Teams notification layer (Tier-2)
SIEM structured forwarder (Tier-2)

About the author

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

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

License

MIT — see LICENSE.

The patterns in this repo are sanitized abstractions, not proprietary client code. Use freely; attribution appreciated.

Language	Python 3.11+
Web	FastAPI + Uvicorn (webhook receiver)
HTTP client	`httpx` (async) + `tenacity` (retry-with-backoff)
Auth	HMAC-SHA1 inbound (Darktrace) · OAuth2 client_credentials outbound (ClearPass)
Config	YAML — severity → action mapping + allowlist
State	SQLite + WAL — quarantine ledger + auto-release
Logging	`structlog` — JSON output for SIEM ingest
Testing	`pytest` + `respx` (httpx mock) + recorded fixtures
Deploy	Docker Compose, single-VM friendly

SRP	`webhook/` split into `auth` + `replay` + `models` + routing. `clearpass/` split into `client` + `auth` + `ports`. `ledger/` split into `store` + `ports` + `schema`.
OCP	New NAC backends implement `CoAClient` Protocol — no changes to webhook or engine.
LSP	Tests use in-memory fakes that satisfy the same Protocols. Pipeline behavior unchanged.
ISP	Ledger split into 5 segregated ports (`EventStore`, `QuarantineWriter`, `QuarantineReader`, `ReleaseManager`, `HealthChecker`). Webhook depends only on the first two; engine only on `QuarantineReader`.
DIP	`webhook/app.py` and `engine/decision.py` depend on Protocols, never on concrete classes.

zero-touch-containment

Most Popular

zero-touch-containment

Why this exists

What's inside

Quick start

Architecture (one-screen view)

Tech stack

What this is NOT

Real-world context

What you'll learn from docs/lessons-learned.md

Architecture (SOLID-compliant)

Running the test suite

Roadmap

About the author

License

What you'll learn from `docs/lessons-learned.md`