agentic-threat-hunting-framework 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

{agentic_threat_hunting_framework-0.2.3.dist-info → agentic_threat_hunting_framework-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-threat-hunting-framework
-Version: 0.2.3
+Version: 0.3.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>
@@ -33,6 +33,7 @@ Requires-Dist: click>=8.0.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=10.0.0
 Requires-Dist: jinja2>=3.0.0
+Requires-Dist: importlib_resources>=5.0.0; python_version < "3.9"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -76,6 +77,7 @@ ATHF provides structure and persistence for threat hunting programs. It's a mark
 - Maintains a searchable repository of past investigations
 - Enables AI assistants to reference your environment and previous work
 - Works with any SIEM/EDR platform
+- **NEW:** Includes AI-powered research and hypothesis generation agents (v0.3.0+)
 
 ## The Problem
 
@@ -115,8 +117,8 @@ ATHF defines a simple maturity model. Each level builds on the previous one.
 | **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 |
+| **3** | Generative | AI executes queries via MCP tools, conducts research |
+| **4** | Agentic | Autonomous agents monitor and act, generate hypotheses |
 
 **Level 1:** Operational within a day
 **Level 2:** Operational within a week
@@ -136,8 +138,11 @@ pip install agentic-threat-hunting-framework
 # Initialize your hunt program
 athf init
 
-# Create your first hunt
-athf hunt new --technique T1003.001 --title "LSASS Credential Dumping"
+# NEW: Conduct research before hunting (5-skill methodology)
+athf research new --topic "LSASS dumping" --technique T1003.001
+
+# Create your first hunt (link to research)
+athf hunt new --technique T1003.001 --title "LSASS Credential Dumping" --research R-0001
 ```
 
 ### Option 2: Install from Source (Development)
@@ -161,7 +166,8 @@ 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
+mkdir -p hunts
+cp athf/data/templates/HUNT_LOCK.md hunts/H-0001.md
 
 # Customize AGENTS.md with your environment
 # Add your SIEM, EDR, and data sources
@@ -182,6 +188,23 @@ athf init                           # Interactive setup
 athf init --non-interactive         # Use defaults
 ```
 
+### Research & Hypothesis Generation (NEW in v0.3.0)
+
+```bash
+# Conduct thorough pre-hunt research (15-20 min)
+athf research new --topic "LSASS dumping" --technique T1003.001
+
+# Quick research for urgent hunts (5 min)
+athf research new --topic "Pass-the-Hash" --depth basic
+
+# Generate AI-powered hypothesis from threat intel
+athf agent run hypothesis-generator --threat-intel "APT29 targeting SaaS"
+
+# List research and agents
+athf research list
+athf agent list
+```
+
 ### Create Hunts
 
 ```bash
@@ -189,7 +212,8 @@ athf hunt new                       # Interactive mode
 athf hunt new \
   --technique T1003.001 \
   --title "LSASS Dumping Detection" \
-  --platform windows
+  --platform windows \
+  --research R-0001                 # Link to research document
 ```
 
 ### List & Search
@@ -199,6 +223,7 @@ 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
+athf research search "credential"   # Search research docs
 ```
 
 ### Validate & Stats
@@ -208,6 +233,7 @@ 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
+athf research stats                 # Research metrics
 ```
 
 **Full documentation:** [CLI Reference](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
@@ -222,35 +248,12 @@ Watch ATHF in action: initialize a workspace, create hunts, and explore your thr
 
 ## Installation
 
-### Prerequisites
+See the [Quick Start](#-quick-start) section above for installation options (PyPI, source, or pure markdown).
+
+**Prerequisites:**
 - Python 3.8-3.13 (for CLI option)
 - Your favorite AI code assistant
 
-### 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 Installation)
-
-```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
@@ -297,21 +300,16 @@ Agentic threat hunting is not about replacing analysts. It's about building syst
 
 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
+## 💬 Community & Adoption
 
 - **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](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
-
-ATHF is a framework to internalize, not a platform to extend. Fork it, customize it, make it yours.
+**Using ATHF in Your Organization:** ATHF is a framework to internalize, not a platform to extend. Fork it, customize it, make it yours. 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.
 
 **Repository:** [https://github.com/Nebulock-Inc/agentic-threat-hunting-framework](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
 
-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.
 
 ---

agentic_threat_hunting_framework-0.3.0.dist-info/RECORD

@@ -0,0 +1,51 @@
+agentic_threat_hunting_framework-0.3.0.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
+athf/__init__.py,sha256=OrjZe8P97_BTEkscapnwSsqKSjwXNP9d8-HtGr19Ni0,241
+athf/__version__.py,sha256=1uOy8XMZ6490EmE359rotOAMj4-r0qm1IZG5gSmm_7g,59
+athf/cli.py,sha256=rkg_Nx9Yy_UqTXBOh-pwaiD-lXO0_IXQMA1SQpDj7g0,4639
+athf/commands/__init__.py,sha256=KbpUcLPjmltq5a_m1MjhrIe4sk3DvqsnAw1wCAZfZNo,85
+athf/commands/agent.py,sha256=k-NWiLppt2oWbiJ-hx1inkK51jhfsAYiFhixbzzQmQI,16565
+athf/commands/context.py,sha256=V-at81-OgKcLY-In48-AccTnHfTgdofmnjE8S5kypoI,12678
+athf/commands/env.py,sha256=JPKRsv48cgsIAjSFaGJ1-Nu0nQKGSVg4AbiFxb9jVX4,11887
+athf/commands/hunt.py,sha256=PcYz0Zj9qqB10s9mkbfHk-hl2IbcfJekeB6cA2exXPo,22991
+athf/commands/init.py,sha256=Qn0iETNyuQvM-ySqCeoDz-pPemeuzROX_karQF5yN_o,12685
+athf/commands/investigate.py,sha256=mK_id5vjfN_ukqB_-fyia0FNa0pBmtn0Xv6CKHQI1Qo,24663
+athf/commands/research.py,sha256=FrLph4agaGQ_rIxMh0OQwh1MIGDFtj40zJ3E1ZFwaAw,18112
+athf/commands/similar.py,sha256=FTTVr4zzP9bdJrirscp6pOxdQbE8zot6pa20-_TYiuo,11804
+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/research_manager.py,sha256=i4fUjuZJcAik8I4pwbLkQlu6cuxkWDlqaIRQrzAfB0s,14512
+athf/core/template_engine.py,sha256=vNTVhlxIXZpxU7VmQyrqCSt6ORS0IVjAV54TOmUDMTE,5636
+athf/core/web_search.py,sha256=B9IhmwH7gy2RVA6WSN3L7yGp3Q4L8OsiiwcEvnnZejU,10320
+athf/data/__init__.py,sha256=QtgONloCaS3E9Ow995FMxyy6BbszpfmYeWpySQ2b9Mc,502
+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.3.0.dist-info/METADATA,sha256=TT9rzSs2CSKI3TTKMkSP7ZRehUXtntbgYCWfCFK7qbU,15838
+agentic_threat_hunting_framework-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agentic_threat_hunting_framework-0.3.0.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
+agentic_threat_hunting_framework-0.3.0.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
+agentic_threat_hunting_framework-0.3.0.dist-info/RECORD,,

athf/__version__.py

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

athf/cli.py

@@ -6,7 +6,8 @@ import click
 from rich.console import Console
 
 from athf.__version__ import __version__
-from athf.commands import context, env, hunt, init, investigate, similar
+from athf.commands import context, env, hunt, init, investigate, research, similar
+from athf.commands.agent import agent
 
 console = Console()
 
@@ -40,7 +41,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.
@@ -80,12 +81,16 @@ def cli() -> None:
 cli.add_command(init.init)
 cli.add_command(hunt.hunt)
 cli.add_command(investigate.investigate)
+cli.add_command(research.research)
 
 # Phase 1 commands (env, context, similar)
 cli.add_command(env.env)
 cli.add_command(context.context)
 cli.add_command(similar.similar)
 
+# Agent commands
+cli.add_command(agent)
+
 
 @cli.command(hidden=True)
 def wisdom() -> None:

athf/commands/__init__.py

@@ -1 +1,5 @@
 """ATHF CLI commands."""
+
+from athf.commands.agent import agent
+
+__all__ = ["agent"]