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

athf/data/prompts/basic-prompts.md

@@ -0,0 +1,316 @@
+# Basic Hunt Prompts
+
+**Level:** 0-1 (Manual/Documented)
+**Purpose:** Copy-paste prompts for ChatGPT, Claude, or other AI assistants
+
+Use these prompts when you're working outside of an AI-enabled IDE and need quick assistance with hypothesis generation, query building, or documentation.
+
+---
+
+## Section 1: Generate Hypothesis
+
+Use this when you have context (CTI, alerts, anomalies) but need help forming a testable hypothesis.
+
+### Prompt Template
+
+```
+You are a threat hunting expert helping generate behavior-based hunt hypotheses.
+
+CONTEXT:
+[Paste your context here - CTI snippet, alert, baseline drift, or gap]
+
+RULES:
+1. Generate 1-3 tightly scoped hypotheses
+2. Each hypothesis must follow this pattern: "Adversaries use [behavior] to [goal] on [target]"
+3. Focus on observable behaviors in data, not indicators
+4. Include relevant ATT&CK technique (T####)
+5. Keep hypotheses specific and testable
+
+OUTPUT FORMAT:
+For each hypothesis provide:
+- Hypothesis statement
+- ATT&CK Technique
+- Tactic
+- Data sources needed (e.g., "Windows Event Logs, Sysmon")
+- Why this is worth hunting now
+
+EXAMPLE OUTPUT:
+Hypothesis: "Adversaries use base64-encoded PowerShell commands to establish persistence on Windows servers"
+ATT&CK: T1059.001 (PowerShell)
+Tactic: TA0003 (Persistence)
+Data Needed: Sysmon Event ID 1, PowerShell logs
+Why Now: Recent CTI shows APT29 using this technique; baseline shows low historical usage on servers
+
+Generate hypothesis now:
+```
+
+### Tips
+
+- **Be specific with context** - More details = better hypotheses
+- **Ask for alternatives** - "Give me 3 different approaches"
+- **Iterate** - Refine based on what data you actually have
+- **Test for specificity** - Can you write a query from this hypothesis?
+
+### Refining Hypotheses
+
+If too broad:
+
+- Add "on [specific target]" (e.g., "on domain controllers")
+- Add time constraints (e.g., "during business hours")
+- Add environmental context (e.g., "in production network")
+
+If too narrow:
+
+- Remove overly specific indicators
+- Focus on behavior pattern, not single event
+- Generalize target or timeframe
+
+---
+
+## Section 2: Build Query
+
+Use this when you have a hypothesis and need help drafting a safe, bounded query.
+
+### Prompt Template
+
+```
+You are a threat hunting query expert. Help me write a safe, bounded query to test a hunt hypothesis.
+
+HYPOTHESIS:
+[Your hypothesis here]
+
+PLATFORM: [Splunk / KQL (Sentinel/Defender) / Elastic]
+
+DATA AVAILABLE:
+- Index/Table: [name]
+- Sourcetype/DataSource: [name]
+- Key fields: [list]
+
+CONSTRAINTS:
+1. Time range: earliest=-24h latest=now (adjust as needed)
+2. Result cap: head 1000 (or | take 1000 for KQL)
+3. Use tstats (Splunk) or summarize (KQL) when possible for performance
+4. Include metadata comments with hunt ID and ATT&CK technique
+5. Return only essential fields
+6. Add eval/extend to tag results with hunt_id and attack_technique
+
+OUTPUT FORMAT:
+Provide:
+1. The complete query
+2. Brief explanation of what it does
+3. Expected runtime estimate
+4. Suggestions for tuning if results are too noisy
+
+Generate query now:
+```
+
+### Query Templates
+
+**Splunk SPL:**
+
+```spl
+/* H-#### | ATT&CK: T#### | Purpose: [description]
+   Earliest: -24h | Latest: now | Cap: 1000 | Owner: [name] */
+
+| tstats count from datamodel=YourDataModel where
+  [your conditions]
+  by _time, host, [key_fields] span=5m
+| head 1000
+| eval hunt_id="H-####", attack_technique="T####"
+| fields _time, host, [relevant_fields], hunt_id, attack_technique
+```
+
+**KQL:**
+
+```kql
+// H-#### | ATT&CK: T#### | Purpose: [description]
+// TimeRange: ago(24h) | Cap: 1000 | Owner: [name]
+
+YourTable
+| where TimeGenerated >= ago(24h)
+| where [your conditions]
+| summarize Count=count() by bin(TimeGenerated, 5m), Computer, [key_fields]
+| take 1000
+| extend HuntId="H-####", AttackTechnique="T####"
+```
+
+### Query Best Practices
+
+**Performance:**
+
+- Use data models (Splunk) or summarize (KQL) when possible
+- Filter early - most restrictive conditions first
+- Limit fields - only return what you need
+- Set sensible time ranges - start with 24h, expand if needed
+
+**Safety:**
+
+- Always bound time - never open-ended searches
+- Always cap results - protect your SIEM
+- Test on small timeframes first - 1 hour before 24 hours
+- Use lookups for enrichment - don't join large datasets inline
+
+**Signal Quality:**
+
+- Filter known good - baseline automation, admin tools
+- Add context - enrich with asset inventory, user roles
+- Look for anomalies - rare processes, unusual times, unexpected hosts
+- Use stats wisely - count, distinct count, rare events
+
+### Troubleshooting
+
+**Too many results?**
+
+- Add more specific filters
+- Shorten time range
+- Filter out known benign activity
+- Use rare() or unusual patterns
+
+**Too few results?**
+
+- Broaden conditions
+- Check field names and values
+- Verify data is actually indexed
+- Expand time range
+
+**Query too slow?**
+
+- Use data models/accelerated searches
+- Reduce time range
+- Remove expensive operations (regex, complex joins)
+- Add index= constraints
+
+---
+
+## Section 3: Document Results
+
+Use this after executing a hunt to help write concise findings in LOCK format.
+
+### Prompt Template
+
+```
+You are a threat hunting analyst helping document hunt results following the LOCK pattern.
+
+HYPOTHESIS:
+[Your hypothesis]
+
+QUERY EXECUTED:
+[Paste query]
+
+RESULTS SUMMARY:
+- Time range: [earliest to latest]
+- Rows examined: [count]
+- Rows returned: [count]
+- Runtime: [seconds]
+- Key findings: [brief description of what you found]
+
+RAW OBSERVATIONS:
+[Paste sample results or describe what you saw]
+
+TASK:
+Write a concise summary for the KEEP section of my hunt file.
+Focus on:
+- What we found (2-4 sentences)
+- Decision (accept/reject/needs_changes) with reason
+- Next steps (one concrete action)
+- Lessons learned (one key takeaway)
+
+Keep it to 5-8 sentences total.
+
+Generate summary now:
+```
+
+### What Makes Good Documentation
+
+**Be Concise:**
+
+- 5-8 sentences total for findings
+- 3 bullet points max per section
+- Focus on signal, not every detail
+
+**Be Honest:**
+
+- Accept = Found useful signal or suspicious activity
+- Reject = Benign, false positive, or baseline noise
+- Needs Changes = Interesting but query needs refinement
+
+Don't be afraid to reject! Useful negatives teach us what's normal.
+
+**Be Specific:**
+
+- ❌ "Found some suspicious stuff, need to investigate"
+- ✅ "Found 3 hosts with encoded PowerShell outside business hours; 2 match known deployment patterns, 1 requires IR escalation"
+
+**Capture Lessons:**
+This is the most important part - it's what makes the system smarter.
+
+Good lessons:
+
+- "Baseline automation reduced signal-to-noise by 80%"
+- "Time-of-day filtering eliminated weekend maintenance jobs"
+- "Parent process context critical for distinguishing admin vs adversary"
+
+Avoid vague lessons:
+
+- "Queries should be better"
+- "Need more data"
+- "This was hard"
+
+---
+
+## Usage Notes
+
+### Workflow
+
+1. **Generate Hypothesis** - Use Section 1 with your context
+2. **Build Query** - Use Section 2 with your hypothesis
+3. **Execute Hunt** - Run query in your SIEM (test small timeframes first!)
+4. **Document Results** - Use Section 3 to capture findings
+
+### Safety Reminders
+
+- **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
+
+### Platform-Specific Tips
+
+**Splunk:**
+
+- Mention "Splunk SPL" in your prompt
+- Specify data models when available
+- AI knows common Splunk patterns
+
+**KQL (Sentinel/Defender):**
+
+- Mention "KQL for Sentinel" or "KQL for Defender"
+- Specify table names (SecurityEvent, DeviceProcessEvents, etc.)
+- AI understands Sentinel-specific syntax
+
+**Elastic:**
+
+- Mention "Elastic EQL" or "Lucene query"
+- Specify index patterns
+- Note which Elastic stack version
+
+---
+
+## Next Steps
+
+Once you're comfortable with these basic prompts:
+
+1. **Build your hunt repository** - Document hunts using [templates/HUNT_LOCK.md](../templates/HUNT_LOCK.md)
+2. **Progress to Level 2** - Use [ai-workflow.md](ai-workflow.md) for AI tools with repository access
+3. **See real examples** - Review [H-0001.md](../hunts/H-0001.md) and [H-0002.md](../hunts/H-0002.md)
+
+---
+
+## 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

