nebulock-inc/agentic-threat-hunting-frameworkATHF è un framework per la caccia alle minacce agentica - costruire sistemi che possono ricordare, apprendere e agire con 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)**
*Dai al tuo programma di threat hunting memoria e capacità di azione.*
L'**Agentic Threat Hunting Framework (ATHF)** è il livello di memoria e automazione per il tuo programma di threat hunting. Dà alle tue cacce struttura, persistenza e contesto - rendendo ogni indagine passata accessibile sia agli esseri umani che all'IA.
ATHF funziona con qualsiasi metodologia di hunting (PEAK, TaHiTI o il tuo processo personale). Non è un sostituto; è il livello che rende il tuo processo esistente pronto per l'IA.
## Cos'è ATHF?
ATHF fornisce struttura e persistenza per i programmi di threat hunting. È un framework basato su markdown che:
- Documenta le cacce usando il pattern LOCK (Learn → Observe → Check → Keep)
- Mantiene un repository ricercabile delle indagini passate
- Consente agli assistenti IA di fare riferimento al tuo ambiente e al lavoro precedente
- Funziona con qualsiasi piattaforma SIEM/EDR
- **NOVITÀ:** Include agenti di ricerca e generazione di ipotesi basati su IA (v0.3.0+)
## Il Problema
La maggior parte dei programmi di threat hunting perde contesto prezioso una volta terminata una caccia. Le note vivono in Slack o nei ticket, le query vengono scritte una volta e dimenticate, e le lezioni apprese esistono solo nella testa degli analisti.
Anche gli strumenti IA partono da zero ogni volta senza accesso al tuo ambiente, ai tuoi dati o alle tue cacce passate.
ATHF cambia questo dando alle tue cacce struttura, persistenza e contesto.
**Leggi di più:** [docs/why-athf.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md)
## Il Pattern LOCK
Ogni threat hunt segue lo stesso ciclo di base: **Learn → Observe → Check → Keep**.
- **Learn:** Raccogli contesto da threat intel, alert o anomalie
- **Observe:** Formula un'ipotesi sul comportamento dell'avversario
- **Check:** Verifica le ipotesi con query mirate
- **Keep:** Registra i risultati e le lezioni apprese
**Perché LOCK?** È abbastanza piccolo da essere usato e abbastanza rigoroso da poter essere interpretato dagli agenti. Catturando ogni caccia in questo formato, ATHF rende possibile per gli assistenti IA richiamare il lavoro precedente e suggerire query raffinate basate sui risultati passati.
**Leggi di più:** [docs/lock-pattern.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md)
## Metodo GATES: Validazione della Promozione da Hunt a Detection
Dopo aver completato la fase **KEEP** di una caccia, il **metodo GATES** valida se i tuoi risultati dovrebbero essere promossi a detection di produzione, cacce ricorrenti o advisory.
**G**eneralizable, **A**dditive, **T**unable, **E**xposure-tested, **S**ustainable
> **Nota:** GATES è progettato per funzionare con il framework ATHF ed è stato ampiamente testato in quel contesto. Sebbene la metodologia (5 criteri BASE, tipi di verdetto) sia concettualmente portabile, raccomandiamo di usarla come parte del flusso di lavoro ATHF completo per ottenere i migliori risultati. Vedi `.claude/skills/gates/` per l'integrazione completa.
> **Installazione:** GATES è attualmente disponibile solo tramite `git clone`. Gli utenti che hanno installato tramite `pip install` dovrebbero clonare il repository per accedere a GATES. Stiamo lavorando per includere GATES nella distribuzione pip (tracciato come Issue #21).
GATES valuta le detection derivate dalle cacce usando un framework a due livelli: 5 criteri BASE (valutati dai dati della caccia) identificano i candidati alla distribuzione, mentre 5 criteri ADVANCED (validati in produzione) garantiscono **detection resilienti con bassi tassi di falsi positivi e falsi negativi**:
| Gate | Domanda | Cosa intercetta |
|------|----------|---------|
| **G** - Generalizable | È ripetibile? | Regole basate su IOC che scadono rapidamente |
| **A** - Additive | Colma una lacuna di copertura? | Detection duplicate o ridondanti |
| **T** - Tunable | Possiamo distinguere un attacco dal normale? | Disallineamento del rumore di baseline (principale causa di FP) |
| **E** - Exposure-tested | Abbiamo coperto le evasioni? | Detection monodimensionali |
| **S** - Sustainable | Possiamo mantenerla? | Regole ad alto volume e basso TP |
I verdetti si basano sui punteggi BASE (/5). Vedi `.claude/skills/gates/` per i metodi di validazione ADVANCED.
**Quick Start** — digita questo al tuo assistente; `/gates` è una skill, non un comando shell:
```text
/gates --hunt H-0001
```
**Tipi di verdetto:**
- ✅ **PROMOTE** (4.0-5.0) - Distribuisci come rilevamento permanente
- ⚠️ **CONDITIONAL** (3.0-3.9) - Distribuisci dopo aver soddisfatto i prerequisiti
- ❌ **HOLD** (0.0-2.9) - Conserva la logica, non distribuire
- ⏱️ **TIME_BOX** - Specifico per campagna, aggiornamento ogni 90 giorni
- 🔄 **RECURRING_HUNT** - Esecuzione trimestrale, non 24/7
- 🚫 **DROP** - Non vale la pena rilevarlo; registrato per non riproporlo
Un **gate FAIL sovrascrive la fascia di punteggio**, e quando due gate falliscono vince la prima corrispondenza in
quest'ordine: A→DROP, G→TIME_BOX, E→HOLD, S→RECURRING_HUNT, T→CONDITIONAL. Le
fasce sopra si applicano solo quando nessun gate è FAILed. Regola completa:
`.claude/skills/gates/SKILL.md` Step 4.
**Nota:** Il verdetto "PROMOTE" di GATES significa distribuire una regola di rilevamento. Questo è distinto da `athf hunt promote`, che sposta i file di hunt tra directory.
**Integrazione con ADEF (Detection Engineering Framework):**
Dopo la validazione GATES, procedi con ADEF per l'ingegneria di rilevamento in produzione:
```
ATHF Workspace ADEF Workspace
────────────── ──────────────
Hunt (LOCK)
↓
GATES Validate
↓
H-XXXX_GATES.yaml ────────────→ FORGE (F-O-R-G-E)
↓
Production Rule
```
**Workflow completo:**
1. Nel workspace ATHF, convalidare la caccia — input dell'assistente, non un comando shell:
```text
/gates --hunt H-0903
```
→ scrive `hunt-promotion-analysis/H-0903_GATES.yaml` (un file per hunt, N
candidati all'interno). Un hunt il cui verdetto è archiviato (`HOLD`, `DROP`, `TIME_BOX`,
`RECURRING_HUNT`) emette invece una narrazione `.md` — non c'è alcuna regola da costruire, quindi
il passo 2 si applica solo all'output `.yaml`.
2. Importa quel documento in ADEF:
```bash
adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-0903_GATES.yaml
# --dry-run first to preview what it would mint
```
I candidati distribuibili arrivano ciascuno alla fase Find con un `D-XXXX`, un record di catalogo e un journal; quelli archiviati vengono segnalati come saltati. Nessun `cd` necessario — ADEF risolve il suo workspace da `ADEF_WORKSPACE` (predefinito `~/work/adef-workspace/`). Conferma che il tuo ADEF abbia questa modalità con `adef hunt-promote --help`.
**Repository ADEF:** https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
GATES ti assicura di distribuire le detection giuste nel modo giusto, evitando l'affaticamento da alert e l'attrito operativo.
**Leggi di più:** [.claude/skills/gates/README.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md)
## I Cinque Livelli dell'Hunting Agentico
ATHF definisce un semplice modello di maturità. Ogni livello si costruisce sul precedente.
**La maggior parte dei team vivrà ai Livelli 1–2. Tutto ciò che va oltre è maturità opzionale.**
| Livello | Capacità | Cosa Ottieni |
|-------|-----------|--------------|
| **0** | Ad-hoc | Gli hunt esistono in Slack, ticket o note degli analisti |
| **1** | Documentato | Record di hunt persistenti usando LOCK |
| **2** | Ricercabile | L'AI legge e richiama i tuoi hunt |
| **3** | Generativo | L'AI esegue query tramite strumenti MCP, conduce ricerche |
| **4** | Agentico | Agenti autonomi monitorano e agiscono, generano ipotesi |
**Livello 1:** Operativo entro un giorno
**Livello 2:** Operativo entro una settimana
**Livello 3:** 2-4 settimane (opzionale)
**Livello 4:** 1-3 mesi (opzionale)
**Leggi di più:** [docs/maturity-model.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md)
## 🚀 Avvio Rapido
### Opzione 1: Installa da PyPI (Consigliato)
```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
```
### Opzione 2: Installazione dal codice sorgente (sviluppo)
```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
```
### Opzione 3: Markdown puro (nessuna installazione)
```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
```
**Scegli il tuo assistente AI:** Claude Code, GitHub Copilot o Cursor - qualsiasi strumento in grado di leggere i file del tuo repository.
**Guida completa:** [docs/getting-started.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md)
## 🔧 Comandi CLI
ATHF include una CLI completa per la gestione delle tue cacce. Ecco un riferimento rapido:
### Inizializza Workspace
```bash
athf init # Interactive setup
athf init --non-interactive # Use defaults
```
### Ricerca e Generazione di Ipotesi (NOVITÀ nella 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
```
### Crea 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
```
### Elenco e ricerca
```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
```
### Validazione e Statistiche
```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
```
La qualità del rilevamento viene valutata dalla **skill** GATES, che il tuo assistente invoca —
non fa parte della CLI `athf`, quindi non appartiene al blocco shell qui sopra:
```text
/gates --hunt H-0001
```
### Gestione dei dati ATT&CK (NOVITÀ nella 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
```
Senza `mitreattack-python`, ATHF utilizza un fallback hardcoded v14 (14 tattiche, conteggi approssimativi). Con esso, ottieni metadati completi delle tecniche: piattaforme, fonti di dati, sotto-tecniche e conteggi accurati.
### MCP Server (NOVITÀ in 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
```
Configurare in `~/.claude/mcp-servers.json`:
```json
{
"athf": {
"command": "athf-mcp",
"env": { "ATHF_WORKSPACE": "/path/to/your/hunts" }
}
}
```
Il punto di ingresso standalone `athf-mcp` rileva automaticamente il tuo workspace dalla cwd o dalla variabile d'ambiente `ATHF_WORKSPACE`. Usa `athf mcp serve --workspace /path` per percorsi espliciti.
> **Nota di sicurezza:** i trasporti `sse` e `streamable-http` si legano a `127.0.0.1` e sono **non autenticati**. Ogni strumento legge l'intero workspace e alcuni invocano agenti LLM a tue spese. Passa `--host` solo per legare un'interfaccia instradabile, e metti un proxy di autenticazione davanti quando lo fai. Il trasporto predefinito `stdio` non apre alcun socket.
Espone 17 strumenti: gestione delle hunt, ricerca semantica, copertura ATT&CK, ricerca, indagini e generazione di ipotesi basata sull'AI — tutti accessibili direttamente dal tuo assistente AI per la programmazione.
**Documentazione completa:** [Riferimento CLI](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
## 📺 Guardalo in Azione
Guarda ATHF in azione: inizializza un workspace, crea hunt ed esplora il tuo catalogo di threat hunting in meno di 60 secondi.
**[Visualizza hunt di esempio →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
## Installazione
Consulta la sezione [Avvio Rapido](#-quick-start) qui sopra per le opzioni di installazione (PyPI, sorgente o puro markdown).
**Prerequisiti:**
- Python 3.11 o superiore (per l'opzione CLI)
- Il tuo assistente AI per la programmazione preferito
## Documentazione
### Concetti Fondamentali
- [Perché Esiste ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md) - Il problema e la soluzione
- [Il Pattern LOCK](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md) - Struttura per tutte le hunt
- [Modello di Maturità](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md) - I cinque livelli spiegati
- [Per Iniziare](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md) - Onboarding passo dopo passo
### Guide Specifiche per Livello
- [Livello 1: Hunt Documentate](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-1-documented-hunts)
- [Livello 2: Memoria Ricercabile](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-2-searchable-memory)
- [Livello 3: Capacità Generative](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
- [Livello 4: Workflow Agentici](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
### Integrazione e Personalizzazione
- [Installazione e Sviluppo](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md) - Setup, personalizzazione del fork, testing
- [Metodo GATES](https://github.com/nebulock-inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md) - Skill di validazione del rilevamento (collega LOCK → ADEF)
- [Catalogo MCP](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/integrations/MCP_CATALOG.md) - Integrazioni di strumenti disponibili
- [Guide di Avvio Rapido](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/tree/main/integrations/quickstart/) - Setup per strumenti specifici
- [Usare ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) - Adozione e personalizzazione
## 🎖️ Hunt in Evidenza
### H-0001: Rilevamento di Information Stealer su macOS
Rilevato Atomic Stealer mentre raccoglieva cookie di Safari tramite AppleScript.
**Risultato:** 1 vero positivo, host isolato prima dell'esfiltrazione.
**Intuizione Chiave:** il rilevamento basato sul comportamento ha superato gli approcci basati sulle firme. La validazione della firma del processo ha identificato malware non firmato che tentava la raccolta dati.
[Visualizza la hunt completa →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/hunts/H-0001.md) | [Vedi altri esempi →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)
## Perché Questo Conta
Potresti chiederti come questo interagisca con framework come [PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html). PEAK ti fornisce un metodo solido su come cacciare. ATHF costruisce su quella base dandoti struttura, memoria e continuità. PEAK guida il lavoro. ATHF assicura che tu catturi il lavoro, lo organizzi e lo riutilizzi nelle hunt future.
L'agentic threat hunting non riguarda la sostituzione degli analisti. Riguarda la costruzione di sistemi che possono:
- Ricordare ciò che è stato fatto prima
- Imparare dai successi e dagli errori passati
- Supportare il giudizio umano con il richiamo contestuale
Quando il tuo framework ha memoria, smetti di perdere conoscenza a causa del turnover o di appunti dimenticati. Quando il tuo assistente AI può fare riferimento a quella memoria, diventa un moltiplicatore di forza.
## 💬 Community e Adozione
- **Discussioni GitHub:** [Fai domande, condividi hunt](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
- **Issue:** [Segnala bug o richiedi funzionalità](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
- **LinkedIn:** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - Segui per aggiornamenti
**Usare ATHF nella Tua Organizzazione:** ATHF è un framework da interiorizzare, non una piattaforma da estendere. Fai il fork, personalizzalo, rendilo tuo. Consulta [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) per la guida all'adozione. Le tue hunt restano tue—condividerle è opzionale ma apprezzato.
**Repository:** [https://github.com/Nebulock-Inc/agentic-threat-hunting-framework](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
L'obiettivo è aiutare ogni team di threat hunting a passare da una memoria ad-hoc a una capacità strutturata e agentica.
---
## 🛠️ Sviluppo e Personalizzazione
ATHF è progettato per essere forkato e personalizzato per la tua organizzazione.
**Consulta [docs/INSTALL.md#development--customization](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md#development--customization) per:**
- Configurare il tuo fork per lo sviluppo
- Hook pre-commit per la qualità del codice
- Testing e type checking
- Esempi di personalizzazione
- Integrazione CI/CD
Avvio rapido:
```bash
pip install -e ".[dev]" # Install dev dependencies
pre-commit install # Set up quality checks
pytest tests/ -v # Run tests
```
---
## 👤 Autore
Creato da **Sydney Marrone** © 2025
---
**Inizia in piccolo. Documenta una caccia. Aggiungi struttura. Costruisci memoria.**
La memoria è il moltiplicatore. L'agentività è la forza.
Una volta che il tuo programma può ricordare, tutto il resto diventa possibile.
Buona caccia!