agentic-threat-hunting-framework 0.3.1__tar.gz → 0.5.0__tar.gz

{agentic_threat_hunting_framework-0.3.1/agentic_threat_hunting_framework.egg-info → agentic_threat_hunting_framework-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.3.1
+Version: 0.5.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.1 → agentic_threat_hunting_framework-0.5.0/agentic_threat_hunting_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.3.1
+Version: 0.5.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.1 → agentic_threat_hunting_framework-0.5.0}/agentic_threat_hunting_framework.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ assets/athf_manual_v_ai.png
 athf/__init__.py
 athf/__version__.py
 athf/cli.py
+athf/plugin_system.py
 athf/agents/__init__.py
 athf/agents/base.py
 athf/agents/llm/__init__.py
@@ -37,12 +38,21 @@ athf/commands/init.py
 athf/commands/investigate.py
 athf/commands/research.py
 athf/commands/similar.py
+athf/commands/splunk.py
 athf/core/__init__.py
 athf/core/attack_matrix.py
+athf/core/clickhouse_connection.py
 athf/core/hunt_manager.py
 athf/core/hunt_parser.py
 athf/core/investigation_parser.py
+athf/core/metrics_tracker.py
+athf/core/query_executor.py
+athf/core/query_parser.py
+athf/core/query_suggester.py
+athf/core/query_validator.py
 athf/core/research_manager.py
+athf/core/session_manager.py
+athf/core/splunk_client.py
 athf/core/template_engine.py
 athf/core/web_search.py
 athf/data/__init__.py

{agentic_threat_hunting_framework-0.3.1 → agentic_threat_hunting_framework-0.5.0}/agentic_threat_hunting_framework.egg-info/requires.txt

@@ -2,6 +2,7 @@ click>=8.0.0
 pyyaml>=6.0
 rich>=10.0.0
 jinja2>=3.0.0
+python-dotenv>=0.19.0
 
 [:python_version < "3.9"]
 importlib_resources>=5.0.0
@@ -23,3 +24,6 @@ mkdocs-material>=9.0.0
 
 [similarity]
 scikit-learn>=1.0.0
+
+[splunk]
+requests>=2.25.0

{agentic_threat_hunting_framework-0.3.1 → agentic_threat_hunting_framework-0.5.0}/athf/__version__.py

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

{agentic_threat_hunting_framework-0.3.1 → agentic_threat_hunting_framework-0.5.0}/athf/cli.py

@@ -3,11 +3,15 @@
 import random
 
 import click
+from dotenv import load_dotenv
 from rich.console import Console
 
-from athf.__version__ import __version__
-from athf.commands import context, env, hunt, init, investigate, research, similar
-from athf.commands.agent import agent
+# Load .env file from current directory (if it exists)
+load_dotenv()
+
+from athf.__version__ import __version__  # noqa: E402
+from athf.commands import context, env, hunt, init, investigate, research, similar, splunk  # noqa: E402
+from athf.commands.agent import agent  # noqa: E402
 
 console = Console()
 
@@ -78,19 +82,30 @@ def cli() -> None:
 
 
 # Register command groups
-cli.add_command(init.init)
-cli.add_command(hunt.hunt)
-cli.add_command(investigate.investigate)
-cli.add_command(research.research)
+cli.add_command(init)
+cli.add_command(hunt)
+cli.add_command(investigate)
+cli.add_command(research)
 
 # Phase 1 commands (env, context, similar)
-cli.add_command(env.env)
-cli.add_command(context.context)
-cli.add_command(similar.similar)
+cli.add_command(env)
+cli.add_command(context)
+cli.add_command(similar)
 
 # Agent commands
 cli.add_command(agent)
 
+# Integration commands (optional, requires additional dependencies)
+if splunk is not None:
+    cli.add_command(splunk)
+
+# Load and register plugins
+from athf.plugin_system import PluginRegistry
+
+PluginRegistry.load_plugins()
+for name, cmd in PluginRegistry._commands.items():
+    cli.add_command(cmd, name=name)
+
 
 @cli.command(hidden=True)
 def wisdom() -> None:

