agentic-threat-hunting-framework 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

{agentic_threat_hunting_framework-0.1.0.dist-info → agentic_threat_hunting_framework-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.1.0
+Version: 0.2.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>
@@ -46,30 +46,23 @@ Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
 Provides-Extra: docs
 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"
 Dynamic: license-file
 
-<p align="center">
-  <img src="assets/athf_logo.png" alt="ATHF Logo" width="400"/>
-</p>
+# Agentic Threat Hunting Framework (ATHF)
 
-<h1 align="center">Agentic Threat Hunting Framework (ATHF)</h1>
+![ATHF Logo](https://raw.githubusercontent.com/Nebulock-Inc/agentic-threat-hunting-framework/main/assets/athf_logo.png)
 
-<p align="center">
-  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8%2B-blue" alt="Python Version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
-  <a href="https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/stargazers"><img src="https://img.shields.io/github/stars/Nebulock-Inc/agentic-threat-hunting-framework?style=social" alt="GitHub stars"></a>
-</p>
+[![PyPI version](https://img.shields.io/pypi/v/agentic-threat-hunting-framework)](https://pypi.org/project/agentic-threat-hunting-framework/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/agentic-threat-hunting-framework)](https://pypi.org/project/agentic-threat-hunting-framework/)
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/Nebulock-Inc/agentic-threat-hunting-framework?style=social)](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/stargazers)
 
-<p align="center">
-  <strong><a href="#-quick-start">Quick Start</a></strong> •
-  <strong><a href="#installation">Installation</a></strong> •
-  <strong><a href="#documentation">Documentation</a></strong> •
-  <strong><a href="SHOWCASE.md">Examples</a></strong>
-</p>
+**[Quick Start](#-quick-start)** • **[Installation](#installation)** • **[Documentation](#documentation)** • **[Examples](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
 
-<p align="center">
-  <em>Give your threat hunting program memory and agency.</em>
-</p>
+*Give your threat hunting program memory and agency.*
 
 The **Agentic Threat Hunting Framework (ATHF)** is the memory and automation layer for your threat hunting program. It gives your hunts structure, persistence, and context - making every past investigation accessible to both humans and AI.
 
@@ -92,13 +85,13 @@ Even AI tools start from zero every time without access to your environment, you
 
 ATHF changes that by giving your hunts structure, persistence, and context.
 
-**Read more:** [docs/why-athf.md](docs/why-athf.md)
+**Read more:** [docs/why-athf.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md)
 
 ## The LOCK Pattern
 
 Every threat hunt follows the same basic loop: **Learn → Observe → Check → Keep**.
 
-![The LOCK Pattern](assets/athf_lock.png)
+![The LOCK Pattern](https://raw.githubusercontent.com/Nebulock-Inc/agentic-threat-hunting-framework/main/assets/athf_lock.png)
 
 - **Learn:** Gather context from threat intel, alerts, or anomalies
 - **Observe:** Form a hypothesis about adversary behavior
@@ -107,7 +100,7 @@ Every threat hunt follows the same basic loop: **Learn → Observe → Check →
 
 **Why LOCK?** It's small enough to use and strict enough for agents to interpret. By capturing every hunt in this format, ATHF makes it possible for AI assistants to recall prior work and suggest refined queries based on past results.
 
-**Read more:** [docs/lock-pattern.md](docs/lock-pattern.md)
+**Read more:** [docs/lock-pattern.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md)
 
 ## The Five Levels of Agentic Hunting
 
@@ -115,7 +108,7 @@ ATHF defines a simple maturity model. Each level builds on the previous one.
 
 **Most teams will live at Levels 1–2. Everything beyond that is optional maturity.**
 
-![The Five Levels](assets/athf_fivelevels.png)
+![The Five Levels](https://raw.githubusercontent.com/Nebulock-Inc/agentic-threat-hunting-framework/main/assets/athf_fivelevels.png)
 
 | Level | Capability | What You Get |
 |-------|-----------|--------------|
@@ -130,17 +123,15 @@ ATHF defines a simple maturity model. Each level builds on the previous one.
 **Level 3:** 2-4 weeks (optional)
 **Level 4:** 1-3 months (optional)
 
-**Read more:** [docs/maturity-model.md](docs/maturity-model.md)
+**Read more:** [docs/maturity-model.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md)
 
 ## 🚀 Quick Start
 
-### Option 1: Python CLI (Recommended)
+### Option 1: Install from PyPI (Recommended)
 
 ```bash
-# Clone and install from source
-git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
-cd agentic-threat-hunting-framework
-pip install -e .
+# Install ATHF
+pip install agentic-threat-hunting-framework
 
 # Initialize your hunt program
 athf init
@@ -149,7 +140,20 @@ athf init
 athf hunt new --technique T1003.001 --title "LSASS Credential Dumping"
 ```
 
-### Option 2: Pure Markdown (No Installation)
+### Option 2: Install from Source (Development)
+
+```bash
+# Clone and install from source
+git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
+cd agentic-threat-hunting-framework
+pip install -e .
+
+# Initialize and start hunting
+athf init
+athf hunt new --technique T1003.001
+```
+
+### Option 3: Pure Markdown (No Installation)
 
 ```bash
 # Clone the repository
@@ -165,7 +169,7 @@ cp templates/HUNT_LOCK.md hunts/H-0001.md
 
 **Choose your AI assistant:** Claude Code, GitHub Copilot, or Cursor - any tool that can read your repository files.
 
-**Full guide:** [docs/getting-started.md](docs/getting-started.md)
+**Full guide:** [docs/getting-started.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md)
 
 ## 🔧 CLI Commands
 
@@ -206,32 +210,39 @@ athf hunt stats                     # Show statistics
 athf hunt coverage                  # MITRE ATT&CK coverage
 ```
 
-**Full documentation:** [CLI Reference](docs/CLI_REFERENCE.md)
+**Full documentation:** [CLI Reference](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
 
 ## 📺 See It In Action
 
-![ATHF Demo](assets/athf-cli-workflow.gif)
+![ATHF Demo](https://raw.githubusercontent.com/Nebulock-Inc/agentic-threat-hunting-framework/main/assets/athf-cli-workflow.gif)
 
 Watch ATHF in action: initialize a workspace, create hunts, and explore your threat hunting catalog in under 60 seconds.
 
-**[View example hunts →](SHOWCASE.md)**
+**[View example hunts →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
 
 ## Installation
 
 ### Prerequisites
 - Python 3.8-3.13 (for CLI option)
-- Git
 - Your favorite AI code assistant
 
-### CLI Installation
+### From PyPI (Recommended)
+
+```bash
+pip install agentic-threat-hunting-framework
+athf init
+```
+
+### From Source (Development)
 
 ```bash
 git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
 cd agentic-threat-hunting-framework
 pip install -e .
+athf init
 ```
 
-### Markdown-Only Setup (No CLI)
+### Markdown-Only Setup (No Installation)
 
 ```bash
 git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
@@ -244,24 +255,24 @@ Start documenting hunts in the `hunts/` directory using the LOCK pattern.
 
 ### Core Concepts
 
-- [Why ATHF Exists](docs/why-athf.md) - The problem and solution
-- [The LOCK Pattern](docs/lock-pattern.md) - Structure for all hunts
-- [Maturity Model](docs/maturity-model.md) - The five levels explained
-- [Getting Started](docs/getting-started.md) - Step-by-step onboarding
+- [Why ATHF Exists](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md) - The problem and solution
+- [The LOCK Pattern](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md) - Structure for all hunts
+- [Maturity Model](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md) - The five levels explained
+- [Getting Started](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md) - Step-by-step onboarding
 
 ### Level-Specific Guides
 
-- [Level 1: Documented Hunts](docs/maturity-model.md#level-1-documented-hunts)
-- [Level 2: Searchable Memory](docs/maturity-model.md#level-2-searchable-memory)
-- [Level 3: Generative Capabilities](docs/level4-agentic-workflows.md)
-- [Level 4: Agentic Workflows](docs/level4-agentic-workflows.md)
+- [Level 1: Documented Hunts](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-1-documented-hunts)
+- [Level 2: Searchable Memory](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-2-searchable-memory)
+- [Level 3: Generative Capabilities](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
+- [Level 4: Agentic Workflows](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
 
 ### Integration & Customization
 
-- [Installation & Development](docs/INSTALL.md) - Setup, fork customization, testing
-- [MCP Catalog](integrations/MCP_CATALOG.md) - Available tool integrations
-- [Quickstart Guides](integrations/quickstart/) - Setup for specific tools
-- [Using ATHF](USING_ATHF.md) - Adoption and customization
+- [Installation & Development](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md) - Setup, fork customization, testing
+- [MCP Catalog](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/integrations/MCP_CATALOG.md) - Available tool integrations
+- [Quickstart Guides](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/tree/main/integrations/quickstart/) - Setup for specific tools
+- [Using ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) - Adoption and customization
 
 ## 🎖️ Featured Hunts
 
@@ -272,7 +283,7 @@ Detected Atomic Stealer collecting Safari cookies via AppleScript.
 
 **Key Insight:** Behavior-based detection outperformed signature-based approaches. Process signature validation identified unsigned malware attempting data collection.
 
-[View full hunt →](hunts/H-0001.md) | [See more examples →](SHOWCASE.md)
+[View full hunt →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/hunts/H-0001.md) | [See more examples →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)
 
 ## Why This Matters
 
@@ -290,7 +301,7 @@ When your framework has memory, you stop losing knowledge to turnover or forgott
 
 - **GitHub Discussions:** [Ask questions, share hunts](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
 - **Issues:** [Report bugs or request features](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
-- **Adoption Guide:** See [USING_ATHF.md](USING_ATHF.md) for how to use ATHF in your organization
+- **Adoption Guide:** See [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) for how to use ATHF in your organization
 - **LinkedIn:** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - Follow for updates
 
 ## 📖 Using ATHF
@@ -299,7 +310,7 @@ ATHF is a framework to internalize, not a platform to extend. Fork it, customize
 
 **Repository:** [https://github.com/Nebulock-Inc/agentic-threat-hunting-framework](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
 
-See [USING_ATHF.md](USING_ATHF.md) for adoption guidance. Your hunts stay yours—sharing back is optional but appreciated ([Discussions](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)).
+See [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) for adoption guidance. Your hunts stay yours—sharing back is optional but appreciated ([Discussions](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)).
 
 The goal is to help every threat hunting team move from ad-hoc memory to structured, agentic capability.
 
@@ -309,7 +320,7 @@ The goal is to help every threat hunting team move from ad-hoc memory to structu
 
 ATHF is designed to be forked and customized for your organization.
 
-**See [docs/INSTALL.md#development--customization](docs/INSTALL.md#development--customization) for:**
+**See [docs/INSTALL.md#development--customization](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md#development--customization) for:**
 - Setting up your fork for development
 - Pre-commit hooks for code quality
 - Testing and type checking

agentic_threat_hunting_framework-0.2.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+agentic_threat_hunting_framework-0.2.0.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
+athf/__init__.py,sha256=OrjZe8P97_BTEkscapnwSsqKSjwXNP9d8-HtGr19Ni0,241
+athf/__version__.py,sha256=qT3kQNuJrw6IXvX9OpVNABZ8axShk7vcwAcufNBLlls,59
+athf/cli.py,sha256=XLNRXEs9kHPH6utJ7_SnzLFcldbGAnACPMTe0xMOkhQ,4492
+athf/commands/__init__.py,sha256=uDyr0bz-agpGO8fraXQl24wuQCxqbeCevZsJ2bDK29s,25
+athf/commands/context.py,sha256=nWETwEqPMTxxkUdsfVwH-K3Td41_EKQkxutdPbbIwos,11908
+athf/commands/env.py,sha256=Y1UZXn5sStpkRYMJ0ZMjr_ox3ve4ZuhqGGJPBo6Ytko,11828
+athf/commands/hunt.py,sha256=2KORNWAqEvLY-Wc1q-a894g8kOpcqw_iJfnenKJeTDI,23019
+athf/commands/init.py,sha256=L_29fvZF8SZ1BKh2D6NyDuacCC5JXOTezIxdBnnK88E,10941
+athf/commands/investigate.py,sha256=WjwPtafs9bOSu09RC1QW4CVFYJjdn2C96wRa9M_o2PI,24650
+athf/commands/similar.py,sha256=d8AArbknc08qlyGw8kTzF35q9Dk-qBXN4SMP5n0z4-I,11793
+athf/core/__init__.py,sha256=yG7C8ljx3UW4QZoYvDjUxsWHlbS8M-GLGB7Je7rRfqo,31
+athf/core/attack_matrix.py,sha256=Tp-519BLjjov8NAQ84iRvIv7STegLBtF09E5vf7jO9s,2958
+athf/core/hunt_manager.py,sha256=5fxGXbtRGfUR8B0E2jb62peSQhwISmim71SZPRrJRr0,11361
+athf/core/hunt_parser.py,sha256=FUj0yyBIcZnaS9aItMImeBDhegQwpkewIwUMNXW_ZWU,5122
+athf/core/investigation_parser.py,sha256=tZnUqrFGLMUif9rayu7hgb6sKBWIvui46siUdDokAAA,6797
+athf/core/template_engine.py,sha256=vNTVhlxIXZpxU7VmQyrqCSt6ORS0IVjAV54TOmUDMTE,5636
+athf/utils/__init__.py,sha256=aEAPI1xnAsowOtc036cCb9ZOek5nrrfevu8PElhbNgk,30
+agentic_threat_hunting_framework-0.2.0.dist-info/METADATA,sha256=4XD3KtzPLvRcA4a4lfjmRhLAuA5AAkQBF1IdXFM7ZvQ,15472
+agentic_threat_hunting_framework-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agentic_threat_hunting_framework-0.2.0.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
+agentic_threat_hunting_framework-0.2.0.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
+agentic_threat_hunting_framework-0.2.0.dist-info/RECORD,,

athf/__version__.py

@@ -1,3 +1,3 @@
 """Version information for ATHF."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

athf/cli.py

@@ -6,7 +6,7 @@ import click
 from rich.console import Console
 
 from athf.__version__ import __version__
-from athf.commands import hunt, init
+from athf.commands import context, env, hunt, init, investigate, similar
 
 console = Console()
 
@@ -79,6 +79,12 @@ def cli() -> None:
 # Register command groups
 cli.add_command(init.init)
 cli.add_command(hunt.hunt)
+cli.add_command(investigate.investigate)
+
+# Phase 1 commands (env, context, similar)
+cli.add_command(env.env)
+cli.add_command(context.context)
+cli.add_command(similar.similar)
 
 
 @cli.command(hidden=True)

athf/commands/context.py

@@ -0,0 +1,358 @@
+"""Context export command for AI-optimized context loading."""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import click
+import yaml
+from rich.console import Console
+
+console = Console()
+
+CONTEXT_EPILOG = """
+\b
+Examples:
+  # Export context for specific hunt
+  athf context --hunt H-0013
+
+  # Export context for all credential access hunts
+  athf context --tactic credential-access
+
+  # Export context for macOS platform hunts
+  athf context --platform macos
+
+  # Export full repository context (large output)
+  athf context --full
+
+  # Export as JSON (default)
+  athf context --hunt H-0013 --format json
+
+  # Export as markdown
+  athf context --hunt H-0013 --format markdown
+
+\b
+Why This Helps AI:
+  • Single tool call instead of 5+ Read operations
+  • Pre-filtered, relevant content only
+  • Structured format (easier to parse)
+  • Token optimization (strips unnecessary formatting)
+  • Saves ~2,000 tokens per hunt
+"""
+
+
+@click.command(epilog=CONTEXT_EPILOG)
+@click.option("--hunt", help="Hunt ID to export context for (e.g., H-0013)")
+@click.option(
+    "--tactic",
+    help="MITRE tactic to filter hunts (e.g., credential-access)",
+)
+@click.option("--platform", help="Platform to filter hunts (e.g., macos, windows, linux)")
+@click.option("--full", is_flag=True, help="Export full repository context (use sparingly)")
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "markdown", "yaml"]),
+    default="json",
+    help="Output format (default: json)",
+)
+@click.option("--output", type=click.Path(), help="Output file path (default: stdout)")
+def context(
+    hunt: Optional[str],
+    tactic: Optional[str],
+    platform: Optional[str],
+    full: bool,
+    output_format: str,
+    output: Optional[str],
+) -> None:
+    """Export AI-optimized context bundle.
+
+    Combines relevant files into single structured output:
+    - environment.md (tech stack, data sources)
+    - hunts/INDEX.md (hunt metadata index)
+    - Hunt files (filtered by hunt ID, tactic, or platform)
+    - Domain knowledge (if relevant)
+
+    \b
+    Use Cases:
+    • AI assistants: Reduce context-loading from ~5 tool calls to 1
+    • Token optimization: Pre-filtered, structured content only
+    • Hunt planning: Get all relevant context in one shot
+    • Query generation: Include past hunt lessons and data sources
+
+    \b
+    Token Savings:
+    • Without context: ~5 Read operations, ~3,000 tokens
+    • With context: 1 command, ~1,000 tokens
+    • Savings: ~2,000 tokens per hunt (~$0.03 per hunt)
+    """
+    # Validate mutually exclusive options
+    exclusive_options = sum([bool(hunt), bool(tactic), bool(platform), full])
+    if exclusive_options == 0:
+        console.print("[red]Error: Must specify one of: --hunt, --tactic, --platform, or --full[/red]")
+        console.print("\n[dim]Examples:[/dim]")
+        console.print("  athf context --hunt H-0013")
+        console.print("  athf context --tactic credential-access")
+        console.print("  athf context --platform macos")
+        raise click.Abort()
+
+    if exclusive_options > 1:
+        console.print("[red]Error: Only one filter option allowed at a time[/red]")
+        raise click.Abort()
+
+    # Build context bundle
+    context_data = _build_context(hunt=hunt, tactic=tactic, platform=platform, full=full)
+
+    # Format output
+    if output_format == "json":
+        # Use ensure_ascii=True to force proper escaping of all special characters
+        # This fixes issues with unescaped control characters and newlines
+        formatted_output = json.dumps(context_data, indent=2, ensure_ascii=True)
+    elif output_format == "yaml":
+        formatted_output = yaml.dump(context_data, default_flow_style=False, sort_keys=False, allow_unicode=True)
+    else:  # markdown
+        formatted_output = _format_as_markdown(context_data)
+
+    # Write to file or stdout
+    if output:
+        Path(output).write_text(formatted_output, encoding='utf-8')
+        console.print(f"[green]✅ Context exported to: {output}[/green]")
+    else:
+        # Use plain print() for JSON/YAML to avoid Rich formatting issues
+        if output_format in ("json", "yaml"):
+            print(formatted_output)
+        else:
+            console.print(formatted_output)
+
+
+def _build_context(
+    hunt: Optional[str] = None,
+    tactic: Optional[str] = None,
+    platform: Optional[str] = None,
+    full: bool = False,
+) -> Dict[str, Any]:
+    """Build context bundle based on filters."""
+    context: Dict[str, Any] = {
+        "metadata": {
+            "generated_by": "athf context",
+            "filters": {
+                "hunt": hunt,
+                "tactic": tactic,
+                "platform": platform,
+                "full": full,
+            },
+        },
+        "environment": None,
+        "hunt_index": None,
+        "hunts": [],
+        "domain_knowledge": [],
+    }
+
+    # Always include environment.md
+    env_path = Path("environment.md")
+    if env_path.exists():
+        context["environment"] = _read_and_optimize(env_path)
+
+    # Always include hunts/INDEX.md
+    index_path = Path("hunts/INDEX.md")
+    if index_path.exists():
+        context["hunt_index"] = _read_and_optimize(index_path)
+
+    # Load hunts based on filter
+    if hunt:
+        hunt_files = [Path(f"hunts/{hunt}.md")]
+    elif tactic:
+        hunt_files = _find_hunts_by_tactic(tactic)
+    elif platform:
+        hunt_files = _find_hunts_by_platform(platform)
+    elif full:
+        hunt_files = list(Path("hunts").glob("H-*.md"))
+    else:
+        hunt_files = []
+
+    # Load hunt content
+    for hunt_file in hunt_files:
+        if hunt_file.exists():
+            context["hunts"].append(
+                {
+                    "hunt_id": hunt_file.stem,
+                    "content": _read_and_optimize(hunt_file),
+                }
+            )
+
+    # Load relevant domain knowledge
+    if tactic or full:
+        domain_files = _get_relevant_domain_files(tactic)
+        for domain_file in domain_files:
+            if domain_file.exists():
+                context["domain_knowledge"].append(
+                    {
+                        "file": str(domain_file),
+                        "content": _read_and_optimize(domain_file),
+                    }
+                )
+
+    return context
+
+
+def _read_and_optimize(file_path: Path) -> str:
+    """Read file and optimize for token efficiency."""
+    content = file_path.read_text()
+
+    # First pass: Remove all control characters except tabs and newlines
+    # Control characters are U+0000 through U+001F (0-31), except tab (9), LF (10), CR (13)
+    cleaned_content = "".join(
+        char for char in content
+        if ord(char) >= 32 or char in "\t\n\r"
+    )
+
+    # Token optimization:
+    # 1. Strip excessive whitespace (but preserve single newlines)
+    lines = cleaned_content.split("\n")
+    optimized_lines = []
+    prev_empty = False
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            if not prev_empty:
+                optimized_lines.append("")
+                prev_empty = True
+        else:
+            optimized_lines.append(line.rstrip())
+            prev_empty = False
+
+    return "\n".join(optimized_lines)
+
+
+def _find_hunts_by_tactic(tactic: str) -> List[Path]:
+    """Find hunt files matching MITRE tactic."""
+    hunts_dir = Path("hunts")
+    matching_hunts = []
+
+    # Normalize tactic name (e.g., "credential-access" -> "credential access")
+    normalized_tactic = tactic.replace("-", " ").lower()
+
+    for hunt_file in hunts_dir.glob("H-*.md"):
+        content = hunt_file.read_text()
+
+        # Check YAML frontmatter for tactics field
+        if content.startswith("---"):
+            try:
+                # Extract YAML frontmatter
+                yaml_end = content.find("---", 3)
+                if yaml_end > 0:
+                    frontmatter = content[3:yaml_end]
+                    metadata = yaml.safe_load(frontmatter)
+
+                    if metadata and "tactics" in metadata:
+                        hunt_tactics = [t.lower().replace("-", " ") for t in metadata["tactics"]]
+                        if normalized_tactic in hunt_tactics:
+                            matching_hunts.append(hunt_file)
+            except yaml.YAMLError:
+                continue
+
+    return matching_hunts
+
+
+def _find_hunts_by_platform(platform: str) -> List[Path]:
+    """Find hunt files matching platform."""
+    hunts_dir = Path("hunts")
+    matching_hunts = []
+
+    normalized_platform = platform.lower()
+
+    for hunt_file in hunts_dir.glob("H-*.md"):
+        content = hunt_file.read_text()
+
+        # Check YAML frontmatter for platform field
+        if content.startswith("---"):
+            try:
+                yaml_end = content.find("---", 3)
+                if yaml_end > 0:
+                    frontmatter = content[3:yaml_end]
+                    metadata = yaml.safe_load(frontmatter)
+
+                    if metadata and "platform" in metadata:
+                        hunt_platforms = [p.lower() for p in metadata["platform"]]
+                        if normalized_platform in hunt_platforms:
+                            matching_hunts.append(hunt_file)
+            except yaml.YAMLError:
+                continue
+
+    return matching_hunts
+
+
+def _get_relevant_domain_files(tactic: Optional[str] = None) -> List[Path]:
+    """Get relevant domain knowledge files based on tactic."""
+    domain_files = []
+
+    # Always include core hunting knowledge
+    domain_files.append(Path("knowledge/hunting-knowledge.md"))
+
+    # Add tactic-specific domain files
+    if tactic:
+        tactic_lower = tactic.lower().replace("-", " ")
+
+        # Map tactics to domain files
+        tactic_domain_map = {
+            "credential access": [Path("knowledge/domains/iam-security.md")],
+            "persistence": [Path("knowledge/domains/endpoint-security.md")],
+            "privilege escalation": [Path("knowledge/domains/endpoint-security.md")],
+            "defense evasion": [Path("knowledge/domains/endpoint-security.md")],
+            "execution": [Path("knowledge/domains/endpoint-security.md")],
+            "initial access": [
+                Path("knowledge/domains/endpoint-security.md"),
+                Path("knowledge/domains/iam-security.md"),
+            ],
+            "collection": [Path("knowledge/domains/insider-threat.md")],
+            "exfiltration": [Path("knowledge/domains/insider-threat.md")],
+            "impact": [Path("knowledge/domains/insider-threat.md")],
+        }
+
+        if tactic_lower in tactic_domain_map:
+            domain_files.extend(tactic_domain_map[tactic_lower])
+
+    return list(set(domain_files))  # Remove duplicates
+
+
+def _format_as_markdown(context_data: Dict[str, Any]) -> str:
+    """Format context data as markdown."""
+    md = "# ATHF Context Export\n\n"
+
+    # Metadata
+    filters = context_data["metadata"]["filters"]
+    active_filters = [f"{k}={v}" for k, v in filters.items() if v]
+    md += f"**Filters:** {', '.join(active_filters)}\n\n"
+
+    md += "---\n\n"
+
+    # Environment
+    if context_data.get("environment"):
+        md += "## Environment\n\n"
+        md += context_data["environment"]
+        md += "\n\n---\n\n"
+
+    # Hunt Index
+    if context_data.get("hunt_index"):
+        md += "## Hunt Index\n\n"
+        md += context_data["hunt_index"]
+        md += "\n\n---\n\n"
+
+    # Hunts
+    if context_data.get("hunts"):
+        md += "## Hunts\n\n"
+        for hunt in context_data["hunts"]:
+            md += f"### {hunt['hunt_id']}\n\n"
+            md += hunt["content"]
+            md += "\n\n---\n\n"
+
+    # Domain Knowledge
+    if context_data.get("domain_knowledge"):
+        md += "## Domain Knowledge\n\n"
+        for domain in context_data["domain_knowledge"]:
+            md += f"### {domain['file']}\n\n"
+            md += domain["content"]
+            md += "\n\n---\n\n"
+
+    return md