zero-touch-containment

Antigena (Darktrace) → Aruba ClearPass CoA bridge — управляемая моделями изоляция пользователей/устройств в реальном времени. Ноль кликов SOC между обнаружением и сдерживанием.

Санитизированная эталонная реализация интеграционного паттерна NDR↔NAC, эксплуатировавшегося в масштабе финансового сектора (многотысячные конечные точки, круглосуточный SOC). Клиентские части заменены синтетическими фикстурами; архитектура, поток принятия решений и операционные паттерны — настоящие.

---

Зачем это существует

Обещание NDR (Darktrace, ExtraHop, Vectra) — обнаружение за секунды. Реальность в большинстве банков: обнаружение за секунды, сдерживание за часы — потому что передача от SOC к командам NAC/брандмауэров выполняется вручную.

Этот набор инструментов закрывает разрыв, соединяя Antigena (модуль автономного реагирования Darktrace) с Aruba ClearPass через REST API ClearPass. Когда срабатывает модель Darktrace выше заданного порога серьезности, набор:

1. Принимает вебхук Antigena (с проверкой HMAC).
2. Сопоставляет модель + серьезность с действием изоляции через YAML-конфиг.
3. Вызывает REST API ClearPass для назначения новой роли конечной точки (VLAN карантина), разрыва сессии или обоих действий.
4. Регистрирует каждое решение в SQLite-журнале для аудита и автоматического освобождения.
5. Уведомляет SOC через Slack/Teams.
6. Отправляет структурированные события аудита в SIEM (LogRhythm, Elastic).

Сквозная медианная задержка от срабатывания модели до активации VLAN карантина: менее 5 секунд.

---

Что внутри

zero-touch-containment/
├── README.md                       ← Вы здесь
├── LICENSE
├── .gitignore
├── docs/
│   ├── architecture.md             ← Полное погружение в архитектуру + SOLID
│   └── lessons-learned.md          ← 10 уроков из эксплуатации в продакшене
│
├── webhook/                        ← Входящий HTTP-уровень (разделение по SRP)
│   ├── app.py                      ← Только FastAPI-роуты + время жизни
│   ├── auth.py                     ← verify_hmac() — проверка HMAC-SHA1
│   ├── replay.py                   ← ReplayCache — LRU-защита от повторов
│   └── models.py                   ← Схема AntigenaEvent (pydantic)
│
├── engine/                         ← Движок принятия решений на YAML
│   ├── decision.py                 ← DecisionEngine (зависит от протокола QuarantineReader)
│   ├── rules.py                    ← Загрузчики YAML для маппинга и белого списка
│   └── models.py                   ← Action + MappingRule + ActionKind
│
├── clearpass/                      ← Адаптер NAC (реализует протокол CoAClient)
│   ├── client.py                   ← ClearPassClient — операции CoA через REST
│   ├── ports.py                    ← Протокол CoAClient — порт для любого NAC-бэкенда
│   └── auth.py                     ← OAuth2 TokenCache
│
├── ledger/                         ← SQLite-журнал (реализует 5 портов — применён ISP)
│   ├── store.py                    ← SqliteLedger — монолитная реализация
│   ├── ports.py                    ← EventStore + QuarantineWriter + QuarantineReader
│   │                                 + ReleaseManager + HealthChecker (разделены)
│   └── schema.py                   ← SQL DDL-константа
│
├── cli/                            ← CLI для операций SOC
│   └── soc.py                      ← `ztc release-expired` + планируемые команды
│
├── config/
│   ├── mapping.example.yaml        ← Маппинг «серьёзность → действие»
│   └── allowlist.example.yaml      ← Список VIP / «никогда не изолировать»
│
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── .env.example
│
├── tests/                          ← 60 тестов, покрывающих каждый слой
│   ├── test_decision.py
│   ├── test_ledger.py
│   ├── test_webhook_helpers.py
│   ├── test_clearpass_client.py
│   ├── test_protocols.py           ← Структурные тесты соответствия ISP/DIP
│   └── 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  # заполните CLEARPASS_HOST, учётные данные OAuth, секрет HMAC

# Запустите приёмник вебхуков
uvicorn webhook.app:app --host 0.0.0.0 --port 8080

# В другом терминале: воспроизведите пример события
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

Вебхук проверяет HMAC-SHA1, запускает движок принятия решений из mapping.yaml и либо:

• режим сухого прогона (по умолчанию в dev) → логирует действие, которое было бы выполнено
• рабочий режим → вызывает REST API ClearPass для принудительного применения

---

Архитектура (обзор на одном экране)

┌──────────────┐   1. вебхук    ┌──────────────────┐   2. проверка   ┌──────────────────┐
│  Darktrace   │ ──────────────▶ │  Приёмник        │ ───────────────▶ │  Движок          │
│  Antigena    │  HMAC-SHA1      │  вебхуков        │  разбор + аут.   │  принятия        │
│  срабатывает │                 │  (FastAPI)       │                  │  решений         │
│  модель      │                 └──────────────────┘                  │  (на YAML)       │
└──────────────┘                                                       └─────────┬────────┘
                                                                                  │
                                                                                  ▼
                                                                       3. разрешение действия
                                                                       (белый список + лимит)
                                                                                  │
                                  ┌───────────────────────┬───────────────────────┼────────────────────────┐
                                  ▼                       ▼                       ▼                        ▼
                          ┌──────────────┐       ┌────────────────┐      ┌──────────────┐         ┌─────────────┐
                          │ ClearPass    │       │ SQLite-        │      │ Slack/Teams  │         │ SIEM        │
                          │ REST API     │       │ журнал         │      │ уведомление  │         │ (структур.  │
                          │ - смена роли  │       │ - состояние    │      │              │         │  логи)      │
                          │ - отключение │       │ - автовыпуск   │      │              │         │             │
                          └──────────────┘       └────────────────┘      └──────────────┘         └─────────────┘

См. docs/architecture.md для полного разбора.

---

Технический стек