agentic-threat-hunting-framework 0.5.2__py3-none-any.whl → 0.7.0__py3-none-any.whl

{agentic_threat_hunting_framework-0.5.2.dist-info → agentic_threat_hunting_framework-0.7.0.dist-info}/METADATA

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

@@ -1,59 +1,60 @@
-agentic_threat_hunting_framework-0.5.2.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
+agentic_threat_hunting_framework-0.7.0.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
 athf/__init__.py,sha256=OrjZe8P97_BTEkscapnwSsqKSjwXNP9d8-HtGr19Ni0,241
-athf/__version__.py,sha256=wCIQoU9b7qKcSNQiIOgHaD2buzBC-dlQYtvg8X5WS4A,59
-athf/cli.py,sha256=108PnDRlaytJj9KzjzcTLljB3DeerMIXZOeAQJrmtPU,5052
-athf/plugin_system.py,sha256=eS_P56IAZQEtyefQkp-x2J-8pxKcZX_394-WoCY7M3U,2323
+athf/__version__.py,sha256=F90ZPthTNEvn7TDS840_bjxhiK6dF6YhliP-VF4Wj98,59
+athf/cli.py,sha256=xbbgqAzwyb1ygWnn0lgmUOuO2H-vAYczgD20TdFFOiQ,5065
+athf/plugin_system.py,sha256=QoXSFPPFDqdSE46d5gHhvgaUDU2Ym0Dq6C1BJHOqEWs,2325
 athf/agents/__init__.py,sha256=iaSJpvnXm9rz4QS7gBrsaLEjm49uvsMs4BLPOJeyp78,346
 athf/agents/base.py,sha256=ZLqSW6I0pKqs1Z3OIoV8urkysMRzNDs52yNIxDgQjTU,3981
 athf/agents/llm/__init__.py,sha256=qSGA-NaInjsDkMpGQwnTz3S1OgCVlzetpMcDS_to1co,671
-athf/agents/llm/hunt_researcher.py,sha256=dIyD2Izh3zdf62kCHug1DwXFgmWhOMQUTim7qM3UAIs,27071
+athf/agents/llm/hunt_researcher.py,sha256=Eb4BQZxxTTln07Wicgs1YhPi5Me-MjV0FErDRWysKDY,27078
 athf/agents/llm/hypothesis_generator.py,sha256=XkbJz8IS4zwQjEy-ZD0zy2XW5uRnAy87Lii-5XTY0WU,8564
 athf/commands/__init__.py,sha256=-ZOfg6uV1eSh7RDW7dKzdufuYvQTT0KGMF4JB6waHsY,635
-athf/commands/agent.py,sha256=c7ZeZa3OArXyXTgVjmUB2JXa3m9IpLFJ_FEVDhaDLE8,19000
+athf/commands/agent.py,sha256=c4mIZQaB2Gf7EHYEWrlHHX4W_bNg35UfBxPFw5WSEhc,18937
 athf/commands/context.py,sha256=V-at81-OgKcLY-In48-AccTnHfTgdofmnjE8S5kypoI,12678
 athf/commands/env.py,sha256=JPKRsv48cgsIAjSFaGJ1-Nu0nQKGSVg4AbiFxb9jVX4,11887
-athf/commands/hunt.py,sha256=aQdgNddqy_VrxZOkxhuPxIr4KLZtX5a2ZLb9079vLlw,25169
+athf/commands/hunt.py,sha256=a9dbXFNTKR65tC5CdtTlBbEe-AqbmrcAMnoaBpMBPuY,27845
 athf/commands/init.py,sha256=Qn0iETNyuQvM-ySqCeoDz-pPemeuzROX_karQF5yN_o,12685
