zero-touch-containment

Antigena (Darktrace) → Aruba ClearPass CoA 브리지 — 모델 기반 실시간 사용자/장치 격리. 탐지와 차단 사이에 SOC 클릭이 필요 없습니다.

금융 기관 규모(수천 개 엔드포인트, 24/7 SOC)에서 운영된 프로덕션 NDR↔NAC 통합 패턴의 정제된 참조 구현입니다. 고객별 정보는 합성 픽스처로 대체되었으며, 아키텍처, 의사 결정 흐름 및 운영 패턴은 실제 그대로입니다.

왜 필요한가

NDR(Darktrace, ExtraHop, Vectra)의 약속은 몇 초 안에 탐지하는 것입니다. 대부분 은행의 현실: 탐지는 몇 초 안에 이루어지지만 차단은 몇 시간이 걸립니다. SOC가 NAC/방화벽 팀에게 수동으로 인계하기 때문입니다.

이 툴킷은 **Antigena(Darktrace의 자동 대응 모듈)**을 Aruba ClearPass REST API를 통한 ClearPass에 연결하여 그 격차를 해소합니다. Darktrace 모델이 설정 가능한 심각도 임계값을 초과하여 트리거되면 툴킷은:

Antigena 웹훅(HMAC 검증됨)을 수신합니다.
YAML 구성을 통해 모델 + 심각도를 차단 조치에 매핑합니다.
ClearPass REST API를 호출하여 새 엔드포인트 역할(격리 VLAN)을 적용하고, 세션을 끊거나, 두 작업을 모두 수행합니다.
모든 결정을 SQLite 원장에 기록하여 감사 및 자동 해제를 지원합니다.
Slack/Teams를 통해 SOC에 알립니다.
구조화된 감사 이벤트를 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 Protocol에 의존)
│   ├── rules.py                    ← 매핑 + 허용 목록을 위한 YAML 로더
│   └── models.py                   ← Action + MappingRule + ActionKind
│
├── clearpass/                      ← NAC 어댑터 (CoAClient Protocol 구현)
│   ├── client.py                   ← ClearPassClient — REST CoA 스타일 작업
│   ├── ports.py                    ← CoAClient Protocol — 모든 NAC 백엔드용 포트
│   └── auth.py                     ← OAuth2 TokenCache
│
├── ledger/                         ← SQLite 원장 (5개 포트 구현 — ISP 적용)
│   ├── store.py                    ← SqliteLedger — 올인원 구현
│   ├── ports.py                    ← EventStore + QuarantineWriter + QuarantineReader
│   │                                 + ReleaseManager + HealthChecker (분리됨)
│   └── schema.py                   ← SQL DDL 상수
│
├── cli/                            ← SOC 운영 CLI
│   └── 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  # 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

웹훅은 HMAC-SHA1을 검증하고, mapping.yaml을 기준으로 의사 결정 엔진을 실행한 후 다음 중 하나를 수행합니다.

dry-run 모드 (개발 환경 기본값) → 수행되었을 조치를 기록합니다.
live 모드 → ClearPass REST API를 호출하여 적용합니다.

아키텍쳐 (한 눈에 보기)

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

전체 분석은 docs/architecture.md를 참조하세요.

기술 스택

이것이 아닌 것

❌ Darktrace 대체품이 아님 — Antigena의 출력을 소비할 뿐 생성하지 않습니다.
❌ ClearPass 대체품이 아님 — ClearPass REST API 위의 얇은 오케스트레이션 계층입니다.
❌ SIEM이 아님 — 구조화된 이벤트를 SIEM으로 전송할 뿐, 질의/상관 분석은 하지 않습니다.
❌ 모든 사람을 위한 것이 아님 — Darktrace NDR과 Aruba ClearPass NAC를 모두 사용할 때만 유용합니다. 벤더별로 설계되었습니다.

실제 운영 환경

여기에 사용된 패턴은 티어-1 라틴아메리카 금융 기관에서의 다년간 NDR + NAC 프로젝트에서 비롯되었습니다:

