agentic-threat-hunting-framework 0.5.1__tar.gz → 0.7.0__tar.gz

{agentic_threat_hunting_framework-0.5.1/agentic_threat_hunting_framework.egg-info → agentic_threat_hunting_framework-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.5.1
+Version: 0.7.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>

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0/agentic_threat_hunting_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.5.1
+Version: 0.7.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>

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/agentic_threat_hunting_framework.egg-info/SOURCES.txt

@@ -60,10 +60,10 @@ athf/data/docs/lock-pattern.md
 athf/data/docs/maturity-model.md
 athf/data/docs/why-athf.md
 athf/data/hunts/FORMAT_GUIDELINES.md
-athf/data/hunts/H-0001.md
-athf/data/hunts/H-0002.md
-athf/data/hunts/H-0003.md
 athf/data/hunts/README.md
+athf/data/hunts/production/2026/Q1/H-0001.md
+athf/data/hunts/production/2026/Q1/H-0002.md
+athf/data/hunts/production/2026/Q1/H-0003.md
 athf/data/integrations/MCP_CATALOG.md
 athf/data/integrations/README.md
 athf/data/integrations/quickstart/splunk.md
@@ -72,4 +72,5 @@ athf/data/prompts/README.md
 athf/data/prompts/ai-workflow.md
 athf/data/prompts/basic-prompts.md
 athf/data/templates/HUNT_LOCK.md
-athf/utils/__init__.py
+athf/utils/__init__.py
+athf/utils/validation.py

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/__version__.py

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

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/agents/llm/hunt_researcher.py

@@ -13,7 +13,7 @@ import os
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 from athf.agents.base import AgentResult, LLMAgent
 
@@ -457,7 +457,7 @@ class HuntResearcherAgent(LLMAgent[ResearchInput, ResearchOutput]):
         topic: str,
         sources: List[Dict[str, str]],
         search_results: Optional[Any],
-    ) -> tuple[str, List[str]]:
+    ) -> Tuple[str, List[str]]:
         """Use LLM to summarize system research findings."""
         try:
             client = self._get_llm_client()
@@ -502,7 +502,7 @@ Return JSON format:
         technique: Optional[str],
         sources: List[Dict[str, str]],
         search_results: Optional[Any],
-    ) -> tuple[str, List[str]]:
+    ) -> Tuple[str, List[str]]:
         """Use LLM to summarize adversary tradecraft findings."""
         try:
             client = self._get_llm_client()
@@ -549,7 +549,7 @@ Return JSON format:
         technique: Optional[str],
         ocsf_schema: str,
         environment_data: str,
-    ) -> tuple[str, List[str]]:
+    ) -> Tuple[str, List[str]]:
         """Use LLM to map topic to OCSF telemetry fields."""
         try:
             client = self._get_llm_client()
@@ -590,7 +590,7 @@ Return JSON format:
         topic: str,
         technique: Optional[str],
         skills: List[ResearchSkillOutput],
-    ) -> tuple[str, List[str]]:
+    ) -> Tuple[str, List[str]]:
         """Use LLM to synthesize all research findings."""
         try:
             client = self._get_llm_client()

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/cli.py

@@ -12,6 +12,7 @@ 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
+from athf.plugin_system import PluginRegistry  # noqa: E402
 
 console = Console()
 
@@ -100,8 +101,6 @@ 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)

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/commands/agent.py

@@ -41,9 +41,8 @@ def agent() -> None:
     LLM agents use Claude API for creative and analytical tasks.
 
     \b
-    Agent Execution Modes:
+    Agent Execution Mode:
     • INTERACTIVE (default): Step-by-step execution with user approval
