nebulock-inc/agentic-threat-hunting-frameworkATHF é um framework para caça a ameaças agentivas - construindo sistemas que podem lembrar, aprender e agir com autonomia crescente.
# Agentic Threat Hunting Framework (ATHF)
[](https://pypi.org/project/agentic-threat-hunting-framework/)
[](https://pypi.org/project/agentic-threat-hunting-framework/)
[](https://www.python.org/downloads/)
[](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/LICENSE)
[](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/stargazers)
**[Quick Start](#-quick-start)** • **[Installation](#installation)** • **[Documentation](#documentation)** • **[Examples](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
*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](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/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](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/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.
**G**eneralizable, **A**dditive, **T**unable, **E**xposure-tested, **S**ustainable
> **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:
```text
/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:
```text
/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:
```bash
adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-0903_GATES.yaml
# --dry-run first to preview what it would mint
```
Candidatos implantáveis chegam à etapa Find com um `D-XXXX`, um registro de catálogo
e um journal; os arquivais são reportados como ignorados. Não é necessário `cd` — o ADEF resolve
seu workspace a partir de `ADEF_WORKSPACE` (padrão `~/work/adef-workspace/`). Confirme se seu
ADEF possui esse modo com `adef hunt-promote --help`.
**Repositório do ADEF:** https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
O GATES garante que você implante as detecções certas da maneira certa, evitando fadiga de alertas e atrito operacional.
**Leia mais:** [.claude/skills/gates/README.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md)
## Os Cinco Níveis de Caça Agêntica
O ATHF define um modelo de maturidade simples. Cada nível se baseia no anterior.
**A maioria das equipes ficará nos Níveis 1–2. Tudo além disso é maturidade opcional.**
| Nível | Capacidade | O Que Você Obtém |
|-------|-----------|--------------|
| **0** | Ad-hoc | As caças existem no Slack, em tickets ou em anotações de analistas |
| **1** | Documentado | Registros de caça persistentes usando o LOCK |
| **2** | Pesquisável | A IA lê e recupera suas caças |
| **3** | Generativo | A IA executa consultas via ferramentas MCP, conduz pesquisas |
| **4** | Agêntico | Agentes autônomos monitoram e agem, geram hipóteses |
**Nível 1:** Operacional em um dia
**Nível 2:** Operacional em uma semana
**Nível 3:** 2-4 semanas (opcional)
**Nível 4:** 1-3 meses (opcional)
**Leia mais:** [docs/maturity-model.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md)
## 🚀 Início Rápido
### Opção 1: Instalar do PyPI (Recomendado)
```bash
# Install ATHF
pip install agentic-threat-hunting-framework
# Initialize your hunt program
athf init
# NEW: Conduct research before hunting (5-skill methodology)
athf research new --topic "LSASS dumping" --technique T1003.001
# Create your first hunt (link to research)
athf hunt new --technique T1003.001 --title "LSASS Credential Dumping" --research R-0001
```
### Opção 2: Instalar a partir do Código-Fonte (Desenvolvimento)
```bash
# Clone and install from source
git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
cd agentic-threat-hunting-framework
pip install -e .
# Initialize and start hunting
athf init
athf hunt new --technique T1003.001
```
### Opção 3: Markdown Puro (Sem Instalação)
```bash
# Clone the repository
git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
cd agentic-threat-hunting-framework
# Copy a template and start documenting
mkdir -p hunts
cp athf/data/templates/HUNT_LOCK.md hunts/H-0001.md
# Customize AGENTS.md with your environment
# Add your SIEM, EDR, and data sources
```
**Escolha seu assistente de IA:** Claude Code, GitHub Copilot ou Cursor - qualquer ferramenta que consiga ler os arquivos do seu repositório.
**Guia completo:** [docs/getting-started.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md)
## 🔧 Comandos da CLI
O ATHF inclui uma CLI completa para gerenciar suas caçadas. Aqui está uma referência rápida:
### Inicializar o Workspace
```bash
athf init # Interactive setup
athf init --non-interactive # Use defaults
```
### Pesquisa e Geração de Hipóteses (NOVO na v0.3.0)
```bash
# Conduct thorough pre-hunt research (15-20 min)
athf research new --topic "LSASS dumping" --technique T1003.001
# Quick research for urgent hunts (5 min)
athf research new --topic "Pass-the-Hash" --depth basic
# Generate AI-powered hypothesis from threat intel
athf agent run hypothesis-generator --threat-intel "APT29 targeting SaaS"
# List research and agents
athf research list
athf agent list
```
### Criar Hunts
```bash
athf hunt new # Interactive mode
athf hunt new \
--technique T1003.001 \
--title "LSASS Dumping Detection" \
--platform windows \
--hunt-type baseline \
--research R-0001 # Link to research document
# --hunt-type: hypothesis (default) | baseline | model-assisted
```
### Listar e Pesquisar
```bash
athf hunt list # Show all hunts
athf hunt list --status completed # Filter by status
athf hunt list --directory test # Filter by environment (test/production)
athf hunt list --hunt-type baseline # Filter by hunt category
athf hunt list --output json # JSON output
athf hunt search "kerberoasting" # Full-text search
athf hunt search "credential" --directory production # Search with directory filter
athf research search "credential" # Search research docs
```
### Validar e Estatísticas
```bash
athf hunt validate # Validate all hunts
athf hunt validate H-0001 # Validate specific hunt
athf hunt stats # Show statistics (incl. hunts by type)
athf hunt stats --by hunt_type --status completed --output json # Category breakdown
athf hunt coverage # MITRE ATT&CK coverage
athf research stats # Research metrics
```
A qualidade da deteção é avaliada pela **skill** GATES, que o seu assistente invoca —
não faz parte da CLI `athf`, por isso não pertence ao bloco de shell acima:
```text
/gates --hunt H-0001
```
### Gerenciamento de Dados ATT&CK (NOVO na v0.11.0)
```bash
# Install STIX support (optional)
pip install 'agentic-threat-hunting-framework[attack]'
# Download live ATT&CK data (835+ techniques with full metadata)
athf attack update
# Check provider status
athf attack status
# Look up technique metadata
athf attack lookup T1003.001
# List techniques for a tactic
athf attack techniques credential-access
```
Sem `mitreattack-python`, o ATHF usa um fallback v14 hardcoded (14 táticas, contagens aproximadas). Com ele, você obtém metadados completos de técnicas: plataformas, fontes de dados, sub-técnicas e contagens precisas.
### Servidor MCP (NOVO na v0.11.0)
```bash
# Install MCP dependencies
pip install 'agentic-threat-hunting-framework[mcp]'
# Start MCP server (for Claude Code, Copilot, Cursor, etc.)
athf mcp serve --workspace /path/to/hunts
```
Configure em `~/.claude/mcp-servers.json`:
```json
{
"athf": {
"command": "athf-mcp",
"env": { "ATHF_WORKSPACE": "/path/to/your/hunts" }
}
}
```
O ponto de entrada autónomo `athf-mcp` deteta automaticamente o seu workspace a partir do cwd ou da variável de ambiente `ATHF_WORKSPACE`. Utilize `athf mcp serve --workspace /path` para caminhos explícitos.
> **Nota de segurança:** os transportes `sse` e `streamable-http` ligam-se a `127.0.0.1` e são **não autenticados**. Todas as ferramentas leem todo o seu workspace e algumas invocam agentes LLM à sua custa. Só passe `--host` para ligar a uma interface encaminhável, e coloque um proxy de autenticação à frente quando o fizer. O transporte `stdio` predefinido não abre qualquer socket.
Expõe 17 ferramentas: gestão de hunts, pesquisa semântica, cobertura ATT&CK, investigação, investigações e geração de hipóteses com IA — todas acessíveis diretamente a partir do seu assistente de programação com IA.
**Documentação completa:** [Referência da CLI](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
## 📺 Veja em Ação
Veja o ATHF em ação: inicialize um workspace, crie hunts e explore o seu catálogo de threat hunting em menos de 60 segundos.
**[Ver hunts de exemplo →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
## Instalação
Consulte a secção [Início Rápido](#-quick-start) acima para opções de instalação (PyPI, código-fonte ou markdown puro).
**Pré-requisitos:**
- Python 3.11 ou superior (para a opção CLI)
- O seu assistente de programação com IA preferido
## Documentação
### Conceitos Fundamentais
- [Porque Existe o ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md) - O problema e a solução
- [O Padrão LOCK](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md) - Estrutura para todas as hunts
- [Modelo de Maturidade](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md) - Os cinco níveis explicados
- [Primeiros Passos](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md) - Integração passo a passo
### Guias Específicos por Nível
- [Nível 1: Hunts Documentadas](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-1-documented-hunts)
- [Nível 2: Memória Pesquisável](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-2-searchable-memory)
- [Nível 3: Capacidades Generativas](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
- [Nível 4: Fluxos de Trabalho Agênticos](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
### Integração e Personalização
- [Instalação e Desenvolvimento](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md) - Configuração, personalização de fork, testes
- [Método GATES](https://github.com/nebulock-inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md) - Competência de validação de deteção (liga LOCK → ADEF)
- [Catálogo MCP](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/integrations/MCP_CATALOG.md) - Integrações de ferramentas disponíveis
- [Guias de Início Rápido](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/tree/main/integrations/quickstart/) - Configuração para ferramentas específicas
- [Utilizar o ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) - Adoção e personalização
## 🎖️ Hunts em Destaque
### H-0001: Deteção de Information Stealer em macOS
Detetado o Atomic Stealer a recolher cookies do Safari através de AppleScript.
**Resultado:** 1 verdadeiro positivo, host isolado antes da exfiltração.
**Conclusão Principal:** A deteção baseada em comportamento superou as abordagens baseadas em assinaturas. A validação de assinatura de processos identificou malware não assinado a tentar recolher dados.
[Ver hunt completa →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/hunts/H-0001.md) | [Ver mais exemplos →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)
## Porque Isto Importa
Pode perguntar-se como isto interage com frameworks como o [PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html). O PEAK dá-lhe um método sólido para como fazer hunting. O ATHF constrói sobre essa base dando-lhe estrutura, memória e continuidade. O PEAK orienta o trabalho. O ATHF garante que captura o trabalho, o organiza e o reutiliza em hunts futuras.
O threat hunting agêntico não se trata de substituir analistas. Trata-se de construir sistemas que conseguem:
- Recordar o que foi feito antes
- Aprender com sucessos e erros passados
- Apoiar o julgamento humano com recuperação contextual
Quando a sua framework tem memória, deixa de perder conhecimento devido a rotatividade ou notas esquecidas. Quando o seu assistente de IA consegue consultar essa memória, torna-se um multiplicador de força.
## 💬 Comunidade e Adoção
- **Discussões no GitHub:** [Faça perguntas, partilhe hunts](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
- **Issues:** [Reporte bugs ou solicite funcionalidades](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
- **LinkedIn:** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - Siga para atualizações
**Utilizar o ATHF na Sua Organização:** O ATHF é uma framework para internalizar, não uma plataforma para estender. Faça fork, personalize-a, torne-a sua. Consulte [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) para orientações de adoção. As suas hunts permanecem suas—partilhar de volta é opcional mas apreciado.
**Repositório:** [https://github.com/Nebulock-Inc/agentic-threat-hunting-framework](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
O objetivo é ajudar cada equipa de threat hunting a passar de memória ad-hoc para capacidade estruturada e agêntica.
---
## 🛠️ Desenvolvimento e Personalização
O ATHF foi concebido para ser bifurcado e personalizado para a sua organização.
**Consulte [docs/INSTALL.md#development--customization](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md#development--customization) para:**
- Configurar o seu fork para desenvolvimento
- Pre-commit hooks para qualidade de código
- Testes e verificação de tipos
- Exemplos de personalização
- Integração CI/CD
Início rápido:
```bash
pip install -e ".[dev]" # Install dev dependencies
pre-commit install # Set up quality checks
pytest tests/ -v # Run tests
```
---
## 👤 Autor
Criado por **Sydney Marrone** © 2025
---
**Comece pequeno. Documente uma caçada. Adicione estrutura. Construa memória.**
A memória é o multiplicador. A agência é a força.
Assim que o seu programa conseguir lembrar, tudo o resto se torna possível.
Boas caçadas!