Agentic Threat Hunting Framework (ATHF)

Quick Start • Installation • Documentation • Examples

Give your threat hunting program memory and agency.

The Agentic Threat Hunting Framework (ATHF) is the memory and automation layer for your threat hunting program. It gives your hunts structure, persistence, and context - making every past investigation accessible to both humans and AI.

ATHF works with any hunting methodology (PEAK, TaHiTI, or your own process). It's not a replacement; it's the layer that makes your existing process AI-ready.

What is ATHF?

ATHF provides structure and persistence for threat hunting programs. It's a markdown-based framework that:

• Documents hunts using the LOCK pattern (Learn → Observe → Check → Keep)
• Maintains a searchable repository of past investigations
• Enables AI assistants to reference your environment and previous work
• Works with any SIEM/EDR platform
• NEW: Includes AI-powered research and hypothesis generation agents (v0.3.0+)

The Problem

Most threat hunting programs lose valuable context once a hunt ends. Notes live in Slack or tickets, queries are written once and forgotten, and lessons learned exist only in analysts' heads.

Even AI tools start from zero every time without access to your environment, your data, or your past hunts.

ATHF changes that by giving your hunts structure, persistence, and context.

Read more: docs/why-athf.md

The LOCK Pattern

Every threat hunt follows the same basic loop: Learn → Observe → Check → Keep.

• Learn: Gather context from threat intel, alerts, or anomalies
• Observe: Form a hypothesis about adversary behavior
• Check: Test hypotheses with targeted queries
• Keep: Record findings and lessons learned

Why LOCK? It's small enough to use and strict enough for agents to interpret. By capturing every hunt in this format, ATHF makes it possible for AI assistants to recall prior work and suggest refined queries based on past results.

Read more: docs/lock-pattern.md

GATES Method: Hunt-to-Detection Promotion Validation

After completing a hunt's KEEP phase, the GATES method validates whether your findings should be promoted to production detections, recurring hunts, or advisories.

Generalizable, Additive, Tunable, Exposure-tested, Sustainable

Note: GATES is designed to work with the ATHF framework and has been extensively tested in that context. While the methodology (5 BASE criteria, verdict types) is conceptually portable, we recommend using it as part of the complete ATHF workflow for best results. See .claude/skills/gates/ for the full integration.

Installation: GATES is currently available via git clone only. Users who installed via pip install should clone the repository to access GATES. We're working on including GATES in the pip distribution (tracked as Issue #21).

GATES evaluates hunt-derived detections using a two-tier framework: 5 BASE criteria (assessed from hunt data) identify deployment candidates, while 5 ADVANCED criteria (validated in production) ensure resilient detections with low false positive and false negative rates:

Gate	Question	Catches
G - Generalizable	Is this repeatable?	IOC-based rules that expire quickly
A - Additive	Does it fill a coverage gap?	Duplicate or redundant detections
T - Tunable	Can we distinguish attack from normal?	Baseline noise mismatch (top FP cause)
E - Exposure-tested	Did we cover evasions?	Single-dimensional detections
S - Sustainable	Can we maintain this?	High-volume, low-TP rules

Verdicts are based on BASE scores (/5). See .claude/skills/gates/ for ADVANCED validation methods.

Quick Start — type this to your assistant; /gates is a skill, not a shell command:

/gates --hunt H-0001

Tipos de veredicto:

• ✅ PROMOTE (4.0-5.0) - Desplegar como detección permanente
• ⚠️ CONDITIONAL (3.0-3.9) - Desplegar tras cumplir los requisitos previos
• ❌ HOLD (0.0-2.9) - Preservar la lógica, no desplegar
• ⏱️ TIME_BOX - Específico de campaña, actualización cada 90 días
• 🔄 RECURRING_HUNT - Ejecución trimestral, no 24/7
• 🚫 DROP - No merece la pena detectarlo; se registra para que no se vuelva a proponer

Un gate FAIL anula la banda de puntuación, y cuando dos gates fallan gana la primera coincidencia en este orden: A→DROP, G→TIME_BOX, E→HOLD, S→RECURRING_HUNT, T→CONDITIONAL. Las bandas anteriores se aplican solo cuando ningún gate ha fallado. Regla completa: .claude/skills/gates/SKILL.md Paso 4.

Nota: El veredicto "PROMOTE" de GATES significa desplegar una regla de detección. Esto es distinto de athf hunt promote, que mueve archivos de hunt entre directorios.

Integración con ADEF (Detection Engineering Framework):

Tras la validación de GATES, proceda a ADEF para la ingeniería de detección en producción:

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

Flujo de trabajo completo:

1. En el espacio de trabajo de ATHF, valida la búsqueda — entrada del asistente, no un comando de shell:

   /gates --hunt H-0903
   

   → escribe hunt-promotion-analysis/H-0903_GATES.yaml (un archivo por hunt, N candidatos dentro). Un hunt cuyo veredicto es archivístico (HOLD, DROP, TIME_BOX, RECURRING_HUNT) emite una narrativa .md en su lugar — no hay regla que construir, por lo que el paso 2 aplica únicamente a la salida .yaml.

2. Importa ese documento en ADEF:

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

   Los candidatos desplegables llegan a la etapa Find con un D-XXXX, un registro de catálogo y un diario; los de archivo se reportan como omitidos. No se necesita cd — ADEF resuelve su espacio de trabajo desde ADEF_WORKSPACE (por defecto ~/work/adef-workspace/). Confirma que tu ADEF tiene este modo con adef hunt-promote --help.

Repositorio de ADEF: https://github.com/Nebulock-Inc/agentic-detection-engineering-framework

GATES garantiza que despliegues las detecciones correctas de la manera correcta, evitando la fatiga de alertas y la fricción operativa.