-    • AUTONOMOUS (--auto): Runs all steps without check-ins
     """
     pass
 

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/commands/hunt.py

@@ -15,10 +15,29 @@ from rich.table import Table
 from athf.core.hunt_manager import HuntManager
 from athf.core.hunt_parser import validate_hunt_file
 from athf.core.template_engine import render_hunt_template
+from athf.utils.validation import validate_hunt_id, validate_research_id
 
 console = Console()
 
 
+def get_hunt_directory(is_test: bool = False) -> Path:
+    """Calculate hunt directory based on current date.
+
+    Args:
+        is_test: If True, creates in test/ directory, otherwise production/
+
+    Returns:
+        Path to hunt directory (hunts/{environment}/{YYYY}/{QX}/)
+    """
+    now = datetime.now()
+    year = now.year
+    quarter = f"Q{(now.month - 1) // 3 + 1}"
+
+    environment = "test" if is_test else "production"
+
+    return Path("hunts") / environment / str(year) / quarter
+
+
 def get_config_path() -> Path:
     """Get config file path, checking new location first, then falling back to root."""
     new_location = Path("config/.athfconfig.yaml")
@@ -94,6 +113,7 @@ def hunt() -> None:
 @click.option("--tactic", multiple=True, help="MITRE tactics (can specify multiple)")
 @click.option("--platform", multiple=True, help="Target platforms (can specify multiple)")
 @click.option("--data-source", multiple=True, help="Data sources (can specify multiple)")
+@click.option("--test", is_flag=True, help="Create as test hunt (hunts/test/...) instead of production")
 @click.option("--non-interactive", is_flag=True, help="Skip interactive prompts")
 @click.option("--hypothesis", help="Full hypothesis statement")
 @click.option("--threat-context", help="Threat intel or context motivating the hunt")
@@ -109,6 +129,7 @@ def new(
     tactic: Tuple[str, ...],
     platform: Tuple[str, ...],
     data_source: Tuple[str, ...],
+    test: bool,
     non_interactive: bool,
     hypothesis: Optional[str],
     threat_context: Optional[str],
@@ -171,7 +192,23 @@ def new(
 
     # Validate research document if provided
     if research:
+        # Validate research ID format
+        if not validate_research_id(research):
+            console.print(f"[red]Error: Invalid research ID format: {research}[/red]")
+            console.print("[yellow]Expected format: R-0001[/yellow]")
+            return
+
         research_file = Path("research") / f"{research}.md"
+
+        # Validate path is within research directory
+        try:
+            if not research_file.resolve().is_relative_to(Path("research").resolve()):
+                console.print("[red]Error: Invalid research path[/red]")
+                return
+        except (ValueError, OSError):
+            console.print("[red]Error: Invalid research path[/red]")
+            return
+
         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")
@@ -233,9 +270,19 @@ def new(
         spawned_from=research,
     )
 
-    # Write hunt file
-    hunt_file = Path("hunts") / f"{hunt_id}.md"
-    hunt_file.parent.mkdir(exist_ok=True)
+    # Write hunt file using hierarchical directory structure
+    hunt_dir = get_hunt_directory(is_test=test)
+    hunt_dir.mkdir(parents=True, exist_ok=True)
+    hunt_file = hunt_dir / f"{hunt_id}.md"
+
+    # Validate path is within hunts directory
+    try:
+        if not hunt_file.resolve().is_relative_to(Path("hunts").resolve()):
+            console.print("[red]Error: Invalid hunt file path[/red]")
+            return
+    except (ValueError, OSError):
+        console.print("[red]Error: Invalid hunt file path[/red]")
+        return
 
     with open(hunt_file, "w", encoding="utf-8") as f:
         f.write(hunt_content)
@@ -370,10 +417,31 @@ def validate(hunt_id: str) -> None:
     • Verify hunt files are AI-assistant readable
     """
     if hunt_id:
-        # Validate specific hunt
-        hunt_file = Path("hunts") / f"{hunt_id}.md"
+        # Validate hunt ID format
+        if not validate_hunt_id(hunt_id):
+            console.print(f"[red]Error: Invalid hunt ID format: {hunt_id}[/red]")
+            console.print("[yellow]Expected format: H-0001[/yellow]")
+            return
+
+        # Validate specific hunt - search recursively for backward compatibility
+        hunts_dir = Path("hunts")
+        hunt_file = hunts_dir / f"{hunt_id}.md"
+
+        # If not found in flat structure, search recursively
         if not hunt_file.exists():
