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

{agentic_threat_hunting_framework-0.3.0.dist-info → agentic_threat_hunting_framework-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.3.0
+Version: 0.4.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: python-dotenv>=0.19.0
 Requires-Dist: importlib_resources>=5.0.0; python_version < "3.9"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
@@ -49,6 +50,8 @@ Requires-Dist: mkdocs>=1.5.0; extra == "docs"
 Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
 Provides-Extra: similarity
 Requires-Dist: scikit-learn>=1.0.0; extra == "similarity"
+Provides-Extra: splunk
+Requires-Dist: requests>=2.25.0; extra == "splunk"
 Dynamic: license-file
 
 # Agentic Threat Hunting Framework (ATHF)

{agentic_threat_hunting_framework-0.3.0.dist-info → agentic_threat_hunting_framework-0.4.0.dist-info}/RECORD

@@ -1,34 +1,41 @@
-agentic_threat_hunting_framework-0.3.0.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
+agentic_threat_hunting_framework-0.4.0.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
 athf/__init__.py,sha256=OrjZe8P97_BTEkscapnwSsqKSjwXNP9d8-HtGr19Ni0,241
-athf/__version__.py,sha256=1uOy8XMZ6490EmE359rotOAMj4-r0qm1IZG5gSmm_7g,59
-athf/cli.py,sha256=rkg_Nx9Yy_UqTXBOh-pwaiD-lXO0_IXQMA1SQpDj7g0,4639
-athf/commands/__init__.py,sha256=KbpUcLPjmltq5a_m1MjhrIe4sk3DvqsnAw1wCAZfZNo,85
-athf/commands/agent.py,sha256=k-NWiLppt2oWbiJ-hx1inkK51jhfsAYiFhixbzzQmQI,16565
+athf/__version__.py,sha256=wCIQoU9b7qKcSNQiIOgHaD2buzBC-dlQYtvg8X5WS4A,59
+athf/cli.py,sha256=l8PkZCs4ToUOAxX_Ciy5bLD1mV1Qta3_WalBJOA1t9c,4787
+athf/agents/__init__.py,sha256=iaSJpvnXm9rz4QS7gBrsaLEjm49uvsMs4BLPOJeyp78,346
+athf/agents/base.py,sha256=HQJpQAKmY7folbzPnvF2OZ9vhEf205lBFUHrtfOXr64,4352
+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=YYPIbajQf7DN_h8PFNfktgny4oHKKWKGbAU6tItE5vE,500
+athf/commands/agent.py,sha256=c7ZeZa3OArXyXTgVjmUB2JXa3m9IpLFJ_FEVDhaDLE8,19000
 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/hunt.py,sha256=aQdgNddqy_VrxZOkxhuPxIr4KLZtX5a2ZLb9079vLlw,25169
 athf/commands/init.py,sha256=Qn0iETNyuQvM-ySqCeoDz-pPemeuzROX_karQF5yN_o,12685
 athf/commands/investigate.py,sha256=mK_id5vjfN_ukqB_-fyia0FNa0pBmtn0Xv6CKHQI1Qo,24663
 athf/commands/research.py,sha256=FrLph4agaGQ_rIxMh0OQwh1MIGDFtj40zJ3E1ZFwaAw,18112
-athf/commands/similar.py,sha256=FTTVr4zzP9bdJrirscp6pOxdQbE8zot6pa20-_TYiuo,11804
+athf/commands/similar.py,sha256=qy1Gng73_VpqfoLLNUdxF1GBx-X29g-k8Q_wrEx26hA,11868
+athf/commands/splunk.py,sha256=7n7Jl1ExqZCNxUhG0kAKgAvZMqbIoGSgx2Moq7vAu-Y,11622
 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/core/web_search.py,sha256=B9IhmwH7gy2RVA6WSN3L7yGp3Q4L8OsiiwcEvnnZejU,10320
+athf/core/splunk_client.py,sha256=Xib2zVwV2l8eChzqUahI3PZ7Z2XS2wz01sPbF1E0Q18,11611
+athf/core/template_engine.py,sha256=Awp0n9E5Q1dYA35XDKKAd5VJLdpaDl2N967hackUVa8,6010
+athf/core/web_search.py,sha256=lBdApqIemV2kH_NJ3vDd3adH9DwrPjaq_fs5qMjR8mI,10354
 athf/data/__init__.py,sha256=QtgONloCaS3E9Ow995FMxyy6BbszpfmYeWpySQ2b9Mc,502
-athf/data/docs/CHANGELOG.md,sha256=1dAondeKsQnGOn9esy9oZ29uG_oGgRuHxmkcmGQ1Cwo,5950
-athf/data/docs/CLI_REFERENCE.md,sha256=zqUp-tu8OAcqzpOwx3XvzEq7UV6woDraUOcWasZI0a8,43748
+athf/data/docs/CHANGELOG.md,sha256=JKkzzs1n5jSERHFi6fDt6sYEe52MSaY127dfzthkUA8,8655
+athf/data/docs/CLI_REFERENCE.md,sha256=pb76UqkY_WHJMBEXwEmK0TJR8kcGzoBPlJ0WdGMKDQM,54875
 athf/data/docs/INSTALL.md,sha256=JOWxk6q2-rdpgCnWdSPb3-Cp8rX1y4nQm7ObKz2G0uM,13117
 athf/data/docs/README.md,sha256=rp-XQZeqteXJz7M2qKX3sl6o0AVfhGmz8GcNNKAt8pM,1061
 athf/data/docs/environment.md,sha256=K88NBWZM2bI1Jztd0ORa6AYaMgPVjVB-K2fJl8S5-g8,8306
-athf/data/docs/getting-started.md,sha256=j4SAXe-Rm1RhYBDvWaNpV8XS0rc_mZ2Ew0yPCxE4_wQ,14156
-athf/data/docs/level4-agentic-workflows.md,sha256=DX54qu8LbJysjDfQLGSEPSO_Q6BUACLpa-XCsR6xUp4,13439
+athf/data/docs/getting-started.md,sha256=dUCpXHzucRLfUYzDylvnCtdqv9VCukfQCtGg7hTGmrI,15316
+athf/data/docs/level4-agentic-workflows.md,sha256=68crKsDaLyrgxVG37nPIuJyO9NobLi09Obv7D1AnpYs,14123
 athf/data/docs/lock-pattern.md,sha256=eICjNh5SAgIhkOYBDhHg1tgw4A29xgnRDWC9vH1wLEQ,4863
-athf/data/docs/maturity-model.md,sha256=S2m8JSQDe9R5ROBWS4Gy0-sRF5I7mo-CI3cUnmNpxmk,16347
+athf/data/docs/maturity-model.md,sha256=O1FDIKPkO9twNdZmA0w-TUwPvLP331tul2fPpUnCXD4,18181
 athf/data/docs/why-athf.md,sha256=rIoUb7iqdZKbuWNyRlGxhZrRkLx7gWAGS-kurEZDt04,2148
 athf/data/hunts/FORMAT_GUIDELINES.md,sha256=lMyBekmOzhtO1olO1P-M0Gi_n5oY60k7qkRZE63sTgw,15010
 athf/data/hunts/H-0001.md,sha256=rdUIpQ_uN8bx7XS1ED85rW5aRKxFOpMg0X7PANY7eCY,23220
@@ -44,8 +51,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.3.0.dist-info/METADATA,sha256=TT9rzSs2CSKI3TTKMkSP7ZRehUXtntbgYCWfCFK7qbU,15838
-agentic_threat_hunting_framework-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-agentic_threat_hunting_framework-0.3.0.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
-agentic_threat_hunting_framework-0.3.0.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
-agentic_threat_hunting_framework-0.3.0.dist-info/RECORD,,
+agentic_threat_hunting_framework-0.4.0.dist-info/METADATA,sha256=KpwdeeDnNEGhS6zlI3NHdcKGwaN2iGYYJDIQkRr6D9E,15949
+agentic_threat_hunting_framework-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agentic_threat_hunting_framework-0.4.0.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
+agentic_threat_hunting_framework-0.4.0.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
+agentic_threat_hunting_framework-0.4.0.dist-info/RECORD,,

athf/__version__.py

@@ -1,3 +1,3 @@
 """Version information for ATHF."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

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  # type: ignore[import-not-found]
+
+            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  # type: ignore[import-untyped]
+
+            # 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",
+]