agentic_threat_hunting_framework-0.5.0/athf/commands/__init__.py

@@ -0,0 +1,26 @@
+"""ATHF CLI commands (base commands only)."""
+
+from athf.commands.context import context
+from athf.commands.env import env
+from athf.commands.hunt import hunt
+from athf.commands.init import init
+from athf.commands.investigate import investigate
+from athf.commands.research import research
+from athf.commands.similar import similar
+
+# Optional: Splunk integration (requires requests package)
+try:
+    from athf.commands.splunk import splunk
+except ImportError:
+    splunk = None  # type: ignore[assignment]
+
+__all__ = [
+    "init",
+    "hunt",
+    "investigate",
+    "research",
+    "context",
+    "similar",
+    "env",
+    "splunk",
+]

{agentic_threat_hunting_framework-0.3.1 → agentic_threat_hunting_framework-0.5.0}/athf/commands/agent.py

@@ -125,6 +125,7 @@ def info(agent_name: str) -> None:
 
         console.print("\n[bold]Usage:[/bold]")
         console.print('  athf agent run hypothesis-generator --threat-intel "APT29 targeting SaaS"')
+        console.print('  athf agent run hypothesis-generator --threat-intel "..." --research R-0001')
         console.print()
 
     elif agent_name == "hunt-researcher":
@@ -170,6 +171,7 @@ def info(agent_name: str) -> None:
 @agent.command()
 @click.argument("agent_name")
 @click.option("--threat-intel", help="Threat intelligence context (for hypothesis-generator)")