-athf/commands/investigate.py,sha256=mK_id5vjfN_ukqB_-fyia0FNa0pBmtn0Xv6CKHQI1Qo,24663
+athf/commands/investigate.py,sha256=g4GKbvRglhM444IcSPabqu76nJ6IGxCFR_px_kg7Uac,28135
 athf/commands/research.py,sha256=FrLph4agaGQ_rIxMh0OQwh1MIGDFtj40zJ3E1ZFwaAw,18112
 athf/commands/similar.py,sha256=FTTVr4zzP9bdJrirscp6pOxdQbE8zot6pa20-_TYiuo,11804
 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_manager.py,sha256=PA7uDW69weMgCosN5a8GMlVgg9zRWfD9k33mdnE7R4w,12403
 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/research_manager.py,sha256=rwhAyaqtBbs6lgQeHS03ZMXzLNOSiVdNII3pX2gvtUE,15600
 athf/core/splunk_client.py,sha256=Xib2zVwV2l8eChzqUahI3PZ7Z2XS2wz01sPbF1E0Q18,11611
 athf/core/template_engine.py,sha256=Awp0n9E5Q1dYA35XDKKAd5VJLdpaDl2N967hackUVa8,6010
 athf/core/web_search.py,sha256=B9IhmwH7gy2RVA6WSN3L7yGp3Q4L8OsiiwcEvnnZejU,10320
 athf/data/__init__.py,sha256=QtgONloCaS3E9Ow995FMxyy6BbszpfmYeWpySQ2b9Mc,502
 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/INSTALL.md,sha256=6-cTDf1AO_KQ84sqhO2DcRr96OGk3Wc6ywsWECBHEV8,13155
 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=dUCpXHzucRLfUYzDylvnCtdqv9VCukfQCtGg7hTGmrI,15316
+athf/data/docs/getting-started.md,sha256=WPYwRS7Jxhp1yBpbYh4LpAdi3-3ZdcyjZFl3BOFufWg,15335
 athf/data/docs/level4-agentic-workflows.md,sha256=68crKsDaLyrgxVG37nPIuJyO9NobLi09Obv7D1AnpYs,14123
-athf/data/docs/lock-pattern.md,sha256=eICjNh5SAgIhkOYBDhHg1tgw4A29xgnRDWC9vH1wLEQ,4863
+athf/data/docs/lock-pattern.md,sha256=S-T-LGMtuR7X-nRSsCVURtQ-tUhaX7TWFKOrqbQ1Y7A,4920
 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
-athf/data/hunts/H-0002.md,sha256=yF5ZEfl7NAJJMjuVf9ZitafwDfWMTzyU5fgkrAQ4U6I,20405
-athf/data/hunts/H-0003.md,sha256=w0iAaplcM0kFWRmVhQsX53LVIWaRDJsB3TWalI1zz_o,27436
-athf/data/hunts/README.md,sha256=WMj871_NTsMjYBriQ3xezOBktUs3KT7MTKVJSo0iwXA,5812
+athf/data/hunts/FORMAT_GUIDELINES.md,sha256=Q1kje_-nMhXpFFWS7uSVYIyoP_AnR86FRcgjFrfcWO8,15067
+athf/data/hunts/README.md,sha256=NGEjIMTURPyRJnTqT_BKmBeY0NWZn63erowV2Oj3FzM,5869
+athf/data/hunts/production/2026/Q1/H-0001.md,sha256=rdUIpQ_uN8bx7XS1ED85rW5aRKxFOpMg0X7PANY7eCY,23220
+athf/data/hunts/production/2026/Q1/H-0002.md,sha256=yF5ZEfl7NAJJMjuVf9ZitafwDfWMTzyU5fgkrAQ4U6I,20405
+athf/data/hunts/production/2026/Q1/H-0003.md,sha256=w0iAaplcM0kFWRmVhQsX53LVIWaRDJsB3TWalI1zz_o,27436
 athf/data/integrations/MCP_CATALOG.md,sha256=hJ_cyHijEjWdkFiX7WEyBtJqlLtKuRzZCKlqrhbSLrU,1782
 athf/data/integrations/README.md,sha256=jkiK0u5pNjodmFuNKKMR0G40Soq8pqBRVsaP89wP70w,4336
 athf/data/integrations/quickstart/splunk.md,sha256=6REsD05zQOPcT6ezxyeysOtTRsSp7JO6vK_epd7GCJU,4897
 athf/data/knowledge/hunting-knowledge.md,sha256=djublWCzFexl5ssssL6KfMm4RnUI0ANoWMY9zLSQDd0,91107
