agentleFS
Nebulock-IncNebulock-Inc/agentic-threat-hunting-framework/AGENTS.md

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.

  • In this repository2 other files it gives its agents.

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
  1. Very specific:

    🔧 ALWAYS activate the virtual environment FIRST: - Run source .venv/bin/activate before any athf commands (verify with which athf)

    line 13
  2. Distinctive:

    Browse past hunts: - Search hunt history before suggesting new hypotheses

    line 15
  3. Distinctive:

    Use environment.md to understand available data sources

    line 17
  4. Very specific:

    Rule of thumb: If athf has a command for it, use the command.

    line 69
  5. Distinctive:

    CRITICAL: Use structured output formats for query analysis to reduce token costs by 75%.

    line 75
  6. Distinctive:

    Key Principle: All hunts must focus on behaviors and TTPs (top half of Pyramid of Pain).

    line 193
  7. Distinctive:

    Before generating hypotheses (review Section 1 and Section 5)

    line 196
  8. Distinctive:

    When analyzing findings (review Section 4 for confidence scoring)

    line 198
  9. Distinctive:

    AI Note: Always verify data sources exist in the user's environment.md before generating queries or hunt hypotheses.

    line 213
  10. Distinctive:

    Check: - Test with bounded, safe query

    line 229
  11. Distinctive:

    Ensure queries are bounded by time, scope, and impact

    line 234
  12. Distinctive:

    Document lessons learned after hunt execution

    line 235
  13. Very specific:

    Check if we've hunted this before: - Use athf similar "hypothesis keywords" to find duplicate hunts

    line 303
  14. Very specific:

    Every result gets one of five verdicts.

    line 319
  15. Very specific:

    If you have none of these, the verdict is suspected.

    line 341
  16. Very specific:

    Do not write a config inside hunts/: Only the workspace-root config is read.

    line 368
  17. Very specific:

    For AI Assistants: Before running any athf commands, verify venv is activated with which athf.

    line 420
  18. Very specific:

    athf similar "hypothesis keywords": - BEFORE creating hunt hypothesis

    line 428
  19. Very specific:

    athf context --hunt H-XXXX: - BEFORE executing hunt queries

    line 434
  20. Distinctive:

    Execute queries: - Use appropriate data source tools (SIEM interface, query CLI, etc.)

    line 467
  21. Distinctive:

    STOP after each query: - Wait for user feedback before next query

    line 468
  22. Very specific:

    Document findings: - Update hunt file with results, assign a verdict to each (see Verdicts), then run athf hunt validate H-XXXX

    line 469
  23. Distinctive:

    Validate with GATES: - After documenting findings in KEEP phase:

    line 470
  24. Very specific:

    Run /gates --hunt H-XXXX to validate detection quality

    line 471
  25. Very specific:

    Document verdict in hunt file under ### GATES Verdict

    line 472
  26. Very specific:

    Import the GATES document: adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-XXXX_GATES.yaml (--dry-run to preview).

    line 475
  27. Very specific:

    If CONDITIONAL: import the same way, then complete the prerequisites — ADEF marks the record needs_review: gates_conditional so it can't …

    line 482
  28. Very specific:

    If HOLD/DROP/TIME_BOX/RECURRING_HUNT: Document strategy (see GATES output).

    line 484
  29. Distinctive:

    Validate data sources: Check user's environment.md for available telemetry

    line 658
  30. Distinctive:

    Wait for user selection: before creating hunt

    line 660
  31. Distinctive:

    Document priorities in your workspace environment.md

    line 673
  32. Very specific:

    All helpers are best-effort: failures never break callers.

    line 744
  33. Distinctive:

    Pre-filtered, structured content: - Only relevant files included

    line 770
  34. Distinctive:

    Avoid duplicate hunts: - Check if similar hunt already exists

    line 806
  35. Distinctive:

    Before creating new hunt: - Check if similar hunt already exists

    line 835
  36. Distinctive:

    After hypothesis generation: - Verify not duplicating work

    line 838
  37. Distinctive:

    Consult Hunting Brain: - Read knowledge/hunting-knowledge.md Section 1 (Hypothesis Generation) and Section 5 (Pyramid of Pain)

    line 864
  38. Distinctive:

    Validate Environment: - Read user's environment.md to confirm data sources exist

    line 866
  39. Very specific:

    Generate LOCK Hypothesis: - Create testable hypothesis following templates/HUNT_LOCK.md

    line 867
  40. Distinctive:

    Apply Quality Criteria: - Use quality checklist (Falsifiable, Scoped, Observable, Actionable, Contextual)

    line 868
  41. Distinctive:

    Focus on behaviors/TTPs (top of Pyramid of Pain): - Never build hypothesis around hashes or IPs alone

    line 873
  42. Distinctive:

    Consider false positives from similar past hunts

    line 878

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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/activate before any athf commands (verify with which 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 CategoryCLI Command❌ Never Use
Hunt creationathf hunt new --non-interactiveWrite tool, Edit tool
Investigation creationathf investigate new --non-interactiveWrite tool, Edit tool
Research executionathf research new --topic "..."Manual web search, Write tool
Hypothesis generationathf agent run hypothesis-generator --threat-intel "..."Manual hypothesis drafting
Duplicate checkingathf similar "keywords"Grep, manual search
Context loadingathf context --hunt H-XXXXMultiple Read operations
Coverage analysisathf hunt coverageManual ATT&CK counting
Hunt validationathf hunt validate H-XXXXManual YAML parsing
Hunt searchathf 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:

  1. 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
  2. Table Format (Quick triage) - Columnar data for rapid scanning
  3. 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 guides

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

Nested AGENTS.md Files

This repository can use nested AGENTS.md files for specialized context. The closest file in the directory hierarchy takes precedence.

DirectoryContextWhen to Load
Root /General hunting methodologyDefault context
integrations/<datasource>/Query execution, data source specificsWriting queries for that data source
hunts/Hunt execution workflow, LOCK patternCreating/executing hunts
research/Research-first workflowPre-hunt research
queries/Query library, parameterized queriesAlert triage
investigations/Investigation workflowExploratory 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:

  1. Hypothesis Generation - Pattern-based generation, quality criteria, examples
  2. Behavioral Models - ATT&CK TTP → observable mappings, behavior-to-telemetry translation
  3. Pivot Logic - Artifact chains, pivot playbooks, decision criteria
  4. Analytical Rigor - Confidence scoring, evidence strength, bias checks
  5. 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:

  1. Learn - Gather context (CTI, alert, anomaly, threat intel)
  2. Observe - Form hypothesis about adversary behavior
  3. Check - Test with bounded, safe query
  4. 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:

AspectHunts (H-XXXX)Investigations (I-XXXX)
PurposeHypothesis-driven huntingExploratory analysis
MetricsTracked (per-verdict counts, costs)NOT tracked
Directoryhunts/investigations/
ValidationStrict (CI/CD enforced)Lightweight

CLI Commands:

  • athf investigate new - Create investigation (interactive or --non-interactive)
  • athf investigate list [--type finding] - List/filter investigations
  • athf investigate search "keyword" - Full-text search
  • athf investigate validate I-XXXX - Lightweight validation
  • athf investigate promote I-XXXX - Promote to formal hunt

Cross-Referencing:

  • Investigations → Hunts: Use related_hunts: [H-0013] field
  • Hunts → Investigations: Use spawned_from: I-0042 field

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 100 or 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 modes
  • integrations/elasticsearch/AGENTS.md - Query DSL, aggregations
  • integrations/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.

VerdictAssign whenGoes in
confirmedTelemetry evidence plus independent confirmation outside the log corpusfindings
suspectedTelemetry evidence only — you could not independently confirmfindings
attempted_not_vulnerableAttack behavior observed and the control demonstrably held (name the control)ruled_out
benignExplained by specific legitimate activityruled_out
inconclusiveTelemetry 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 typeWhat it means
Controlled reproductionBehavior reproduced in an attack range / lab
Host forensicsThe artifact recovered — crontab entry, plist, binary on disk, registry key
Configuration reviewThe 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 disk

Capabilities 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 outputverdict: suspected + note what confirmation would take
confirmation: as a prose string on confirmedA mapping with method, produced_by, attested_by, detail
attested_by: the team / AI assistant / pipelineA 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 findingDeclare producers in .athfconfig.yaml; never self-certify
Editing config to grant yourself a capabilityReport that confirmation needs work you cannot do
attempted_not_vulnerable listed under findingsPut it in ruled_out — it closed the question
benign listed under findingsPut it in ruled_out
"No findings" when controls heldruled_out entries naming each control that held
attempted_not_vulnerable with no control namedName the control and how you verified it held
Promoting legacy true_positives to confirmedLeave 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/activate

Verify activation:

which athf
# Should output: /path/to/workspace/.venv/bin/athf

athf --version
# Should succeed with version number

Why this matters:

  • System athf (if installed) may lack dependencies like scikit-learn
  • Venv athf has 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:

  1. 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"
  2. 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

StepCommandWhenPurpose
1athf similar "keywords"BEFORE hypothesisCheck for duplicate hunts
2athf research new --topic "..."REQUIRED: Before hypothesisThorough pre-hunt research (15-20 min) - NEW
3athf agent run hypothesis-generator --threat-intel "..."AFTER researchGenerate structured hypothesis - NEW
4athf hunt new --technique T1XXX --title "..." --non-interactiveWHEN creating huntAuto-generate hunt file (⚠️ NEVER use Write tool)
5athf context --hunt H-XXXX --format jsonBEFORE executing queriesLoad all context efficiently

Hunt Execution Steps

  1. Check duplicates: athf similar "hypothesis keywords"
  2. Deep research (REQUIRED): athf research new --topic "..." (creates R-XXXX.md with 5-skill methodology)
  3. Generate hypothesis: athf agent run hypothesis-generator --threat-intel "..."
  4. Create hunt file: athf hunt new --research R-XXXX --non-interactive ... (link to research)
  5. Load context: athf context --hunt H-XXXX --format json
  6. Present hypothesis to user - ABLE scoping table + threat context
  7. Execute queries - Use appropriate data source tools (SIEM interface, query CLI, etc.)
  8. STOP after each query - Wait for user feedback before next query
  9. Document findings - Update hunt file with results, assign a verdict to each (see Verdicts), then run athf hunt validate H-XXXX
  10. Validate with GATES - After documenting findings in KEEP phase:
    • Run /gates --hunt H-XXXX to 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-run to preview). One file in, N detections out — deployable candidates get a D-XXXX, a catalog record and a journal at Find; archival ones are reported as skipped. No cd needed; ADEF resolves its workspace from ADEF_WORKSPACE. Confirm the mode exists with adef 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 promote which moves hunt files between directories.
    • If CONDITIONAL: import the same way, then complete the prerequisites — ADEF marks the record needs_review: gates_conditional so it can't ship unnoticed
    • If HOLD/DROP/TIME_BOX/RECURRING_HUNT: Document strategy (see GATES output). Note a PROMOTE hunt's .yaml can still contain TIME_BOX and HOLD candidates — the hunt-level verdict picks the file format, not each candidate's fate.

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

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

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

  1. System Research - How does this technology normally work?
  2. Adversary Tradecraft - Attack techniques (web search via Tavily)
  3. Telemetry Mapping - OCSF field availability analysis
  4. Related Work - Past hunt correlation via semantic search
  5. 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_KEY for web search (get from https://tavily.com)
  • Configure via .env file: AWS_PROFILE=default or 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-interactive

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

Benefits: ✅ 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 the hunter key 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 into attested_by — attestation names the person answerable for out-of-corpus work, so it is refused.

Common Mistakes

❌ Wrong✅ Correct
Write tool → hunt fileathf hunt new --non-interactive
Skip duplicate checkathf similar "keywords" first
Skip researchathf research new --topic "..." (REQUIRED)
Manual hypothesisathf agent run hypothesis-generator --threat-intel "..."
Multiple Read operationsathf 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:

DomainExample File PathUse Case
MITRE ATT&CKknowledge/mitre-attack.mdTTP mapping, coverage analysis, prioritization
Endpoint Securityknowledge/domains/endpoint-security.mdProcess execution, LOTL, credential access, persistence
IAM Securityknowledge/domains/iam-security.mdPassword spraying, MFA fatigue, impossible travel
Insider Threatknowledge/domains/insider-threat.mdData exfiltration, bulk file access, sabotage
Cloud Securityknowledge/domains/cloud-security.mdAWS/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:

  1. Analyze coverage gaps: athf hunt coverage --tactic all or athf context --tactic all --format json
  2. Validate data sources: Check user's environment.md for available telemetry
  3. Present Top 3 ranked options with MITRE technique, data source, priority reason
  4. Wait for user selection before creating hunt

Full workflow: prompts/ai-workflow.md


Priority TTPs

How to Define Organizational Priorities:

  1. Review threat model (ransomware, insider threat, nation-state, supply chain, etc.)
  2. Map high-risk TTPs from MITRE ATT&CK framework
  3. Prioritize based on detection coverage gaps and business impact
  4. 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 files
  • research/ 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 intel
    • hunt-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=tp

Storage: 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 json

What'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.3

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

Requirements:

  • scikit-learn must be installed for athf similar
  • Install with: pip install scikit-learn

Hypothesis Generation Workflow

Core Process:

  1. Consult Hunting Brain - Read knowledge/hunting-knowledge.md Section 1 (Hypothesis Generation) and Section 5 (Pyramid of Pain)
  2. Search Memory First - REQUIRED: Use athf similar "your hypothesis keywords" to check for duplicate hunts (saves time, avoids redundant work)
  3. Validate Environment - Read user's environment.md to confirm data sources exist
  4. Generate LOCK Hypothesis - Create testable hypothesis following templates/HUNT_LOCK.md
  5. Apply Quality Criteria - Use quality checklist (Falsifiable, Scoped, Observable, Actionable, Contextual)
  6. 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.