agentic-threat-hunting-framework 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

athf/data/docs/getting-started.md

@@ -191,14 +191,25 @@ The repository includes [knowledge/hunting-knowledge.md](../knowledge/hunting-kn
 
 **No changes needed** - this file provides universal hunting expertise that AI assistants will apply to your environment.
 
-### Test AI Integration
+### Test AI Integration and Agent Framework (v0.3.0+)
 
 1. Open your repository in Claude Code, GitHub Copilot, or Cursor
 2. Ask: "What hunts have we documented?"
 3. Ask: "What data sources do we have for Windows endpoint hunting?"
-4. Ask: "Generate a hypothesis for T1003.001 LSASS dumping"
+4. Try the agent framework:
+   ```bash
+   # List available agents
+   athf agent list
+
+   # Generate a hypothesis using the hypothesis-generator agent
+   athf agent run hypothesis-generator \
+     --threat-intel "APT29 using LSASS dumping for credential theft"
 
-If the AI can answer these questions using your repository context, you're successfully at Level 2!
+   # Conduct pre-hunt research
+   athf research new --topic "LSASS dumping" --technique T1003.001
+   ```
+
+If the AI can answer these questions and the agent commands work, you're successfully at Level 2!
 
 **Time investment:** Approximately 1 week to customize AGENTS.md and test AI integration.
 
@@ -332,12 +343,45 @@ Don't build a full agent pipeline on day one:
 
 If you installed the CLI (Option A), here are the most useful commands:
 
+### Agent Framework (v0.3.0+)
+
+```bash
+# List all available agents
+athf agent list
+
+# Get details about a specific agent
+athf agent info hypothesis-generator
+
+# Run an agent
+athf agent run hypothesis-generator --threat-intel "APT29 using WMI"
+athf agent run context-loader --hunt H-0013
+athf agent run similarity-scorer --query "password spraying"
+```
+
+### Research Workflow (v0.3.0+)
+
+```bash
+# Create research document (15-20 min deep research)
+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
+
+# List and view research
+athf research list
+athf research view R-0001
+```
+
 ### Hunt Management
 
 ```bash
 # Create hunts
 athf hunt new                           # Interactive mode
 athf hunt new --technique T1003.001 --title "LSASS Dumping"
+athf hunt new --research R-0001         # Link to research document
+
+# Execute hunt workflow with agents (v0.3.0+)
+athf hunt execute H-0013
 
 # List and search
 athf hunt list                          # All hunts

athf/data/docs/level4-agentic-workflows.md

@@ -124,16 +124,21 @@ At Level 4, multiple specialized agents work together, coordinating through your
 
 ```
 [Triggered by CTI Monitor]
+- Runs: athf agent run similarity-scorer --query "cmd.exe process execution" --limit 5
 - Reviews similar hunts: H-0042 (PowerShell), H-0089 (Process Execution)
+- Runs: athf research new --topic "Qakbot cmd.exe execution" --technique T1059.003 --depth basic
 - Extracts lessons: "Include parent-child process chains", "Filter System32 parents"
+- Runs: athf agent run hypothesis-generator --threat-intel "Qakbot T1059.003 campaign" --technique T1059.003
 - Generates LOCK hypothesis:
 
-  Learn: Qakbot campaign using T1059.003 detected in CTI
+  Learn: Qakbot campaign using T1059.003 detected in CTI. Research document R-0042 created.
   Observe: Adversaries spawn cmd.exe from suspicious parents (Office, browsers)
   Check: [Generated Splunk query with bounds and limits]
   Keep: [Placeholder for execution results]
 
+- Runs: athf hunt new --technique T1059.003 --title "Qakbot cmd.exe Detection" --research R-0042 --non-interactive
 - Creates: hunts/H-0156.md
+- Runs: athf agent run query-validator --sql "[generated query]"
 - Validates query syntax
 - Decision: Draft ready, trigger Validator
 ```
@@ -142,12 +147,15 @@ At Level 4, multiple specialized agents work together, coordinating through your
 
 ```
 [Triggered by Hypothesis Generator]
+- Runs: athf hunt validate H-0156
 - Reads AGENTS.md for data source availability
 - Checks: index=sysmon exists ✓
 - Checks: EventCode=1 available ✓
 - Validates: MITRE technique T1059.003 format ✓
+- Runs: athf agent run query-validator --sql "[generated query from H-0156]"
 - Reviews: Query has time bounds ✓
 - Reviews: Query has result limits ✓
+- Runs: athf agent run coverage-analyzer --tactic initial-access
 - Decision: Hunt validated, trigger Notifier
 ```
 

athf/data/docs/maturity-model.md

@@ -169,7 +169,7 @@ The AI automatically searches your hunts directory, references past investigatio
 4. Open your repo in Claude Code or similar AI assistant
 5. Start asking questions about your hunts
 
-**CLI Commands at Level 2:**
+**CLI Commands at Level 2 (v0.3.0+):**
 At this level, you still run commands manually, but AI helps you decide what to run:
 ```bash
 # AI suggests: "Let me search for related hunts first"
@@ -180,6 +180,12 @@ athf hunt coverage
 
 # AI suggests: "Let's see your success rates"
 athf hunt stats
+
+# AI suggests: "Let's do pre-hunt research first"
+athf research new --topic "LSASS dumping" --technique T1003.001
+
+# AI suggests: "Use the hypothesis generator agent"
+athf agent run hypothesis-generator --threat-intel "APT29 credential theft"
 ```
 
 The AI reads your hunt files and provides context-aware suggestions, but you execute the commands.
@@ -250,23 +256,45 @@ Should I create a Jira ticket for investigation?"
 
 **The difference:** Claude executes queries, enriches data, and creates tickets - not just suggests them.
 
-### CLI Integration at Level 3
+### CLI Integration at Level 3 (v0.3.0+)
 
 At Level 3, AI uses CLI commands directly as part of workflows:
 
-**Example: AI-Driven Hunt Creation**
+**Example: AI-Driven Hunt Creation with Research**
 ```
-You: "Search for SSH brute force and create a hunt"
+You: "Research and create a hunt for SSH brute force"
+
+AI: [Uses: athf research new --topic "SSH brute force" --depth basic]
+    "Research complete. Key findings:
+    - SSH brute force typically targets default accounts
+    - Failed auth patterns indicate automated tools
+    - Successful login after failures is high-confidence indicator"
 
-AI: [Executes Splunk query via MCP]
+    [Uses: athf agent run hypothesis-generator --threat-intel "SSH brute force campaign"]
+    "Generated hypothesis focusing on failed auth clustering"
+
+    [Executes Splunk query via MCP]
     [Gets results: 3 high-volume IPs]
-    [Uses: athf hunt new --technique T1110.001 --title "SSH Brute Force Detection"]
+    [Uses: athf hunt new --technique T1110.001 --research R-0023]
     [Documents findings in hunt file]
     [Uses: athf hunt validate to check structure]
-    "Created H-0087.md documenting SSH brute force activity. Review?"
+    "Created H-0087.md with research link. Review?"
+```
+
+**Example: Orchestrated Hunt Execution (v0.3.0+)**
+```
+You: "Execute hunt H-0042 end-to-end"
+
+AI: [Uses: athf hunt execute H-0042 --dry-run]
+    "Dry run validates all queries and data sources"
+    [Uses: athf hunt execute H-0042]
+    "Executing hunt with agent orchestration:
+    - Context loaded via context-loader agent
+    - Queries validated via query-validator agent
+    - Results analyzed, 2 suspicious findings flagged"
 ```
 
-**The difference:** You direct the workflow, AI executes both MCP tools (Splunk) and CLI commands (athf).
+**The difference:** You direct the workflow, AI executes both MCP tools (Splunk) and CLI commands (athf), including research and agent orchestration.
 
 ### Getting Started at Level 3
 
@@ -329,7 +357,7 @@ At Level 4, multiple specialized agents work together:
 **You wake up to:**
 > "3 new draft hunts created overnight based on recent CTI. Ready for your review."
 
-### CLI Commands in Autonomous Workflows
+### CLI Commands in Autonomous Workflows (v0.3.0+)
 
 At Level 4, agents use CLI commands without your intervention:
 
@@ -337,28 +365,42 @@ At Level 4, agents use CLI commands without your intervention:
 ```bash
 # CTI Monitor Agent (runs every 6 hours)
 athf hunt search "T1059.003"  # Check for existing hunts
+athf agent run similarity-scorer --query "Qakbot JavaScript"  # Find related hunts
 # No matches found
 
+# Research Agent (triggered if new TTP)
+athf research new \
+  --topic "Qakbot JavaScript dropper" \
+  --technique T1059.003 \
+  --depth basic  # Quick research for autonomous workflows
+
 # Hypothesis Generator Agent (triggered by CTI Monitor)
+athf agent run hypothesis-generator \
+  --threat-intel "Qakbot campaign using T1059.003 for initial access" \
+  --technique T1059.003
+
+# Create hunt file with generated hypothesis and research link
 athf hunt new \
   --technique T1059.003 \
   --title "Qakbot JavaScript Dropper Detection" \
+  --research R-0042 \
   --platform windows \
   --non-interactive
 
 # Validator Agent (triggered by Generator)
+athf agent run query-validator --sql "[generated query]"
 athf hunt validate H-0156  # Ensure structure is correct
-athf hunt coverage  # Update coverage metrics
+athf agent run coverage-analyzer --tactic initial-access  # Update coverage metrics
 
 # Notifier Agent (triggered by Validator)
-# Posts to Slack: "H-0156 ready for review"
+# Posts to Slack: "H-0156 ready for review (research: R-0042)"
 ```
 
 **The progression:**
 - **Level 1:** You run `athf hunt new` manually
-- **Level 2:** AI suggests when to run `athf hunt new`
-- **Level 3:** AI runs `athf hunt new` when you ask
-- **Level 4:** Agents run `athf hunt new` autonomously based on objectives
+- **Level 2:** AI suggests when to run `athf hunt new` and `athf agent run`
+- **Level 3:** AI runs `athf hunt new`, `athf agent run`, and `athf research new` when you ask
+- **Level 4:** Agents run all commands autonomously based on objectives
 
 ### The Maturity Progression