-athf/data/prompts/README.md,sha256=5Jtz38Csh-rWjgX_zN46e3DxJoOfeeVQLDcIpcVExJ0,5029
-athf/data/prompts/ai-workflow.md,sha256=rZtOcGuAEi35qx7182TwHJEORdz1-RxkZMBVkg611Rs,17087
-athf/data/prompts/basic-prompts.md,sha256=2bunpO35RoBdJWYthXVi40RNl2UWrfwOaFthBLHF5sU,8463
+athf/data/prompts/README.md,sha256=bQetg4OxuyI-UZJTOlrMjyjzGXgL5H1Sion7xyXOa80,5067
+athf/data/prompts/ai-workflow.md,sha256=8bpITJeeOx6zv1sIlPtulC2DMZ4m-eSHvbgElifY9u8,17125
+athf/data/prompts/basic-prompts.md,sha256=eX1eM_lWph3fNZgH2aPaLBZZntbAl9XpSeO53RqW6Ws,8501
 athf/data/templates/HUNT_LOCK.md,sha256=zXxHaKMWbRDLewLTegYJMbXRM72s9gFFvjdwFfGNeJE,7386
 athf/utils/__init__.py,sha256=aEAPI1xnAsowOtc036cCb9ZOek5nrrfevu8PElhbNgk,30
-agentic_threat_hunting_framework-0.5.2.dist-info/METADATA,sha256=YfuSvYBFEkY6HIsnVOIuC7Yjx16mCRvycZHfXAwSZIA,15949
-agentic_threat_hunting_framework-0.5.2.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-agentic_threat_hunting_framework-0.5.2.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
-agentic_threat_hunting_framework-0.5.2.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
-agentic_threat_hunting_framework-0.5.2.dist-info/RECORD,,
+athf/utils/validation.py,sha256=j1efs0RsNT0YsI9-ttOgImkBAMQ_is84WNXbVu5SPL8,4789
+agentic_threat_hunting_framework-0.7.0.dist-info/METADATA,sha256=39SV82zgEtWOD8WeqcKsWLCRQDLlpqJICcxq4rrwP_0,15949
+agentic_threat_hunting_framework-0.7.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+agentic_threat_hunting_framework-0.7.0.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
+agentic_threat_hunting_framework-0.7.0.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
+agentic_threat_hunting_framework-0.7.0.dist-info/RECORD,,

{agentic_threat_hunting_framework-0.5.2.dist-info → agentic_threat_hunting_framework-0.7.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.10.1)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

athf/__version__.py

@@ -1,3 +1,3 @@
 """Version information for ATHF."""
 
-__version__ = "0.4.0"
+__version__ = "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()

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)

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
 

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]")

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")

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

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)
 

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)
 
 ---
 

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

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

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.

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

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/)
 

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.**

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)
 
 ---
 

athf/plugin_system.py

@@ -1,6 +1,8 @@
 """Plugin system for ATHF extensions."""
-from typing import Any, Dict, Optional, Type
+
 import sys
+from typing import Any, Dict, Optional, Type
+
 from click import Command
 
 # Handle importlib.metadata API changes across Python versions
@@ -46,9 +48,9 @@ class PluginRegistry:
         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')
+                eps = entry_points(group="athf.commands")
             else:
-                eps = entry_points().get('athf.commands', [])
+                eps = entry_points().get("athf.commands", [])
 
             for ep in eps:
                 command = ep.load()
@@ -59,9 +61,9 @@ class PluginRegistry:
         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')
+                eps = entry_points(group="athf.agents")
             else:
-                eps = entry_points().get('athf.agents', [])
+                eps = entry_points().get("athf.agents", [])
 
             for ep in eps:
                 agent = ep.load()

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