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.

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+)

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

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

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:

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

Verdict Types:

• ✅ PROMOTE (4.0-5.0) - Deploy as standing detection
• ⚠️ CONDITIONAL (3.0-3.9) - Deploy after prerequisites met
• ❌ HOLD (0.0-2.9) - Preserve logic, don't deploy
• ⏱️ TIME_BOX - Campaign-specific, 90-day refresh
• 🔄 RECURRING_HUNT - Quarterly execution, not 24/7
• 🚫 DROP - Not worth detecting; recorded so it isn't re-proposed

A gate FAIL overrides the score band, and when two gates fail the first match in this order wins: A→DROP, G→TIME_BOX, E→HOLD, S→RECURRING_HUNT, T→CONDITIONAL. The bands above apply only when no gate FAILed. Full rule: .claude/skills/gates/SKILL.md Step 4.

Note: GATES "PROMOTE" verdict means deploying a detection rule. This is distinct from athf hunt promote, which moves hunt files between directories.

Integration with ADEF (Detection Engineering Framework):

After GATES validation, proceed to ADEF for production detection engineering:

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

Complete Workflow:

1. In the ATHF workspace, validate the hunt — assistant input, not a shell command:

   /gates --hunt H-0903
   

   → writes hunt-promotion-analysis/H-0903_GATES.yaml (one file per hunt, N candidates inside). A hunt whose verdict is archival (HOLD, DROP, TIME_BOX, RECURRING_HUNT) emits a .md narrative instead — there is no rule to build, so step 2 applies to .yaml output only.

2. Import that document into ADEF:

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

   Deployable candidates each land at the Find stage with a D-XXXX, a catalog record and a journal; archival ones are reported as skipped. No cd needed — ADEF resolves its workspace from ADEF_WORKSPACE (default ~/work/adef-workspace/). Confirm your ADEF has this mode with adef hunt-promote --help.

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

GATES ensures you deploy the right detections the right way, avoiding alert fatigue and operational friction.

Read more: .claude/skills/gates/README.md

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 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

# 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

# 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

# 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

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

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

# 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

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

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

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

Detection quality is scored by the GATES skill, which your assistant invokes — it is not part of the athf CLI, so it does not belong in the shell block above:

/gates --hunt H-0001

# 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

Without mitreattack-python, ATHF uses a hardcoded v14 fallback (14 tactics, approximate counts). With it, you get full technique metadata: platforms, data sources, sub-techniques, and accurate counts.

# 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

Configure in ~/.claude/mcp-servers.json:

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

The standalone athf-mcp entry point auto-detects your workspace from cwd or ATHF_WORKSPACE env var. Use athf mcp serve --workspace /path for explicit paths.

Security note: the sse and streamable-http transports bind to 127.0.0.1 and are unauthenticated. Every tool reads your whole workspace and some invoke LLM agents at your expense. Only pass --host to bind a routable interface, and put an authenticating proxy in front when you do. The default stdio transport opens no socket at all.

Exposes 17 tools: hunt management, semantic search, ATT&CK coverage, research, investigations, and AI-powered hypothesis generation — all accessible directly from your AI coding assistant.

Full documentation: CLI Reference

Watch ATHF in action: initialize a workspace, create hunts, and explore your threat hunting catalog in under 60 seconds.

View example hunts →

See the Quick Start section above for installation options (PyPI, source, or pure markdown).

Prerequisites:

• Python 3.11 or higher (for CLI option)
• Your favorite AI code assistant

• Why ATHF Exists - The problem and solution
• The LOCK Pattern - Structure for all hunts
• Maturity Model - The five levels explained
• Getting Started - Step-by-step onboarding

• Level 1: Documented Hunts
• Level 2: Searchable Memory
• Level 3: Generative Capabilities
• Level 4: Agentic Workflows

• Installation & Development - Setup, fork customization, testing
• GATES Method - Detection validation skill (bridges LOCK → ADEF)
• MCP Catalog - Available tool integrations
• Quickstart Guides - Setup for specific tools
• Using ATHF - Adoption and customization

Detected Atomic Stealer collecting Safari cookies via AppleScript. Result: 1 true positive, host isolated before exfiltration.

Key Insight: Behavior-based detection outperformed signature-based approaches. Process signature validation identified unsigned malware attempting data collection.

View full hunt → | See more examples →

You might wonder how this interacts with frameworks like PEAK. PEAK gives you a solid method for how to hunt. ATHF builds on that foundation by giving you structure, memory, and continuity. PEAK guides the work. ATHF ensures you capture the work, organize it, and reuse it across future hunts.

Agentic threat hunting is not about replacing analysts. It's about building systems that can:

• Remember what has been done before
• Learn from past successes and mistakes
• Support human judgment with contextual recall

When your framework has memory, you stop losing knowledge to turnover or forgotten notes. When your AI assistant can reference that memory, it becomes a force multiplier.

• GitHub Discussions: Ask questions, share hunts
• Issues: Report bugs or request features
• LinkedIn: Nebulock Inc. - Follow for updates

Using ATHF in Your Organization: ATHF is a framework to internalize, not a platform to extend. Fork it, customize it, make it yours. See USING_ATHF.md for adoption guidance. Your hunts stay yours—sharing back is optional but appreciated.

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

The goal is to help every threat hunting team move from ad-hoc memory to structured, agentic capability.

ATHF is designed to be forked and customized for your organization.

See docs/INSTALL.md#development--customization for:

• Setting up your fork for development
• Pre-commit hooks for code quality
• Testing and type checking
• Customization examples
• CI/CD integration

Quick start:

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

Created by Sydney Marrone © 2025

Start small. Document one hunt. Add structure. Build memory.

Memory is the multiplier. Agency is the force. Once your program can remember, everything else becomes possible.

Happy hunting!