+@click.option("--research", help="Research document ID (e.g., R-0001) to load context from")
 @click.option("--topic", help="Research topic (for hunt-researcher)")
 @click.option("--technique", help="MITRE ATT&CK technique (for hunt-researcher)")
 @click.option(
@@ -191,6 +193,7 @@ def info(agent_name: str) -> None:
 def run(  # noqa: C901
     agent_name: str,
     threat_intel: Optional[str],
+    research: Optional[str],
     topic: Optional[str],
     technique: Optional[str],
     depth: str,
@@ -208,6 +211,7 @@ def run(  # noqa: C901
       # Hypothesis Generator
       athf agent run hypothesis-generator --threat-intel "APT29 targeting SaaS applications"
       athf agent run hypothesis-generator --threat-intel "Insider threat data exfiltration" --tactic collection
+      athf agent run hypothesis-generator --threat-intel "Credential dumping" --research R-0001
 
       # Hunt Researcher
       athf agent run hunt-researcher --topic "LSASS dumping"
@@ -232,6 +236,32 @@ def run(  # noqa: C901
             # Try to load past hunts and environment data if available
             past_hunts: List[dict[str, Any]] = []
             environment = {}
+            research_context = None
+
+            # Load research document if provided
+            if research:
+                try:
+                    from pathlib import Path
+
+                    from athf.core.research_manager import ResearchManager
+
+                    research_mgr = ResearchManager(Path.cwd())
+                    research_doc = research_mgr.get_research(research)
+
+                    if research_doc:
+                        # Extract relevant research context
+                        research_context = {
+                            "research_id": research_doc.get("metadata", {}).get("research_id"),
+                            "topic": research_doc.get("metadata", {}).get("topic"),
+                            "recommended_hypothesis": research_doc.get("synthesis", {}).get("recommended_hypothesis"),
+                            "gaps": research_doc.get("synthesis", {}).get("gaps_identified", []),
+                            "key_findings": research_doc.get("synthesis", {}).get("key_findings", []),
+                        }
+                        console.print(f"[green]✓ Loaded research context from {research}[/green]\n")
+                    else:
+                        console.print(f"[yellow]⚠ Research document {research} not found[/yellow]\n")
+                except Exception as e:
+                    console.print(f"[yellow]⚠ Could not load research document: {e}[/yellow]\n")
 
             # Try to load environment.md if it exists
             try:
@@ -252,10 +282,22 @@ def run(  # noqa: C901
                     "platforms": ["Windows", "macOS", "Linux"],
                 }
 
+            # If research context is provided, append it to threat intel
+            threat_intel_with_research = threat_intel
+            if research_context:
+                threat_intel_with_research = (
+                    f"{threat_intel}\n\n"
+                    f"Research Context from {research_context['research_id']}:\n"
+                    f"- Topic: {research_context['topic']}\n"
+                    f"- Recommended Hypothesis: {research_context.get('recommended_hypothesis', 'N/A')}\n"
+                )
+                if research_context.get("gaps"):
+                    threat_intel_with_research += f"- Gaps: {', '.join(research_context['gaps'][:3])}\n"
+
             # Execute agent
             hypothesis_result = hypothesis_agent.execute(
                 HypothesisGenerationInput(
-                    threat_intel=threat_intel,
+                    threat_intel=threat_intel_with_research,
                     past_hunts=past_hunts,
                     environment=environment,
                 )

{agentic_threat_hunting_framework-0.3.1 → agentic_threat_hunting_framework-0.5.0}/athf/commands/hunt.py

@@ -40,6 +40,9 @@ Examples:
   # Non-interactive with all options
   athf hunt new --technique T1003.001 --title "LSASS Dumping" --non-interactive
 
+  # Link research document to hunt
+  athf hunt new --research R-0001 --title "Hunt Title" --non-interactive
+
   # List hunts with filters
   athf hunt list --status completed --tactic credential-access
 
@@ -52,6 +55,9 @@ Examples:
   # Show coverage gaps
   athf hunt coverage
 
+  # Filter coverage by tactic
+  athf hunt coverage --tactic credential-access
+
   # Validate hunt structure
   athf hunt validate H-0042
 
@@ -96,6 +102,7 @@ def hunt() -> None:
 @click.option("--location", help="Location/scope (for ABLE framework)")
 @click.option("--evidence", help="Evidence description (for ABLE framework)")
 @click.option("--hunter", help="Hunter name", default="AI Assistant")
+@click.option("--research", help="Research document ID (e.g., R-0001) this hunt is based on")
 def new(
     technique: Optional[str],
     title: Optional[str],
@@ -110,6 +117,7 @@ def new(
     location: Optional[str],
     evidence: Optional[str],
     hunter: Optional[str],
+    research: Optional[str],
 ) -> None:
     """Create a new hunt hypothesis with LOCK structure.
 
@@ -119,6 +127,7 @@ def new(
     • YAML frontmatter with metadata
     • LOCK pattern sections (Learn, Observe, Check, Keep)
     • MITRE ATT&CK mapping
+    • Optional link to research document
 
     \b
     Interactive mode (default):
@@ -131,6 +140,11 @@ def new(
       Example: athf hunt new --technique T1003.001 --title "LSASS Dumping" \\
                --tactic credential-access --platform Windows --non-interactive
 
+    \b
+    With research document:
+      Link a pre-hunt research document to the hunt.
+      Example: athf hunt new --research R-0001 --title "Hunt Title" --non-interactive
+
     \b
     After creation:
       1. Edit hunts/H-XXXX.md to flesh out your hypothesis
@@ -155,6 +169,13 @@ def new(
 
     console.print(f"[bold]Hunt ID:[/bold] {hunt_id}")
 
+    # Validate research document if provided
+    if research:
+        research_file = Path("research") / f"{research}.md"
+        if not research_file.exists():
+            console.print(f"[yellow]Warning: Research document {research} not found at {research_file}[/yellow]")
+            console.print("[yellow]Hunt will still be created, but research link may be broken.[/yellow]\n")
+
     # Gather hunt details
     if non_interactive:
         if not title:
@@ -209,6 +230,7 @@ def new(
         behavior=behavior,
         location=location,
         evidence=evidence,
+        spawned_from=research,
     )
 
     # Write hunt file
@@ -529,8 +551,9 @@ def _render_progress_bar(covered: int, total: int, width: int = 20) -> str:
 
 
 @hunt.command()
+@click.option("--tactic", help="Filter by specific tactic (or 'all' for all tactics)")
 @click.option("--detailed", is_flag=True, help="Show detailed technique coverage with hunt references")
-def coverage(detailed: bool) -> None:
+def coverage(tactic: Optional[str], detailed: bool) -> None:
     """Show MITRE ATT&CK technique coverage across hunts.
 
     \b
@@ -542,11 +565,17 @@ def coverage(detailed: bool) -> None:
 
     \b
     Examples:
-      # Show coverage overview
+      # Show coverage overview for all tactics
       athf hunt coverage
 
-      # Show detailed technique mapping
-      athf hunt coverage --detailed
+      # Show all tactics explicitly
+      athf hunt coverage --tactic all
+
+      # Show coverage for a specific tactic
+      athf hunt coverage --tactic credential-access
+
+      # Show detailed technique mapping for execution tactic
+      athf hunt coverage --tactic execution --detailed
 
     \b
     Note on technique counts:
@@ -578,12 +607,31 @@ def coverage(detailed: bool) -> None:
     summary = coverage["summary"]
     by_tactic = coverage["by_tactic"]
 
+    # Determine which tactics to display
+    tactics_to_display = []
+    if tactic and tactic.lower() != "all":
+        # Validate tactic exists
+        if tactic not in ATTACK_TACTICS:
+            console.print(f"[red]Error: Unknown tactic '{tactic}'[/red]")
+            console.print("\n[bold]Valid tactics:[/bold]")
+            for tactic_key in get_sorted_tactics():
+                console.print(f"  • {tactic_key}")
+            return
+        tactics_to_display = [tactic]
+    else:
+        # Show all tactics
+        tactics_to_display = get_sorted_tactics()
+
     # Display title
-    console.print("\n[bold]MITRE ATT&CK Coverage[/bold]")
+    if tactic and tactic.lower() != "all":
+        tactic_display_name = ATTACK_TACTICS[tactic]["name"]
+        console.print(f"\n[bold]MITRE ATT&CK Coverage - {tactic_display_name}[/bold]")
+    else:
+        console.print("\n[bold]MITRE ATT&CK Coverage[/bold]")
     console.print("─" * 60 + "\n")
 
-    # Display all tactics in ATT&CK order with hunt counts
-    for tactic_key in get_sorted_tactics():
+    # Display selected tactics in ATT&CK order with hunt counts
+    for tactic_key in tactics_to_display:
         data = by_tactic.get(tactic_key, {})
         tactic_name = ATTACK_TACTICS[tactic_key]["name"]
 
@@ -596,16 +644,19 @@ def coverage(detailed: bool) -> None:
         else:
             console.print(f"{tactic_name:<24} [dim]no coverage[/dim]")
 
-    # Display overall coverage
-    console.print(
-        f"\n[bold]Overall: {summary['unique_techniques']}/{summary['total_techniques']} techniques ({summary['overall_coverage_pct']:.0f}%)[/bold]\n"
-    )
+    # Display overall coverage only if showing all tactics
+    if not tactic or tactic.lower() == "all":
+        console.print(
+            f"\n[bold]Overall: {summary['unique_techniques']}/{summary['total_techniques']} techniques ({summary['overall_coverage_pct']:.0f}%)[/bold]\n"
+        )
+    else:
+        console.print()
 
     # Display detailed technique coverage if requested
     if detailed:
         console.print("\n[bold cyan]🔍 Detailed Technique Coverage[/bold cyan]\n")
 
-        for tactic_key in get_sorted_tactics():
+        for tactic_key in tactics_to_display:
             data = by_tactic.get(tactic_key, {})
             if data.get("hunt_count", 0) == 0:
                 continue  # Skip tactics with no hunts in detailed view