agentic-threat-hunting-framework 0.2.3__tar.gz → 0.2.4__tar.gz

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4}/MANIFEST.in

@@ -7,23 +7,8 @@ include USING_ATHF.md
 include INSTALL.md
 include CHANGELOG.md
 
-# Include all markdown documentation in docs/
-recursive-include docs *.md
-
-# Include templates
-recursive-include templates *.md
-
-# Include example hunts
-recursive-include hunts *.md
-
-# Include example queries
-recursive-include queries *.spl *.kql *.sql
-
-# Include knowledge base
-recursive-include knowledge *.md
-
-# Include integration documentation
-recursive-include integrations *.md
+# Include all data files (moved to athf/data/)
+recursive-include athf/data *.md
 
 # Include visual assets
 recursive-include assets *.png *.gif *.svg

{agentic_threat_hunting_framework-0.2.3/agentic_threat_hunting_framework.egg-info → agentic_threat_hunting_framework-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.2.3
+Version: 0.2.4
 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.2.3 → agentic_threat_hunting_framework-0.2.4}/USING_ATHF.md

@@ -132,11 +132,11 @@ ATHF is designed to work with your existing stack. The README provides:
 - **Level 3: Generative Capabilities** - "Bring Your Own Tools" approach with MCP servers or APIs for SIEM, EDR, ticketing, and threat intel
 - **Level 3-4 Examples** - Visual diagrams and detailed workflows showing multi-MCP coordination and autonomous agent patterns
 
-See [integrations/README.md](integrations/README.md) and [integrations/MCP_CATALOG.md](integrations/MCP_CATALOG.md) for tool-specific guidance.
+See [integrations/README.md](athf/data/integrations/README.md) and [integrations/MCP_CATALOG.md](athf/data/integrations/MCP_CATALOG.md) for tool-specific guidance.
 
 ## Maintaining Environmental Context
 
-The [environment.md](docs/environment.md) file is a living document that informs hunt planning and enables AI-assisted hypothesis generation at all maturity levels.
+The [environment.md](athf/data/docs/environment.md) file is a living document that informs hunt planning and enables AI-assisted hypothesis generation at all maturity levels.
 
 ### Who Maintains This File?
 

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4/agentic_threat_hunting_framework.egg-info}/PKG-INFO

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

@@ -10,13 +10,13 @@ agentic_threat_hunting_framework.egg-info/dependency_links.txt
 agentic_threat_hunting_framework.egg-info/entry_points.txt
 agentic_threat_hunting_framework.egg-info/requires.txt
 agentic_threat_hunting_framework.egg-info/top_level.txt
+assets/ATHF_level_3.png
 assets/athf-cli-workflow.gif
 assets/athf-level0.gif
 assets/athf-level1.gif
 assets/athf-level2.gif
 assets/athf-level3.gif
 assets/athf_fivelevels.png
-assets/athf_level_3.png
 assets/athf_lock.png
 assets/athf_logo.png
 assets/athf_manual_v_ai.png
@@ -36,24 +36,28 @@ athf/core/hunt_manager.py
 athf/core/hunt_parser.py
 athf/core/investigation_parser.py
 athf/core/template_engine.py
-athf/utils/__init__.py
-docs/CHANGELOG.md
-docs/CLI_REFERENCE.md
-docs/INSTALL.md
-docs/README.md
-docs/environment.md
-docs/getting-started.md
-docs/level4-agentic-workflows.md
-docs/lock-pattern.md
-docs/maturity-model.md
-docs/why-athf.md
-hunts/FORMAT_GUIDELINES.md
-hunts/H-0001.md
-hunts/H-0002.md
-hunts/H-0003.md
-hunts/README.md
-integrations/MCP_CATALOG.md
-integrations/README.md
-integrations/quickstart/splunk.md
-knowledge/hunting-knowledge.md
-templates/HUNT_LOCK.md
+athf/data/__init__.py
+athf/data/docs/CHANGELOG.md
+athf/data/docs/CLI_REFERENCE.md
+athf/data/docs/INSTALL.md
+athf/data/docs/README.md
+athf/data/docs/environment.md
+athf/data/docs/getting-started.md
+athf/data/docs/level4-agentic-workflows.md
+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/integrations/MCP_CATALOG.md
+athf/data/integrations/README.md
+athf/data/integrations/quickstart/splunk.md
+athf/data/knowledge/hunting-knowledge.md
+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

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4}/athf/__version__.py

