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

athf/data/hunts/README.md

@@ -0,0 +1,231 @@
+# Hunt Directory
+
+This folder contains your threat hunting investigations using the **LOCK methodology** (Learn-Observe-Check-Keep) with **ABLE scoping** (Actor-Behavior-Location-Evidence).
+
+For template structure details, see [FORMAT_GUIDELINES.md](FORMAT_GUIDELINES.md).
+
+## File Structure
+
+```
+hunts/
+├── H-0001.md    ← macOS Data Collection via AppleScript Detection (T1005)
+├── H-0002.md    ← Linux Crontab Persistence Detection (T1053.003)
+├── H-0003.md    ← AWS Lambda Persistence Detection (T1546.004)
+└── H-####.md    ← Your next hunt
+```
+
+Each file is a complete hunt from planning through execution results.
+
+## Quick Start
+
+### 1. Create a New Hunt
+
+**Using CLI (Recommended):**
+
+```bash
+# Interactive mode - prompts you for details
+athf hunt new
+
+# Or specify details directly
+athf hunt new --technique T1110.001 --title "SSH Brute Force Detection" --platform linux
+```
+
+**Manual Method (Alternative):**
+
+Copy the template and fill it out:
+
+```bash
+cp ../templates/HUNT_LOCK.md hunts/H-0004.md
+```
+
+**Either way, start with the LEARN section:**
+
+- Write your hypothesis
+- Fill out ABLE scoping table (Actor, Behavior, Location, Evidence)
+- Add threat intel and MITRE ATT&CK context
+
+Set status to **Planning** while developing queries.
+
+### 2. Execute the Hunt
+
+Update the same file as you run your hunt:
+
+- Change status from **Planning** → **In Progress**
+- Fill out **CHECK** section with data source details
+- Add your queries and results
+- Document what worked and what didn't
+
+### 3. Capture Results
+
+Complete the **KEEP** section:
+
+- Executive summary of findings
+- True positives / false positives / suspicious events
+- Lessons learned
+- Follow-up actions and new hunt ideas
+
+Change status to **Completed** when done.
+
+### 4. Iterate
+
+Next time you hunt the same behavior:
+
+- Open the same H-####.md file
+- Update queries based on lessons learned
+- Re-run and update findings
+- Keep refining
+
+The file becomes your evolving playbook for that technique.
+
+## Searching Past Hunts
+
+### Using AI Assistants (Level 2+)
+
+If you're using Claude Code or similar AI tools, just ask:
+
+```
+"Have we hunted macOS data collection before?"
+"What lessons did we learn from persistence hunts?"
+"Find hunts that detected true positives"
+"Show me all Linux persistence hunts"
+```
+
+The AI will search the hunts/ folder and summarize findings.
+
+### CLI Search (Recommended)
+
+```bash
+# Find hunts by MITRE technique
+athf hunt list --technique T1110.001
+
+# Find by behavior (full-text search)
+athf hunt search "brute force"
+
+# Find by technology
+athf hunt search "powershell"
+
+# See completed hunts
+athf hunt list --status completed
+
+# Get hunt statistics
+athf hunt stats
+```
+
+### Manual Grep (Fallback)
+
+```bash
+# Find hunts by MITRE technique
+grep -l "T1110.001" hunts/H-*.md
+
+# Find by behavior
+grep -i "brute force" hunts/H-*.md
+
+# Find by technology
+grep -i "powershell" hunts/H-*.md
+
+# See completed hunts
+grep "Status.*Completed" hunts/H-*.md
+
+# Learn from past lessons
+grep "Lessons Learned" -A 5 hunts/H-*.md
+```
+
+## Hunt Status Tracking
+
+```bash
+# List all hunts
+ls hunts/H-*.md
+
+# Count total hunts
+ls hunts/H-*.md | wc -l
+
+# Find in-progress hunts
+grep "Status.*In Progress" hunts/H-*.md
+
+# Find hunts that need follow-up
+grep "Follow-up Actions" -A 10 hunts/H-*.md | grep "\[ \]"
+```
+
+## Level 3: MCP Integration
+
+At Level 3, you can connect MCPs to execute hunts directly through Claude.
+
+### What are MCPs?
+
+MCP (Model Context Protocol) servers let Claude interact with your security tools:
+
+- Execute Splunk queries
+- Analyze results automatically
+- Create tickets with findings
+- Enrich data with threat intel
+
+### Example Workflow
+
+```
+User: "Run hunt H-0001"
+
+Claude:
+1. Reads H-0001.md hypothesis and queries
+2. Executes Splunk query via MCP
+3. Analyzes results and identifies TPs/FPs
+4. Updates hunt file with findings
+5. Creates tickets for true positives
+
+"Hunt completed. Found 3 brute force attempts. Created INC-2847."
+```
+
+### Getting Started with MCPs
+
+1. **Setup guide:** [../integrations/README.md](../integrations/README.md)
+2. **Splunk walkthrough:** [../integrations/MCP_CATALOG.md](../integrations/MCP_CATALOG.md)
+3. **Splunk quickstart:** [../integrations/quickstart/splunk.md](../integrations/quickstart/splunk.md)
+
+### Time Savings
+
+**Without MCPs (Level 2):**
+
+- Manual query execution: ~10 minutes
+- Copy/paste results: ~5 minutes
+- Analysis and documentation: ~25 minutes
+- Ticket creation: ~5 minutes
+- **Total:** ~45 minutes per hunt
+
+**With MCPs (Level 3):**
+
+- Claude executes and analyzes automatically
+- Results documented in hunt file
+- Tickets created with full context
+- **Total:** ~5 minutes per hunt
+
+## Tips
+
+**Creating Hunts:**
+
+- Start with ABLE scoping - be specific about Evidence (log sources, key fields, examples)
+- Actor is optional - focus on Behavior first
+- Use clear MITRE ATT&CK technique IDs in titles
+
+**Executing Hunts:**
+
+- Document query iterations - show what didn't work and why
+- Be honest about false positives - they're learning opportunities
+- Capture telemetry gaps for engineering follow-up
+
+**Refining Hunts:**
+
+- Update the same file as you iterate
+- Keep old queries (comment them out) to show evolution
+- Link related hunts in Follow-up Hunts section
+
+**Status Management:**
+
+- **Planning** = Developing hypothesis and queries
+- **In Progress** = Actively executing and collecting data
+- **Completed** = Results documented, lessons captured
+
+## Example Hunts
+
+- [H-0001.md](H-0001.md) - macOS Data Collection via AppleScript Detection (T1005, T1059.002, T1555.003)
+- [H-0002.md](H-0002.md) - Linux Crontab Persistence Detection (T1053.003)
+- [H-0003.md](H-0003.md) - AWS Lambda Persistence Detection (T1546.004, T1098)
+- [FORMAT_GUIDELINES.md](FORMAT_GUIDELINES.md) - Template structure reference

