agentic-threat-hunting-framework 0.2.4__tar.gz → 0.3.0__tar.gz

{agentic_threat_hunting_framework-0.2.4/agentic_threat_hunting_framework.egg-info → agentic_threat_hunting_framework-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.2.4
+Version: 0.3.0
 Summary: Agentic Threat Hunting Framework - Memory and AI for threat hunters
 Author-email: Sydney Marrone <athf@nebulock.io>
 Maintainer-email: Sydney Marrone <athf@nebulock.io>
@@ -33,6 +33,7 @@ Requires-Dist: click>=8.0.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=10.0.0
 Requires-Dist: jinja2>=3.0.0
+Requires-Dist: importlib_resources>=5.0.0; python_version < "3.9"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -76,6 +77,7 @@ ATHF provides structure and persistence for threat hunting programs. It's a mark
 - Maintains a searchable repository of past investigations
 - Enables AI assistants to reference your environment and previous work
 - Works with any SIEM/EDR platform
+- **NEW:** Includes AI-powered research and hypothesis generation agents (v0.3.0+)
 
 ## The Problem
 
@@ -115,8 +117,8 @@ ATHF defines a simple maturity model. Each level builds on the previous one.
 | **0** | Ad-hoc | Hunts exist in Slack, tickets, or analyst notes |
 | **1** | Documented | Persistent hunt records using LOCK |
 | **2** | Searchable | AI reads and recalls your hunts |
-| **3** | Generative | AI executes queries via MCP tools |
-| **4** | Agentic | Autonomous agents monitor and act |
+| **3** | Generative | AI executes queries via MCP tools, conducts research |
+| **4** | Agentic | Autonomous agents monitor and act, generate hypotheses |
 
 **Level 1:** Operational within a day
 **Level 2:** Operational within a week
@@ -136,8 +138,11 @@ pip install agentic-threat-hunting-framework
 # Initialize your hunt program
 athf init
 
-# Create your first hunt
-athf hunt new --technique T1003.001 --title "LSASS Credential Dumping"
+# NEW: Conduct research before hunting (5-skill methodology)
+athf research new --topic "LSASS dumping" --technique T1003.001
+
+# Create your first hunt (link to research)
+athf hunt new --technique T1003.001 --title "LSASS Credential Dumping" --research R-0001
 ```
 
 ### Option 2: Install from Source (Development)
@@ -161,7 +166,8 @@ git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
 cd agentic-threat-hunting-framework
 
 # Copy a template and start documenting
-cp templates/HUNT_LOCK.md hunts/H-0001.md
+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
@@ -182,6 +188,23 @@ athf init                           # Interactive setup
 athf init --non-interactive         # Use defaults
 ```
 
+### Research & Hypothesis Generation (NEW in v0.3.0)
+
+```bash
+# Conduct thorough pre-hunt research (15-20 min)
+athf research new --topic "LSASS dumping" --technique T1003.001
+
+# Quick research for urgent hunts (5 min)
+athf research new --topic "Pass-the-Hash" --depth basic
+
+# Generate AI-powered hypothesis from threat intel
+athf agent run hypothesis-generator --threat-intel "APT29 targeting SaaS"
+
+# List research and agents
+athf research list
+athf agent list
+```
+
 ### Create Hunts
 
 ```bash
@@ -189,7 +212,8 @@ athf hunt new                       # Interactive mode
 athf hunt new \
   --technique T1003.001 \
   --title "LSASS Dumping Detection" \
-  --platform windows
+  --platform windows \
+  --research R-0001                 # Link to research document
 ```
 
 ### List & Search
@@ -199,6 +223,7 @@ athf hunt list                      # Show all hunts
 athf hunt list --status completed   # Filter by status
 athf hunt list --output json        # JSON output
 athf hunt search "kerberoasting"    # Full-text search
+athf research search "credential"   # Search research docs
 ```
 
 ### Validate & Stats
@@ -208,6 +233,7 @@ athf hunt validate                  # Validate all hunts
 athf hunt validate H-0001           # Validate specific hunt
 athf hunt stats                     # Show statistics
 athf hunt coverage                  # MITRE ATT&CK coverage
+athf research stats                 # Research metrics
 ```
 
 **Full documentation:** [CLI Reference](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
@@ -222,35 +248,12 @@ Watch ATHF in action: initialize a workspace, create hunts, and explore your thr
 
 ## Installation
 
-### Prerequisites
+See the [Quick Start](#-quick-start) section above for installation options (PyPI, source, or pure markdown).
+
+**Prerequisites:**
 - Python 3.8-3.13 (for CLI option)
 - Your favorite AI code assistant
 
-### From PyPI (Recommended)
-
-```bash
-pip install agentic-threat-hunting-framework
-athf init
-```
-
-### From Source (Development)
-
-```bash
-git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
-cd agentic-threat-hunting-framework
-pip install -e .
-athf init
-```
-
-### Markdown-Only Setup (No Installation)
-
-```bash
-git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
-cd agentic-threat-hunting-framework
-```
-
-Start documenting hunts in the `hunts/` directory using the LOCK pattern.
-
 ## Documentation
 
 ### Core Concepts
@@ -297,21 +300,16 @@ Agentic threat hunting is not about replacing analysts. It's about building syst
 
 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.
 
-## 💬 Community & Support
+## 💬 Community & Adoption
 
 - **GitHub Discussions:** [Ask questions, share hunts](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
 - **Issues:** [Report bugs or request features](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
-- **Adoption Guide:** See [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) for how to use ATHF in your organization
 - **LinkedIn:** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - Follow for updates
 
-## 📖 Using ATHF
-
-ATHF is a framework to internalize, not a platform to extend. Fork it, customize it, make it yours.
+**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](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/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](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
 
-See [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) for adoption guidance. Your hunts stay yours—sharing back is optional but appreciated ([Discussions](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)).
-
 The goal is to help every threat hunting team move from ad-hoc memory to structured, agentic capability.
 
 ---

{agentic_threat_hunting_framework-0.2.4 → agentic_threat_hunting_framework-0.3.0}/README.md

@@ -24,6 +24,7 @@ ATHF provides structure and persistence for threat hunting programs. It's a mark
 - Maintains a searchable repository of past investigations
 - Enables AI assistants to reference your environment and previous work
 - Works with any SIEM/EDR platform
+- **NEW:** Includes AI-powered research and hypothesis generation agents (v0.3.0+)
 
 ## The Problem
 
@@ -63,8 +64,8 @@ ATHF defines a simple maturity model. Each level builds on the previous one.
 | **0** | Ad-hoc | Hunts exist in Slack, tickets, or analyst notes |
 | **1** | Documented | Persistent hunt records using LOCK |
 | **2** | Searchable | AI reads and recalls your hunts |
-| **3** | Generative | AI executes queries via MCP tools |
-| **4** | Agentic | Autonomous agents monitor and act |
+| **3** | Generative | AI executes queries via MCP tools, conducts research |
+| **4** | Agentic | Autonomous agents monitor and act, generate hypotheses |
 
 **Level 1:** Operational within a day
 **Level 2:** Operational within a week
@@ -84,8 +85,11 @@ pip install agentic-threat-hunting-framework
 # Initialize your hunt program
 athf init
 
-# Create your first hunt
-athf hunt new --technique T1003.001 --title "LSASS Credential Dumping"
+# NEW: Conduct research before hunting (5-skill methodology)
+athf research new --topic "LSASS dumping" --technique T1003.001
+
+# Create your first hunt (link to research)
+athf hunt new --technique T1003.001 --title "LSASS Credential Dumping" --research R-0001
 ```
 
 ### Option 2: Install from Source (Development)
@@ -109,7 +113,8 @@ git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
 cd agentic-threat-hunting-framework
 
 # Copy a template and start documenting
-cp templates/HUNT_LOCK.md hunts/H-0001.md
+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
@@ -130,6 +135,23 @@ athf init                           # Interactive setup
 athf init --non-interactive         # Use defaults
 ```
 
+### Research & Hypothesis Generation (NEW in v0.3.0)
+
+```bash
+# Conduct thorough pre-hunt research (15-20 min)
+athf research new --topic "LSASS dumping" --technique T1003.001
+
+# Quick research for urgent hunts (5 min)
+athf research new --topic "Pass-the-Hash" --depth basic
+
+# Generate AI-powered hypothesis from threat intel
+athf agent run hypothesis-generator --threat-intel "APT29 targeting SaaS"
+
+# List research and agents
+athf research list
+athf agent list
+```
+
 ### Create Hunts
 
 ```bash
@@ -137,7 +159,8 @@ athf hunt new                       # Interactive mode
 athf hunt new \
   --technique T1003.001 \
   --title "LSASS Dumping Detection" \
-  --platform windows
+  --platform windows \
+  --research R-0001                 # Link to research document
 ```
 
 ### List & Search
@@ -147,6 +170,7 @@ athf hunt list                      # Show all hunts
 athf hunt list --status completed   # Filter by status
 athf hunt list --output json        # JSON output
 athf hunt search "kerberoasting"    # Full-text search
+athf research search "credential"   # Search research docs
 ```
 
 ### Validate & Stats
@@ -156,6 +180,7 @@ athf hunt validate                  # Validate all hunts
 athf hunt validate H-0001           # Validate specific hunt
 athf hunt stats                     # Show statistics
 athf hunt coverage                  # MITRE ATT&CK coverage
+athf research stats                 # Research metrics
 ```
 
 **Full documentation:** [CLI Reference](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
@@ -170,35 +195,12 @@ Watch ATHF in action: initialize a workspace, create hunts, and explore your thr
 
 ## Installation
 
-### Prerequisites
+See the [Quick Start](#-quick-start) section above for installation options (PyPI, source, or pure markdown).
+
+**Prerequisites:**
 - Python 3.8-3.13 (for CLI option)
 - Your favorite AI code assistant
 
-### From PyPI (Recommended)
-
-```bash
-pip install agentic-threat-hunting-framework
-athf init
-```
-
-### From Source (Development)
-
-```bash
-git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
-cd agentic-threat-hunting-framework
-pip install -e .
-athf init
-```
-
-### Markdown-Only Setup (No Installation)
-
-```bash
-git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
-cd agentic-threat-hunting-framework
-```
-
-Start documenting hunts in the `hunts/` directory using the LOCK pattern.
-
 ## Documentation
 
 ### Core Concepts
@@ -245,21 +247,16 @@ Agentic threat hunting is not about replacing analysts. It's about building syst
 
 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.
 
-## 💬 Community & Support
+## 💬 Community & Adoption
 
 - **GitHub Discussions:** [Ask questions, share hunts](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
 - **Issues:** [Report bugs or request features](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
-- **Adoption Guide:** See [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) for how to use ATHF in your organization
 - **LinkedIn:** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - Follow for updates
 
-## 📖 Using ATHF
-
-ATHF is a framework to internalize, not a platform to extend. Fork it, customize it, make it yours.
+**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](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/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](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
 
-See [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) for adoption guidance. Your hunts stay yours—sharing back is optional but appreciated ([Discussions](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)).
-
 The goal is to help every threat hunting team move from ad-hoc memory to structured, agentic capability.
 
 ---

agentic_threat_hunting_framework-0.3.0/USING_ATHF.md

@@ -0,0 +1,209 @@
+# Using ATHF in Your Organization
+
+ATHF is a **framework for building agentic capability** in threat hunting. This guide helps you adopt it.
+
+## Philosophy
+
+ATHF teaches systems how to hunt with memory, learning, and augmentation.
+
+- **Framework, not platform** - Structure over software, adapt to your environment
+- **Capability-focused** - Adds memory and agents to any hunting methodology ([PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html), [SQRRL](https://www.threathunting.net/files/The%20Threat%20Hunting%20Reference%20Model%20Part%202_%20The%20Hunting%20Loop%20_%20Sqrrl.pdf), custom)
+- **Progression-minded** - Start simple, scale when complexity demands it
+
+## How to Adopt ATHF
+
+### 1. Clone and Customize
+
+```bash
+git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
+cd agentic-threat-hunting-framework
+
+# Option A: With CLI (Recommended)
+pip install -e .
+athf init
+
+# Option B: Markdown-Only
+# Just start documenting hunts in hunts/ folder
+```
+
+> The CLI is optional convenience tooling. The framework structure (hunts/, LOCK pattern, AGENTS.md) enables AI assistance.
+
+### 2. Choose Your Integration Approach
+
+**Standalone:** Use ATHF's LOCK pattern as your hunting methodology (simple, agentic-first).
+
+**Layered:** Keep your existing framework ([PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html), [SQRRL](https://www.threathunting.net/files/The%20Threat%20Hunting%20Reference%20Model%20Part%202_%20The%20Hunting%20Loop%20_%20Sqrrl.pdf), [TaHiTI](https://www.betaalvereniging.nl/en/safety/tahiti/)) and use ATHF to add memory and AI capability.
+
+### 3. Customize Environmental Context
+
+**environment.md** - Your actual tech stack:
+- Security tools (SIEM, EDR, firewalls)
+- Technology stack (languages, frameworks, cloud platforms)
+- Known gaps and blind spots
+- Update quarterly or when major changes occur
+
+**AGENTS.md** - AI assistant context:
+- Data sources and tools
+- Organization threat model and priorities
+- Compliance requirements
+- High-priority ATT&CK TTPs
+
+**knowledge/hunting-knowledge.md** - Expert hunting frameworks (included):
+- Pre-loaded hunting methodology and analytical rigor
+- Use as-is or customize for your organization
+
+### 4. Start at Your Maturity Level
+
+See the [README](README.md) for detailed maturity model explanation.
+
+**Level 1: Documented (Week 1)**
+- Create repository, start documenting hunts in LOCK format
+- Use `athf hunt new` or manual markdown
+
+**Level 2: Searchable (Week 2-4)**
+- Add AGENTS.md and hunting-knowledge.md
+- Choose AI tool (GitHub Copilot, Claude Code, Cursor)
+- AI reads your hunt history automatically
+
+**Level 3+: Generative/Agentic (Month 3-6+)**
+- Build scripts for repetitive tasks (if needed)
+- Add structured memory when grep becomes slow (50+ hunts)
+
+## Maintaining Environmental Context
+
+### Ownership & Cadence
+
+**Who maintains:**
+- **Infrastructure/DevOps:** Tech stack changes, new services
+- **Security architects:** Network architecture, security tools
+- **Threat hunters:** Hunt findings, discovered services, blind spots
+
+**When to update:**
+- **Quarterly:** Scheduled review of environment.md
+- **Event-driven:** New security tools, infrastructure migrations, major application launches
+- **AGENTS.md:** As needed when data sources or AI tools change
+- **hunting-knowledge.md:** Rarely (core hunting frameworks are stable)
+
+### Memory Scaling
+
+| Hunt Volume | Approach | Tools |
+|-------------|----------|-------|
+| **10-50 hunts** | Grep or CLI search | `grep -i "keyword" hunts/*.md` or `athf hunt search` |
+| **50-200 hunts** | CLI + simple helpers | Tags in markdown, hunt index, `athf hunt list --filter` |
+| **200+ hunts** | Structured memory | JSON index, SQLite, full-text search |
+
+**Key principle:** Don't build structure until grep becomes painful.
+
+### Asset Management Integration (Optional)
+
+**Manual (Level 1-2):** Reference CMDB/asset inventory in environment.md, add links to ServiceNow/Jira/wikis.
+
+**Automated (Level 3+):** Script to pull tech stack from CMDB API, auto-update environment.md sections.
+
+## Scaling by Team Size
+
+| Team Size | Level | Focus |
+|-----------|-------|-------|
+| **Solo Hunter** | 1-2 | Personal repo + AI tool, maintain environment.md yourself (15-30 min/quarter) |
+| **Small Team (2-5)** | 1-2 | Shared repo + AI tools, collaborative memory, shared environment.md responsibility |
+| **Security Team (5-20)** | 2-3 | Optional automation scripts, metrics dashboards, formalized environment.md updates |
+| **Enterprise SOC (20+)** | 3-4 | Hunt library by TTP, detection engineering pipeline, automated environment.md from CMDB |
+
+## Customizing the LOCK Loop
+
+LOCK is flexible—add gates as needed:
+
+```
+# Add approval gates
+Learn → Observe → [Manager Approval] → Check → Keep
+
+# Add peer review
+Learn → Observe → Check → [Peer Review] → Keep
+
+# Add detection pipeline
+Learn → Observe → Check → Keep → [AI Converts to Detection] → Deploy
+```
+
+## Customization Examples
+
+### Add Organization-Specific Fields
+
+```markdown
+## Organization Context
+**Business Unit**: [Sales / Engineering / Finance]
+**Data Classification**: [Public / Internal / Confidential]
+**Compliance Framework**: [NIST / PCI / SOC2]
+```
+
+### Add Your Threat Model
+
+Create `threat_model.md` to document:
+- Priority threat actors for your industry
+- Common initial access vectors
+- Crown jewels and critical assets
+- Known coverage gaps
+
+### Organize Hunts by Priority
+
+```
+hunts/
+├── ransomware/
+├── insider_threat/
+├── supply_chain/
+└── cloud_compromise/
+```
+
+## Integration Patterns
+
+### With HEARTH
+```bash
+./tools/convert_to_hearth.py hunts/H-0001.md
+```
+
+### With Detection-as-Code
+```bash
+./tools/export_to_sigma.py queries/H-0001.spl
+```
+
+### With SOAR
+Trigger automated hunts from playbooks using generated hypotheses.
+
+## Making ATHF "Yours"
+
+### Rebrand
+- Change logo, update terminology, add your security principles
+
+### Add Your Voice
+- Replace examples with your real hunts (redacted)
+- Document your team's unique lessons
+- Share your threat hunting philosophy
+
+### Extend with Tools
+
+**Built-in CLI:** See [README](README.md#-cli-commands) for complete command reference including:
+- Hunt management (`athf hunt new/list/search/validate/stats/coverage`)
+- Research agent (`athf research new`) - Deep pre-hunt research with 5-skill methodology
+- Hypothesis generator (`athf agent run hypothesis-generator`) - AI-generated hunt hypotheses
+
+**Custom helpers:** Build additional tools as needed (query validators, metrics dashboards, SOAR integrations).
+
+## Questions?
+
+1. Review templates and example hunt (H-0001) for patterns
+2. Check prompts/ folder for AI-assisted workflows
+3. See [README](README.md) for workflow diagrams and integration patterns
+4. Adapt freely - this framework is yours to modify
+
+## Sharing Back (Optional)
+
+We'd love to hear how you're using ATHF:
+- Blog about your experience
+- Share anonymized metrics
+- Present at conferences
+- Open a discussion at [github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
+
+Your hunts, data, and lessons stay **yours**.
+
+---
+
+**Remember**: ATHF is a framework to internalize, not a platform to extend. Make it yours.