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 모델이 설정 가능한 심각도 임계값을 초과하여 트리거되면 툴킷은:

1. Antigena 웹훅(HMAC 검증됨)을 수신합니다.
2. YAML 구성을 통해 모델 + 심각도를 차단 조치에 매핑합니다.
3. ClearPass REST API를 호출하여 새 엔드포인트 역할(격리 VLAN)을 적용하고, 세션을 끊거나, 두 작업을 모두 수행합니다.
4. 모든 결정을 SQLite 원장에 기록하여 감사 및 자동 해제를 지원합니다.
5. Slack/Teams를 통해 SOC에 알립니다.
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 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를 참조하세요.

---

기술 스택

계층	도구
언어	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 친화적

---

이것이 아닌 것

• ❌ 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에서 배울 점