nebulock-inc/agentic-threat-hunting-frameworkATHF est un framework pour la chasse aux menaces agentique - construisant des systèmes capables de se souvenir, d'apprendre et d'agir avec une autonomie croissante.
# 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)**
*Donnez à votre programme de threat hunting de la mémoire et de l'autonomie.*
L'**Agentic Threat Hunting Framework (ATHF)** est la couche de mémoire et d'automatisation de votre programme de threat hunting. Il donne à vos chasses une structure, une persistance et un contexte - rendant chaque investigation passée accessible aussi bien aux humains qu'à l'IA.
ATHF fonctionne avec n'importe quelle méthodologie de chasse (PEAK, TaHiTI, ou votre propre processus). Ce n'est pas un remplacement ; c'est la couche qui rend votre processus existant prêt pour l'IA.
## Qu'est-ce qu'ATHF ?
ATHF fournit une structure et une persistance pour les programmes de threat hunting. C'est un framework basé sur Markdown qui :
- Documente les chasses en utilisant le pattern LOCK (Learn → Observe → Check → Keep)
- Maintient un dépôt consultable des investigations passées
- Permet aux assistants IA de référencer votre environnement et vos travaux précédents
- Fonctionne avec n'importe quelle plateforme SIEM/EDR
- **NOUVEAU :** Inclut des agents de recherche et de génération d'hypothèses propulsés par l'IA (v0.3.0+)
## Le Problème
La plupart des programmes de threat hunting perdent un contexte précieux dès qu'une chasse se termine. Les notes vivent dans Slack ou des tickets, les requêtes sont écrites une fois puis oubliées, et les leçons apprises n'existent que dans la tête des analystes.
Même les outils d'IA repartent de zéro à chaque fois, sans accès à votre environnement, vos données ou vos chasses passées.
ATHF change cela en donnant à vos chasses une structure, une persistance et un contexte.
**En savoir plus :** [docs/why-athf.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md)
## Le Pattern LOCK
Chaque threat hunt suit la même boucle de base : **Learn → Observe → Check → Keep**.
- **Learn :** Rassembler le contexte à partir du renseignement sur les menaces, des alertes ou des anomalies
- **Observe :** Formuler une hypothèse sur le comportement de l'adversaire
- **Check :** Tester les hypothèses avec des requêtes ciblées
- **Keep :** Consigner les conclusions et les leçons apprises
**Pourquoi LOCK ?** Il est suffisamment simple à utiliser et suffisamment strict pour que les agents puissent l'interpréter. En capturant chaque chasse dans ce format, ATHF permet aux assistants IA de se rappeler des travaux antérieurs et de suggérer des requêtes affinées basées sur les résultats passés.
**En savoir plus :** [docs/lock-pattern.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md)
## Méthode GATES : Validation de la Promotion Hunt-vers-Détection
Après avoir complété la phase **KEEP** d'une chasse, la **méthode GATES** valide si vos conclusions doivent être promues en détections de production, chasses récurrentes ou avis.
**G**eneralizable (Généralisable), **A**dditive (Additif), **T**unable (Ajustable), **E**xposure-tested (Testé en exposition), **S**ustainable (Durable)
> **Note :** GATES est conçu pour fonctionner avec le framework ATHF et a été largement testé dans ce contexte. Bien que la méthodologie (5 critères BASE, types de verdicts) soit conceptuellement portable, nous recommandons de l'utiliser dans le cadre du workflow ATHF complet pour de meilleurs résultats. Voir `.claude/skills/gates/` pour l'intégration complète.
> **Installation :** GATES est actuellement disponible uniquement via `git clone`. Les utilisateurs ayant installé via `pip install` doivent cloner le dépôt pour accéder à GATES. Nous travaillons à inclure GATES dans la distribution pip (suivi sous l'Issue #21).
GATES évalue les détections issues de chasses en utilisant un framework à deux niveaux : 5 critères BASE (évalués à partir des données de chasse) identifient les candidats au déploiement, tandis que 5 critères ADVANCED (validés en production) garantissent des **détections résilientes avec de faibles taux de faux positifs et de faux négatifs** :
| Gate | Question | Détecte |
|------|----------|---------|
| **G** - Generalizable | Est-ce reproductible ? | Règles basées sur des IOC qui expirent rapidement |
| **A** - Additive | Comble-t-il une lacune de couverture ? | Détections dupliquées ou redondantes |
| **T** - Tunable | Pouvons-nous distinguer une attaque d'un comportement normal ? | Inadéquation du bruit de référence (principale cause de FP) |
| **E** - Exposure-tested | Avons-nous couvert les évasions ? | Détections unidimensionnelles |
| **S** - Sustainable | Pouvons-nous maintenir cela ? | Règles à fort volume et faible TP |
Les verdicts sont basés sur les scores BASE (/5). Voir `.claude/skills/gates/` pour les méthodes de validation ADVANCED.
**Quick Start** — tapez ceci à votre assistant ; `/gates` est une skill, pas une commande shell :
```text
/gates --hunt H-0001
```
**Types de verdict :**
- ✅ **PROMOTE** (4.0-5.0) - Déployer comme détection permanente
- ⚠️ **CONDITIONAL** (3.0-3.9) - Déployer après avoir rempli les prérequis
- ❌ **HOLD** (0.0-2.9) - Préserver la logique, ne pas déployer
- ⏱️ **TIME_BOX** - Spécifique à une campagne, rafraîchissement tous les 90 jours
- 🔄 **RECURRING_HUNT** - Exécution trimestrielle, pas en 24/7
- 🚫 **DROP** - Ne vaut pas la peine d'être détecté ; enregistré pour ne pas être reproposé
Un **échec de gate prime sur la bande de score**, et lorsque deux gates échouent, la première correspondance dans
cet ordre l'emporte : A→DROP, G→TIME_BOX, E→HOLD, S→RECURRING_HUNT, T→CONDITIONAL. Les
bandes ci-dessus ne s'appliquent que lorsqu'aucun gate n'a échoué. Règle complète :
`.claude/skills/gates/SKILL.md` Step 4.
**Remarque :** Le verdict « PROMOTE » de GATES signifie déployer une règle de détection. Cela est distinct de `athf hunt promote`, qui déplace les fichiers de hunt entre les répertoires.
**Intégration avec ADEF (Detection Engineering Framework) :**
Après la validation GATES, passer à ADEF pour l'ingénierie de détection en production :
```
ATHF Workspace ADEF Workspace
────────────── ──────────────
Hunt (LOCK)
↓
GATES Validate
↓
H-XXXX_GATES.yaml ────────────→ FORGE (F-O-R-G-E)
↓
Production Rule
```
**Flux de travail complet :**
1. Dans l'espace de travail ATHF, validez la chasse — saisie de l'assistant, pas une commande shell :
```text
/gates --hunt H-0903
```
→ écrit `hunt-promotion-analysis/H-0903_GATES.yaml` (un fichier par hunt, N
candidats à l'intérieur). Un hunt dont le verdict est archivable (`HOLD`, `DROP`, `TIME_BOX`,
`RECURRING_HUNT`) émet à la place une narration `.md` — il n'y a pas de règle à construire, donc
l'étape 2 s'applique uniquement à la sortie `.yaml`.
2. Importer ce document dans ADEF :
```bash
adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-0903_GATES.yaml
# --dry-run first to preview what it would mint
```
Les candidats déployables arrivent chacun à l'étape Find avec un `D-XXXX`, un enregistrement de catalogue et un journal ; les candidats archivistiques sont signalés comme ignorés. Aucun `cd` nécessaire — ADEF résout son espace de travail à partir de `ADEF_WORKSPACE` (par défaut `~/work/adef-workspace/`). Confirmez que votre ADEF dispose de ce mode avec `adef hunt-promote --help`.
**Dépôt ADEF :** https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
GATES vous garantit de déployer les bonnes détections de la bonne manière, en évitant la fatigue d'alerte et les frictions opérationnelles.
**En savoir plus :** [.claude/skills/gates/README.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md)
## Les cinq niveaux du hunting agentique
ATHF définit un modèle de maturité simple. Chaque niveau s'appuie sur le précédent.
**La plupart des équipes resteront aux niveaux 1–2. Tout ce qui va au-delà relève d'une maturité optionnelle.**
| Niveau | Capacité | Ce que vous obtenez |
|-------|-----------|--------------|
| **0** | Ad-hoc | Les hunts existent dans Slack, les tickets ou les notes d'analystes |
| **1** | Documenté | Enregistrements de hunt persistants via LOCK |
| **2** | Interrogeable | L'IA lit et se remémore vos hunts |
| **3** | Génératif | L'IA exécute des requêtes via les outils MCP, mène des recherches |
| **4** | Agentique | Des agents autonomes surveillent et agissent, génèrent des hypothèses |
**Niveau 1 :** Opérationnel en une journée
**Niveau 2 :** Opérationnel en une semaine
**Niveau 3 :** 2-4 semaines (optionnel)
**Niveau 4 :** 1-3 mois (optionnel)
**En savoir plus :** [docs/maturity-model.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md)
## 🚀 Démarrage rapide
### Option 1 : Installer depuis PyPI (Recommandé)
```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
```
### Option 2 : Installation depuis les sources (développement)
```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
```
### Option 3 : Markdown pur (aucune installation)
```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
```
**Choisissez votre assistant IA :** Claude Code, GitHub Copilot ou Cursor - tout outil capable de lire les fichiers de votre dépôt.
**Guide complet :** [docs/getting-started.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md)
## 🔧 Commandes CLI
ATHF inclut une CLI complète pour gérer vos chasses. Voici une référence rapide :
### Initialiser l'espace de travail
```bash
athf init # Interactive setup
athf init --non-interactive # Use defaults
```
### Recherche et génération d'hypothèses (NOUVEAU dans la 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
```
### Créer des 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
```
### Lister et rechercher
```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
```
### Validation et statistiques
```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é de détection est évaluée par la **compétence** GATES, que votre assistant invoque —
elle ne fait pas partie de la CLI `athf`, elle n'a donc pas sa place dans le bloc shell ci-dessus :
```text
/gates --hunt H-0001
```
### Gestion des données ATT&CK (NOUVEAU dans la 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
```
Sans `mitreattack-python`, ATHF utilise un fallback v14 codé en dur (14 tactiques, comptages approximatifs). Avec lui, vous obtenez les métadonnées complètes des techniques : plateformes, sources de données, sous-techniques et comptages précis.
### Serveur MCP (NOUVEAU dans la 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
```
Configurer dans `~/.claude/mcp-servers.json` :
```json
{
"athf": {
"command": "athf-mcp",
"env": { "ATHF_WORKSPACE": "/path/to/your/hunts" }
}
}
```
Le point d'entrée autonome `athf-mcp` détecte automatiquement votre espace de travail à partir du cwd ou de la variable d'environnement `ATHF_WORKSPACE`. Utilisez `athf mcp serve --workspace /path` pour des chemins explicites.
> **Note de sécurité :** les transports `sse` et `streamable-http` se lient à `127.0.0.1` et ne sont **pas authentifiés**. Chaque outil lit l'intégralité de votre espace de travail et certains invoquent des agents LLM à vos frais. Ne passez `--host` que pour lier une interface routable, et placez un proxy d'authentification devant lorsque vous le faites. Le transport `stdio` par défaut n'ouvre aucune socket.
Expose 17 outils : gestion de chasses, recherche sémantique, couverture ATT&CK, recherche, investigations et génération d'hypothèses assistée par IA — tous accessibles directement depuis votre assistant de codage IA.
**Documentation complète :** [Référence CLI](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
## 📺 Voyez-le en action
Regardez ATHF en action : initialisez un espace de travail, créez des chasses et explorez votre catalogue de chasse aux menaces en moins de 60 secondes.
**[Voir des exemples de chasses →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
## Installation
Consultez la section [Démarrage rapide](#-quick-start) ci-dessus pour les options d'installation (PyPI, source ou markdown pur).
**Prérequis :**
- Python 3.11 ou supérieur (pour l'option CLI)
- Votre assistant de codage IA préféré
## Documentation
### Concepts fondamentaux
- [Pourquoi ATHF existe](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md) - Le problème et la solution
- [Le pattern LOCK](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md) - Structure pour toutes les chasses
- [Modèle de maturité](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md) - Les cinq niveaux expliqués
- [Premiers pas](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md) - Intégration étape par étape
### Guides spécifiques aux niveaux
- [Niveau 1 : Chasses documentées](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-1-documented-hunts)
- [Niveau 2 : Mémoire interrogeable](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-2-searchable-memory)
- [Niveau 3 : Capacités génératives](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
- [Niveau 4 : Workflows agentiques](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
### Intégration et personnalisation
- [Installation et développement](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md) - Configuration, personnalisation du fork, tests
- [Méthode GATES](https://github.com/nebulock-inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md) - Compétence de validation de détection (fait le lien entre LOCK → ADEF)
- [Catalogue MCP](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/integrations/MCP_CATALOG.md) - Intégrations d'outils disponibles
- [Guides de démarrage rapide](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/tree/main/integrations/quickstart/) - Configuration pour des outils spécifiques
- [Utiliser ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) - Adoption et personnalisation
## 🎖️ Chasses en vedette
### H-0001 : Détection de voleur d'informations macOS
Détection d'Atomic Stealer collectant les cookies Safari via AppleScript.
**Résultat :** 1 vrai positif, hôte isolé avant l'exfiltration.
**Enseignement clé :** La détection basée sur le comportement a surpassé les approches basées sur les signatures. La validation de signature de processus a identifié un malware non signé tentant une collecte de données.
[Voir la chasse complète →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/hunts/H-0001.md) | [Voir plus d'exemples →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)
## Pourquoi c'est important
Vous vous demandez peut-être comment cela interagit avec des frameworks comme [PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html). PEAK vous donne une méthode solide pour chasser. ATHF s'appuie sur cette fondation en vous offrant structure, mémoire et continuité. PEAK guide le travail. ATHF garantit que vous capturez le travail, l'organisez et le réutilisez dans vos futures chasses.
La chasse aux menaces agentique ne consiste pas à remplacer les analystes. Il s'agit de construire des systèmes capables de :
- Se souvenir de ce qui a été fait auparavant
- Apprendre des succès et des erreurs passés
- Soutenir le jugement humain par un rappel contextuel
Lorsque votre framework possède une mémoire, vous cessez de perdre des connaissances à cause du turnover ou de notes oubliées. Lorsque votre assistant IA peut référencer cette mémoire, il devient un multiplicateur de force.
## 💬 Communauté et adoption
- **Discussions GitHub :** [Posez des questions, partagez des chasses](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
- **Issues :** [Signalez des bugs ou demandez des fonctionnalités](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
- **LinkedIn :** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - Suivez pour les mises à jour
**Utiliser ATHF dans votre organisation :** ATHF est un framework à internaliser, pas une plateforme à étendre. Forkez-le, personnalisez-le, faites-en le vôtre. Consultez [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) pour des conseils d'adoption. Vos chasses restent les vôtres—le partage en retour est optionnel mais apprécié.
**Dépôt :** [https://github.com/Nebulock-Inc/agentic-threat-hunting-framework](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
L'objectif est d'aider chaque équipe de chasse aux menaces à passer d'une mémoire ad hoc à une capacité structurée et agentique.
---
## 🛠️ Développement et personnalisation
ATHF est conçu pour être forké et personnalisé pour votre organisation.
**Consultez [docs/INSTALL.md#development--customization](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md#development--customization) pour :**
- Configurer votre fork pour le développement
- Les hooks pre-commit pour la qualité du code
- Les tests et la vérification de types
- Des exemples de personnalisation
- L'intégration CI/CD
Démarrage rapide :
```bash
pip install -e ".[dev]" # Install dev dependencies
pre-commit install # Set up quality checks
pytest tests/ -v # Run tests
```
---
## 👤 Auteur
Créé par **Sydney Marrone** © 2025
---
**Commencez petit. Documentez une chasse. Ajoutez de la structure. Construisez la mémoire.**
La mémoire est le multiplicateur. L'action est la force.
Une fois que votre programme peut se souvenir, tout le reste devient possible.
Bonne chasse !