agentic-threat-hunting-framework 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

{agentic_threat_hunting_framework-0.2.2.dist-info → agentic_threat_hunting_framework-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.2.2
+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.4.dist-info/RECORD

@@ -0,0 +1,47 @@
+agentic_threat_hunting_framework-0.2.4.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
+athf/__init__.py,sha256=OrjZe8P97_BTEkscapnwSsqKSjwXNP9d8-HtGr19Ni0,241
+athf/__version__.py,sha256=Cl7hGHiamJWMCcDKQ8Lcm6Vlc50BZ6GasydpyAoWkg8,59
+athf/cli.py,sha256=LSOazv6E_RChZFqoyMcdfDPH1hIJeZc1s95fssjDLZs,4515
+athf/commands/__init__.py,sha256=uDyr0bz-agpGO8fraXQl24wuQCxqbeCevZsJ2bDK29s,25
+athf/commands/context.py,sha256=WvOf0OuttAsEk_h4QDtdfqYI4CulDg2UCtq_5r5iJAA,12686
+athf/commands/env.py,sha256=AisRllJXbyCjK_2ii21qBBmCz9raxhBUemwM7BxqIYg,11859
+athf/commands/hunt.py,sha256=9ZEI11y8DUixUqw8-yR01K4hVz2JSJJokRwWk8tnNn4,22969
+athf/commands/init.py,sha256=Qn0iETNyuQvM-ySqCeoDz-pPemeuzROX_karQF5yN_o,12685
+athf/commands/investigate.py,sha256=mK_id5vjfN_ukqB_-fyia0FNa0pBmtn0Xv6CKHQI1Qo,24663
+athf/commands/similar.py,sha256=lniOkSOn--ZIztsfTZS-afioJpqJEJQjmqfxsDy6xZQ,11790
+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_parser.py,sha256=FUj0yyBIcZnaS9aItMImeBDhegQwpkewIwUMNXW_ZWU,5122
+athf/core/investigation_parser.py,sha256=wbfjnq4gFgIc0a4bHIAnidVNPhbHDpIXWY1SGLk0Xls,6804
+athf/core/template_engine.py,sha256=vNTVhlxIXZpxU7VmQyrqCSt6ORS0IVjAV54TOmUDMTE,5636
+athf/data/__init__.py,sha256=eC5AiaYPQ7oYR3ktxTvRhUHVd_RB1zhQgcVPD3o-9Vw,364
+athf/data/docs/CHANGELOG.md,sha256=1dAondeKsQnGOn9esy9oZ29uG_oGgRuHxmkcmGQ1Cwo,5950
+athf/data/docs/CLI_REFERENCE.md,sha256=zqUp-tu8OAcqzpOwx3XvzEq7UV6woDraUOcWasZI0a8,43748
+athf/data/docs/INSTALL.md,sha256=JOWxk6q2-rdpgCnWdSPb3-Cp8rX1y4nQm7ObKz2G0uM,13117
+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=j4SAXe-Rm1RhYBDvWaNpV8XS0rc_mZ2Ew0yPCxE4_wQ,14156
+athf/data/docs/level4-agentic-workflows.md,sha256=DX54qu8LbJysjDfQLGSEPSO_Q6BUACLpa-XCsR6xUp4,13439
+athf/data/docs/lock-pattern.md,sha256=eICjNh5SAgIhkOYBDhHg1tgw4A29xgnRDWC9vH1wLEQ,4863
+athf/data/docs/maturity-model.md,sha256=S2m8JSQDe9R5ROBWS4Gy0-sRF5I7mo-CI3cUnmNpxmk,16347
+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/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/templates/HUNT_LOCK.md,sha256=zXxHaKMWbRDLewLTegYJMbXRM72s9gFFvjdwFfGNeJE,7386
+athf/utils/__init__.py,sha256=aEAPI1xnAsowOtc036cCb9ZOek5nrrfevu8PElhbNgk,30
+agentic_threat_hunting_framework-0.2.4.dist-info/METADATA,sha256=gcqEWImt2gBOrH2q5VUhafR5OiG_xIoCdpfbtEy1mt0,15472
+agentic_threat_hunting_framework-0.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agentic_threat_hunting_framework-0.2.4.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
+agentic_threat_hunting_framework-0.2.4.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
+agentic_threat_hunting_framework-0.2.4.dist-info/RECORD,,

athf/__version__.py

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

athf/commands/context.py

@@ -22,6 +22,9 @@ Examples:
   # Export context for macOS platform hunts
   athf context --platform macos
 
+  # Combine filters: persistence hunts on Linux
+  athf context --tactic persistence --platform linux
+
   # Export full repository context (large output)
   athf context --full
 
@@ -86,18 +89,20 @@ def context(
     • 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]")
+    # Validate that at least one filter is provided
+    has_filter = any([hunt, tactic, platform, full])
+    if not has_filter:
+        console.print("[red]Error: Must specify at least 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")
+        console.print("  athf context --tactic persistence --platform linux")
         raise click.Abort()
 
-    if exclusive_options > 1:
-        console.print("[red]Error: Only one filter option allowed at a time[/red]")
+    # --full flag is mutually exclusive with other filters
+    if full and (hunt or tactic or platform):
+        console.print("[red]Error: --full cannot be combined with other filters[/red]")
         raise click.Abort()
 
     # Build context bundle
@@ -158,17 +163,26 @@ def _build_context(
     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:
+    # Load hunts based on filters (can be combined)
+    if full:
+        # Full export: include all hunts
         hunt_files = list(Path("hunts").glob("H-*.md"))
+    elif hunt:
+        # Specific hunt: only load that one
+        hunt_files = [Path(f"hunts/{hunt}.md")]
     else:
-        hunt_files = []
+        # Combine tactic and platform filters
+        if tactic and platform:
+            # Both filters: find hunts matching both criteria
+            tactic_hunts = set(_find_hunts_by_tactic(tactic))
+            platform_hunts = set(_find_hunts_by_platform(platform))
+            hunt_files = list(tactic_hunts & platform_hunts)  # Intersection
+        elif tactic:
+            hunt_files = _find_hunts_by_tactic(tactic)
+        elif platform:
+            hunt_files = _find_hunts_by_platform(platform)
+        else:
+            hunt_files = []
 
     # Load hunt content
     for hunt_file in hunt_files:

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

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

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)

athf/core/hunt_manager.py

@@ -154,7 +154,14 @@ class HuntManager:
         results = []
         query_lower = query.lower()
 
+        # Exclude documentation files
+        exclude_files = {"README.md", "FORMAT_GUIDELINES.md"}
+
         for hunt_file in self.hunts_dir.glob("*.md"):
+            # Skip documentation files
+            if hunt_file.name in exclude_files:
+                continue
+
             try:
                 with open(hunt_file, "r", encoding="utf-8") as f:
                     content = f.read()

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

athf/data/docs/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to the Agentic Threat Hunting Framework (ATHF) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- None
+
+### Changed
+- None
+
+### Deprecated
+- None
+
+### Removed
+- None
+
+### Fixed
+- None
+
+### Security
+- None
+
+## [0.2.2] - 2024-12-17
+
+### Fixed
+- Type errors in `athf/core/attack_matrix.py` (added TypedDict for proper mypy checking)
+- Python 3.8 compatibility: `list[str]` → `List[str]` in `athf/core/attack_matrix.py`
+- Python 3.8 compatibility: `tuple[...]` → `Tuple[...]` in `athf/core/investigation_parser.py`
+- Python 3.8 compatibility: `tuple[...]`, `list[str]` → `Tuple[...]`, `List[str]` in `athf/commands/investigate.py`
+- Python 3.8 compatibility: `set[str]` → `Set[str]` in `athf/core/hunt_manager.py`
+- Python 3.8 compatibility: `int | str` → `Union[int, str]` in `athf/commands/env.py`
+- Windows UTF-8 encoding errors in `athf/commands/context.py` (3 instances) and `athf/commands/similar.py` (2 instances)
+- Test assertion errors in `tests/commands/test_env.py` for env info and activate commands
+- Mypy unused-ignore errors in `athf/commands/similar.py` (sklearn imports handled by --ignore-missing-imports flag)
+- CI/CD pipeline errors blocking builds on Python 3.8-3.12 across all platforms
+
+## [0.2.1] - 2024-12-17
+
+### Fixed
+- Type errors in `athf/core/attack_matrix.py` (added TypedDict for proper mypy checking)
+- Python 3.8 compatibility: `list[str]` → `List[str]` in `athf/core/attack_matrix.py`
+- Python 3.8 compatibility: `tuple[...]` → `Tuple[...]` in `athf/core/investigation_parser.py`
+- Python 3.8 compatibility: `tuple[...]`, `list[str]` → `Tuple[...]`, `List[str]` in `athf/commands/investigate.py`
+- Python 3.8 compatibility: `set[str]` → `Set[str]` in `athf/core/hunt_manager.py`
+- Python 3.8 compatibility: `int | str` → `Union[int, str]` in `athf/commands/env.py`
+- Windows UTF-8 encoding errors in `athf/commands/context.py` (3 instances) and `athf/commands/similar.py` (2 instances)
+- Test assertion errors in `tests/commands/test_env.py` for env info and activate commands
+- Mypy unused-ignore errors in `athf/commands/similar.py` (sklearn imports handled by --ignore-missing-imports flag)
+- CI/CD pipeline errors blocking builds on Python 3.8-3.12 across all platforms
+
+## [0.2.0] - 2024-12-17
+
+### Added
+- **CLI Commands**
+  - `athf context` - AI-optimized context loading (replaces ~5 Read operations, 75% token savings)
+  - `athf env` - Environment setup and management (setup, info, activate, clean)
+  - `athf investigate` - Investigation workflow for exploratory work (separate from hunt metrics)
+  - `athf similar` - Semantic search for similar hunts using scikit-learn embeddings
+- **Core Modules**
+  - `athf/core/attack_matrix.py` - MITRE ATT&CK coverage tracking and analysis
+  - `athf/core/investigation_parser.py` - Parser for I-XXXX investigation files
+- **Testing Infrastructure**
+  - Comprehensive test suite for all new commands (tests/commands/)
+  - Command-specific test modules (test_context.py, test_env.py, test_similar.py)
+  - Integration tests for multi-command workflows
+- **Rich Content CLI Flags**
+  - `--hypothesis`, `--threat-context`, `--actor`, `--behavior`, `--location`, `--evidence`
+  - Enable fully-populated hunt files via single CLI command
+  - AI-friendly one-liner hunt creation without manual editing
+
+### Changed
+- Enhanced `athf hunt` command with investigation integration
+- Updated CLI help system with improved command descriptions
+- Improved context bundling for AI workflows (structured JSON/YAML output)
+- Updated documentation to reflect new commands and workflows
+
+### Fixed
+- Python 3.8 compatibility issues
+- Testing framework stability improvements
+
+## [0.1.0] - 2024-12-10
+
+### Added
+- Initial ATHF framework documentation
+  - LOCK pattern (Learn, Observe, Check, Keep)
+  - 5-level maturity model
+  - USING_ATHF.md adoption guide
+  - INSTALL.md installation guide
+- Example hunt implementations
+  - H-0001: macOS Data Collection via AppleScript Detection
+  - H-0002: Linux Crontab Persistence Detection
+  - H-0003: AWS Lambda Persistence Detection
+- Templates
+  - HUNT_LOCK.md template
+  - Query templates for Splunk, KQL, Elastic
+- Documentation
+  - README.md with visual enhancements
+  - SHOWCASE.md with real results
+  - docs/CLI_REFERENCE.md (planned for CLI implementation)
+- Knowledge base
+  - hunting-knowledge.md expert hunting frameworks
+  - AGENTS.md AI assistant instructions
+  - environment.md template
+- Integration guides
+  - MCP_CATALOG.md for tool integrations
+  - SIEM integration examples
+  - EDR integration examples
+
+### Philosophy
+- Framework-first approach: "Structure over software, adapt to your environment"
+- Document-first methodology: Works with markdown, git, and AI assistants
+- Optional tooling: CLI enhances but doesn't replace core workflow
+- Progression-minded: Start simple, scale when complexity demands it
+
+---
+
+## Version History
+
+**Legend:**
+- `[Unreleased]` - Changes in development
+- `[X.Y.Z]` - Released versions
+
+**Version Format:**
+- `X` - Major version (breaking changes)
+- `Y` - Minor version (new features, backward compatible)
+- `Z` - Patch version (bug fixes, backward compatible)
+
+**Change Categories:**
+- `Added` - New features
+- `Changed` - Changes to existing functionality
+- `Deprecated` - Soon-to-be removed features
+- `Removed` - Removed features
+- `Fixed` - Bug fixes
+- `Security` - Security improvements
+
+---
+
+## Contribution Notes
+
+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).