athf/data/templates/HUNT_LOCK.md

@@ -0,0 +1,228 @@
+---
+hunt_id: H-XXXX
+title: [Hunt Title]
+status: planning  # Options: planning, in-progress, completed
+date: YYYY-MM-DD
+hunter: [Your Name]
+platform: [Windows, macOS, Linux, Cloud, Network]  # Array - can include multiple platforms
+tactics: [initial-access, persistence, privilege-escalation, defense-evasion, credential-access, discovery, lateral-movement, collection, command-and-control, exfiltration, impact]
+techniques: [T1003.001, T1059.001]  # MITRE ATT&CK technique IDs
+data_sources: [Splunk, ClickHouse, Sentinel, etc.]  # SIEM/log platforms used
+related_hunts: []  # Hunt IDs that relate to this hunt (e.g., [H-0001, H-0005])
+findings_count: 0  # Total findings discovered (optional - can update post-execution)
+true_positives: 0  # Count of confirmed malicious activity (optional)
+false_positives: 0  # Count of benign activity flagged (optional)
+customer_deliverables: []  # For managed service providers tracking client reports (optional)
+tags: [supply-chain, credential-theft, living-off-the-land]  # Freeform tags for categorization
+---
+
+# H-XXXX: [Hunt Title]
+
+> **Note:** YAML frontmatter above enables AI filtering and automation (Level 2+). It's optional at Level 0-1, recommended at Level 2+, required at Level 3+. The markdown metadata section below provides human-readable context.
+
+**Hunt Metadata**
+
+- **Date:** YYYY-MM-DD
+- **Hunter:** [Your Name]
+- **Status:** [Planning|In Progress|Completed]
+- **MITRE ATT&CK:** [T####.### - Technique Name]
+
+---
+
+## LEARN: Prepare the Hunt
+
+### Hypothesis Statement
+
+[Clear statement of what you're hunting for and why. Example: "Detect credential dumping attempts via mimikatz on corporate Windows servers based on recent APT29 activity patterns."]
+
+### ABLE Scoping
+
+Define your hunt scope using the ABLE framework:
+
+| **Field**   | **Your Input** |
+|-------------|----------------|
+| **Actor** *(Optional)* | [Threat actor or "N/A" - Focus on behavior first unless actor context adds value] |
+| **Behavior** | [Describe the actions, TTPs, methods, or tools involved] |
+| **Location** | [Where: endpoint, network segment, cloud environment, etc.] |
+| **Evidence** | **Source:** [Log source]<br>**Key Fields:** [field1, field2, field3]<br>**Example:** [What malicious activity looks like]<br><br>**Source:** [Additional source]<br>**Key Fields:** [field1, field2, field3]<br>**Example:** [What malicious activity looks like] |
+
+**ABLE Example:**
+
+| **Field** | **Example** |
+|-----------|-------------|
+| **Actor** | `APT29 (Cozy Bear)` |
+| **Behavior** | `Credential dumping via mimikatz.exe (T1003)` |
+| **Location** | `Corporate Windows Servers` |
+| **Evidence** | **Source:** Sysmon Event ID 1 (Process Creation)<br>**Key Fields:** process_name, command_line, parent_process, user, hash<br>**Example:** Execution of mimikatz.exe with "privilege::debug sekurlsa::logonpasswords"<br><br>**Source:** Windows Security Events 4624/4625<br>**Key Fields:** user, source_ip, event_id, timestamp<br>**Example:** Successful logon followed by high-privilege process launches |
+
+### Threat Intel & Research
+
+- **MITRE ATT&CK Techniques:**
+  - `T#### - Tactic Name`
+  - `T####.### - Technique Name`
+- **CTI Sources & References:**
+  - [Link to threat report, blog, or intel source]
+  - [Additional reference]
+- **Historical Context:**
+  - Has this been observed before in your environment?
+  - Are there existing detections or mitigations?
+  - What makes this hunt relevant now?
+
+### Related Tickets
+
+| **Team** | **Ticket/Details** |
+|----------|-------------------|
+| **SOC/IR** | [Incident ticket or "N/A"] |
+| **Threat Intel** | [TI ticket or "N/A"] |
+| **Detection Engineering** | [Detection ticket or "N/A"] |
+| **Other** | [Related context or "N/A"] |
+
+---
+
+## OBSERVE: Expected Behaviors
+
+### What Normal Looks Like
+
+[Describe legitimate activity that might trigger false positives]
+
+- [Example: System administrators running privileged commands]
+- [Example: Automated maintenance scripts]
+
+### What Suspicious Looks Like
+
+[Describe the anomalous behavior you're hunting for]
+
+- [Example: Mimikatz execution outside maintenance windows]
+- [Example: Credential access from non-admin users]
+
+### Expected Observables
+
+- **Processes:** [process_name, command_line patterns]
+- **Network:** [connections, destinations, protocols]
+- **Files:** [paths, names, hashes]
+- **Registry:** [keys, values modified]
+- **Authentication:** [logon types, privilege escalations]
+
+---
+
+## CHECK: Execute & Analyze
+
+### Data Source Information
+
+- **Index/Data Source:** [e.g., index=windows, Sysmon logs, CloudTrail]
+- **Time Range:** [Start datetime] to [End datetime]
+- **Events Analyzed:** [Number or "TBD"]
+- **Data Quality:** [Good|Fair|Poor - note any telemetry gaps]
+
+### Hunting Queries
+
+#### Initial Query
+
+```[language: spl, kql, sigma, etc.]
+[Your initial hunt query]
+```
+
+**Query Notes:**
+
+- Did this return expected results?
+- False positives encountered?
+- Gaps identified?
+
+#### Refined Query
+
+```[language]
+[Refined query after initial analysis]
+```
+
+**Refinement Rationale:**
+
+- What changed and why?
+- What improvements did this bring?
+
+### Visualization & Analytics
+
+- [Describe any time-series, heatmaps, or anomaly detection used]
+- [Note patterns observed in visualizations]
+- [Add screenshots to support findings]
+
+### Query Performance
+
+- **What Worked Well:** [Effective detection logic, good data sources]
+- **What Didn't Work:** [Query issues, detection gaps, data limitations]
+- **Iterations Made:** [Summary of query refinements]
+
+---
+
+## KEEP: Findings & Response
+
+### Executive Summary
+
+[3-5 sentences summarizing the investigation. State whether hypothesis was proved/disproved and key findings.]
+
+### Findings
+
+| **Finding** | **Ticket** | **Description** |
+|-------------|-----------|-----------------|
+| [True Positive / False Positive / Suspicious] | [INC-####] | [Brief description of finding and impact] |
+| [Finding type] | [Ticket] | [Description] |
+| [Finding type] | [Ticket] | [Description] |
+
+**True Positives:** [Count and summary]
+**False Positives:** [Count and common patterns]
+**Suspicious Events:** [Count requiring further investigation]
+
+### Detection Logic
+
+**Automation Opportunity:**
+
+- Could this hunt become an automated detection?
+- What thresholds or conditions would trigger alerts?
+- Tuning considerations to reduce false positives?
+
+**Proposed Detection:**
+
+```[language]
+[Draft detection rule if applicable]
+```
+
+### Lessons Learned
+
+**What Worked Well:**
+
+- [Successful query strategies]
+- [Effective data sources]
+- [Useful analysis techniques]
+
+**What Could Be Improved:**
+
+- [Query refinements needed]
+- [Data gaps to address]
+- [Tooling or process improvements]
+
+**Telemetry Gaps Identified:**
+
+- [Missing log sources]
+- [Insufficient field visibility]
+- [Collection improvements needed]
+
+### Follow-up Actions
+
+- [ ] [Escalate true positives to incident response]
+- [ ] [Create detection rule from hunt logic]
+- [ ] [Update hypothesis with learnings]
+- [ ] [Address telemetry gaps with engineering team]
+- [ ] [Schedule recurring hunt execution]
+- [ ] [Document findings in knowledge base]
+- [ ] [Share insights with SOC/IR/TI teams]
+
+### Follow-up Hunts
+
+[New hunt ideas spawned from this investigation]
+
+- H-XXXX: [New hunt based on findings]
+- H-XXXX: [Pivot hunt to explore related TTPs]
+
+---
+
+**Hunt Completed:** [Date]
+**Next Review:** [Date for recurring hunt or "N/A"]

agentic_threat_hunting_framework-0.2.3.dist-info/RECORD

@@ -1,23 +0,0 @@
-agentic_threat_hunting_framework-0.2.3.dist-info/licenses/LICENSE,sha256=_KObErRfiKoolznt-DF0nJnr3U9Rdh7Z4Ba7G5qqckk,1071
-athf/__init__.py,sha256=OrjZe8P97_BTEkscapnwSsqKSjwXNP9d8-HtGr19Ni0,241
-athf/__version__.py,sha256=p9cAuZ-dTEMpo-qoeYkFo2166r8LvKpa5qHBZihGq3w,59
-athf/cli.py,sha256=XLNRXEs9kHPH6utJ7_SnzLFcldbGAnACPMTe0xMOkhQ,4492
-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=2KORNWAqEvLY-Wc1q-a894g8kOpcqw_iJfnenKJeTDI,23019
-athf/commands/init.py,sha256=L_29fvZF8SZ1BKh2D6NyDuacCC5JXOTezIxdBnnK88E,10941
-athf/commands/investigate.py,sha256=mK_id5vjfN_ukqB_-fyia0FNa0pBmtn0Xv6CKHQI1Qo,24663
-athf/commands/similar.py,sha256=ROoMs4NP1otCaXwM1XzpLWxmANknoeASlBT7zuMDqas,11793
-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/utils/__init__.py,sha256=aEAPI1xnAsowOtc036cCb9ZOek5nrrfevu8PElhbNgk,30
-agentic_threat_hunting_framework-0.2.3.dist-info/METADATA,sha256=I3x8s2Rff1A7BjYz-lfy_M6I_qw0-nDBC2Ypc0DcxTA,15472
-agentic_threat_hunting_framework-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-agentic_threat_hunting_framework-0.2.3.dist-info/entry_points.txt,sha256=GopR2iTiBs-yNMWiUZ2DaFIFglXxWJx1XPjTa3ePtfE,39
-agentic_threat_hunting_framework-0.2.3.dist-info/top_level.txt,sha256=Cxxg6SMLfawDJWBITsciRzq27XV8fiaAor23o9Byoes,5
-agentic_threat_hunting_framework-0.2.3.dist-info/RECORD,,