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

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
 

athf/plugin_system.py

@@ -0,0 +1,48 @@
+"""Plugin system for ATHF extensions."""
+from typing import Dict, Type, Callable
+import importlib.metadata
+from click import Command
+
+
+class PluginRegistry:
+    """Central registry for ATHF plugins."""
+
+    _agents: Dict[str, Type] = {}
+    _commands: Dict[str, Command] = {}
+
+    @classmethod
+    def register_agent(cls, name: str, agent_class: Type) -> None:
+        """Register an agent plugin."""
+        cls._agents[name] = agent_class
+
+    @classmethod
+    def register_command(cls, name: str, command: Command) -> None:
+        """Register a CLI command plugin."""
+        cls._commands[name] = command
+
+    @classmethod
+    def get_agent(cls, name: str) -> Type:
+        """Get registered agent by name."""
+        return cls._agents.get(name)
+
+    @classmethod
+    def get_command(cls, name: str) -> Command:
+        """Get registered command by name."""
+        return cls._commands.get(name)
+
+    @classmethod
+    def load_plugins(cls) -> None:
+        """Auto-discover and load all installed plugins."""
+        try:
+            for ep in importlib.metadata.entry_points(group='athf.commands'):
+                command = ep.load()
+                cls.register_command(ep.name, command)
+        except Exception:
+            pass  # No plugins installed yet
+
+        try:
+            for ep in importlib.metadata.entry_points(group='athf.agents'):
+                agent = ep.load()
+                cls.register_agent(ep.name, agent)
+        except Exception:
+            pass  # No plugins installed yet