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

{agentic_threat_hunting_framework-0.2.4.dist-info → agentic_threat_hunting_framework-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.2.4
+Version: 0.3.1
 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.dist-info → agentic_threat_hunting_framework-0.3.1.dist-info}/RECORD

@@ -1,22 +1,31 @@
-agentic_threat_hunting_framework-0.2.4.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
+agentic_threat_hunting_framework-0.3.1.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
 athf/__init__.py,sha256=OrjZe8P97_BTEkscapnwSsqKSjwXNP9d8-HtGr19Ni0,241
-athf/__version__.py,sha256=Cl7hGHiamJWMCcDKQ8Lcm6Vlc50BZ6GasydpyAoWkg8,59
-athf/cli.py,sha256=LSOazv6E_RChZFqoyMcdfDPH1hIJeZc1s95fssjDLZs,4515
-athf/commands/__init__.py,sha256=uDyr0bz-agpGO8fraXQl24wuQCxqbeCevZsJ2bDK29s,25
-athf/commands/context.py,sha256=WvOf0OuttAsEk_h4QDtdfqYI4CulDg2UCtq_5r5iJAA,12686
-athf/commands/env.py,sha256=AisRllJXbyCjK_2ii21qBBmCz9raxhBUemwM7BxqIYg,11859
-athf/commands/hunt.py,sha256=9ZEI11y8DUixUqw8-yR01K4hVz2JSJJokRwWk8tnNn4,22969
+athf/__version__.py,sha256=BCXUHJGbpcGJIqpp7wAIo-a46Xl8TlClrdkqx9_kTW8,59
+athf/cli.py,sha256=rkg_Nx9Yy_UqTXBOh-pwaiD-lXO0_IXQMA1SQpDj7g0,4639
+athf/agents/__init__.py,sha256=iaSJpvnXm9rz4QS7gBrsaLEjm49uvsMs4BLPOJeyp78,346
+athf/agents/base.py,sha256=lnVDIOQUOyP-Apa9UM2E1mRXUPnNJ4hVqQXOwVw2u4c,4286
+athf/agents/llm/__init__.py,sha256=qSGA-NaInjsDkMpGQwnTz3S1OgCVlzetpMcDS_to1co,671
+athf/agents/llm/hunt_researcher.py,sha256=dIyD2Izh3zdf62kCHug1DwXFgmWhOMQUTim7qM3UAIs,27071
+athf/agents/llm/hypothesis_generator.py,sha256=XkbJz8IS4zwQjEy-ZD0zy2XW5uRnAy87Lii-5XTY0WU,8564
+athf/commands/__init__.py,sha256=KbpUcLPjmltq5a_m1MjhrIe4sk3DvqsnAw1wCAZfZNo,85
+athf/commands/agent.py,sha256=k-NWiLppt2oWbiJ-hx1inkK51jhfsAYiFhixbzzQmQI,16565
+athf/commands/context.py,sha256=V-at81-OgKcLY-In48-AccTnHfTgdofmnjE8S5kypoI,12678
+athf/commands/env.py,sha256=JPKRsv48cgsIAjSFaGJ1-Nu0nQKGSVg4AbiFxb9jVX4,11887
+athf/commands/hunt.py,sha256=PcYz0Zj9qqB10s9mkbfHk-hl2IbcfJekeB6cA2exXPo,22991
 athf/commands/init.py,sha256=Qn0iETNyuQvM-ySqCeoDz-pPemeuzROX_karQF5yN_o,12685
 athf/commands/investigate.py,sha256=mK_id5vjfN_ukqB_-fyia0FNa0pBmtn0Xv6CKHQI1Qo,24663
-athf/commands/similar.py,sha256=lniOkSOn--ZIztsfTZS-afioJpqJEJQjmqfxsDy6xZQ,11790
+athf/commands/research.py,sha256=FrLph4agaGQ_rIxMh0OQwh1MIGDFtj40zJ3E1ZFwaAw,18112
+athf/commands/similar.py,sha256=FTTVr4zzP9bdJrirscp6pOxdQbE8zot6pa20-_TYiuo,11804
 athf/core/__init__.py,sha256=yG7C8ljx3UW4QZoYvDjUxsWHlbS8M-GLGB7Je7rRfqo,31
 athf/core/attack_matrix.py,sha256=QZKKmxckQ6-U7lqVdGUJoj2jEAhP3Juvr3sqaNx2oTw,3238
 athf/core/hunt_manager.py,sha256=PFsg8Ecg94NCpuFZpApo82lyORkgK5IfOIih-7-XsmM,11580
 athf/core/hunt_parser.py,sha256=FUj0yyBIcZnaS9aItMImeBDhegQwpkewIwUMNXW_ZWU,5122
 athf/core/investigation_parser.py,sha256=wbfjnq4gFgIc0a4bHIAnidVNPhbHDpIXWY1SGLk0Xls,6804
