Agentic Threat Hunting Framework (ATHF)

Quick Start • Installation • Documentation • Examples

Dê ao seu programa de threat hunting memória e agência.

O Agentic Threat Hunting Framework (ATHF) é a camada de memória e automação para o seu programa de threat hunting. Ele dá às suas hunts estrutura, persistência e contexto - tornando cada investigação passada acessível tanto para humanos quanto para IA.

O ATHF funciona com qualquer metodologia de hunting (PEAK, TaHiTI ou o seu próprio processo). Não é um substituto; é a camada que torna o seu processo existente pronto para IA.

O que é o ATHF?

O ATHF fornece estrutura e persistência para programas de threat hunting. É um framework baseado em markdown que:

• Documenta hunts usando o padrão LOCK (Learn → Observe → Check → Keep)
• Mantém um repositório pesquisável de investigações passadas
• Permite que assistentes de IA referenciem o seu ambiente e trabalhos anteriores
• Funciona com qualquer plataforma SIEM/EDR
• NOVO: Inclui agentes de pesquisa e geração de hipóteses com IA (v0.3.0+)

O Problema

A maioria dos programas de threat hunting perde contexto valioso assim que uma hunt termina. As notas ficam no Slack ou em tickets, as queries são escritas uma vez e esquecidas, e as lições aprendidas existem apenas na cabeça dos analistas.

Até mesmo ferramentas de IA começam do zero toda vez, sem acesso ao seu ambiente, aos seus dados ou às suas hunts passadas.

O ATHF muda isso ao dar às suas hunts estrutura, persistência e contexto.

Leia mais: docs/why-athf.md

O Padrão LOCK

Toda threat hunt segue o mesmo loop básico: Learn → Observe → Check → Keep.

• Learn: Reúna contexto a partir de threat intel, alertas ou anomalias
• Observe: Formule uma hipótese sobre o comportamento do adversário
• Check: Teste hipóteses com queries direcionadas
• Keep: Registre descobertas e lições aprendidas

Por que LOCK? É pequeno o suficiente para ser usado e estrito o suficiente para que agentes o interpretem. Ao capturar cada hunt nesse formato, o ATHF torna possível que assistentes de IA recordem trabalhos anteriores e sugiram queries refinadas com base em resultados passados.

Leia mais: docs/lock-pattern.md

Método GATES: Validação de Promoção de Hunt para Detecção

Após concluir a fase KEEP de uma hunt, o método GATES valida se as suas descobertas devem ser promovidas para detecções de produção, hunts recorrentes ou advisories.

Generalizable, Additive, Tunable, Exposure-tested, Sustainable

Nota: O GATES foi projetado para funcionar com o framework ATHF e foi extensivamente testado nesse contexto. Embora a metodologia (5 critérios BASE, tipos de veredito) seja conceitualmente portável, recomendamos usá-la como parte do fluxo de trabalho completo do ATHF para melhores resultados. Consulte .claude/skills/gates/ para a integração completa.

Instalação: O GATES está atualmente disponível apenas via git clone. Usuários que instalaram via pip install devem clonar o repositório para acessar o GATES. Estamos trabalhando para incluir o GATES na distribuição pip (rastreado como Issue #21).

O GATES avalia detecções derivadas de hunts usando um framework de dois níveis: 5 critérios BASE (avaliados a partir dos dados da hunt) identificam candidatos à implantação, enquanto 5 critérios ADVANCED (validados em produção) garantem detecções resilientes com baixas taxas de falsos positivos e falsos negativos:

Gate	Pergunta	Detecta
G - Generalizable	Isso é repetível?	Regras baseadas em IOC que expiram rapidamente
A - Additive	Isso preenche uma lacuna de cobertura?	Detecções duplicadas ou redundantes
T - Tunable	Conseguimos distinguir ataque de normal?	Incompatibilidade de ruído de baseline (principal causa de FP)
E - Exposure-tested	Cobrimos as evasões?	Detecções unidimensionais
S - Sustainable	Conseguimos manter isso?	Regras de alto volume e baixo TP

Os vereditos são baseados nas pontuações BASE (/5). Consulte .claude/skills/gates/ para os métodos de validação ADVANCED.

Quick Start — digite isto para o seu assistente; /gates é uma skill, não um comando de shell:

/gates --hunt H-0001

Tipos de Veredito:

• ✅ PROMOTE (4.0-5.0) - Implantar como deteção permanente
• ⚠️ CONDITIONAL (3.0-3.9) - Implantar após pré-requisitos cumpridos
• ❌ HOLD (0.0-2.9) - Preservar a lógica, não implantar
• ⏱️ TIME_BOX - Específico da campanha, atualização a cada 90 dias
• 🔄 RECURRING_HUNT - Execução trimestral, não 24/7
• 🚫 DROP - Não vale a pena detetar; registado para não ser reproposto

Um gate FAIL sobrepõe-se à faixa de pontuação, e quando dois gates falham, a primeira correspondência nesta ordem vence: A→DROP, G→TIME_BOX, E→HOLD, S→RECURRING_HUNT, T→CONDITIONAL. As faixas acima aplicam-se apenas quando nenhum gate falhou. Regra completa: .claude/skills/gates/SKILL.md Passo 4.

Nota: O veredito "PROMOTE" do GATES significa implantar uma regra de deteção. Isto é distinto de athf hunt promote, que move ficheiros de caça entre diretórios.

Integração com ADEF (Detection Engineering Framework):

Após a validação do GATES, prossiga para o ADEF para engenharia de deteção em produção:

ATHF Workspace                    ADEF Workspace
──────────────                    ──────────────
Hunt (LOCK)                       
   ↓
GATES Validate                    
   ↓
H-XXXX_GATES.yaml  ────────────→  FORGE (F-O-R-G-E)
                                     ↓
                                  Production Rule

Fluxo de Trabalho Completo:

1. No workspace do ATHF, valide a caçada — entrada do assistente, não um comando de shell:

   /gates --hunt H-0903
   

   → escreve hunt-promotion-analysis/H-0903_GATES.yaml (um arquivo por hunt, N candidatos dentro). Um hunt cujo veredito é arquivístico (HOLD, DROP, TIME_BOX, RECURRING_HUNT) emite uma narrativa .md em vez disso — não há regra a construir, então o passo 2 aplica-se apenas à saída .yaml.

2. Importe esse documento para o ADEF:

   adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-0903_GATES.yaml
   # --dry-run first to preview what it would mint