zero-touch-containment

Antigena (Darktrace) → Ponte Aruba ClearPass CoA — contenção em tempo real de usuário/dispositivo orientada por modelos. Zero cliques do SOC entre detecção e contenção.

Implementação de referência sanitizada de um padrão de integração NDR↔NAC operado em escala de setor financeiro (milhares de endpoints, SOC 24/7). Partes específicas do cliente substituídas por fixtures sintéticas; a arquitetura, o fluxo de decisão e os padrões operacionais são os reais.

---

Por que isso existe

A promessa do NDR (Darktrace, ExtraHop, Vectra) é detecção em segundos. A realidade na maioria dos bancos: detecção em segundos, contenção em horas — porque a transferência do SOC para as equipes de NAC/firewall é manual.

Este conjunto de ferramentas fecha essa lacuna ao conectar Antigena (módulo de Resposta Autônoma do Darktrace) ao Aruba ClearPass via API REST do ClearPass. Quando um modelo do Darktrace dispara acima de um limite de severidade configurável, o conjunto de ferramentas:

1. Recebe o webhook do Antigena (validado por HMAC).
2. Mapeia o modelo + severidade para uma ação de contenção via configuração YAML.
3. Chama a API REST do ClearPass para aplicar uma nova função de endpoint (VLAN de quarentena), desconectar a sessão, ou ambos.
4. Registra cada decisão em um ledger SQLite para auditoria + liberação automática.
5. Notifica o SOC via Slack/Teams.
6. Encaminha eventos de auditoria estruturados para o SIEM (LogRhythm, Elastic).

Latência mediana de ponta a ponta desde o disparo do modelo até a VLAN de quarentena ativa: abaixo de 5 segundos.

---

O que tem dentro

zero-touch-containment/
├── README.md                       ← Você está aqui
├── LICENSE
├── .gitignore
├── docs/
│   ├── architecture.md             ← Mergulho profundo na arquitetura + rastreio SOLID
│   └── lessons-learned.md          ← 10 lições de executar isso em produção
│
├── webhook/                        ← Camada HTTP de entrada (dividida por SRP)
│   ├── app.py                      ← Apenas rotas FastAPI + lifespan
│   ├── auth.py                     ← verify_hmac() — validação HMAC-SHA1
│   ├── replay.py                   ← ReplayCache — proteção LRU contra repetição
│   └── models.py                   ← Esquema pydantic AntigenaEvent
│
├── engine/                         ← Mecanismo de decisão orientado a YAML
│   ├── decision.py                 ← DecisionEngine (depende do Protocolo QuarantineReader)
│   ├── rules.py                    ← Carregadores YAML para mapeamento + lista de permissões
│   └── models.py                   ← Action + MappingRule + ActionKind
│
├── clearpass/                      ← Adaptador NAC (implementa o Protocolo CoAClient)
│   ├── client.py                   ← ClearPassClient — operações REST estilo CoA
│   ├── ports.py                    ← Protocolo CoAClient — porta para qualquer backend NAC
│   └── auth.py                     ← OAuth2 TokenCache
│
├── ledger/                         ← Ledger SQLite (implementa 5 portas — ISP aplicado)
│   ├── store.py                    ← SqliteLedger — implementação completa
│   ├── ports.py                    ← EventStore + QuarantineWriter + QuarantineReader
│   │                                 + ReleaseManager + HealthChecker (segregados)
│   └── schema.py                   ← Constante DDL SQL
│
├── cli/                            ← CLI de operações do SOC
│   └── soc.py                      ← `ztc release-expired` + comandos planejados
│
├── config/
│   ├── mapping.example.yaml        ← Mapeamento severidade → ação
│   └── allowlist.example.yaml      ← Lista VIP / nunca em quarentena
│
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── .env.example
│
├── tests/                          ← 60 testes cobrindo cada camada
│   ├── test_decision.py
│   ├── test_ledger.py
│   ├── test_webhook_helpers.py
│   ├── test_clearpass_client.py
│   ├── test_protocols.py           ← Testes estruturais de conformidade ISP/DIP
│   └── fixtures/sample_event.json
│
├── requirements.txt
└── pyproject.toml

---

Início rápido

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  # preencha CLEARPASS_HOST, credenciais OAUTH, segredo HMAC

# Execute o receptor de webhook
uvicorn webhook.app:app --host 0.0.0.0 --port 8080

# Em outro shell: reproduza um evento de exemplo
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

O webhook valida HMAC-SHA1, executa o mecanismo de decisão contra mapping.yaml, e:

• modo dry-run (padrão em dev) → registra a ação que teria sido tomada
• modo live → chama a API REST do ClearPass para aplicar

---

Arquitetura (visão geral de uma tela)

┌──────────────┐   1. webhook    ┌──────────────────┐   2. validar    ┌──────────────────┐
│  Darktrace   │ ──────────────▶ │  Receptor        │ ───────────────▶ │  Mecanismo de   │
│  Antigena    │  HMAC-SHA1      │  de webhook      │  analisar +     │  decisão        │
│  dispara     │                 │  (FastAPI)       │  autenticar     │  (orientado a   │
│  modelo      │                 │                  │                  │  YAML)          │
└──────────────┘                 └──────────────────┘                  └─────────┬────────┘
                                                                                  │
                                                                                  ▼
                                                                       3. resolver ação
                                                                       (lista de permissões +
                                                                        limite de taxa)
                                                                                  │
                                  ┌───────────────────────┬───────────────────────┼────────────────────────┐
                                  ▼                       ▼                       ▼                        ▼
                          ┌──────────────┐       ┌────────────────┐      ┌──────────────┐         ┌─────────────┐
                          │ ClearPass    │       │ Ledger         │      │ Slack/Teams  │         │ SIEM        │
                          │ API REST     │       │ SQLite         │      │ notificação  │         │ (logs       │
                          │ - troca de   │       │ - estado       │      │              │         │ estruturados│
                          │   função     │       │ - liberação    │      │              │         │ )           │
                          │ - desconectar│       │   automática   │      │              │         │             │
                          └──────────────┘       └────────────────┘      └──────────────┘         └─────────────┘