zero-touch-containment

Antigena (Darktrace) → Aruba ClearPass CoA 桥接器 — 基于模型驱动的实时用户/设备隔离。零 SOC 点击即可实现从检测到遏制。

这是一个经过清理的生产级 NDR↔NAC 集成模式的参考实现，已在金融行业规模（数千端点，24/7 SOC）中运行。客户特定部分已替换为合成夹具；架构、决策流程和运营模式均为真实版本。

为什么存在

NDR（Darktrace、ExtraHop、Vectra）的承诺是数秒内检测。但在大多数银行中的现实：检测只需数秒，遏制却需要数小时——因为 SOC 与 NAC/防火墙团队的交接是手动的。

该工具包通过将 Antigena（Darktrace 的自主响应模块） 桥接到 Aruba ClearPass（通过 ClearPass REST API） 来缩小这一差距。当 Darktrace 模型触发且超过可配置的严重性阈值时，该工具包：

接收 Antigena webhook（经 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 协议）
│   ├── rules.py                    ← 用于映射 + 白名单的 YAML 加载器
│   └── models.py                   ← Action + MappingRule + ActionKind
│
├── clearpass/                      ← NAC 适配器（实现 CoAClient 协议）
│   ├── client.py                   ← ClearPassClient — REST CoA 样式操作
│   ├── 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/                            ← 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  # 填写 CLEARPASS_HOST、OAUTH 凭证、HMAC 密钥

# 运行 webhook 接收器
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

Webhook 验证 HMAC-SHA1，根据 mapping.yaml 运行决策引擎，然后要么：

dry-run 模式（开发环境默认） → 记录将要采取的动作
live 模式 → 调用 ClearPass REST API 强制执行

架构（一目了然）

┌──────────────┐   1. webhook    ┌──────────────────┐   2. 验证    ┌──────────────────┐
│  Darktrace   │ ──────────────▶ │  Webhook         │ ───────────────▶ │  决策引擎        │
│  Antigena    │  HMAC-SHA1      │  接收器          │  解析 + 认证     │  （YAML 驱动）   │
│  触发模型     │                 │  (FastAPI)       │                  │                   │
└──────────────┘                 └──────────────────┘                  └─────────┬────────┘
                                                                                  │
                                                                                  ▼
                                                                       3. 解析动作
                                                                       （白名单 + 速率限制）
                                                                                  │
                                  ┌───────────────────────┬───────────────────────┼────────────────────────┐
                                  ▼                       ▼                       ▼                        ▼
                          ┌──────────────┐       ┌────────────────┐      ┌──────────────┐         ┌─────────────┐
                          │ ClearPass    │       │ SQLite         │      │ Slack/Teams  │         │ SIEM        │
                          │ REST API     │       │ 分类账         │      │ 通知         │         │ （结构化日志）│
                          │ - 角色切换   │       │ - 状态         │      │              │         │             │
                          │ - 断开连接   │       │ - 自动释放     │      │              │         │             │
                          └──────────────┘       └────────────────┘      └──────────────┘         └─────────────┘

参见 docs/architecture.md 以获取完整分解。

技术栈

这不是什么

❌ 不是 Darktrace 替代品 — 它消费 Antigena 输出，而非产生。
❌ 不是 ClearPass 替代品 — 它是 ClearPass REST API 之上的轻量编排层。
❌ 不是 SIEM — 它将结构化事件发送到 SIEM，不查询/关联。
❌ 不适合所有人 — 仅当你同时运行 Darktrace NDR 和 Aruba ClearPass NAC 时才有用。按设计为特定厂商。

真实世界背景

这里的模式源自 一家一级 LATAM 金融机构多年 NDR + NAC 项目：

数千端点处于 NAC + NDR 联合覆盖下
跨分支、核心数据中心和企业端点环境的 500+ 个 vSensor
6 个 MITRE ATT&CK 威胁类别处于自主响应下：C2 信标、横向移动、数据外泄、UEBA 异常、恶意设备、协议攻击
通过此双向桥接，MTTR 降低 60%（相比手动 SOC 交接）
通过自主响应覆盖，安全事件减少 40%

该工具包是该集成的提炼和清理版本。模型名称、租户 ID、ClearPass 端点、IP 计划已替换为合成等价物。

你将从 `docs/lessons-learned.md` 中学到什么

10 件我希望在 Antigena↔ClearPass 生产部署第一天之前有人告诉我的事 — 涵盖 webhook 可靠性、ClearPass REST API 的细微差别、角色切换与断开连接的区别、误报遏制风暴以及操作员交接设计。

架构（遵循 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 模拟）以及结构化的协议合规性。

路线图

Webhook 接收器 + HMAC 验证
YAML 驱动的决策引擎
ClearPass REST 客户端（角色切换 + 断开连接）
SQLite 分类账 + 自动释放
协议端口 + SOLID 合规性重构
覆盖每一层的 60 测试套件
SOC 覆盖 CLI — list, release, quarantine, audit（第二级）
Slack/Teams 通知层（第二级）
SIEM 结构化转发器（第二级）

关于作者

Leonardo Mejía — 高级网络安全与 SD-WAN 架构师 · 15 年以上经验零信任 · 混合云 · NDR · 企业 SD-WAN

许可证

MIT — 参见 LICENSE。

本仓库中的模式是经过清理的抽象，而非专有客户端代码。可自由使用；如注明出处则表感谢。

语言	Python 3.11+
Web	FastAPI + Uvicorn（webhook 接收器）
HTTP 客户端	`httpx`（异步）+ `tenacity`（带退避的重试）
认证	入站 HMAC-SHA1（Darktrace） · 出站 OAuth2 client_credentials（ClearPass）
配置	YAML — 严重性 → 动作映射 + 白名单
状态	SQLite + WAL — 隔离分类账 + 自动释放
日志	`structlog` — JSON 输出供 SIEM 摄入
测试	`pytest` + `respx`（httpx 模拟）+ 记录夹具
部署	Docker Compose，单 VM 友好

SRP	`webhook/` 拆分为 `auth` + `replay` + `models` + 路由。`clearpass/` 拆分为 `client` + `auth` + `ports`。`ledger/` 拆分为 `store` + `ports` + `schema`。
OCP	新的 NAC 后端实现 `CoAClient` 协议 — webhook 或引擎无需更改。
LSP	测试使用满足相同协议的内存模拟。管道行为不变。
ISP	分类账拆分为 5 个分离的端口（`EventStore`, `QuarantineWriter`, `QuarantineReader`, `ReleaseManager`, `HealthChecker`）。Webhook 仅依赖前两个；引擎仅依赖 `QuarantineReader`。
DIP	`webhook/app.py` 和 `engine/decision.py` 依赖协议，从不依赖具体类。

zero-touch-containment

最受欢迎

zero-touch-containment

为什么存在

内部结构

快速开始

架构（一目了然）

技术栈

这不是什么

真实世界背景

你将从 docs/lessons-learned.md 中学到什么

架构（遵循 SOLID 原则）

运行测试套件

路线图

关于作者

许可证

你将从 `docs/lessons-learned.md` 中学到什么