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

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

┌──────────────┐   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 │      │              │         │             │
                          └──────────────┘       └────────────────┘      └──────────────┘         └─────────────┘

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