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

The Five Levels of Agentic Hunting

ATHF defines a simple maturity model. Each level builds on the previous one.

Most teams will live at Levels 1–2. Everything beyond that is optional maturity.

Level	Capability	What You Get
0	Ad-hoc	Hunts exist in Slack, tickets, or analyst notes
1	Documented	Persistent hunt records using LOCK
2	Searchable	AI reads and recalls your hunts
3	Generative	AI executes queries via MCP tools, conducts research
4	Agentic	Autonomous agents monitor and act, generate hypotheses

Level 1: Operational within a day Level 2: Operational within a week Level 3: 2-4 weeks (optional) Level 4: 1-3 months (optional)

Read more: docs/maturity-model.md

🚀 Quick Start

Option 1: Install from PyPI (Recommended)

# 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: Install from Source (Development)

# 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: Pure Markdown (No Installation)

# 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

Choose your AI assistant: Claude Code, GitHub Copilot, or Cursor - any tool that can read your repository files.

Full guide: docs/getting-started.md

🔧 CLI Commands

ATHF includes a full-featured CLI for managing your hunts. Here's a quick reference:

Initialize Workspace

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

Research & Hypothesis Generation (NEW in 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

Create Hunts

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

List & Search

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

Validate & Stats

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

ATT&CK Data Management (NEW in v0.11.0)