NAC + NDR이 적용된 수천 개 엔드포인트
지점, 코어 데이터센터, 기업 엔드포인트 환경에 걸친 500개 이상의 vSensor
자동 대응(Autonomous Response) 하의 6가지 MITRE ATT&CK 위협 범주: C2 비콘닝, 측면 이동, 데이터 유출, UEBA 이상 징후, 비인가 장치, 프로토콜 공격
이 양방향 브리지를 통해 MTTR 60% 감소 (수동 SOC 인계 대비)
자동 대응 적용으로 보안 사고 40% 감소

이 툴킷은 해당 통합의 정제되고 익명화된 버전입니다. 모델명, 테넌트 ID, ClearPress 엔드포인트, IP 계획은 합성 등가물로 대체되었습니다.

`docs/lessons-learned.md`에서 배울 점

Antigena↔ClearPass 프로덕션 배포의 첫 날 이전에 누군가 알려주었으면 하는 10가지 — 웹훅 신뢰성, ClearPass REST API의 까다로운 점, 역할 전환과 세션 끊기의 차이, 거짓 양성 차단 폭풍, 운영자 인계 설계에 대해 다룹니다.

아키텍쳐 (SOLID 준수)

육각형 계층 구조로, 구체적인 어댑터와 오케스트레이션 코드 사이에 명시적인 Protocol 포트가 있습니다:

전체 분석은 docs/architecture.md를 참조하세요.

테스트 스위트 실행

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

의사 결정 엔진, SQLite 원장, HMAC 검증, 재생 캐시, ClearPass 클라이언트(비동기, respx 모의) 및 구조적 Protocol 준수를 다루는 60개 테스트.

로드맵

웹훅 수신기 + HMAC 검증
YAML 기반 의사 결정 엔진
ClearPass REST 클라이언트 (역할 전환 + 세션 끊기)
SQLite 원장 + 자동 해제
Protocol 포트 + SOLID 준수 리팩터링
모든 계층을 다루는 60개 테스트 스위트
SOC 오버라이드 CLI — list, release, quarantine, audit (티어-2)
Slack/Teams 알림 계층 (티어-2)
SIEM 구조화 전달자 (티어-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` (비동기) + `tenacity` (재시도-백오프)
인증	HMAC-SHA1 인바운드 (Darktrace) · OAuth2 client_credentials 아웃바운드 (ClearPass)
설정	YAML — 심각도 → 조치 매핑 + 허용 목록
상태	SQLite + WAL — 격리 원장 + 자동 해제
로깅	`structlog` — SIEM 수집용 JSON 출력
테스팅	`pytest` + `respx` (httpx 모의) + 기록된 픽스처
배포	Docker Compose, 단일 VM 친화적

SRP	`webhook/`가 `auth` + `replay` + `models` + 라우팅으로 분할됨. `clearpass/`가 `client` + `auth` + `ports`로 분할됨. `ledger/`가 `store` + `ports` + `schema`로 분할됨.
OCP	새로운 NAC 백엔드는 `CoAClient` Protocol을 구현함 — 웹훅이나 엔진에 변경 없음.
LSP	테스트는 동일한 Protocol을 만족하는 인메모리 가짜(fakes)를 사용함. 파이프라인 동작은 변경되지 않음.
ISP	원장이 5개의 분리된 포트(`EventStore`, `QuarantineWriter`, `QuarantineReader`, `ReleaseManager`, `HealthChecker`)로 분할됨. 웹훅은 처음 두 포트에만 의존하고, 엔진은 `QuarantineReader`에만 의존함.
DIP	`webhook/app.py`와 `engine/decision.py`는 구체적인 클래스가 아닌 Protocol에 의존함.

zero-touch-containment

인기

zero-touch-containment

왜 필요한가

내부 구성

빠른 시작

아키텍쳐 (한 눈에 보기)

기술 스택

이것이 아닌 것

실제 운영 환경

docs/lessons-learned.md에서 배울 점

아키텍쳐 (SOLID 준수)

테스트 스위트 실행

로드맵

작성자 정보

라이선스

`docs/lessons-learned.md`에서 배울 점