+athf/core/research_manager.py,sha256=i4fUjuZJcAik8I4pwbLkQlu6cuxkWDlqaIRQrzAfB0s,14512
 athf/core/template_engine.py,sha256=vNTVhlxIXZpxU7VmQyrqCSt6ORS0IVjAV54TOmUDMTE,5636
-athf/data/__init__.py,sha256=eC5AiaYPQ7oYR3ktxTvRhUHVd_RB1zhQgcVPD3o-9Vw,364
-athf/data/docs/CHANGELOG.md,sha256=1dAondeKsQnGOn9esy9oZ29uG_oGgRuHxmkcmGQ1Cwo,5950
+athf/core/web_search.py,sha256=B9IhmwH7gy2RVA6WSN3L7yGp3Q4L8OsiiwcEvnnZejU,10320
+athf/data/__init__.py,sha256=QtgONloCaS3E9Ow995FMxyy6BbszpfmYeWpySQ2b9Mc,502
+athf/data/docs/CHANGELOG.md,sha256=2omJArkID-VADL0gNDfBSS0_E9GnP9OfZLn9ls-l5eA,7074
 athf/data/docs/CLI_REFERENCE.md,sha256=zqUp-tu8OAcqzpOwx3XvzEq7UV6woDraUOcWasZI0a8,43748
 athf/data/docs/INSTALL.md,sha256=JOWxk6q2-rdpgCnWdSPb3-Cp8rX1y4nQm7ObKz2G0uM,13117
 athf/data/docs/README.md,sha256=rp-XQZeqteXJz7M2qKX3sl6o0AVfhGmz8GcNNKAt8pM,1061
@@ -40,8 +49,8 @@ athf/data/prompts/ai-workflow.md,sha256=rZtOcGuAEi35qx7182TwHJEORdz1-RxkZMBVkg61
 athf/data/prompts/basic-prompts.md,sha256=2bunpO35RoBdJWYthXVi40RNl2UWrfwOaFthBLHF5sU,8463
 athf/data/templates/HUNT_LOCK.md,sha256=zXxHaKMWbRDLewLTegYJMbXRM72s9gFFvjdwFfGNeJE,7386
 athf/utils/__init__.py,sha256=aEAPI1xnAsowOtc036cCb9ZOek5nrrfevu8PElhbNgk,30
-agentic_threat_hunting_framework-0.2.4.dist-info/METADATA,sha256=gcqEWImt2gBOrH2q5VUhafR5OiG_xIoCdpfbtEy1mt0,15472
-agentic_threat_hunting_framework-0.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-agentic_threat_hunting_framework-0.2.4.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
-agentic_threat_hunting_framework-0.2.4.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
-agentic_threat_hunting_framework-0.2.4.dist-info/RECORD,,
+agentic_threat_hunting_framework-0.3.1.dist-info/METADATA,sha256=KgED__EriZvPR42CCSDQHf7md832CFyd7RyRTbdtQbU,15838
+agentic_threat_hunting_framework-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agentic_threat_hunting_framework-0.3.1.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
+agentic_threat_hunting_framework-0.3.1.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
+agentic_threat_hunting_framework-0.3.1.dist-info/RECORD,,

athf/__version__.py

@@ -1,3 +1,3 @@
 """Version information for ATHF."""
 
-__version__ = "0.2.4"
+__version__ = "0.3.1"

athf/agents/__init__.py

@@ -0,0 +1,14 @@
+"""ATHF Agent Framework.
+
+This module provides base classes and implementations for ATHF agents.
+Agents can be deterministic (Python-only) or LLM-powered (using Claude API).
+"""
+
+from athf.agents.base import Agent, AgentResult, DeterministicAgent, LLMAgent
+
+__all__ = [
+    "Agent",
+    "AgentResult",
+    "DeterministicAgent",
+    "LLMAgent",
+]

athf/agents/base.py