@@ -1,3 +1,3 @@
 """Version information for ATHF."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4}/athf/cli.py

@@ -40,7 +40,7 @@ Getting Started:
 Documentation:
   • Full docs: https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
   • CLI reference: docs/CLI_REFERENCE.md
-  • AI workflows: prompts/ai-workflow.md
+  • AI workflows: Run 'athf init' to get prompts/ai-workflow.md
 
 \b
 Need help? Run 'athf COMMAND --help' for command-specific help.

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4}/athf/commands/hunt.py

@@ -448,9 +448,7 @@ def stats() -> None:
     # Easter egg: First True Positive milestone
     if stats["true_positives"] == 1 and stats["completed_hunts"] > 0:
         console.print("[bold yellow]🎯 First True Positive Detected![/bold yellow]\n")
-        console.print("[italic]Every expert threat hunter started here.")
-        console.print("This confirms your hypothesis was testable, your data was sufficient,")
-        console.print("and your analytical instincts were sound. Document what worked.[/italic]\n")
+        console.print("[italic]Every expert threat hunter started here. This confirms your hypothesis was testable, your data was sufficient, and your analytical instincts were sound. Document what worked.[/italic]\n")
 
 
 @hunt.command()

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4}/athf/commands/init.py

@@ -1,5 +1,6 @@
 """Initialize ATHF directory structure."""
 
+import shutil
 from pathlib import Path
 
 import click
@@ -7,6 +8,8 @@ import yaml
 from rich.console import Console
 from rich.prompt import Confirm, Prompt
 
+from athf.data import get_data_path
+
 console = Console()
 
 
@@ -107,6 +110,9 @@ def init(path: str, non_interactive: bool) -> None:
         _create_hunt_template(templates_path / "HUNT_LOCK.md")
         console.print("  ✓ Created [cyan]templates/HUNT_LOCK.md[/cyan]")
 
+    # Copy reference files from package data
+    _copy_reference_files(base_path)
+
     console.print("\n[bold green]✅ ATHF initialized successfully![/bold green]")
     console.print("\n[bold]Next steps:[/bold]")
     console.print("  1. Customize [cyan]AGENTS.md[/cyan] with your environment details")
@@ -409,3 +415,42 @@ tags: []
 
     with open(path, "w", encoding="utf-8") as f:
         f.write(content)
+
+
+def _copy_reference_files(base_path: Path) -> None:
+    """Copy reference files from package data to workspace.
+
+    Copies knowledge base, prompts, example hunts, docs, and integrations
+    from the installed package to the user's workspace.
+    """
+    try:
+        data_path = get_data_path()
+    except Exception:
+        # Package data not available (e.g., development mode)
+        console.print("  [dim]Skipping reference file copy (package data not available)[/dim]")
+        return
+
+    # Directories to copy from package to workspace
+    copy_dirs = ["knowledge", "prompts", "hunts", "docs", "integrations"]
+
+    for dir_name in copy_dirs:
+        src_dir = data_path / dir_name
+        dst_dir = base_path / dir_name
+
+        if src_dir.exists() and src_dir.is_dir():
+            try:
+                # Copy files, don't overwrite existing
+                for src_file in src_dir.rglob("*"):
+                    if src_file.is_file():
+                        # Calculate relative path and destination
+                        rel_path = src_file.relative_to(src_dir)
+                        dst_file = dst_dir / rel_path
+
+                        # Only copy if destination doesn't exist
+                        if not dst_file.exists():
+                            dst_file.parent.mkdir(parents=True, exist_ok=True)
+                            shutil.copy2(src_file, dst_file)
+
+                console.print(f"  ✓ Copied reference files to [cyan]{dir_name}/[/cyan]")
+            except Exception as e:
+                console.print(f"  [yellow]Warning: Could not copy {dir_name}/: {e}[/yellow]")

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4}/athf/commands/similar.py

@@ -144,7 +144,7 @@ def _find_similar_hunts(
     hunt_files = list(hunts_dir.glob("H-*.md"))
 
     if not hunt_files:
-        console.print("[yellow]No hunts found in hunts/ directory[/yellow]")
+        # Don't print warning - let the output format handle empty results
         return []
 
     # Extract hunt content and metadata
@@ -172,7 +172,7 @@ def _find_similar_hunts(
         )
 
     if not hunt_data:
-        console.print("[yellow]No hunts available for comparison[/yellow]")
+        # Don't print warning - let the output format handle empty results
         return []
 
     # Build TF-IDF vectors using searchable text (weighted semantic sections)

agentic_threat_hunting_framework-0.2.4/athf/data/__init__.py

@@ -0,0 +1,14 @@
+"""ATHF reference data and templates."""
+
+from importlib.resources import files
+from pathlib import Path
+
+
+def get_data_path() -> Path:
+    """Get the path to ATHF data directory.
+
+    Returns:
+        Path to the athf/data directory containing templates, knowledge,
+        prompts, hunts, docs, and integrations.
+    """
+    return Path(str(files("athf.data")))

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4/athf/data}/docs/CHANGELOG.md

@@ -144,4 +144,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ATHF is a framework to internalize, not a platform to extend. However, if you've adapted ATHF in interesting ways or have feedback, we'd love to hear about it in [GitHub Discussions](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions).
 
-For more on the philosophy, see [../USING_ATHF.md](../USING_ATHF.md).
+For more on the philosophy, see [USING_ATHF.md](../../../USING_ATHF.md).

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4/athf/data}/docs/INSTALL.md

@@ -215,7 +215,7 @@ pytest tests/ -v --cov=athf --cov-report=term-missing
 pytest tests/test_commands.py::TestInitCommand::test_init_creates_structure_non_interactive -v
 ```
 
-Tests use Click's `CliRunner` to test actual CLI commands rather than mocks. See [../tests/test_commands.py](../tests/test_commands.py) for examples.
+Tests use Click's `CliRunner` to test actual CLI commands rather than mocks. See [tests/test_commands.py](../../../tests/test_commands.py) for examples.
 
 **Documentation**: Keep your fork's documentation current:
 - **AGENTS.md** - Update with your environment details, data sources, team context
@@ -302,7 +302,7 @@ athf hunt list --status completed --output json | \
 
 ### CI/CD Integration
 
-ATHF includes a GitHub Actions workflow ([../.github/workflows/tests.yml](../.github/workflows/tests.yml)) that runs:
+ATHF includes a GitHub Actions workflow ([.github/workflows/tests.yml](../../../.github/workflows/tests.yml)) that runs:
 
 - Tests across Python 3.8-3.12 on Ubuntu, macOS, Windows
 - Linting with flake8
@@ -322,7 +322,7 @@ All tools are configured in `pyproject.toml`:
 - **pytest**: Test discovery, coverage reporting
 - **bandit**: Security checks with test exclusions
 
-See [../pyproject.toml](../pyproject.toml) for full configuration.
+See [pyproject.toml](../../../pyproject.toml) for full configuration.
 
 ---
 

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4/athf/data}/docs/README.md

@@ -25,7 +25,7 @@ Complete documentation for the Agentic Threat Hunting Framework.
 
 ## Quick Links
 
-- [Main README](../README.md)
-- [AGENTS.md](../AGENTS.md) - AI assistant context
-- [Example Hunts](../SHOWCASE.md)
-- [Using ATHF](../USING_ATHF.md) - Adoption guide
+- [Main README](../../../README.md)
+- [AGENTS.md](../../../AGENTS.md) - AI assistant context
+- [Example Hunts](../../../SHOWCASE.md)
+- [Using ATHF](../../../USING_ATHF.md) - Adoption guide

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4/athf/data}/docs/getting-started.md

@@ -67,7 +67,7 @@ agentic-threat-hunting-framework/
 
 - [templates/](../templates/) - Ready-to-use LOCK hunt templates
 - [hunts/](../hunts/) - Example hunts showing the LOCK pattern
-- [AGENTS.md](../AGENTS.md) - Template for AI context (customize later)
+- [AGENTS.md](../../../AGENTS.md) - Template for AI context (customize later)
 
 ## Step 3: Document Your First Hunt (Level 1)
 
@@ -155,7 +155,7 @@ To make your hunts AI-accessible, add context files that describe your environme
 
 ### Customize AGENTS.md
 
-1. Open [AGENTS.md](../AGENTS.md)
+1. Open [AGENTS.md](../../../AGENTS.md)
 2. Update the following sections:
    - **Data Sources:** Replace placeholders with your actual SIEM indexes, EDR platforms, etc.
    - **Technology Stack:** List your security tools

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4/athf/data}/docs/lock-pattern.md

@@ -6,7 +6,7 @@ ATHF formalizes that loop with the **LOCK Pattern**, a lightweight structure tha
 
 **Why LOCK?** It's small enough to use and strict enough for agents to interpret.
 
-![The LOCK Pattern](../assets/athf_lock.png)
+![The LOCK Pattern](../../../assets/athf_lock.png)
 
 ## The Four Phases
 
@@ -107,7 +107,7 @@ Next iteration: expand to include remote registry and PSExec telemetry for broad
 - [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
-- [Hunt Showcase](../SHOWCASE.md) - Side-by-side comparison of all three hunts
+- [Hunt Showcase](../../../SHOWCASE.md) - Side-by-side comparison of all three hunts
 
 ## Best Practices
 

{agentic_threat_hunting_framework-0.2.3 → agentic_threat_hunting_framework-0.2.4/athf/data}/docs/maturity-model.md

@@ -4,7 +4,7 @@ ATHF defines a simple maturity model for evolving your hunting program. Each lev
 
 **Most teams will live at Levels 1–2. Everything beyond that is optional maturity.**
 
-![The Five Levels of Agentic Hunting](../assets/athf_fivelevels.png)
+![The Five Levels of Agentic Hunting](../../../assets/athf_fivelevels.png)
 
 ## Overview
 
@@ -130,7 +130,7 @@ At Level 2, you add context files to your repository that provide AI assistants
 
 ### Required Context Files
 
-#### [AGENTS.md](../AGENTS.md)
+#### [AGENTS.md](../../../AGENTS.md)
 
 Provides environmental and structural context:
 
@@ -159,11 +159,11 @@ The AI automatically searches your hunts directory, references past investigatio
 
 **The combination of AGENTS.md (environmental context) and hunting-knowledge.md (domain expertise) transforms AI assistants from generic helpers into informed threat hunting partners.**
 
-![Manual vs. AI-Assisted Content Creation](../assets/athf_manual_v_ai.png)
+![Manual vs. AI-Assisted Content Creation](../../../assets/athf_manual_v_ai.png)
 
 ### Getting Started at Level 2
 
-1. Review the included [AGENTS.md](../AGENTS.md) template
+1. Review the included [AGENTS.md](../../../AGENTS.md) template
 2. Customize it with your environment details
 3. Review [knowledge/hunting-knowledge.md](../knowledge/hunting-knowledge.md) (already included)
 4. Open your repo in Claude Code or similar AI assistant

agentic_threat_hunting_framework-0.2.4/athf/data/prompts/README.md

@@ -0,0 +1,172 @@
+# AI Prompt Library
+
+This folder contains prompts to help you accelerate threat hunting at different maturity levels.
+
+---
+
+## What's Here
+
+### basic-prompts.md
+
+**Level:** 0-1 (Manual/Documented)
+**Use for:** Copy-paste prompts for ChatGPT, Claude, or other AI assistants
+
+Contains three prompt templates:
+
+1. **Generate Hypothesis** - From CTI, alerts, or anomalies
+2. **Build Query** - Safe, bounded queries for Splunk, KQL, or Elastic
+3. **Document Results** - Capture findings in LOCK format
+
+**When to use:** You're working outside an AI-enabled IDE and need quick assistance with hypothesis generation, query building, or documentation.
+
+---
+
+### ai-workflow.md
+
+**Level:** 2 (Searchable) - AI with Memory
+**Use for:** AI tools that can read your repository (Claude Code, GitHub Copilot, Cursor)
+
+Contains:
+
+- System prompt for AI tools
+- 4 core workflows (threat intel, anomaly investigation, proactive hunting, documentation)
+- Complete example conversation showing AI reasoning
+- Tool-specific tips and troubleshooting
+- Quality checklists
+
+**When to use:** You have AI tools with file access to your hunt repository and want them to search past hunts, validate against environment.md, and generate context-aware hypotheses.
+
+---
+
+## How to Choose
+
+**Use basic-prompts.md if:**
+
+- You're just getting started with AI-assisted hunting
+- You don't have AI tool subscriptions yet
+- You want simple copy-paste templates
+- You're working in a web interface (ChatGPT, Claude.ai)
+
+**Use ai-workflow.md if:**
+
+- You have Claude Code, GitHub Copilot, or Cursor
+- Your hunt repository has AGENTS.md, knowledge/hunting-knowledge.md, and documented past hunts
+- You want AI to search memory, apply expert hunting frameworks, and apply lessons learned
+- You're ready for more advanced workflows
+
+---
+
+## Quick Start
+
+### Level 0-1: Basic Prompts
+
+1. Open [basic-prompts.md](basic-prompts.md)
+2. Copy the prompt template you need
+3. Fill in your context (hypothesis, data sources, results)
+4. Paste into ChatGPT, Claude, or your AI assistant
+5. Review and refine the output
+
+**Example:**
+
+```
+# You have threat intel about PowerShell abuse
+→ Use "Generate Hypothesis" prompt from basic-prompts.md
+→ Paste CTI report into context section
+→ AI generates testable hypotheses
+```
+
+### Level 2: AI Workflows
+
+1. Open your hunt repository in Claude Code, Copilot, or Cursor
+2. Provide the system prompt from [ai-workflow.md](ai-workflow.md)
+3. Ask AI to search past hunts before generating new ones
+4. Follow the workflow guides for common scenarios
+
+**Example:**
+
+```
+You: "Check if we've hunted T1003.001 before. Use the system prompt from prompts/ai-workflow.md"
+AI: [Searches hunts/, reads environment.md, generates context-aware hypothesis]
+```
+
+---
+
+## Safety Reminders
+
+### AI Assistance ≠ Autopilot
+
+- **Always review** AI-generated hypotheses for feasibility
+- **Always test** AI-generated queries on small timeframes first
+- **Always validate** that queries are safe and bounded
+- **Use your judgment** - You know your environment better than AI
+
+### Before Running Any AI-Generated Query
+
+1. Check for time bounds (`earliest=-Xd`)
+2. Check for result limits (`| head N` or `| take N`)
+3. Test on 1-hour window before expanding to days
+4. Verify it won't impact SIEM performance
+
+---
+
+## Platform-Specific Tips
+
+**Splunk Users:**
+
+- Mention "Splunk SPL" in your prompts
+- Specify data models when available
+- AI knows common Splunk patterns (tstats, eval, stats)
+
+**KQL Users (Sentinel/Defender):**
+
+- Mention "KQL for Sentinel" or "KQL for Defender"
+- Specify table names (SecurityEvent, DeviceProcessEvents, etc.)
+- AI understands Sentinel-specific syntax
+
+**Elastic Users:**
+
+- Mention "Elastic EQL" or "Lucene query"
+- Specify index patterns
+- Note which Elastic stack version you're using
+
+---
+
+## Next Steps
+
+### After Using Basic Prompts
+
+1. Document your hunts using [templates/HUNT_LOCK.md](../templates/HUNT_LOCK.md)
+2. Create AGENTS.md in your repository (see main README)
+3. Ensure knowledge/hunting-knowledge.md is present (included in repo by default)
+4. Progress to Level 2 with ai-workflow.md
+
+### 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)
+2. Review format guidelines in [hunts/FORMAT_GUIDELINES.md](../hunts/FORMAT_GUIDELINES.md)
+3. Consider Level 3 (MCP integrations) in [integrations/](../integrations/)
+
+---
+
+## Customizing for Your Environment
+
+Feel free to modify these prompts:
+
+- Add your organization's specific data sources
+- Include your ATT&CK coverage gaps
+- Reference your baseline automation
+- Add your threat model priorities
+
+---
+
+## Contributing
+
+Have a better prompt? Found a useful workflow?
+
+- Submit a PR with your improvements
+- Share what works in your environment
+- Help others get started faster
+
+---
+
+**Remember: These prompts are training wheels. They help you get started faster, teach you the LOCK pattern, and over time you'll need them less. But they remain useful for complex hunts.**