-            console.print(f"[red]Hunt not found: {hunt_id}[/red]")
+            matching_files = list(hunts_dir.rglob(f"{hunt_id}.md"))
+            if not matching_files:
+                console.print(f"[red]Hunt not found: {hunt_id}[/red]")
+                return
+            hunt_file = matching_files[0]  # Use first match
+
+        # Validate path is within hunts directory
+        try:
+            if not hunt_file.resolve().is_relative_to(hunts_dir.resolve()):
+                console.print("[red]Error: Invalid hunt file path[/red]")
+                return
+        except (ValueError, OSError):
+            console.print("[red]Error: Invalid hunt file path[/red]")
             return
 
         _validate_single_hunt(hunt_file)
@@ -386,7 +454,7 @@ def validate(hunt_id: str) -> None:
             console.print("[yellow]No hunts directory found.[/yellow]")
             return
 
-        hunt_files = list(hunts_dir.glob("*.md"))
+        hunt_files = list(hunts_dir.rglob("*.md"))
 
         if not hunt_files:
             console.print("[yellow]No hunt files found.[/yellow]")

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/commands/investigate.py

@@ -13,6 +13,7 @@ from rich.prompt import Prompt
 from rich.table import Table
 
 from athf.core.investigation_parser import get_all_investigations, get_next_investigation_id, validate_investigation_file
+from athf.utils.validation import validate_investigation_id
 
 console = Console()
 