@@ -0,0 +1,141 @@
+"""Base classes for hunt-vault agents."""
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, Generic, List, Optional, TypeVar
+
+# Type variables for input/output
+InputT = TypeVar("InputT")
+OutputT = TypeVar("OutputT")
+
+
+@dataclass
+class AgentResult(Generic[OutputT]):
+    """Standard result format for all agents."""
+
+    success: bool
+    data: Optional[OutputT]
+    error: Optional[str] = None
+    warnings: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_success(self) -> bool:
+        """Check if the agent execution was successful."""
+        return self.success and self.error is None
+
+
+class Agent(ABC, Generic[InputT, OutputT]):
+    """Base class for all agents."""
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        """Initialize agent with optional configuration.
+
+        Args:
+            config: Optional configuration dictionary
+        """
+        self.config = config or {}
+        self._setup()
+
+    def _setup(self) -> None:
+        """Optional setup method for subclasses."""
+        pass
+
+    @abstractmethod
+    def execute(self, input_data: InputT) -> AgentResult[OutputT]:
+        """Execute agent logic.
+
+        Args:
+            input_data: Input for the agent
+
+        Returns:
+            AgentResult with output data or error
+        """
+        pass
+
+    def __call__(self, input_data: InputT) -> AgentResult[OutputT]:
+        """Allow calling agent as a function."""
+        return self.execute(input_data)
+
+
+class DeterministicAgent(Agent[InputT, OutputT]):
+    """Base class for deterministic Python agents (no LLM)."""
+
+    pass
+
+
+class LLMAgent(Agent[InputT, OutputT]):
+    """Base class for LLM-powered agents."""
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None, llm_enabled: bool = True):
+        """Initialize LLM agent.
+
+        Args:
+            config: Optional configuration dictionary
+            llm_enabled: Whether to enable LLM functionality
+        """
+        self.llm_enabled = llm_enabled
+        super().__init__(config)
+
+    def _log_llm_metrics(
+        self,
+        agent_name: str,
+        model_id: str,
+        input_tokens: int,
+        output_tokens: int,
+        cost_usd: float,
+        duration_ms: int,
+    ) -> None:
+        """Log LLM call metrics to centralized tracker.
+
+        Args:
+            agent_name: Name of the agent (e.g., "hypothesis-generator")
+            model_id: Bedrock model ID
+            input_tokens: Number of input tokens
+            output_tokens: Number of output tokens
+            cost_usd: Estimated cost in USD
+            duration_ms: Call duration in milliseconds
+        """
+        try:
+            from athf.core.metrics_tracker import MetricsTracker
+
+            MetricsTracker.get_instance().log_bedrock_call(
+                agent=agent_name,
+                model_id=model_id,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                cost_usd=cost_usd,
+                duration_ms=duration_ms,
+            )
+        except Exception:
+            pass  # Never fail agent execution due to metrics logging
+
+    def _get_llm_client(self) -> Any:
+        """Get AWS Bedrock runtime client for Claude models.
+
+        Returns:
+            Bedrock runtime client instance or None if LLM is disabled
+
+        Raises:
+            ValueError: If AWS credentials are not configured
+            ImportError: If boto3 package is not installed
+        """
+        if not self.llm_enabled:
+            return None
+
+        try:
+            import boto3
+
+            # Get AWS region from environment or use default
+            region = os.getenv("AWS_REGION", os.getenv("AWS_DEFAULT_REGION", "us-east-1"))
+
+            # Create Bedrock runtime client
+            # Uses AWS credentials from environment, ~/.aws/credentials, or IAM role
+            client = boto3.client(service_name="bedrock-runtime", region_name=region)
+
+            return client
+        except ImportError:
+            raise ImportError("boto3 package not installed. Run: pip install boto3")
+        except Exception as e:
+            raise ValueError(f"Failed to create Bedrock client: {e}")

athf/agents/llm/__init__.py

@@ -0,0 +1,27 @@
+"""LLM-powered agents for ATHF.
+
+These agents use Claude API for creative and analytical tasks.
+All LLM agents have fallback to deterministic methods when LLM is disabled.
+"""
+
+from athf.agents.llm.hunt_researcher import (
+    HuntResearcherAgent,
+    ResearchInput,
+    ResearchOutput,
+    ResearchSkillOutput,
+)
+from athf.agents.llm.hypothesis_generator import (
+    HypothesisGenerationInput,
+    HypothesisGenerationOutput,
+    HypothesisGeneratorAgent,
+)
+
+__all__ = [
+    "HypothesisGeneratorAgent",
+    "HypothesisGenerationInput",
+    "HypothesisGenerationOutput",
+    "HuntResearcherAgent",
+    "ResearchInput",
+    "ResearchOutput",
+    "ResearchSkillOutput",
+]