athf/data/integrations/MCP_CATALOG.md

@@ -0,0 +1,45 @@
+# MCP Catalog for Threat Hunting
+
+You'll need to **do your own research** to find MCP servers for your organization's security tools. This catalog walks through **Splunk as an example** to demonstrate the process of integrating an MCP server with Claude Code for threat hunting workflows.
+
+## Splunk Integration Walkthrough
+
+**Transform your workflow:** Claude executes Splunk queries directly and analyzes results - no more copy-paste between tools.
+
+**Official MCP:** [Splunkbase app 7931](https://splunkbase.splunk.com/app/7931)
+
+**Complete setup guide:** [quickstart/splunk.md](quickstart/splunk.md) - 4 steps to get Splunk MCP working, includes troubleshooting and usage examples
+
+---
+
+## After You Complete the Splunk Example
+
+Once you understand how MCP integration works through the Splunk walkthrough, you can find MCPs for your other security tools:
+
+**Where to look:**
+
+- Check vendor GitHub repositories (e.g., <https://github.com/elastic>, <https://github.com/microsoft>)
+- Search the official MCP servers collection: <https://github.com/modelcontextprotocol/servers>
+- Look for vendor-published MCPs on their documentation sites
+- Search GitHub for "[tool-name] mcp server"
+
+**Verify before use:**
+
+- Is it from the official vendor or a trusted source?
+- Does it have active maintenance and community support?
+- Does it fit your security and compliance requirements?
+
+---
+
+## MCP Development Resources
+
+Want to build an MCP for your security tool?
+
+- **MCP Documentation:** <https://modelcontextprotocol.io/docs>
+- **Python Quickstart:** <https://modelcontextprotocol.io/quickstart/server>
+- **Example MCPs:** <https://github.com/modelcontextprotocol/servers>
+- **Claude Code Integration:** <https://docs.claude.com/claude-code/mcp>
+
+---
+
+**Last Updated:** 2025-01-11

athf/data/integrations/README.md

@@ -0,0 +1,129 @@
+# Level 3: Generative - Bring Your Own MCP
+
+At Level 3, you extend Claude Code's capabilities by connecting MCP (Model Context Protocol) servers for the security tools you already use. This transforms the LOCK workflow from manual investigation to tool-integrated analysis.
+
+## What Is Level 3?
+
+**Level 1 (Documented):** You manually document hunts in markdown files
+**Level 2 (Searchable):** Claude reads past hunts, applies expert hunting frameworks from knowledge/hunting-knowledge.md, and uses AGENTS.md for environmental context
+**Level 3 (Generative):** Claude executes queries, enriches data, and creates tickets through MCPs
+
+At Level 3, Claude doesn't just read about your tools - it **uses** them.
+
+## What Does Integration Mean?
+
+Instead of copying queries and results back and forth between Claude and your tools, **MCPs let Claude directly interact with your security stack**.
+
+**The transformation:**
+
+- **Before:** You describe your tools to Claude, manually run queries, paste results back
+- **After:** Claude executes queries, analyzes data, and takes actions through tool APIs
+
+**We demonstrate this with Splunk**, but the same principles apply to any tool with an MCP server.
+
+## How MCPs Enhance the LOCK Workflow
+
+### Learn Phase
+
+**Without MCP:** Copy-paste threat intel into Claude
+**With MCP:** Claude queries threat intel platforms directly for TTP context
+
+### Observe Phase
+
+**Without MCP:** Manually list expected behaviors
+**With MCP:** Claude queries asset inventory to understand your environment
+
+### Check Phase
+
+**Without MCP:** Copy queries into Splunk manually
+**With MCP:** Claude executes queries and analyzes results
+
+### Keep Phase
+
+**Without MCP:** Manually create Jira tickets
+**With MCP:** Claude auto-creates tickets with findings
+
+## Getting Started
+
+Ready to try Level 3? We provide a complete Splunk MCP integration walkthrough:
+
+**[Start the Splunk walkthrough →](MCP_CATALOG.md)**
+
+Once you complete it, you'll understand how to integrate MCPs for any security tool.
+
+## Quick Example
+
+### Without MCP Integration (Level 2)
+
+```
+You: "Search for SSH brute force attempts in Splunk"
+Claude: "Here's a Splunk query you can run:
+index=linux_secure action=failure | stats count by src_ip"
+You: [Copies query to Splunk, runs it, pastes results back]
+Claude: "Based on those results, I see 3 high-volume IPs..."
+```
+
+### With MCP Integration (Level 3)
+
+```
+You: "Search for SSH brute force attempts"
+Claude: [Executes Splunk query via MCP]
+"I found 3 source IPs with high failure rates:
+- 203.0.113.45 (127 attempts)
+- 198.51.100.22 (89 attempts)
+- 192.0.2.15 (67 attempts)
+
+203.0.113.45 shows sustained activity over 2 hours. Should I pivot
+to see what accounts were targeted?"
+```
+
+The difference: **Claude executes queries and analyzes results directly, no copy-paste.**
+
+## Security Considerations
+
+### Permissions
+
+MCPs run with the credentials you provide. Follow the principle of least privilege:
+
+- **Read-only access** for SIEMs and asset inventory
+- **Create-only access** for ticketing systems
+- **No destructive permissions** (delete, modify critical data)
+
+### Guardrails
+
+Always maintain human oversight:
+
+- **Queries should be bounded** (time range, result limits)
+- **No automatic remediation** without approval
+- **Audit all MCP actions** in logs
+- **Review generated queries** before execution
+
+### Credential Management
+
+- **Never commit credentials** to your ATHF repository
+- **Use environment variables** for API keys
+- **Rotate keys regularly** per your security policy
+- **Use Claude Code's built-in permission system** to approve/deny MCP usage
+
+## What's Next?
+
+**[Start the Splunk MCP walkthrough →](MCP_CATALOG.md)**
+
+## Level 4 Preview
+
+Once you have MCP integrations working, Level 4 (Agentic) becomes possible. Instead of you asking Claude to run hunts, **autonomous agents** can:
+
+- Monitor CTI feeds and generate draft hunts
+- Execute scheduled hunts automatically
+- Enrich findings with threat intel
+- Create tickets for analyst review
+
+Level 3 gives Claude the **tools**. Level 4 gives it **agency**.
+
+## Support
+
+- **MCP Documentation:** <https://modelcontextprotocol.io>
+- **Claude Code MCP Guide:** <https://docs.claude.com/claude-code/mcp>
+- **ATHF Issues:** <https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues>
+
+Happy hunting!

athf/data/integrations/quickstart/splunk.md

@@ -0,0 +1,162 @@
+# Quickstart: Splunk MCP Integration
+
+This guide shows how to connect Claude Code to Splunk Enterprise or Splunk Cloud via the official Splunk MCP Server.
+
+## What You Get
+
+Once configured, Claude Code can:
+
+- **Query Splunk:** Run SPL searches and get results
+- **Generate SPL:** AI-assisted query generation
+- **Analyze Data:** Get insights from Splunk logs
+- **Browse Indexes:** List and explore available data sources
+
+## Prerequisites
+
+- Splunk Enterprise 8.0+ or Splunk Cloud with admin access
+- Claude Code installed
+
+## Setup Steps
+
+### Step 1: Install Splunk MCP Server App
+
+1. Download the official **Splunk MCP Server** app from [Splunkbase](https://splunkbase.splunk.com/app/7931)
+2. Install it on your Splunk instance via **Settings → Apps → Install app from file**
+3. Grant the `mcp_tool_execute` capability to your user role
+
+**Documentation:** <https://help.splunk.com/en/splunk-cloud-platform/mcp-server-for-splunk-platform/>
+
+### Step 2: Create API Token
+
+1. Log into Splunk Web
+2. Navigate to **Settings → Tokens**
+3. Click **New Token**
+4. **Set Audience to `mcp`** ⚠️ **CRITICAL** - Must be exactly `mcp`
+5. Set expiration per your security policy
+6. Copy the generated token
+
+**Important:** If audience is not set to `mcp`, connection will fail with 403 error.
+
+### Step 3: Configure Claude Code
+
+Edit your `~/.claude.json` and add the Splunk MCP server configuration to the project section:
+
+```json
+{
+  "projects": {
+    "/path/to/your/project": {
+      "mcpServers": {
+        "splunk-mcp-server": {
+          "command": "npx",
+          "args": [
+            "-y",
+            "mcp-remote",
+            "https://your-splunk-host.com:8089/services/mcp",
+            "--header",
+            "Authorization: Bearer YOUR_TOKEN_HERE"
+          ],
+          "env": {
+            "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Configuration:**
+
+- Replace `your-splunk-host.com` with your Splunk server IP or hostname
+- Replace `YOUR_TOKEN_HERE` with the token from Step 2
+- Set `NODE_TLS_REJECT_UNAUTHORIZED: "0"` if using self-signed SSL certificates (testing only)
+- For production with valid SSL certificates, remove the `env` section
+
+**Security:** Store tokens in `.env` files, not directly in `.claude.json`.
+
+### Step 4: Verify Connection
+
+```bash
+# Start Claude Code in your project directory
+cd /path/to/your/project
+claude
+
+# Verify the connection
+claude mcp list
+# Expected: splunk-mcp-server ... ✓ Connected
+```
+
+**That's it!** The Splunk MCP tools are now available.
+
+## Usage Examples
+
+Simple prompts that work once Splunk MCP is configured:
+
+```
+"Show me all available Splunk indexes"
+
+"Search Splunk for failed SSH attempts in the last 24 hours"
+
+"Search for PowerShell executions in the last 4 hours"
+
+"Generate a SPL query to find brute force authentication attempts"
+
+"Run the query from hunt hypothesis H-0001"
+```
+
+Claude will automatically:
+
+- Execute SPL queries
+- Parse and format results
+- Explain findings
+- Suggest follow-up investigations
+
+## Available Tools
+
+The Splunk MCP provides these tools:
+
+- **`run_splunk_query`** - Execute SPL searches
+- **`get_indexes`** - List available indexes
+- **`get_splunk_info`** - Get Splunk instance information
+- **`generate_spl`** - AI-assisted query generation (requires Splunk AI Assistant)
+- **`explain_spl`** - Explain what SPL queries do
+- **`optimize_spl`** - Optimize existing queries
+- **`get_knowledge_objects`** - Access saved searches and lookups
+
+## Security Considerations
+
+**Important:** Ensure you follow your organization's security policies and best practices when deploying this integration. Consider:
+
+- Implementing least-privilege access controls for the MCP user
+- Properly securing and rotating API tokens
+- Monitoring and auditing MCP server usage
+- Following your organization's SSL/TLS certificate policies
+- Storing credentials securely (not in version control)
+
+Consult the [official Splunk MCP documentation](https://help.splunk.com/en/splunk-cloud-platform/mcp-server-for-splunk-platform/) and your security team for specific requirements.
+
+## Troubleshooting
+
+**403 Error:**
+Check token audience is set to `mcp` (not `search` or `claude-code-mcp`)
+
+**Connection Failed:**
+
+- Verify port 8089 is accessible
+- For self-signed certs, add `NODE_TLS_REJECT_UNAUTHORIZED: "0"` to env
+
+**Permission Denied:**
+Grant user the `mcp_tool_execute` capability and index access
+
+**Token Expired:**
+Create a new token in Splunk Web → Settings → Tokens
+
+## Resources
+
+- **Splunk MCP Server App:** <https://splunkbase.splunk.com/app/7931>
+- **Official Documentation:** <https://help.splunk.com/en/splunk-cloud-platform/mcp-server-for-splunk-platform/>
+- **SPL Reference:** <https://docs.splunk.com/Documentation/Splunk/latest/SearchReference>
+
+---
+
+**Questions?** Open an issue in the ATHF repo or check the official Splunk MCP documentation.