Agentic Threat Hunting Framework (ATHF)

Quick Start • Installation • Documentation • Examples

Dale memoria y capacidad de acción a tu programa de caza de amenazas.

El Agentic Threat Hunting Framework (ATHF) es la capa de memoria y automatización para tu programa de caza de amenazas. Proporciona estructura, persistencia y contexto a tus cacerías, haciendo que cada investigación pasada sea accesible tanto para humanos como para IA.

ATHF funciona con cualquier metodología de caza (PEAK, TaHiTI o tu propio proceso). No es un reemplazo; es la capa que hace que tu proceso existente esté listo para IA.

¿Qué es ATHF?

ATHF proporciona estructura y persistencia para programas de caza de amenazas. Es un framework basado en Markdown que:

• Documenta las cacerías usando el patrón LOCK (Learn → Observe → Check → Keep)
• Mantiene un repositorio buscable de investigaciones pasadas
• Permite que los asistentes de IA consulten tu entorno y trabajos previos
• Funciona con cualquier plataforma SIEM/EDR
• NUEVO: Incluye agentes de investigación y generación de hipótesis impulsados por IA (v0.3.0+)

El problema

La mayoría de los programas de caza de amenazas pierden contexto valioso en cuanto termina una cacería. Las notas viven en Slack o en tickets, las consultas se escriben una vez y se olvidan, y las lecciones aprendidas existen solo en la mente de los analistas.

Incluso las herramientas de IA empiezan desde cero cada vez, sin acceso a tu entorno, tus datos ni tus cacerías pasadas.

ATHF cambia esto al dar a tus cacerías estructura, persistencia y contexto.

Lee más: docs/why-athf.md

El patrón LOCK

Toda cacería de amenazas sigue el mismo ciclo básico: Learn → Observe → Check → Keep.

• Learn: Recopila contexto de inteligencia de amenazas, alertas o anomalías
• Observe: Formula una hipótesis sobre el comportamiento del adversario
• Check: Prueba hipótesis con consultas específicas
• Keep: Registra hallazgos y lecciones aprendidas

¿Por qué LOCK? Es lo bastante pequeño para usarlo y lo bastante estricto para que los agentes lo interpreten. Al capturar cada cacería en este formato, ATHF hace posible que los asistentes de IA recuerden trabajos previos y sugieran consultas refinadas basadas en resultados pasados.

Lee más: docs/lock-pattern.md

Los cinco niveles de la caza de amenazas agéntica

ATHF define un modelo de madurez sencillo. Cada nivel se construye sobre el anterior.

La mayoría de los equipos vivirán en los niveles 1–2. Todo lo que supere eso es madurez opcional.

Nivel 1: Operativo en un día Nivel 2: Operativo en una semana Nivel 3: 2-4 semanas (opcional) Nivel 4: 1-3 meses (opcional)

Lee más: docs/maturity-model.md

🚀 Quick Start

Opción 1: Instalar desde PyPI (recomendado)

# 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

Opción 2: Instalar desde el código fuente (desarrollo)

# 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

Opción 3: Markdown puro (sin instalación)

# 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

Elige tu asistente de IA: Claude Code, GitHub Copilot o Cursor: cualquier herramienta que pueda leer los archivos de tu repositorio.

Guía completa: docs/getting-started.md

🔧 Comandos CLI

ATHF incluye una CLI completa para gestionar tus cacerías. Aquí tienes una referencia rápida:

Inicializar el espacio de trabajo

athf init                           # Interactive setup
athf init --non-interactive         # Use defaults

Generación de investigaciones e hipótesis (NUEVO en v0.3.0)

# 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

Crear cacerías

athf hunt new                       # Interactive mode
athf hunt new \
  --technique T1003.001 \
  --title "LSASS Dumping Detection" \
  --platform windows \
  --research R-0001                 # Link to research document

Listar y buscar

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 --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 y estadísticas

athf hunt validate                  # Validate all hunts
athf hunt validate H-0001           # Validate specific hunt
athf hunt stats                     # Show statistics
athf hunt coverage                  # MITRE ATT&CK coverage
athf research stats                 # Research metrics

Gestión de datos ATT&CK (NUEVO en v0.11.0)

# 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

Sin mitreattack-python, ATHF utiliza un fallback v14 hardcodeado (14 tácticas, recuentos aproximados). Con él, obtienes metadatos completos de las técnicas: plataformas, fuentes de datos, sub-técnicas y recuentos precisos.

Servidor MCP (NUEVO en v0.11.0)

# 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

Configúralo en ~/.claude/mcp-servers.json:

{
  "athf": {
    "command": "athf-mcp",
    "env": { "ATHF_WORKSPACE": "/path/to/your/hunts" }
  }
}

