agentic-threat-hunting-framework
AGENTS.md420 starsChanged 45 days agoMITView on GitHub
Purpose: This file provides AI assistants with context about threat hunting repositories using the Agentic Threat Hunting Framework (ATHF). This repository contains threat hunting investigations using the LOCK pattern (Learn → Observe → Check → Keep). AI assistants should: CRITICAL REQUIREMENT: AI assistants MUST use athf CLI commands or athf agent run for ALL tasks that have corresponding CLI functionality. Direct file manipulation is prohibited for framework-managed operations. Why this matters: Enforcement: You MAY use Read, Edit, Grep, Glob tools…
- Reads credentials
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
42 rules. About 0 are common, 25 are distinctive, and 17 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈25
Distinctive · estimate
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
🔧 ALWAYS activate the virtual environment FIRST: - Run source .venv/bin/activate before any athf commands (verify with which athf)
- Distinctive: line 15
Browse past hunts: - Search hunt history before suggesting new hypotheses
- Distinctive: line 17
Use environment.md to understand available data sources
- Very specific: line 69
Rule of thumb: If athf has a command for it, use the command.
- Distinctive: line 75
CRITICAL: Use structured output formats for query analysis to reduce token costs by 75%.
- Distinctive: line 193
Key Principle: All hunts must focus on behaviors and TTPs (top half of Pyramid of Pain).
- Distinctive: line 196
Before generating hypotheses (review Section 1 and Section 5)
- Distinctive: line 198
When analyzing findings (review Section 4 for confidence scoring)
- Distinctive: line 213
AI Note: Always verify data sources exist in the user's environment.md before generating queries or hunt hypotheses.
- Distinctive: line 229
Check: - Test with bounded, safe query
- Distinctive: line 234
Ensure queries are bounded by time, scope, and impact
- Distinctive: line 235
Document lessons learned after hunt execution
- Very specific: line 303
Check if we've hunted this before: - Use athf similar "hypothesis keywords" to find duplicate hunts
- Very specific: line 319
Every result gets one of five verdicts.
- Very specific: line 341
If you have none of these, the verdict is suspected.
- Very specific: line 368
Do not write a config inside
hunts/: Only the workspace-root config is read. - Very specific: line 420
For AI Assistants: Before running any athf commands, verify venv is activated with which athf.
- Very specific: line 428
athf similar "hypothesis keywords": - BEFORE creating hunt hypothesis - Very specific: line 434
athf context --hunt H-XXXX: - BEFORE executing hunt queries - Distinctive: line 467
Execute queries: - Use appropriate data source tools (SIEM interface, query CLI, etc.)
- Distinctive: line 468
STOP after each query: - Wait for user feedback before next query
- Very specific: line 469
Document findings: - Update hunt file with results, assign a verdict to each (see Verdicts), then run athf hunt validate H-XXXX
- Distinctive: line 470
Validate with GATES: - After documenting findings in KEEP phase:
- Very specific: line 471
Run /gates --hunt H-XXXX to validate detection quality
- Very specific: line 472
Document verdict in hunt file under ### GATES Verdict
- Very specific: line 475
Import the GATES document: adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-XXXX_GATES.yaml (--dry-run to preview).
- Very specific: line 482
If CONDITIONAL: import the same way, then complete the prerequisites — ADEF marks the record needs_review: gates_conditional so it can't …
- Very specific: line 484
If HOLD/DROP/TIME_BOX/RECURRING_HUNT: Document strategy (see GATES output).
- Distinctive: line 658
Validate data sources: Check user's environment.md for available telemetry
- Distinctive: line 660
Wait for user selection: before creating hunt
- Distinctive: line 673
Document priorities in your workspace environment.md
- Very specific: line 744
All helpers are best-effort: failures never break callers.
- Distinctive: line 770
Pre-filtered, structured content: - Only relevant files included
- Distinctive: line 806
Avoid duplicate hunts: - Check if similar hunt already exists
- Distinctive: line 835
Before creating new hunt: - Check if similar hunt already exists
- Distinctive: line 838
After hypothesis generation: - Verify not duplicating work
- Distinctive: line 864
Consult Hunting Brain: - Read knowledge/hunting-knowledge.md Section 1 (Hypothesis Generation) and Section 5 (Pyramid of Pain)
- Distinctive: line 866
Validate Environment: - Read user's environment.md to confirm data sources exist
- Very specific: line 867
Generate LOCK Hypothesis: - Create testable hypothesis following templates/HUNT_LOCK.md
- Distinctive: line 868
Apply Quality Criteria: - Use quality checklist (Falsifiable, Scoped, Observable, Actionable, Contextual)
- Distinctive: line 873
Focus on behaviors/TTPs (top of Pyramid of Pain): - Never build hypothesis around hashes or IPs alone
- Distinctive: line 878
Consider false positives from similar past hunts
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md - Context for AI Assistants Using ATHF
Purpose: This file provides AI assistants with context about threat hunting repositories using the Agentic Threat Hunting Framework (ATHF).
Repository Overview
This repository contains threat hunting investigations using the LOCK pattern (Learn → Observe → Check → Keep).
AI assistants should:
- 🔧 ALWAYS activate the virtual environment FIRST - Run
source .venv/bin/activatebefore anyathfcommands (verify withwhich athf) - Read knowledge/hunting-knowledge.md - Expert hunting frameworks and analytical methods
- Browse past hunts - Search hunt history before suggesting new hypotheses
- Reference lessons learned when generating queries
- Use environment.md to understand available data sources
- Focus on behaviors and TTPs (top of Pyramid of Pain), not indicators
🚨 MANDATORY: Use ATHF CLI Commands & Agents
CRITICAL REQUIREMENT: AI assistants MUST use athf CLI commands or athf agent run for ALL tasks that have corresponding CLI functionality. Direct file manipulation is prohibited for framework-managed operations.
✅ ALWAYS Use CLI For
| Task Category | CLI Command | ❌ Never Use |
| Hunt creation | athf hunt new --non-interactive | Write tool, Edit tool |
| Investigation creation | athf investigate new --non-interactive | Write tool, Edit tool |
| Research execution | athf research new --topic "..." | Manual web search, Write tool |
| Hypothesis generation | athf agent run hypothesis-generator --threat-intel "..." | Manual hypothesis drafting |
| Duplicate checking | athf similar "keywords" | Grep, manual search |
| Context loading | athf context --hunt H-XXXX | Multiple Read operations |
| Coverage analysis | athf hunt coverage | Manual ATT&CK counting |
| Hunt validation | athf hunt validate H-XXXX | Manual YAML parsing |
| Hunt search | athf hunt search "keyword" | Grep, manual file search |
🎯 CLI-First Policy
Why this matters:
- ✅ CLI provides proper validation and error checking
- ✅ Auto-generates correct YAML frontmatter and LOCK structure
- ✅ Maintains hunt ID sequences and file naming conventions
- ✅ Ensures consistency across all hunt documents
- ✅ Reduces token costs (single command vs. multiple tool calls)
- ✅ Prevents malformed hunt files that break CI/CD pipelines
Enforcement:
- ❌ NEVER use Write/Edit tools to create hunt or investigation files
- ❌ NEVER manually construct YAML frontmatter
- ❌ NEVER bypass CLI for hunt management operations
- ✅ ALWAYS verify virtual environment is activated (
which athf) - ✅ ALWAYS use CLI for file generation and validation
📋 When Manual Tools Are Acceptable
You MAY use Read, Edit, Grep, Glob tools for:
- Reading existing hunt/investigation/research files
- Editing hunt file content AFTER creation (query results, findings, lessons learned)
- Searching file contents (complement to
athf hunt search) - Exploring codebase structure
- Reading environment.md and knowledge files
Rule of thumb: If athf has a command for it, use the command. Manual tools are for content, not structure.
🎯 TOKEN OPTIMIZATION: Structured Output Rules
CRITICAL: Use structured output formats for query analysis to reduce token costs by 75%.
Three Output Modes:
- JSON Format (Use 80% of time) - For security findings, event logs, structured data
- Rules: JSON only, suspicion_score > 30 only, one-sentence reasons, no preambles
- Table Format (Quick triage) - Columnar data for rapid scanning
- Narrative (Sparingly) - Final hunt reports, deliverables, hypothesis generation
Impact: Verbose output ~2,000 tokens vs. Structured ~500 tokens = significant cost savings
Repository Structure
Framework Source Code (athf/)
athf/ # CLI source code
├── agents/ # Agent implementations
│ ├── base.py # Base agent classes
│ └── llm/ # LLM-powered agents
│ ├── hypothesis_generator.py # Hypothesis generation
│ └── hunt_researcher.py # Pre-hunt research agent
├── commands/ # CLI commands
│ ├── agent.py # Agent management
│ ├── attack.py # ATT&CK data management (STIX)
│ ├── context.py # Context export for AI
│ ├── env.py # Virtual environment setup
│ ├── hunt.py # Hunt management commands
│ ├── init.py # Workspace initialization
│ ├── investigate.py # Investigation commands
│ ├── research.py # Research management
│ └── similar.py # Semantic search
├── core/ # Core functionality
│ ├── attack_matrix.py # MITRE ATT&CK coverage (STIX provider + fallback)
│ ├── hunt_manager.py # Hunt lifecycle management
│ ├── hunt_parser.py # Hunt file parser
│ ├── investigation_parser.py # Investigation parser
│ ├── research_manager.py # Research lifecycle
│ ├── template_engine.py # Template rendering
│ └── web_search.py # Tavily search integration
├── utils/ # Helper utilities
└── data/ # Bundled templates and docs
├── docs/ # Framework documentation
├── templates/ # Hunt templates
├── knowledge/ # Hunting expertise
├── prompts/ # AI workflow templates
├── hunts/ # Example hunts
└── integrations/ # Integration guidesUser Workspace (Created by athf init)
/
├── README.md # Project overview
├── AGENTS.md # 🤖 This file - AI context
├── .athfconfig.yaml # Workspace configuration
├── environment.md # Data sources and tech stack
│
├── hunts/ # Hunt investigations (H-XXXX.md)
│ └── README.md # Hunt creation guide
│
├── investigations/ # Exploratory work (I-XXXX.md)
│ └── README.md # Investigation workflow guide
│
├── queries/ # Query implementations
│ └── README.md # Query library documentation
│
├── knowledge/ # Hunting expertise and frameworks
│ ├── hunting-knowledge.md # Core hunting knowledge
│ ├── mitre-attack.md # ATT&CK framework methodology
│ └── domains/ # (EXAMPLE) Domain-specific knowledge
│ ├── endpoint-security.md
│ ├── iam-security.md
│ ├── insider-threat.md
│ └── cloud-security.md
│
├── integrations/ # Data source integrations
│ └── MCP_CATALOG.md # Available integrations
│
└── docs/ # Additional documentation
└── CLI_REFERENCE.md # Complete CLI command referenceNested AGENTS.md Files
This repository can use nested AGENTS.md files for specialized context. The closest file in the directory hierarchy takes precedence.
| Directory | Context | When to Load |
Root / | General hunting methodology | Default context |
integrations/<datasource>/ | Query execution, data source specifics | Writing queries for that data source |
hunts/ | Hunt execution workflow, LOCK pattern | Creating/executing hunts |
research/ | Research-first workflow | Pre-hunt research |
queries/ | Query library, parameterized queries | Alert triage |
investigations/ | Investigation workflow | Exploratory analysis |
Note: Nested AGENTS.md files are optional. Organizations can add them to provide context-specific guidance.
Hunting Knowledge Base
knowledge/hunting-knowledge.md
The file knowledge/hunting-knowledge.md contains expert threat hunting knowledge that AI should apply when generating hypotheses:
Core Sections:
- Hypothesis Generation - Pattern-based generation, quality criteria, examples
- Behavioral Models - ATT&CK TTP → observable mappings, behavior-to-telemetry translation
- Pivot Logic - Artifact chains, pivot playbooks, decision criteria
- Analytical Rigor - Confidence scoring, evidence strength, bias checks
- Framework Mental Models - Pyramid of Pain, Diamond Model, Hunt Maturity, Data Quality
Key Principle: All hunts must focus on behaviors and TTPs (top half of Pyramid of Pain). Never build hunts solely around hashes, IPs, or domains.
When to consult:
- Before generating hypotheses (review Section 1 and Section 5)
- During hunt execution (review Section 3 for pivot logic)
- When analyzing findings (review Section 4 for confidence scoring)
Data Sources
See environment.md for documenting your organization's data sources:
- SIEM/log aggregation platforms
- EDR/endpoint telemetry coverage
- Network visibility capabilities
- Cloud logging (AWS CloudTrail, Azure Activity Logs, GCP Audit Logs)
- Identity and authentication logs
- Known visibility gaps and blind spots
AI Note: Always verify data sources exist in the user's environment.md before generating queries or hunt hypotheses.
Supported Integrations: Any data source with query capabilities
Common Examples: Splunk, Elasticsearch, Athena, BigQuery, PostgreSQL, Microsoft Sentinel, Sumo Logic, etc.
Integration-Specific Guidance: Organizations should create integrations/<datasource>/AGENTS.md files for data source-specific query syntax, field naming, and best practices.
Hunting Methodology
This repository follows the LOCK pattern:
- Learn - Gather context (CTI, alert, anomaly, threat intel)
- Observe - Form hypothesis about adversary behavior
- Check - Test with bounded, safe query
- Keep - Record decision and lessons learned
AI assistants should:
- Generate hypotheses in LOCK format (see templates/HUNT_LOCK.md)
- Ensure queries are bounded by time, scope, and impact
- Document lessons learned after hunt execution
- Reference past hunts when suggesting new ones
Investigation vs Hunt
Purpose: Investigations (I-XXXX) are for exploratory work, alert triage, and ad-hoc analysis that does NOT contribute to hunt metrics.
Use investigations when: Alert triage, exploring new data sources, testing queries, uncertain hypothesis, avoiding metrics pollution
Use hunts when: Testable hypothesis, repeatable detection logic, tracking metrics, deliverables, ATT&CK coverage
Key Differences:
| Aspect | Hunts (H-XXXX) | Investigations (I-XXXX) |
| Purpose | Hypothesis-driven hunting | Exploratory analysis |
| Metrics | Tracked (per-verdict counts, costs) | NOT tracked |
| Directory | hunts/ | investigations/ |
| Validation | Strict (CI/CD enforced) | Lightweight |
CLI Commands:
athf investigate new- Create investigation (interactive or --non-interactive)athf investigate list [--type finding]- List/filter investigationsathf investigate search "keyword"- Full-text searchathf investigate validate I-XXXX- Lightweight validationathf investigate promote I-XXXX- Promote to formal hunt
Cross-Referencing:
- Investigations → Hunts: Use
related_hunts: [H-0013]field - Hunts → Investigations: Use
spawned_from: I-0042field
Query Guardrails
Universal Rules (Apply to All Data Sources)
Mandatory Rules:
- ✅ Always include time bounds (7 days max initially for exploratory queries)
- ✅ Always start with
LIMIT 100or equivalent (progressive strategy) - ✅ Use
athf validate query --sql "..."before executing (if supported by your data source) - ✅ COUNT-FIRST: Count baseline → Count filtered → Analyze → Pull results only if justified
- ✅ Sequential execution: ONE query at a time, STOP for user feedback
- ❌ Never omit LIMIT or time constraints
- ❌ Never execute multiple queries in parallel without user approval
COUNT-FIRST Decision Tree:
- count = 0 → Skip (no results)
- count < 100 → LIMIT 100
- count 100-1000 → LIMIT 1000
- count > 1000 → Refine filters first, then proceed
If timeout or slow query: Reduce time range → Add filters → Simplify aggregations
Data Source-Specific Guidance
Query syntax, field naming, and performance optimization vary by data source. Refer to integration-specific AGENTS.md files in your workspace:
integrations/splunk/AGENTS.md- SPL query patterns, search modesintegrations/elasticsearch/AGENTS.md- Query DSL, aggregationsintegrations/athena/AGENTS.md- Presto SQL, partition optimization
See your workspace integrations/ directory for deployed data source guidance.
Hypothesis Validation
- Check if we've hunted this before - Use
athf similar "hypothesis keywords"to find duplicate hunts - Verify data source availability - Reference environment.md
- Ensure hypothesis is testable - Can be validated with a query
- Consider false positive rate - Will this hunt generate noise?
Documentation
- Use LOCK structure for all hunt documentation
- Capture negative results - Hunts that found nothing are still valuable
- Record lessons learned - What worked, what didn't, what to try next
- Link related hunts - Reference past work
Verdicts: How to Classify What You Found
Every result gets one of five verdicts. TP / FP is no longer sufficient — it collapses "the attack happened and our control stopped it" together with "the thing wasn't there," and those are different answers.
| Verdict | Assign when | Goes in |
confirmed | Telemetry evidence plus independent confirmation outside the log corpus | findings |
suspected | Telemetry evidence only — you could not independently confirm | findings |
attempted_not_vulnerable | Attack behavior observed and the control demonstrably held (name the control) | ruled_out |
benign | Explained by specific legitimate activity | ruled_out |
inconclusive | Telemetry too sparse or missing to decide (name the field/source) | ruled_out |
🚨 The Evidence Gate — Non-Negotiable
Query results are not confirmation. You MUST NOT write verdict: confirmed on the strength of telemetry alone, no matter how convincing the query output looks. Reading logs back and reporting what they say is not verification — it's restating the input.
confirmed requires one of these, from outside the log corpus:
| Confirmation type | What it means |
| Controlled reproduction | Behavior reproduced in an attack range / lab |
| Host forensics | The artifact recovered — crontab entry, plist, binary on disk, registry key |
| Configuration review | The actual config inspected, proving the activity was possible and occurred |
If you have none of these, the verdict is suspected. That is the correct, complete answer — not a downgrade, and not something to apologize for or work around. Escalate to the user that confirmation is needed; do not promote the verdict yourself.
Provenance: confirmed Needs a Producer, Not Better Prose
The gate does not read your confirmation text and decide whether it sounds like real work — that check was measured and cannot separate cross-validated by running a second query against the same table from genuine corroboration. Instead, confirmation is a mapping and the gate checks who produced it:
findings:
- subject: web-prod-04
verdict: confirmed
evidence: OCSF process_activity shows sh writing /var/spool/cron/crontabs/svc_deploy
confirmation:
method: host_forensics # must be a capability the producer declared
produced_by: ir-team # must exist in .athfconfig.yaml provenance.producers
attested_by: J. Halloran # a named person, never a role or "the team"
detail: >-
Recovered the crontab entry and the dropper binary from the imaged diskCapabilities are declared in .athfconfig.yaml, never in the finding. If you write capabilities:, analyst_capabilities:, or producer_capabilities: inside a finding, validation refuses it outright. You cannot grant yourself the ability to confirm.
If you can only run queries, your ceiling is suspected — permanently. A producer whose declared capabilities are all corpus-reading (clickhouse_query, siem_search, log_review) cannot reach confirmed no matter what it writes. That is by construction, not an obstacle to route around. Do not add capabilities to config to unblock yourself; report to the user that confirmation requires out-of-corpus work.
No producers declared means no confirmed. A workspace with no provenance section refuses every confirmed entry. That is intended: the absence of a declaration is not permission.
Name the surface you actually are, not the team you belong to. A producer is one thing that produces findings, scoped by what it can reach — so a single team legitimately declares several. When you write produced_by, pick the entry matching the surface that did the work: if a query-only agent produced the finding, name that agent, never the human team that also does forensics. Borrowing the team's entry to inherit its capabilities is self-certification with an extra step.
Do not write a config inside hunts/. Only the workspace-root config is read; one placed beside a hunt file is ignored. Writing a producer declaration next to your own finding is self-certification, and it will not work.
attested_by must name a person, not the producer. Repeating produced_by there — or naming any other declared producer — is refused: an attestation is a second party vouching for the work, and nothing in config can be asked what it saw. If no person can vouch for the out-of-corpus work, the verdict is suspected. Do not put a colleague's name there to satisfy the field; ask the user who should attest.
Routing Rules for AI Assistants
| ❌ Wrong | ✅ Correct |
verdict: confirmed backed only by query output | verdict: suspected + note what confirmation would take |
confirmation: as a prose string on confirmed | A mapping with method, produced_by, attested_by, detail |
attested_by: the team / AI assistant / pipeline | A named person answerable for the out-of-corpus work |
attested_by: repeating produced_by (or another producer) | A person distinct from the producer — self-attestation is refused |
Declaring analyst_capabilities: in the finding | Declare producers in .athfconfig.yaml; never self-certify |
| Editing config to grant yourself a capability | Report that confirmation needs work you cannot do |
attempted_not_vulnerable listed under findings | Put it in ruled_out — it closed the question |
benign listed under findings | Put it in ruled_out |
| "No findings" when controls held | ruled_out entries naming each control that held |
attempted_not_vulnerable with no control named | Name the control and how you verified it held |
Promoting legacy true_positives to confirmed | Leave legacy counts alone — they never passed the gate |
Verify before closeout: athf hunt validate H-XXXX enforces the evidence gate and the routing rule. Run it after writing findings.
Full field reference: athf/data/hunts/FORMAT_GUIDELINES.md → The Verdict Ladder
CLI Commands (Required Workflow)
Purpose: ATHF includes CLI tools (athf command) that automate common hunt management tasks. When available, these commands are faster and more reliable than manual file operations.
🔧 SETUP: Virtual Environment Activation
CRITICAL: The athf command requires the virtual environment to be activated. Activate it once at the start of your session:
source .venv/bin/activateVerify activation:
which athf
# Should output: /path/to/workspace/.venv/bin/athf
athf --version
# Should succeed with version numberWhy this matters:
- System
athf(if installed) may lack dependencies likescikit-learn - Venv
athfhas all required dependencies (scikit-learn, anthropic, etc.) - Activation ensures correct Python interpreter
For AI Assistants: Before running any athf commands, verify venv is activated with which athf. If it returns a system path, run source .venv/bin/activate first.
⚠️ CRITICAL: Two Mandatory Tools for AI Assistants
These two commands are REQUIRED for all hunt workflows:
athf similar "hypothesis keywords"- BEFORE creating hunt hypothesis- Prevents duplicate hunts
- Finds related past work
- Saves time and token costs
- Example:
athf similar "password spraying"
athf context --hunt H-XXXX- BEFORE executing hunt queries- Loads all context in one command (~5 Read operations → 1 command)
- Saves ~75% token usage
- Returns JSON/YAML/Markdown with environment.md + past hunts + domain knowledge
- Example:
athf context --tactic credential-access --format json
Failure to use these tools will result in:
- Duplicate hunts (wasted effort)
- Excessive token costs
- Slower hunt execution
Five Mandatory Tools
| Step | Command | When | Purpose |
| 1 | athf similar "keywords" | BEFORE hypothesis | Check for duplicate hunts |
| 2 | athf research new --topic "..." | REQUIRED: Before hypothesis | Thorough pre-hunt research (15-20 min) - NEW |
| 3 | athf agent run hypothesis-generator --threat-intel "..." | AFTER research | Generate structured hypothesis - NEW |
| 4 | athf hunt new --technique T1XXX --title "..." --non-interactive | WHEN creating hunt | Auto-generate hunt file (⚠️ NEVER use Write tool) |
| 5 | athf context --hunt H-XXXX --format json | BEFORE executing queries | Load all context efficiently |
Hunt Execution Steps
- Check duplicates:
athf similar "hypothesis keywords" - Deep research (REQUIRED):
athf research new --topic "..."(creates R-XXXX.md with 5-skill methodology) - Generate hypothesis:
athf agent run hypothesis-generator --threat-intel "..." - Create hunt file:
athf hunt new --research R-XXXX --non-interactive ...(link to research) - Load context:
athf context --hunt H-XXXX --format json - Present hypothesis to user - ABLE scoping table + threat context
- Execute queries - Use appropriate data source tools (SIEM interface, query CLI, etc.)
- STOP after each query - Wait for user feedback before next query
- Document findings - Update hunt file with results, assign a verdict to each (see Verdicts), then run
athf hunt validate H-XXXX - Validate with GATES - After documenting findings in KEEP phase:
- Run
/gates --hunt H-XXXXto validate detection quality - Document verdict in hunt file under
### GATES Verdict - If PROMOTE: Proceed to ADEF for detection engineering
- Install ADEF:
pip install agentic-detection-engineering-framework - Import the GATES document:
adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-XXXX_GATES.yaml(--dry-runto preview). One file in, N detections out — deployable candidates get aD-XXXX, a catalog record and a journal at Find; archival ones are reported as skipped. Nocdneeded; ADEF resolves its workspace fromADEF_WORKSPACE. Confirm the mode exists withadef hunt-promote --help. - ADEF Repo: https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
- Note: GATES "PROMOTE" means deploy detection rule to production. This is separate from
athf hunt promotewhich moves hunt files between directories.
- Install ADEF:
- If CONDITIONAL: import the same way, then complete the prerequisites — ADEF
marks the record
needs_review: gates_conditionalso it can't ship unnoticed - If HOLD/DROP/TIME_BOX/RECURRING_HUNT: Document strategy (see GATES output).
Note a PROMOTE hunt's
.yamlcan still contain TIME_BOX and HOLD candidates — the hunt-level verdict picks the file format, not each candidate's fate.
- Run
Additional Commands
# Agent management (NEW - AI-powered capabilities)
athf agent list # List available agents
athf agent info hypothesis-generator # Get info about specific agent
athf agent run hunt-researcher --topic "LSASS dumping"
# Hunt management
athf hunt coverage # ATT&CK coverage analysis
athf hunt coverage --tactic credential-access
athf hunt search "credential dumping" # Full-text search across hunts
athf hunt validate H-0001 # Validate hunt file structure
# Research management (NEW)
athf research list # List research documents
athf research view R-0001 # View specific research
athf research search "credential access" # Search research documents
athf research stats # Show research metrics
# ATT&CK data management (optional: pip install 'agentic-threat-hunting-framework[attack]')
athf attack update # Download/refresh STIX data
athf attack status # Show provider type, version, cache info
athf attack lookup T1003.001 # Look up technique metadata
athf attack techniques credential-access # List techniques for a tactic
# Similarity search
athf similar "LSASS dumping" # Find similar hunts by query
athf similar --hunt H-0001 # Find hunts similar to H-0001Research Commands (REQUIRED Pre-Hunt Investigation) - NEW
# Deep research before hunting (15-20 min, uses web search + LLM) - DEFAULT
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
# Offline mode (no web search)
athf research new --topic "Credential Access" --no-web-search
# List and view research documents
athf research list
athf research list --status completed
athf research view R-0001
athf research search "kerberos"
# Statistics
athf research stats
# Link research to hunt during creation (REQUIRED)
athf hunt new --research R-0001 --non-interactiveResearch is now REQUIRED for all hunts to ensure:
- Deep understanding of system internals before hunting (Skill 1: System Research)
- Adversary tradecraft is mapped to available telemetry (Skill 2: Adversary Tradecraft via web search)
- Telemetry gaps identified early (Skill 3: OCSF Field Mapping)
- Past hunts are reviewed to avoid duplication (Skill 4: Related Work)
- Hunt hypotheses are informed by structured research (Skill 5: Synthesis)
5-Skill Research Methodology:
- System Research - How does this technology normally work?
- Adversary Tradecraft - Attack techniques (web search via Tavily)
- Telemetry Mapping - OCSF field availability analysis
- Related Work - Past hunt correlation via semantic search
- Research Synthesis - Key findings, gaps, recommended hypothesis
Time investment:
- Advanced (default): 15-20 minutes - thorough 5-skill methodology
- Basic (urgent): 5 minutes - rapid research for time-sensitive hunts
Environment:
- Requires
TAVILY_API_KEYfor web search (get from https://tavily.com) - Configure via
.envfile:AWS_PROFILE=defaultor AWS credentials
AI-Friendly Hunt Creation (One-Liner Support)
NEW: athf hunt new supports rich content flags for fully-populated hunt files without manual editing.
Basic Usage:
athf hunt new --title "Hunt Title" --technique T1003.001 --non-interactiveAI-Friendly One-Liner (Full Hypothesis + ABLE Framework):
athf hunt new \
--title "macOS Unix Shell Abuse for Reconnaissance" \
--technique "T1059.004" \
--tactic "execution" \
--platform "macOS" \
--data-source "EDR process telemetry" \
--hypothesis "Adversaries execute malicious commands via native macOS shells..." \
--threat-context "macOS developer workstations are high-value targets..." \
--actor "Generic adversary (malware droppers, supply chain attackers...)" \
--behavior "Shell execution from unusual parents performing reconnaissance..." \
--location "macOS endpoints (developer workstations)..." \
--evidence "EDR process telemetry - Fields: process.name, parent.process.name..." \
--hunter "Your Name" \
--non-interactiveBenefits: ✅ AI assistants can create fully-populated hunt files in one command ✅ No manual file editing required for basic hunts ✅ All LOCK template fields can be populated via CLI ✅ Backwards compatible (all flags are optional)
Available Rich Content Flags:
--hypothesis- Full hypothesis statement--threat-context- Threat intel or context motivating the hunt--actor- Threat actor (for ABLE framework)--behavior- Behavior description (for ABLE framework)--location- Location/scope (for ABLE framework)--evidence- Evidence description (for ABLE framework)--research- Research document ID (e.g., R-0001) to link to hunt--hunter- Hunter name. Falls back to thehunterkey in.athfconfig.yaml, and if neither is set the field is left visibly unfilled rather than filled with a name nobody chose. Never put your own name here on an AI assistant's behalf, and never carry the unfilled marker intoattested_by— attestation names the person answerable for out-of-corpus work, so it is refused.
Common Mistakes
| ❌ Wrong | ✅ Correct |
| Write tool → hunt file | athf hunt new --non-interactive |
| Skip duplicate check | athf similar "keywords" first |
| Skip research | athf research new --topic "..." (REQUIRED) |
| Manual hypothesis | athf agent run hypothesis-generator --threat-intel "..." |
| Multiple Read operations | athf context --hunt H-XXXX |
Full CLI Reference: docs/CLI_REFERENCE.md
Domain-Specific Knowledge
ATHF includes bundled hunting knowledge files to inform hunt hypotheses and query generation.
Example domain-specific knowledge files organizations can add:
| Domain | Example File Path | Use Case |
| MITRE ATT&CK | knowledge/mitre-attack.md | TTP mapping, coverage analysis, prioritization |
| Endpoint Security | knowledge/domains/endpoint-security.md | Process execution, LOTL, credential access, persistence |
| IAM Security | knowledge/domains/iam-security.md | Password spraying, MFA fatigue, impossible travel |
| Insider Threat | knowledge/domains/insider-threat.md | Data exfiltration, bulk file access, sabotage |
| Cloud Security | knowledge/domains/cloud-security.md | AWS/Azure/GCP, CloudTrail, IAM manipulation |
Note: These are example paths. Organizations should create custom domain knowledge files in their workspace knowledge/ directory as needed.
Hunt Idea Generation
When user requests hunt ideas:
- Analyze coverage gaps:
athf hunt coverage --tactic allorathf context --tactic all --format json - Validate data sources: Check user's environment.md for available telemetry
- Present Top 3 ranked options with MITRE technique, data source, priority reason
- Wait for user selection before creating hunt
Full workflow: prompts/ai-workflow.md
Priority TTPs
How to Define Organizational Priorities:
- Review threat model (ransomware, insider threat, nation-state, supply chain, etc.)
- Map high-risk TTPs from MITRE ATT&CK framework
- Prioritize based on detection coverage gaps and business impact
- Document priorities in your workspace environment.md
Example Priorities (Customize for Your Organization):
- TA0006 - Credential Access
- TA0004 - Privilege Escalation
- TA0008 - Lateral Movement
- TA0003 - Persistence
- TA0010 - Exfiltration
AI Note: Prioritize hunt suggestions based on org's threat model and TTPs documented in environment.md. High-priority TTPs should guide coverage gap analysis.
Memory and Search
Maturity Level: Level 4 (Agentic) - AI assistants can autonomously execute hunt workflows using CLI tools
AI capabilities:
- Execute queries via data source integrations
- Semantic similarity search (
athf similar) - Pre-hunt research with web search (
athf research new) - 5-skill methodology - NEW - LLM-powered agents (
athf agent run) - Hypothesis generation, hunt research - NEW - Automated hypothesis generation (
athf agent run hypothesis-generator) - NEW - Automated hunt research (
athf agent run hunt-researcher) - NEW - ATT&CK coverage analysis (
athf hunt coverage) - ATT&CK STIX data (
athf attack update/status/lookup/techniques) - live technique metadata - NEW - Context loading optimization (
athf context) - Session tracking (
athf session) - Hunting metrics (
athf metrics show/summary/extract/record) - cost, tokens, queries, outcomes - NEW - MCP integrations (Notion, GitHub, custom tools)
Data sources AI can access:
hunts/folder and past hunt filesresearch/folder (R-XXXX.md documents) - NEW- Data sources via integrations (Splunk, etc. - via CLI or MCP)
- Web search via Tavily API (
athf research new) - NEW - User's environment.md
Agent Infrastructure (NEW):
- LLM Agents: AI-powered agents
- Agent Types:
hypothesis-generator- Generates creative hunt hypotheses from threat intelhunt-researcher- Conducts thorough 5-skill pre-hunt research
- Execution Modes: Interactive (default, step-by-step execution with user approval)
MCP Server Integration: Organizations can extend AI capabilities by installing MCP servers. See integrations/MCP_CATALOG.md for available integrations.
Hunting Metrics
Purpose: Track cost, tokens, queries, web searches, similarity searches, and outcomes per hunt and across the workspace.
ATHF auto-instruments three surfaces:
- LLM calls via
athf.agents.base.LLMAgent - Web searches via
athf.core.web_search.TavilySearchClient - Similarity searches via
athf similar
Anything else — vault-side queries, custom plugin work, hunt outcomes — calls the public Python API:
import athf.metrics as m
m.record_query(sql="...", duration_ms=15, rows=42)
m.record_hunt_outcome(hunt_id="H-0019", outcome="TP")
m.record("manual", hunt_id="H-0019", duration_ms=300, custom={"step": "triage"})All helpers are best-effort: failures never break callers. hunt_id / session_id auto-resolve from the active SessionManager when omitted.
CLI:
athf metrics show --hunt H-0019 # per-hunt detail
athf metrics summary # workspace totals + rollups
athf metrics extract # rebuild aggregates.json
athf metrics record --type hunt_outcome --hunt H-0019 --field outcome=tpStorage: metrics/events.jsonl (canonical, append-only) and metrics/aggregates.json (derived, regenerable).
Full reference: athf/data/docs/metrics.md
CLI Context Export & Semantic Search
Purpose: Two commands designed specifically for AI assistants to reduce token usage and avoid duplicate hunts.
athf context - AI-Optimized Context Loading
Why this helps AI:
- Reduces context-loading from ~5 tool calls to 1 - Single command replaces multiple Read operations
- Saves ~2,000 tokens per hunt
- Pre-filtered, structured content - Only relevant files included
- Easier parsing - JSON/YAML output formats
Usage examples:
# Export context for specific hunt
athf context --hunt H-0013 --format json
# Export context for all credential access hunts
athf context --tactic credential-access --format json
# Export context for macOS platform hunts
athf context --platform macos --format json
# Combine filters: persistence hunts on Linux platform
athf context --tactic persistence --platform linux --format json
# Export full repository context (use sparingly)
athf context --full --format jsonWhat's included:
- User's environment.md - Tech stack, data sources
- Past hunts - Filtered by hunt ID, tactic, platform, or combinations
- Domain knowledge - Relevant domain files based on tactic
When to use:
- Before generating hunt hypothesis - Get environment, past hunts, domain knowledge
- Before generating queries - Get data sources, past query examples
- When user asks about specific hunt - Load hunt content + context
- When exploring tactics - Get all hunts for a specific tactic
athf similar - Semantic Hunt Search
Why this helps AI:
- Find similar hunts even with different terminology - Semantic search, not keyword matching
- Avoid duplicate hunts - Check if similar hunt already exists
- Discover patterns - Find related hunts across history
- Better than grep - Conceptual matching, not string matching
Usage examples:
# Find hunts similar to text query
athf similar "password spraying via RDP"
# Find hunts similar to specific hunt
athf similar --hunt H-0013
# Limit results to top 5
athf similar "kerberos" --limit 5
# Export as JSON for parsing
athf similar "credential theft" --format json
# Set minimum similarity threshold
athf similar "reconnaissance" --threshold 0.3Similarity scoring:
- ≥0.50 = Very similar (likely duplicate or closely related)
- 0.30-0.49 = Similar (same domain or tactic)
- 0.15-0.29 = Somewhat similar (related concepts)
- <0.15 = Low similarity (different topics)
When to use:
- Before creating new hunt - Check if similar hunt already exists
- When user describes hunt - Find existing hunts matching description
- When exploring patterns - Discover hunt clusters by topic
- After hypothesis generation - Verify not duplicating work
Combined workflow (context + similar):
User: "Help me hunt for Kerberoasting"
AI: 1. athf similar "kerberoasting" --format json
→ Check for similar hunts first
2. If similar hunt exists (score > 0.3):
- athf context --hunt H-XXXX --format json
- Suggest continuing existing hunt
3. If no similar hunt:
- athf context --tactic credential-access --format json
- Generate new hypothesis with context
- Create new huntRequirements:
scikit-learnmust be installed forathf similar- Install with:
pip install scikit-learn
Hypothesis Generation Workflow
Core Process:
- Consult Hunting Brain - Read knowledge/hunting-knowledge.md Section 1 (Hypothesis Generation) and Section 5 (Pyramid of Pain)
- Search Memory First - REQUIRED: Use
athf similar "your hypothesis keywords"to check for duplicate hunts (saves time, avoids redundant work) - Validate Environment - Read user's environment.md to confirm data sources exist
- Generate LOCK Hypothesis - Create testable hypothesis following templates/HUNT_LOCK.md
- Apply Quality Criteria - Use quality checklist (Falsifiable, Scoped, Observable, Actionable, Contextual)
- Suggest Next Steps - Offer to create hunt file or draft query
Key Requirements:
- Focus on behaviors/TTPs (top of Pyramid of Pain) - Never build hypothesis around hashes or IPs alone
- Match hypothesis format: "Adversaries use [behavior] to [goal] on [target]"
- Reference past hunts by ID (e.g., "Building on H-0022 lessons...")
- Specify data sources from user's environment.md
- Include bounded time range with justification
- Consider false positives from similar past hunts
- Apply hypothesis quality rubric from hunting-knowledge.md
Output Must Follow: templates/HUNT_LOCK.md structure
Complete workflow details: prompts/ai-workflow.md
Maintenance
Review this file when:
- Adding new data sources (update "Data Sources" section or user's environment.md)
- Changing priority TTPs (update "Priority TTPs" section or user's environment.md)
- Discovering AI generates incorrect assumptions (add to "Guardrails" or "Common Mistakes")
- New integrations or MCP servers added (update "Memory and Search")
- Team practices change (update CLI workflow or hunt execution steps)
Last Updated: 2026-01-12 Maintained By: ATHF Framework Team
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

