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

agentic_threat_hunting_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: agentic-threat-hunting-framework
+Version: 0.1.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>
+License: MIT
+Project-URL: Homepage, https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
+Project-URL: Documentation, https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/tree/main/docs
+Project-URL: Repository, https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
+Project-URL: Issues, https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues
+Project-URL: Discussions, https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions
+Keywords: threat-hunting,security,cybersecurity,mitre-attack,detection-engineering,soc,blue-team,incident-response,threat-intelligence,agentic-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Monitoring
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=10.0.0
+Requires-Dist: jinja2>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: bandit[toml]>=1.7.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+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"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/athf_logo.png" alt="ATHF Logo" width="400"/>
+</p>
+
+<h1 align="center">Agentic Threat Hunting Framework (ATHF)</h1>
+
+<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>
+
+<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>
+
+<p align="center">
+  <em>Give your threat hunting program memory and agency.</em>
+</p>
+
+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.
+
+ATHF works with any hunting methodology (PEAK, TaHiTI, or your own process). It's not a replacement; it's the layer that makes your existing process AI-ready.
+
+## What is ATHF?
+
+ATHF provides structure and persistence for threat hunting programs. It's a markdown-based framework that:
+
+- Documents hunts using the LOCK pattern (Learn → Observe → Check → Keep)
+- Maintains a searchable repository of past investigations
+- Enables AI assistants to reference your environment and previous work
+- Works with any SIEM/EDR platform
+
+## The Problem
+
+Most threat hunting programs lose valuable context once a hunt ends. Notes live in Slack or tickets, queries are written once and forgotten, and lessons learned exist only in analysts' heads.
+
+Even AI tools start from zero every time without access to your environment, your data, or your past hunts.
+
+ATHF changes that by giving your hunts structure, persistence, and context.
+
+**Read more:** [docs/why-athf.md](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)
+
+- **Learn:** Gather context from threat intel, alerts, or anomalies
+- **Observe:** Form a hypothesis about adversary behavior
+- **Check:** Test hypotheses with targeted queries
+- **Keep:** Record findings and lessons learned
+
+**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)
+
+## The Five Levels of Agentic Hunting
+
+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)
+
+| Level | Capability | What You Get |
+|-------|-----------|--------------|
+| **0** | Ad-hoc | Hunts exist in Slack, tickets, or analyst notes |
+| **1** | Documented | Persistent hunt records using LOCK |
+| **2** | Searchable | AI reads and recalls your hunts |
+| **3** | Generative | AI executes queries via MCP tools |
+| **4** | Agentic | Autonomous agents monitor and act |
+
+**Level 1:** Operational within a day
+**Level 2:** Operational within a week
+**Level 3:** 2-4 weeks (optional)
+**Level 4:** 1-3 months (optional)
+
+**Read more:** [docs/maturity-model.md](docs/maturity-model.md)
+
+## 🚀 Quick Start
+
+### Option 1: Python CLI (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 .
+
+# Initialize your hunt program
+athf init
+
+# Create your first hunt
+athf hunt new --technique T1003.001 --title "LSASS Credential Dumping"
+```
+
+### Option 2: Pure Markdown (No Installation)
+
+```bash
+# Clone the repository
+git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
+cd agentic-threat-hunting-framework
+
+# Copy a template and start documenting
+cp templates/HUNT_LOCK.md hunts/H-0001.md
+
+# Customize AGENTS.md with your environment
+# Add your SIEM, EDR, and data sources
+```
+
+**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)
+
+## 🔧 CLI Commands
+
+ATHF includes a full-featured CLI for managing your hunts. Here's a quick reference:
+
+### Initialize Workspace
+
+```bash
+athf init                           # Interactive setup
+athf init --non-interactive         # Use defaults
+```
+
+### Create Hunts
+
+```bash
+athf hunt new                       # Interactive mode
+athf hunt new \
+  --technique T1003.001 \
+  --title "LSASS Dumping Detection" \
+  --platform windows
+```
+
+### List & Search
+
+```bash
+athf hunt list                      # Show all hunts
+athf hunt list --status completed   # Filter by status
+athf hunt list --output json        # JSON output
+athf hunt search "kerberoasting"    # Full-text search
+```
+
+### Validate & Stats
+
+```bash
+athf hunt validate                  # Validate all hunts
+athf hunt validate H-0001           # Validate specific hunt
+athf hunt stats                     # Show statistics
+athf hunt coverage                  # MITRE ATT&CK coverage
+```
+
+**Full documentation:** [CLI Reference](docs/CLI_REFERENCE.md)
+
+## 📺 See It In Action
+
+![ATHF Demo](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)**
+
+## Installation
+
+### Prerequisites
+- Python 3.8-3.13 (for CLI option)
+- Git
+- Your favorite AI code assistant
+
+### CLI Installation
+
+```bash
+git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
+cd agentic-threat-hunting-framework
+pip install -e .
+```
+
+### Markdown-Only Setup (No CLI)
+
+```bash
+git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
+cd agentic-threat-hunting-framework
+```
+
+Start documenting hunts in the `hunts/` directory using the LOCK pattern.
+
+## Documentation
+
+### 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
+
+### 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)
+
+### 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
+
+## 🎖️ Featured Hunts
+
+### H-0001: macOS Information Stealer Detection
+
+Detected Atomic Stealer collecting Safari cookies via AppleScript.
+**Result:** 1 true positive, host isolated before exfiltration.
+
+**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)
+
+## Why This Matters
+
+You might wonder how this interacts with frameworks like [PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html). PEAK gives you a solid method for how to hunt. ATHF builds on that foundation by giving you structure, memory, and continuity. PEAK guides the work. ATHF ensures you capture the work, organize it, and reuse it across future hunts.
+
+Agentic threat hunting is not about replacing analysts. It's about building systems that can:
+
+- Remember what has been done before
+- Learn from past successes and mistakes
+- Support human judgment with contextual recall
+
+When your framework has memory, you stop losing knowledge to turnover or forgotten notes. When your AI assistant can reference that memory, it becomes a force multiplier.
+
+## 💬 Community & Support
+
+- **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
+- **LinkedIn:** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - Follow for updates
+
+## 📖 Using ATHF
+
+ATHF is a framework to internalize, not a platform to extend. Fork it, customize it, make it yours.
+
+**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)).
+
+The goal is to help every threat hunting team move from ad-hoc memory to structured, agentic capability.
+
+---
+
+## 🛠️ Development & Customization
+
+ATHF is designed to be forked and customized for your organization.
+
+**See [docs/INSTALL.md#development--customization](docs/INSTALL.md#development--customization) for:**
+- Setting up your fork for development
+- Pre-commit hooks for code quality
+- Testing and type checking
+- Customization examples
+- CI/CD integration
+
+Quick start:
+```bash
+pip install -e ".[dev]"       # Install dev dependencies
+pre-commit install            # Set up quality checks
+pytest tests/ -v              # Run tests
+```
+
+---
+
+## 👤 Author
+
+Created by **Sydney Marrone** © 2025
+
+---
+
+**Start small. Document one hunt. Add structure. Build memory.**
+
+Memory is the multiplier. Agency is the force.
+Once your program can remember, everything else becomes possible.
+
+Happy hunting!

agentic_threat_hunting_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+agentic_threat_hunting_framework-0.1.0.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
+athf/__init__.py,sha256=OrjZe8P97_BTEkscapnwSsqKSjwXNP9d8-HtGr19Ni0,241
+athf/__version__.py,sha256=esXptUrfVtDh81i72UK2ehkLx1LobFoISaPLeDdwcNM,59
+athf/cli.py,sha256=l7pptt14nWCkdRkLDo2e4KKDA90ZNyxW1wdqMLYIxTg,4280
+athf/commands/__init__.py,sha256=uDyr0bz-agpGO8fraXQl24wuQCxqbeCevZsJ2bDK29s,25
+athf/commands/hunt.py,sha256=BOHk8H5t1LVETUlNFbSmPmmKOEcnqlR5KpTYZxIVBIU,20132
+athf/commands/init.py,sha256=L_29fvZF8SZ1BKh2D6NyDuacCC5JXOTezIxdBnnK88E,10941
+athf/core/__init__.py,sha256=yG7C8ljx3UW4QZoYvDjUxsWHlbS8M-GLGB7Je7rRfqo,31
+athf/core/hunt_manager.py,sha256=tJywunHB_06e0Z3gPWoktGqsLtEyHAO5ZsrUjAXy-IQ,8064
+athf/core/hunt_parser.py,sha256=FUj0yyBIcZnaS9aItMImeBDhegQwpkewIwUMNXW_ZWU,5122
+athf/core/template_engine.py,sha256=vNTVhlxIXZpxU7VmQyrqCSt6ORS0IVjAV54TOmUDMTE,5636
+athf/utils/__init__.py,sha256=aEAPI1xnAsowOtc036cCb9ZOek5nrrfevu8PElhbNgk,30
+agentic_threat_hunting_framework-0.1.0.dist-info/METADATA,sha256=nn-YAzCd2zd-8UkfyT-ruhcmgfJ0yvmJ-M_ll0H5fzU,12900
+agentic_threat_hunting_framework-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agentic_threat_hunting_framework-0.1.0.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
+agentic_threat_hunting_framework-0.1.0.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
+agentic_threat_hunting_framework-0.1.0.dist-info/RECORD,,

agentic_threat_hunting_framework-0.1.0.dist-info/WHEEL

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

agentic_threat_hunting_framework-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+athf = athf.cli:main

agentic_threat_hunting_framework-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sydney Marrone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_threat_hunting_framework-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+athf

athf/__init__.py

@@ -0,0 +1,9 @@
+"""Agentic Threat Hunting Framework (ATHF)
+
+A memory and automation layer for threat hunting programs.
+Makes every past investigation accessible to both humans and AI.
+"""
+
+from athf.__version__ import __version__
+
+__all__ = ["__version__"]

athf/__version__.py

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

athf/cli.py

@@ -0,0 +1,127 @@
+"""ATHF command-line interface."""
+
+import random
+
+import click
+from rich.console import Console
+
+from athf.__version__ import __version__
+from athf.commands import hunt, init
+
+console = Console()
+
+
+EPILOG = """
+\b
+Examples:
+  # Initialize a new hunting workspace
+  athf init
+
+  # Create your first hunt
+  athf hunt new
+
+  # Search for credential dumping hunts
+  athf hunt search "credential dumping"
+
+  # List all completed hunts
+  athf hunt list --status completed
+
+  # Show program statistics
+  athf hunt stats
+
+\b
+Getting Started:
+  1. Run 'athf init' to set up your workspace
+  2. Run 'athf hunt new' to create your first hunt
+  3. Document using the LOCK pattern (Learn → Observe → Check → Keep)
+  4. Track findings and iterate
+
+\b
+Documentation:
+  • Full docs: https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
+  • CLI reference: docs/CLI_REFERENCE.md
+  • AI workflows: prompts/ai-workflow.md
+
+\b
+Need help? Run 'athf COMMAND --help' for command-specific help.
+
+\b
+Created by Sydney Marrone © 2025
+"""
+
+
+@click.group(epilog=EPILOG)
+@click.version_option(
+    version=__version__,
+    prog_name="athf",
+    message="%(prog)s version %(version)s\nAgentic Threat Hunting Framework\nCreated by Sydney Marrone © 2025",
+)
+def cli() -> None:
+    """Agentic Threat Hunting Framework (ATHF) - Hunt management CLI
+
+    \b
+    ATHF gives your threat hunting program memory and agency by:
+    • Structured documentation with the LOCK pattern
+    • Hunt tracking and metrics across your program
+    • AI-assisted hypothesis generation and workflows
+    • MITRE ATT&CK coverage analysis
+
+    \b
+    Quick Start:
+      athf init           Set up a new hunting workspace
+      athf hunt new       Create a hunt from template
+      athf hunt list      View all hunts
+      athf hunt search    Find hunts by keyword
+      athf hunt stats     Show program metrics
+    """
+
+
+# Register command groups
+cli.add_command(init.init)
+cli.add_command(hunt.hunt)
+
+
+@cli.command(hidden=True)
+def wisdom() -> None:
+    """Security wisdom for threat hunters."""
+    quotes = [
+        "The best threat hunters build memory, not just alerts.",
+        "Adversaries don't repeat signatures. They repeat behaviors.",
+        "A hunt without findings is still a hunt. Absence of evidence is evidence.",
+        "Your SIEM doesn't have a storage problem. It has a memory problem.",
+        "Indicators expire. Behaviors persist.",
+        "The top of the Pyramid of Pain is the adversary's comfort zone. Make them uncomfortable.",
+        "Hunt for TTPs, not IOCs. Adversaries swap infrastructure daily, not tactics.",
+        "False positives teach you about your environment. True positives teach you about adversaries.",
+        "Every expert threat hunter started with their first hypothesis. Keep building.",
+        "The LOCK pattern isn't just documentation—it's institutional memory.",
+        "Threat intelligence tells you what to hunt. Your environment tells you how.",
+        "Behavioral detections age like wine. Signature detections age like milk.",
+        "The most dangerous threats blend in. Hunt for the subtle, not the obvious.",
+        "A mature hunt program isn't measured by detections. It's measured by learning velocity.",
+        "Pivoting is an art. Knowing when to stop pivoting is wisdom.",
+        "Your baseline is your best threat intelligence. Protect it.",
+        "Hunt like an adversary thinks: what would I do if I were already inside?",
+        "The best detection is a hunt hypothesis validated repeatedly.",
+        "Memory is the multiplier. Agency is the force.",
+        "Document the hunt that found nothing—it eliminates hypotheses for everyone who comes after you.",
+    ]
+
+    console.print(f"\n💭 [italic]{random.choice(quotes)}[/italic]\n")
+
+
+@cli.command(hidden=True)
+def thrunt() -> None:
+    """The real command all along."""
+    console.print("\n[bold cyan]🎯 THRUNT MODE ACTIVATED[/bold cyan]\n")
+    console.print("[italic]You've discovered the secret: threat hunting has always been 'thrunting'.[/italic]")
+    console.print("[italic]Welcome to the club. Now go hunt some threats.[/italic]\n")
+
+
+def main() -> None:
+    """Main entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

athf/commands/__init__.py

@@ -0,0 +1 @@
+"""ATHF CLI commands."""