El punto de entrada independiente athf-mcp detecta automáticamente tu espacio de trabajo desde el directorio actual o la variable de entorno ATHF_WORKSPACE. Usa athf mcp serve --workspace /path para rutas explícitas.

Nota de seguridad: los transportes sse y streamable-http se vinculan a 127.0.0.1 y no están autenticados. Cada herramienta lee todo tu espacio de trabajo y algunas invocan agentes LLM por tu cuenta. Solo pasa --host para vincular una interfaz enrutable y coloca un proxy de autenticación delante cuando lo hagas. El transporte predeterminado stdio no abre ningún socket.

Expone 17 herramientas: gestión de cacerías, búsqueda semántica, cobertura ATT&CK, investigación, indagaciones y generación de hipótesis impulsada por IA, todo accesible directamente desde tu asistente de codificación con IA.

Documentación completa: CLI Reference

📺 Míralo en acción

Mira ATHF en acción: inicializa un espacio de trabajo, crea cacerías y explora tu catálogo de caza de amenazas en menos de 60 segundos.

Ver ejemplos de cacerías →

Installation

Consulta la sección Quick Start anterior para ver las opciones de instalación (PyPI, código fuente o Markdown puro).

Requisitos previos:

• Python 3.8-3.13 (para la opción CLI)
• Tu asistente de codificación con IA favorito

Documentation

Conceptos clave

• Por qué existe ATHF - El problema y la solución
• El patrón LOCK - Estructura para todas las cacerías
• Modelo de madurez - Los cinco niveles explicados
• Primeros pasos - Incorporación paso a paso

Guías por niveles

• Nivel 1: Cacerías documentadas
• Nivel 2: Memoria buscable
• Nivel 3: Capacidades generativas
• Nivel 4: Flujos de trabajo agénticos

Integración y personalización

• Instalación y desarrollo - Configuración, personalización del fork, pruebas
• Catálogo MCP - Integraciones de herramientas disponibles
• Guías de inicio rápido - Configuración para herramientas específicas
• Usando ATHF - Adopción y personalización

🎖️ Cacerías destacadas

H-0001: Detección de ladrón de información en macOS

Detectó Atomic Stealer recopilando cookies de Safari mediante AppleScript. Resultado: 1 verdadero positivo, host aislado antes de la exfiltración.

Conclusión clave: La detección basada en comportamiento superó a los enfoques basados en firmas. La validación de firmas de procesos identificó malware sin firmar que intentaba recopilar datos.

Ver la cacería completa → | Ver más ejemplos →

Por qué es importante

Quizá te preguntes cómo interactúa esto con frameworks como PEAK. PEAK te ofrece un método sólido sobre cómo cazar. ATHF se basa en ese fundamento al darte estructura, memoria y continuidad. PEAK guía el trabajo. ATHF garantiza que captures el trabajo, lo organices y lo reutilices en futuras cacerías.

La caza de amenazas agéntica no consiste en reemplazar a los analistas. Se trata de construir sistemas que puedan:

• Recordar lo que se ha hecho antes
• Aprender de éxitos y errores pasados
• Respaldar el juicio humano con recuperación contextual

Cuando tu framework tiene memoria, dejas de perder conocimiento por rotación de personal o notas olvidadas. Cuando tu asistente de IA puede consultar esa memoria, se convierte en un multiplicador de fuerza.

💬 Comunidad y adopción

• Discusiones de GitHub: Haz preguntas, comparte cacerías
• Issues: Reporta errores o solicita funciones
• LinkedIn: Nebulock Inc. - Síguenos para estar al día

Usar ATHF en tu organización: ATHF es un framework para internalizar, no una plataforma para extender. Hazle fork, personalízalo, hazlo tuyo. Consulta USING_ATHF.md para obtener orientación sobre adopción. Tus cacerías siguen siendo tuyas: compartirlas es opcional, pero se agradece.

Repositorio: https://github.com/Nebulock-Inc/agentic-threat-hunting-framework

El objetivo es ayudar a todos los equipos de caza de amenazas a pasar de la memoria ad-hoc a una capacidad estructurada y agéntica.

🛠️ Desarrollo y personalización

ATHF está diseñado para que hagas fork y lo personalices para tu organización.

Consulta docs/INSTALL.md#development--customization para:

• Configurar tu fork para desarrollo
• Ganchos de pre-commit para calidad de código
• Pruebas y comprobación de tipos
• Ejemplos de personalización
• Integración de CI/CD

Inicio rápido:

pip install -e ".[dev]"       # Install dev dependencies
pre-commit install            # Set up quality checks
pytest tests/ -v              # Run tests

👤 Autor

Creado por Sydney Marrone © 2025

Empieza poco a poco. Documenta una cacería. Añade estructura. Construye memoria.

La memoria es el multiplicador. La agencia es la fuerza. Una vez que tu programa puede recordar, todo lo demás se vuelve posible.

¡Buena caza!