@@ -183,6 +184,15 @@ def new(
     # Write investigation file
     investigation_file = investigations_dir / f"{investigation_id}.md"
 
+    # Validate path is within investigations directory
+    try:
+        if not investigation_file.resolve().is_relative_to(investigations_dir.resolve()):
+            console.print("[red]Error: Invalid investigation file path[/red]")
+            return
+    except (ValueError, OSError):
+        console.print("[red]Error: Invalid investigation file path[/red]")
+        return
+
     with open(investigation_file, "w", encoding="utf-8") as f:
         f.write(investigation_content)
 
@@ -542,9 +552,24 @@ def validate(investigation_id: str) -> None:
       # Validate after editing
       athf investigate validate I-0001
     """
+    # Validate investigation ID format
+    if not validate_investigation_id(investigation_id):
+        console.print(f"[red]Error: Invalid investigation ID format: {investigation_id}[/red]")
+        console.print("[yellow]Expected format: I-0001[/yellow]")
+        return
+
     investigations_dir = Path("investigations")
     investigation_file = investigations_dir / f"{investigation_id}.md"
 
+    # Validate path is within investigations directory
+    try:
+        if not investigation_file.resolve().is_relative_to(investigations_dir.resolve()):
+            console.print("[red]Error: Invalid investigation file path[/red]")
+            return
+    except (ValueError, OSError):
+        console.print("[red]Error: Invalid investigation file path[/red]")
+        return
+
     if not investigation_file.exists():
         console.print(f"[red]Error: Investigation file not found: {investigation_file}[/red]")
         return
@@ -606,10 +631,25 @@ def promote(
 
     console.print("\n[bold cyan]🔄 Promoting investigation to hunt[/bold cyan]\n")
 
+    # Validate investigation ID format
+    if not validate_investigation_id(investigation_id):
+        console.print(f"[red]Error: Invalid investigation ID format: {investigation_id}[/red]")
+        console.print("[yellow]Expected format: I-0001[/yellow]")
+        return
+
     # Check investigation file exists
     investigations_dir = Path("investigations")
     investigation_file = investigations_dir / f"{investigation_id}.md"
 
+    # Validate path is within investigations directory
+    try:
+        if not investigation_file.resolve().is_relative_to(investigations_dir.resolve()):
+            console.print("[red]Error: Invalid investigation file path[/red]")
+            return
+    except (ValueError, OSError):
+        console.print("[red]Error: Invalid investigation file path[/red]")
+        return
+
     if not investigation_file.exists():
         console.print(f"[red]Error: Investigation file not found: {investigation_file}[/red]")
         return
@@ -724,18 +764,60 @@ def promote(
     hunts_dir.mkdir(exist_ok=True)
     hunt_file = hunts_dir / f"{hunt_id}.md"
 
+    # Validate path is within hunts directory
+    try:
+        if not hunt_file.resolve().is_relative_to(hunts_dir.resolve()):
+            console.print("[red]Error: Invalid hunt file path[/red]")
+            return
+    except (ValueError, OSError):
+        console.print("[red]Error: Invalid hunt file path[/red]")
+        return
+
     with open(hunt_file, "w", encoding="utf-8") as f:
         f.write(hunt_content)
 
     console.print(f"\n[bold green]✅ Promoted {investigation_id} to {hunt_id}[/bold green]")
 
-    # Update investigation with promotion note
+    # Update investigation's related_hunts field in frontmatter
+    try:
+        # Read the investigation file
+        with open(investigation_file, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        # Split frontmatter and body
+        parts = content.split("---")
+        if len(parts) >= 3:
+            frontmatter_yaml = parts[1]
+            body = "---".join(parts[2:])
+
+            # Parse and update frontmatter
+            frontmatter = yaml.safe_load(frontmatter_yaml)
+            if "related_hunts" not in frontmatter or frontmatter["related_hunts"] is None:
+                frontmatter["related_hunts"] = []
+
+            # Add new hunt ID if not already present
+            if hunt_id not in frontmatter["related_hunts"]:
+                frontmatter["related_hunts"].append(hunt_id)
+
+            # Rebuild file with updated frontmatter
+            updated_yaml = yaml.dump(frontmatter, default_flow_style=False, sort_keys=False)
+            updated_content = f"---\n{updated_yaml}---{body}"
+
+            # Write back to file
+            with open(investigation_file, "w", encoding="utf-8") as f:
+                f.write(updated_content)
+
+            console.print(f"[dim]Updated {investigation_file} with hunt reference in related_hunts[/dim]")
+    except Exception as e:
+        console.print(f"[yellow]Warning: Could not update investigation frontmatter: {e}[/yellow]")
+
+    # Add promotion note to the end of the document
     promotion_note = f"\n\n---\n\n**Promoted to Hunt:** {hunt_id} on {today}\n"
 
     with open(investigation_file, "a", encoding="utf-8") as f:
         f.write(promotion_note)
 
-    console.print(f"[dim]Updated {investigation_file} with promotion note[/dim]")
+    console.print(f"[dim]Added promotion note to {investigation_file}[/dim]")
 
     console.print("\n[bold]Next steps:[/bold]")
     console.print(f"  1. Edit [cyan]{hunt_file}[/cyan] to refine hunt hypothesis")

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/core/hunt_manager.py

@@ -6,6 +6,7 @@ from typing import Any, Dict, List, Optional, Set
 
 from athf.core.attack_matrix import ATTACK_TACTICS, TOTAL_TECHNIQUES, get_sorted_tactics
 from athf.core.hunt_parser import parse_hunt_file
+from athf.utils.validation import validate_hunt_id
 
 
 class HuntManager:
@@ -42,8 +43,8 @@ class HuntManager:
         """
         hunts = []
 
-        # Find all hunt files
-        hunt_files = sorted(self.hunts_dir.glob("*.md"))
+        # Find all hunt files recursively (supports both flat and hierarchical structure)
+        hunt_files = sorted(self.hunts_dir.rglob("*.md"))
 
         for hunt_file in hunt_files:
             try:
@@ -102,9 +103,26 @@ class HuntManager:
         Returns:
             Hunt data dict or None if not found
         """
+        # Validate hunt ID format and prevent path traversal
+        if not validate_hunt_id(hunt_id):
+            return None
+
+        # First try flat structure for backward compatibility
         hunt_file = self.hunts_dir / f"{hunt_id}.md"
 
+        # If not found in flat structure, search recursively
         if not hunt_file.exists():
+            # Search recursively for the hunt file
+            matching_files = list(self.hunts_dir.rglob(f"{hunt_id}.md"))
+            if not matching_files:
+                return None
+            hunt_file = matching_files[0]  # Use first match
+
+        # Validate path is within hunts directory
+        try:
+            if not hunt_file.resolve().is_relative_to(self.hunts_dir.resolve()):
+                return None
+        except (ValueError, OSError):
             return None
 
         return parse_hunt_file(hunt_file)
@@ -157,7 +175,7 @@ class HuntManager:
         # Exclude documentation files
         exclude_files = {"README.md", "FORMAT_GUIDELINES.md"}
 
-        for hunt_file in self.hunts_dir.glob("*.md"):
+        for hunt_file in self.hunts_dir.rglob("*.md"):
             # Skip documentation files
             if hunt_file.name in exclude_files:
                 continue

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/core/research_manager.py

@@ -7,6 +7,8 @@ from typing import Any, Dict, List, Optional
 
 import yaml
 
+from athf.utils.validation import validate_research_id
+
 
 class ResearchParser:
     """Parser for research files (YAML frontmatter + markdown)."""
@@ -240,15 +242,34 @@ class ResearchManager:
         Returns:
             Research data dict or None if not found
         """
+        # Validate research ID format and prevent path traversal
+        if not validate_research_id(research_id):
+            return None
+
         # Try direct file
         research_file = self.research_dir / f"{research_id}.md"
+
+        # Validate path is within research directory
+        try:
+            if not research_file.resolve().is_relative_to(self.research_dir.resolve()):
+                return None
+        except (ValueError, OSError):
+            return None
+
         if research_file.exists():
             return parse_research_file(research_file)
 
         # Try nested search
         research_files = list(self.research_dir.rglob(f"{research_id}.md"))
         if research_files:
-            return parse_research_file(research_files[0])
+            # Validate nested file is also within research directory
+            nested_file = research_files[0]
+            try:
+                if not nested_file.resolve().is_relative_to(self.research_dir.resolve()):
+                    return None
+            except (ValueError, OSError):
+                return None
+            return parse_research_file(nested_file)
 
         return None
 
@@ -368,6 +389,14 @@ class ResearchManager:
 
         # Write file
         file_path = self.research_dir / f"{research_id}.md"
+
+        # Validate path is within research directory
+        try:
+            if not file_path.resolve().is_relative_to(self.research_dir.resolve()):
+                raise ValueError("Invalid research file path")
+        except (ValueError, OSError) as e:
+            raise ValueError(f"Invalid research file path: {e}") from e
+
         with open(file_path, "w", encoding="utf-8") as f:
             f.write(file_content)
 

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/data/docs/INSTALL.md

@@ -572,7 +572,7 @@ After installation:
 2. **Read the getting started guide**: [getting-started.md](getting-started.md)
 3. **Review the CLI reference**: [CLI_REFERENCE.md](CLI_REFERENCE.md)
 4. **Create your first hunt**: `athf hunt new`
-5. **Explore example hunts**: [../hunts/H-0001.md](../hunts/H-0001.md)
+5. **Explore example hunts**: [../hunts/production/2026/Q1/H-0001.md](../hunts/production/2026/Q1/H-0001.md)
 
 ---
 

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/data/docs/getting-started.md

@@ -120,7 +120,7 @@ athf hunt list
 
 ### Example Structure
 
-See [hunts/H-0001.md](../hunts/H-0001.md) for a complete example. Here's a simplified structure:
+See [hunts/H-0001.md](../hunts/production/2026/Q1/H-0001.md) for a complete example. Here's a simplified structure:
 
 ```markdown
 # H-0001: SSH Brute Force Detection

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/data/docs/lock-pattern.md

@@ -104,9 +104,9 @@ Next iteration: expand to include remote registry and PSExec telemetry for broad
 ```
 
 **See full hunt examples:**
-- [H-0001: macOS Information Stealer Detection](../hunts/H-0001.md) - Complete hunt with YAML frontmatter, detailed LOCK sections, query evolution, and results
-- [H-0002: Linux Crontab Persistence Detection](../hunts/H-0002.md) - Multi-query approach with behavioral analysis
-- [H-0003: AWS Lambda Persistence Detection](../hunts/H-0003.md) - Cloud hunting with CloudTrail correlation
+- [H-0001: macOS Information Stealer Detection](../hunts/production/2026/Q1/H-0001.md) - Complete hunt with YAML frontmatter, detailed LOCK sections, query evolution, and results
+- [H-0002: Linux Crontab Persistence Detection](../hunts/production/2026/Q1/H-0002.md) - Multi-query approach with behavioral analysis
+- [H-0003: AWS Lambda Persistence Detection](../hunts/production/2026/Q1/H-0003.md) - Cloud hunting with CloudTrail correlation
 - [Hunt Showcase](../../../SHOWCASE.md) - Side-by-side comparison of all three hunts
 
 ## Best Practices

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/data/hunts/FORMAT_GUIDELINES.md

@@ -504,4 +504,4 @@ The result is a condensed, practical template that guides hunters from hypothesi
 
 ## Example Reference
 
-See [H-0001.md](H-0001.md), [H-0002.md](H-0002.md), and [H-0003.md](H-0003.md) for complete hunt examples.
+See [H-0001.md](production/2026/Q1/H-0001.md), [H-0002.md](production/2026/Q1/H-0002.md), and [H-0003.md](production/2026/Q1/H-0003.md) for complete hunt examples.

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/data/hunts/README.md

@@ -225,7 +225,7 @@ Claude:
 
 ## Example Hunts
 
-- [H-0001.md](H-0001.md) - macOS Data Collection via AppleScript Detection (T1005, T1059.002, T1555.003)
-- [H-0002.md](H-0002.md) - Linux Crontab Persistence Detection (T1053.003)
-- [H-0003.md](H-0003.md) - AWS Lambda Persistence Detection (T1546.004, T1098)
+- [H-0001.md](production/2026/Q1/H-0001.md) - macOS Data Collection via AppleScript Detection (T1005, T1059.002, T1555.003)
+- [H-0002.md](production/2026/Q1/H-0002.md) - Linux Crontab Persistence Detection (T1053.003)
+- [H-0003.md](production/2026/Q1/H-0003.md) - AWS Lambda Persistence Detection (T1546.004, T1098)
 - [FORMAT_GUIDELINES.md](FORMAT_GUIDELINES.md) - Template structure reference

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/data/prompts/README.md

@@ -142,7 +142,7 @@ AI: [Searches hunts/, reads environment.md, generates context-aware hypothesis]
 
 ### After Level 2 Workflows
 
-1. See real examples in [hunts/H-0001.md](../hunts/H-0001.md) and [hunts/H-0002.md](../hunts/H-0002.md)
+1. See real examples in [hunts/H-0001.md](../hunts/production/2026/Q1/H-0001.md) and [hunts/H-0002.md](../hunts/production/2026/Q1/H-0002.md)
 2. Review format guidelines in [hunts/FORMAT_GUIDELINES.md](../hunts/FORMAT_GUIDELINES.md)
 3. Consider Level 3 (MCP integrations) in [integrations/](../integrations/)
 

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/data/prompts/ai-workflow.md

@@ -575,7 +575,7 @@ Before finalizing any AI-generated content:
 
 - **Basic Prompts:** [basic-prompts.md](basic-prompts.md) for Level 0-1
 - **Hunt Template:** [../templates/HUNT_LOCK.md](../templates/HUNT_LOCK.md)
-- **Real Examples:** [../hunts/H-0001.md](../hunts/H-0001.md), [../hunts/H-0002.md](../hunts/H-0002.md)
+- **Real Examples:** [../hunts/H-0001.md](../hunts/production/2026/Q1/H-0001.md), [../hunts/H-0002.md](../hunts/production/2026/Q1/H-0002.md)
 - **Repository Context:** [AGENTS.md](../../../AGENTS.md)
 
 **Remember: AI augments, doesn't replace. Always validate, always learn, always improve.**

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/athf/data/prompts/basic-prompts.md

@@ -302,7 +302,7 @@ Once you're comfortable with these basic prompts:
 
 1. **Build your hunt repository** - Document hunts using [templates/HUNT_LOCK.md](../templates/HUNT_LOCK.md)
 2. **Progress to Level 2** - Use [ai-workflow.md](ai-workflow.md) for AI tools with repository access
-3. **See real examples** - Review [H-0001.md](../hunts/H-0001.md) and [H-0002.md](../hunts/H-0002.md)
+3. **See real examples** - Review [H-0001.md](../hunts/production/2026/Q1/H-0001.md) and [H-0002.md](../hunts/production/2026/Q1/H-0002.md)
 
 ---
 

agentic_threat_hunting_framework-0.7.0/athf/plugin_system.py

@@ -0,0 +1,72 @@
+"""Plugin system for ATHF extensions."""
+
+import sys
+from typing import Any, Dict, Optional, Type
+
+from click import Command
+
+# Handle importlib.metadata API changes across Python versions
+if sys.version_info >= (3, 10):
+    from importlib.metadata import entry_points
+else:
+    # Python 3.8-3.9: use importlib_metadata backport API
+    try:
+        from importlib.metadata import entry_points
+    except ImportError:
+        from importlib_metadata import entry_points  # type: ignore
+
+
+class PluginRegistry:
+    """Central registry for ATHF plugins."""
+
+    _agents: Dict[str, Type[Any]] = {}
+    _commands: Dict[str, Command] = {}
+
+    @classmethod
+    def register_agent(cls, name: str, agent_class: Type[Any]) -> 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) -> Optional[Type[Any]]:
+        """Get registered agent by name."""
+        return cls._agents.get(name)
+
+    @classmethod
+    def get_command(cls, name: str) -> Optional[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:
+            # Python 3.10+ uses group= parameter, 3.8-3.9 uses dict-like access
+            if sys.version_info >= (3, 10):
+                eps = entry_points(group="athf.commands")
+            else:
+                eps = entry_points().get("athf.commands", [])
+
+            for ep in eps:
+                command = ep.load()
+                cls.register_command(ep.name, command)
+        except Exception:
+            pass  # No plugins installed yet
+
+        try:
+            # Python 3.10+ uses group= parameter, 3.8-3.9 uses dict-like access
+            if sys.version_info >= (3, 10):
+                eps = entry_points(group="athf.agents")
+            else:
+                eps = entry_points().get("athf.agents", [])
+
+            for ep in eps:
+                agent = ep.load()
+                cls.register_agent(ep.name, agent)
+        except Exception:
+            pass  # No plugins installed yet

agentic_threat_hunting_framework-0.7.0/athf/utils/validation.py

@@ -0,0 +1,170 @@
+"""Input validation utilities to prevent path traversal and injection attacks."""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+
+def validate_hunt_id(hunt_id: str) -> bool:
+    """Validate hunt ID format and prevent path traversal.
+
+    Args:
+        hunt_id: Hunt ID to validate (e.g., H-0001)
+
+    Returns:
+        True if valid, False otherwise
+
+    Examples:
+        >>> validate_hunt_id("H-0001")
+        True
+        >>> validate_hunt_id("H-9999")
+        True
+        >>> validate_hunt_id("../../etc/passwd")
+        False
+        >>> validate_hunt_id("H-0001/../secrets.txt")
+        False
+    """
+    if not hunt_id or not isinstance(hunt_id, str):
+        return False
+
+    # Check format: single letter(s) + dash + 4 digits
+    if not re.match(r"^[A-Z]+-\d{4}$", hunt_id):
+        return False
+
+    # Prevent path traversal
+    if ".." in hunt_id or "/" in hunt_id or "\\" in hunt_id:
+        return False
+
+    return True
+
+
+def validate_investigation_id(investigation_id: str) -> bool:
+    """Validate investigation ID format and prevent path traversal.
+
+    Args:
+        investigation_id: Investigation ID to validate (e.g., I-0001)
+
+    Returns:
+        True if valid, False otherwise
+
+    Examples:
+        >>> validate_investigation_id("I-0001")
+        True
+        >>> validate_investigation_id("../../../secrets")
+        False
+    """
+    if not investigation_id or not isinstance(investigation_id, str):
+        return False
+
+    # Check format: single letter + dash + 4 digits
+    if not re.match(r"^[A-Z]+-\d{4}$", investigation_id):
+        return False
+
+    # Prevent path traversal
+    if ".." in investigation_id or "/" in investigation_id or "\\" in investigation_id:
+        return False
+
+    return True
+
+
+def validate_research_id(research_id: str) -> bool:
+    """Validate research ID format and prevent path traversal.
+
+    Args:
+        research_id: Research ID to validate (e.g., R-0001)
+
+    Returns:
+        True if valid, False otherwise
+
+    Examples:
+        >>> validate_research_id("R-0001")
+        True
+        >>> validate_research_id("R-0001/../../secrets")
+        False
+    """
+    if not research_id or not isinstance(research_id, str):
+        return False
+
+    # Check format: single letter + dash + 4 digits
+    if not re.match(r"^[A-Z]+-\d{4}$", research_id):
+        return False
+
+    # Prevent path traversal
+    if ".." in research_id or "/" in research_id or "\\" in research_id:
+        return False
+
+    return True
+
+
+def validate_file_path(file_path: Path, base_dir: Path) -> bool:
+    """Validate that resolved file path is within base directory.
+
+    Args:
+        file_path: File path to validate
+        base_dir: Base directory that file must be within
+
+    Returns:
+        True if file is within base directory, False otherwise
+
+    Examples:
+        >>> base = Path("/app/hunts")
+        >>> validate_file_path(Path("/app/hunts/H-0001.md"), base)
+        True
+        >>> validate_file_path(Path("/etc/passwd"), base)
+        False
+    """
+    try:
+        # Resolve to absolute paths
+        resolved_file = file_path.resolve()
+        resolved_base = base_dir.resolve()
+
+        # Check if file is relative to base directory
+        return resolved_file.is_relative_to(resolved_base)
+    except (ValueError, OSError):
+        return False
+
+
+def safe_path_join(base_dir: Path, id_value: str, extension: str = ".md") -> Optional[Path]:
+    """Safely join base directory with ID to create file path.
+
+    Validates ID format and ensures resulting path is within base directory.
+
+    Args:
+        base_dir: Base directory (e.g., Path("hunts"))
+        id_value: ID value (e.g., "H-0001")
+        extension: File extension (default: .md)
+
+    Returns:
+        Validated Path object or None if validation fails
+
+    Examples:
+        >>> safe_path_join(Path("hunts"), "H-0001")
+        Path('hunts/H-0001.md')
+        >>> safe_path_join(Path("hunts"), "../../etc/passwd")
+        None
+    """
+    # Validate ID format based on first letter
+    if id_value.startswith("H-"):
+        if not validate_hunt_id(id_value):
+            return None
+    elif id_value.startswith("I-"):
+        if not validate_investigation_id(id_value):
+            return None
+    elif id_value.startswith("R-"):
+        if not validate_research_id(id_value):
+            return None
+    else:
+        # Unknown prefix - validate generic format
+        if not re.match(r"^[A-Z]+-\d{4}$", id_value):
+            return None
+        if ".." in id_value or "/" in id_value or "\\" in id_value:
+            return None
+
+    # Construct path
+    file_path = base_dir / f"{id_value}{extension}"
+
+    # Validate path is within base directory
+    if not validate_file_path(file_path, base_dir):
+        return None
+
+    return file_path

{agentic_threat_hunting_framework-0.5.1 → agentic_threat_hunting_framework-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-threat-hunting-framework"
-version = "0.5.1"
+version = "0.7.0"
 description = "Agentic Threat Hunting Framework - Memory and AI for threat hunters"
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.8"

agentic_threat_hunting_framework-0.5.1/athf/plugin_system.py

@@ -1,48 +0,0 @@
-"""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