lama-labs/zero-touch-containmentAntigena (Darktrace) → Aruba ClearPass CoA bridge — モデル駆動型、リアルタイムのユーザー/デバイス隔離。SOC操作不要。ヘキサゴナルアーキテクチャ、テストカバレッジ82%。
Antigena (Darktrace) → Aruba ClearPass CoA ブリッジ — モデル駆動型、リアルタイムのユーザー/デバイス隔離。検出から封じ込めまで、SOCのクリックは不要。
実運用のNDR↔NAC統合パターンを参考にした、サニタイズされたリファレンス実装。金融機関規模（数千エンドポイント、24時間365日稼働のSOC）で運用されました。顧客固有の部分は合成フィクスチャに置き換えられていますが、アーキテクチャ、意思決定フロー、運用パターンは本物です。
NDR（Darktrace、ExtraHop、Vectra）の約束は「秒単位の検出」です。しかし、ほとんどの銀行における現実は「秒単位の検出、時間単位の封じ込め」です。なぜなら、SOCからNAC/ファイアウォールチームへの引き継ぎが手動だからです。
このツールキットは、Antigena（Darktraceの自律応答モジュール） と Aruba ClearPass（ClearPass REST API経由） の間を橋渡しすることで、そのギャップを埋めます。Darktraceのモデルが設定可能な重要度しきい値を超えて発動した場合、ツールキットは以下を実行します。
モデル発動から隔離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に対して判断エンジンを実行し、次のいずれかを出力します。
┌──────────────┐ 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 を参照してください。
ここに示したパターンは、南米のTier1金融機関における複数年にわたるNDR + NACプロジェクトから生まれました。
このツールキットは、その統合から抽出・サニタイズされたバージョンです。モデル名、テナントID、ClearPassエンドポイント、IP計画はすべて合成の同等物に置き換えられています。
docs/lessons-learned.md から学べることAntigena↔ClearPassの本番デプロイにおける初日から知っておきたかった10のこと — Webhookの信頼性、ClearPass REST APIの癖、ロールスワップと切断の違い、誤検知による封じ込めストーム、オペレーター引き継ぎ設計について。
具体的なアダプターとオーケストレーションコードの間に明示的なプロトコルポートを配置したヘキサゴナルレイヤリング。
完全な内訳は 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モック）、構造的プロトコル準拠をカバーする60のテスト。
list、release、quarantine、audit（Tier-2）Leonardo Mejía — シニアサイバーセキュリティ＆SD-WANアーキテクト · 15年以上 Zero Trust · ハイブリッドクラウド · 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 — SIEM取り込み用JSON出力 |
| テスト | 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は最初の2つにのみ依存し、エンジンは QuarantineReader のみに依存。 |
| DIP | webhook/app.py と engine/decision.py はプロトコルに依存し、具象クラスには依存しない。 |