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 выше заданного порога серьезности, набор:

Принимает вебхук Antigena (с проверкой HMAC).
Сопоставляет модель + серьезность с действием изоляции через YAML-конфиг.
Вызывает REST API ClearPass для назначения новой роли конечной точки (VLAN карантина), разрыва сессии или обоих действий.
Регистрирует каждое решение в SQLite-журнале для аудита и автоматического освобождения.
Уведомляет SOC через Slack/Teams.
Отправляет структурированные события аудита в 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 для полного разбора.

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

Чем это НЕ является

❌ Не замена Darktrace — потребляет вывод Antigena, а не создаёт его.
❌ Не замена ClearPass — это тонкий уровень оркестрации поверх REST API ClearPass.
❌ Не SIEM — отправляет структурированные события в вашу SIEM, не выполняет запросы/корреляцию.
❌ Не для всех — полезно только если вы используете и Darktrace NDR, и Aruba ClearPass NAC. Специфично для вендоров.

Реальный контекст

Представленные паттерны выросли из многолетнего внедрения NDR + NAC в финансовом учреждении Tier-1 в Латинской Америке:

Многотысячные конечные точки под комбинированным покрытием NAC + NDR
500+ vSensors в филиалах, основном ЦОД и корпоративной среде конечных точек
6 категорий угроз MITRE ATT&CK под автономным реагированием: C2-бекдоры, боковое перемещение, эксфильтрация данных, аномалии UEBA, мошеннические устройства, атаки на протоколы
Снижение MTTR на 60% благодаря этому двунаправленному мосту (против ручной передачи SOC)
Снижение количества инцидентов безопасности на 40% за счёт покрытия автономным реагированием

Этот инструмент — дистиллированная и санитизированная версия той интеграции. Имена моделей, идентификаторы арендаторов, конечные точки ClearPass, IP-планы заменены синтетическими эквивалентами.

Что вы узнаете из `docs/lessons-learned.md`

10 вещей, которые я хотел бы знать до первого дня продакшн-развёртывания Antigena↔ClearPass — охватывающие надёжность вебхуков, особенности REST API ClearPass, разницу между сменой роли и отключением, штормы ложноположительных изоляций и проектирование передачи операторам.

Архитектура (SOLID-совместимая)

Гексагональная структура с явными протокольными портами между конкретными адаптерами и кодом оркестрации:

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

Запуск тестового набора

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

60 тестов, покрывающих движок принятия решений, SQLite-журнал, проверку HMAC, кеш повторов, клиент ClearPass (асинхронный, respx-мокированный) и структурное соответствие протоколам.

План развития

Приёмник вебхуков + проверка HMAC
Движок принятия решений на YAML
REST-клиент ClearPass (смена роли + отключение)
SQLite-журнал + автовыпуск
Протокольные порты + рефакторинг для SOLID
60 тестов, покрывающих каждый слой
CLI для SOC — list, release, quarantine, audit (уровень Tier-2)
Уведомления через Slack/Teams (уровень Tier-2)
Структурированный пересылщик событий в SIEM (уровень Tier-2)

Об авторе

Leonardo Mejía — старший архитектор кибербезопасности и SD-WAN · 15+ лет Zero Trust · Гибридные облака · NDR · Корпоративный SD-WAN

LinkedIn: linkedin.com/in/leonardomejia
GitHub: github.com/zimlama
Репозиторий смежного портфолио: sdwan-automation-toolkit

Лицензия

MIT — см. LICENSE.

Паттерны в этом репозитории — санитизированные абстракции, а не проприетарный клиентский код. Используйте свободно; атрибуция приветствуется.

Язык	Python 3.11+
Веб	FastAPI + Uvicorn (приёмник вебхуков)
HTTP-клиент	`httpx` (async) + `tenacity` (повторы с откатом)
Аутентификация	Входящая: HMAC-SHA1 (Darktrace) · Исходящая: OAuth2 client_credentials (ClearPass)
Конфигурация	YAML — маппинг серьёзность → действие + белый список
Состояние	SQLite + WAL — журнал карантина + автовыпуск
Логирование	`structlog` — JSON-вывод для приёма в SIEM
Тестирование	`pytest` + `respx` (мок httpx) + записанные фикстуры
Развёртывание	Docker Compose, подходит для одной ВМ

SRP	`webhook/` разделён на `auth` + `replay` + `models` + роутинг. `clearpass/` разделён на `client` + `auth` + `ports`. `ledger/` разделён на `store` + `ports` + `schema`.
OCP	Новые NAC-бэкенды реализуют протокол `CoAClient` — без изменений в вебхуке или движке.
LSP	Тесты используют поддельные объекты в памяти, удовлетворяющие тем же протоколам. Поведение конвейера не меняется.
ISP	Журнал разделён на 5 изолированных портов (`EventStore`, `QuarantineWriter`, `QuarantineReader`, `ReleaseManager`, `HealthChecker`). Вебхук зависит только от первых двух; движок — только от `QuarantineReader`.
DIP	`webhook/app.py` и `engine/decision.py` зависят от протоколов, никогда от конкретных классов.

zero-touch-containment

Популярное

zero-touch-containment

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

Что внутри

Быстрый старт

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

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

Чем это НЕ является

Реальный контекст

Что вы узнаете из docs/lessons-learned.md

Архитектура (SOLID-совместимая)

Запуск тестового набора

План развития

Об авторе

Лицензия

Что вы узнаете из `docs/lessons-learned.md`