@query-ai/digital-workers 1.0.0

package/skills/fsql-expert/fsql-reference.md

@@ -0,0 +1,525 @@
+# FSQL Investigation Cheat Sheet
+
+> **This is a quick-reference supplement, not the complete syntax reference.** For full FSQL syntax (all ~40 observable types, SUMMARIZE/GROUP BY, set operations, depth modifiers), read the MCP resource `fsql://docs/syntax-reference` via `ReadMcpResourceTool`.
+
+## Query Structure
+
+```
+QUERY <fields> [WITH <filters>] [BEFORE <end>] [AFTER <start>] [FROM <connectors>]
+```
+
+Alternative (filter-first):
+```
+QUERY <filter> [SHOW <fields>] [BEFORE <end>] [AFTER <start>] [FROM <connectors>]
+```
+
+## Selectors
+
+| Selector | Description | Example |
+|----------|-------------|---------|
+| `.` | Direct path | `authentication.user.username` |
+| `*` | All fields at level | `authentication.*` |
+| `**` | All fields recursively | `authentication.**` |
+| `#` | Category (all events in category) | `#network.*` |
+| `%` | Observable (searches all matching fields) | `%ip`, `%hash`, `%email`, `%username`, `%domain` |
+| `@` | Type filter | `@ip`, `@user` |
+
+## Operators
+
+| Operator | Aliases | Description |
+|----------|---------|-------------|
+| `=` | | Equals |
+| `==` | | Case-insensitive equals |
+| `!=` | | Not equals |
+| `CONTAINS` | `~` | Contains substring |
+| `ICONTAINS` | `~~` | Case-insensitive contains |
+| `STARTSWITH` | `^=` | Starts with |
+| `ENDSWITH` | `$=` | Ends with |
+| `IN` | | In list (comma-separated) |
+| `<`, `>`, `<=`, `>=` | | Numeric comparison |
+| `empty` | | Field is null/empty |
+| `ANY` | | Array quantifier: any element matches |
+| `ALL` | | Array quantifier: all elements match |
+
+## Combining Filters
+
+- `AND` — both conditions must match
+- `OR` — at least one must match
+- Parentheses for grouping: `(A OR B) AND C`
+
+## Time Ranges
+
+- `AFTER 24h` — data from at least 24 hours ago
+- `BEFORE 12h` — data from up to 12 hours ago
+- Units: `h/hr/hrs`, `d/day/days`, `w/week/weeks`, `m/month/months`
+
+## Data Sources
+
+```
+FROM 'Crowdstrike Falcon', 'AWS CloudTrail', 'Splunk'
+```
+
+## EXPLAIN Commands (Schema Discovery)
+
+```
+EXPLAIN ATTRIBUTES network_activity.%ip     -- List all IP fields in network_activity
+EXPLAIN SCHEMA network_activity.proxy.%ip   -- Schema details for matching fields
+EXPLAIN GRAPHQL QUERY ...                   -- Translate FSQL to GraphQL (validation)
+```
+
+## Key OCSF Event Types
+
+| Category | Events | Use For |
+|----------|--------|---------|
+| Findings | `detection_finding`, `security_finding`, `vulnerability_finding` | Alerts, detections |
+| Identity | `authentication`, `account_change`, `authorize_session` | Auth analysis |
+| Network | `network_activity`, `http_activity`, `dns_activity`, `ssh_activity`, `email_activity` | Network investigation |
+| System | `process_activity`, `file_activity`, `module_activity` | Endpoint investigation |
+| Application | `api_activity`, `web_resource_activity` | Cloud/app investigation |
+
+## Investigation Query Patterns
+
+### Discovery Scans (Layer 1a — always start here)
+
+Use `*.message, *.time` to find which event types have data for IOCs, without overflowing. The `__event` field in results tells you the event type.
+
+**BATCH same-type IOCs using `IN` — one query per IOC type, not one per IOC:**
+
+```
+-- Discover where multiple IPs appear (1 query instead of 5)
+QUERY *.message, *.time WITH %ip IN '10.0.0.1', '10.0.0.2', '10.0.0.3', '10.0.0.4', '10.0.0.5' AFTER 7d
+
+-- Discover where multiple hashes appear
+QUERY *.message, *.time WITH %hash IN '44d88612fea8a8f36de82e1278abb02f', 'abc123def456' AFTER 7d
+
+-- Discover where multiple usernames appear
+QUERY *.message, *.time WITH %username IN 'jsmith', 'jdoe', 'admin' AFTER 7d
+
+-- Single IOC is fine too
+QUERY *.message, *.time WITH %domain = 'evil.com' AFTER 7d
+```
+
+**NEVER use `QUERY ** WITH %observable` or bare `QUERY %observable` — these return full OCSF events and will overflow.**
+
+### Aggregation Patterns (SUMMARIZE — after discovery)
+
+Use SUMMARIZE when you need counts or distributions instead of individual events. Always after Layer 1a/1b identifies what you're looking at. Pass SUMMARIZE queries to `Validate_FSQL_Query` the same as QUERY (the tool prepends `VALIDATE` automatically — do NOT include `VALIDATE` in the query string). All fields must reference the same OCSF event class.
+
+**Execution constraints:** `status_id = NEW` filtering fails on detection_finding (use GROUP BY status_id instead). `FROM` clause not supported. High-cardinality GROUP BY (IPs, hashes) can overflow — scope with a WITH filter. email_activity and file_activity SUMMARIZE execution fails. If SUMMARIZE returns empty, fall back to QUERY. Check `summarize_support` in the environment profile before querying.
+
+**Alert triage — severity and status distribution:**
+```
+-- How many alerts by type? (GROUP BY status_id to separate NEW from RESOLVED in results)
+SUMMARIZE COUNT detection_finding.message GROUP BY detection_finding.message, detection_finding.status_id
+AFTER 24h
+
+-- Status distribution (are these NEW or already RESOLVED?)
+SUMMARIZE COUNT detection_finding.status_id GROUP BY detection_finding.status_id
+WITH detection_finding.severity_id IN HIGH, CRITICAL AFTER 7d
+
+-- Severity breakdown with status
+SUMMARIZE COUNT detection_finding.severity_id GROUP BY detection_finding.severity_id, detection_finding.status_id
+AFTER 24h
+```
+
+**Scope assessment — how many hosts/users/IPs are affected?**
+```
+-- Per-host alert count with status (filter NEW in results, not in query)
+SUMMARIZE COUNT detection_finding.message GROUP BY detection_finding.device.hostname, detection_finding.status_id
+WITH detection_finding.severity_id IN HIGH, CRITICAL AFTER 24h
+
+-- Per-host alert count over wider window
+SUMMARIZE COUNT detection_finding.message GROUP BY detection_finding.device.hostname, detection_finding.status_id
+AFTER 7d
+
+-- Unique users in authentication events
+SUMMARIZE COUNT DISTINCT authentication.actor.user.email_addr
+WITH authentication.status_id = FAILURE AFTER 24h
+```
+
+**Identity investigation — auth failure distribution:**
+```
+-- Failure count by source IP (spray detection)
+SUMMARIZE COUNT authentication.user.uid GROUP BY authentication.src_endpoint.ip
+WITH authentication.status_id = FAILURE AFTER 24h
+
+-- Distinct users per source IP (credential stuffing signal)
+SUMMARIZE COUNT DISTINCT authentication.actor.user.email_addr
+GROUP BY authentication.src_endpoint.ip
+WITH authentication.status_id = FAILURE AFTER 24h
+
+-- Distinct IPs per user (impossible travel signal)
+SUMMARIZE COUNT DISTINCT authentication.device.ip
+GROUP BY authentication.actor.user.email_addr
+WITH authentication.status_id = SUCCESS AFTER 24h
+```
+
+**Network investigation — connection volume and port distribution:**
+```
+-- Outbound connection count by source (scanning detection)
+SUMMARIZE COUNT network_activity.message GROUP BY network_activity.src_endpoint.ip
+WITH network_activity.src_endpoint.ip IN '10.0.0.1', '10.0.0.2' AFTER 7d
+
+-- Unique destination ports (port scan breadth)
+SUMMARIZE COUNT DISTINCT network_activity.dst_endpoint.port
+WITH network_activity.src_endpoint.ip = '10.0.0.1' AFTER 7d
+```
+
+**False positive verification:**
+```
+-- Confirm all instances of an alert are resolved
+SUMMARIZE COUNT detection_finding.status_id GROUP BY detection_finding.status_id
+WITH detection_finding.message = 'Yttrium Actor activity detected' AFTER 7d
+-- If result shows 100% RESOLVED → confirmed false positive pattern
+```
+
+**Hash/observable distribution across event types:**
+```
+-- Which event types have hits for a hash? (complements Layer 1a discovery)
+-- Note: Use Layer 1a (*.message, *.time) first. Use SUMMARIZE to quantify.
+SUMMARIZE COUNT detection_finding.message GROUP BY detection_finding.message
+WITH %hash = 'f6c3023f' AFTER 7d
+```
+
+### Targeted Follow-Ups (Layer 1b — after discovery)
+
+Once you know which event types have hits, query specific fields:
+
+```
+-- Pull new high/critical alerts (ALWAYS use status_id = NEW)
+QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id,
+      detection_finding.time, detection_finding.observables, detection_finding.attacks
+WITH detection_finding.severity_id IN HIGH, CRITICAL, FATAL
+AND detection_finding.status_id = NEW AFTER 24h
+
+-- Auth failures for a user
+QUERY authentication.message, authentication.time, authentication.status_id,
+      authentication.src_endpoint.ip, authentication.user.username
+WITH authentication.user.username = 'jsmith' AND authentication.status_id = FAILURE AFTER 7d
+
+-- Email activity for phishing investigation
+QUERY email_activity.message, email_activity.time, email_activity.actor.user.email_addr,
+      email_activity.email.subject
+WITH %email = 'suspect@evil.com' AFTER 7d
+
+-- Process activity (suspicious execution)
+QUERY process_activity.message, process_activity.time, process_activity.device.hostname,
+      process_activity.process.cmd_line
+WITH process_activity.process.cmd_line CONTAINS 'powershell'
+AND process_activity.process.cmd_line CONTAINS 'hidden' AFTER 24h
+```
+
+### Per-Host Deep Dives (priority hosts only)
+
+After identifying the 2-5 most suspicious hosts, run per-host queries with wider lookback:
+
+```
+-- Detections on a single host (7d lookback for multi-day patterns)
+QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id,
+      detection_finding.time, detection_finding.attacks
+WITH detection_finding.device.hostname = 'BD-2578' AFTER 7d
+
+-- Full process activity on a single host (scoped — ** is OK here)
+QUERY process_activity.** WITH process_activity.device.hostname = 'BD-2578' AFTER 24h
+
+-- All network activity from a single host
+QUERY #network.src_endpoint.ip, #network.dst_endpoint.ip, #network.dst_endpoint.port,
+      #network.message, #network.time
+WITH #network.src_endpoint.hostname = 'BD-2578' AFTER 48h
+```
+
+---
+
+## Pivoting from Findings to Telemetry
+
+**The most common investigation mistake is staying in `detection_finding` for the entire investigation.** Detection findings tell you *what an alert fired on*. Telemetry event types tell you *what actually happened*. You need both.
+
+### When to Pivot
+
+After Gate 1 (intake) or Gate 2 (enrichment), once you know which hosts and IOCs are involved, **always query the underlying telemetry**. The pivot depends on what the alert is about:
+
+| Alert Type | Pivot To | Why |
+|------------|----------|-----|
+| Suspicious process/script execution | `process_activity` | See the actual command lines, parent processes, execution chains |
+| Malware/file-based alert | `file_activity` | See file creation, modification, drops on the host |
+| Network/C2/lateral movement | `network_activity`, `dns_activity`, `http_activity` | See actual traffic flows, DNS lookups, HTTP connections |
+| Identity/auth anomaly | `authentication` | See login patterns, source IPs, success/failure over time |
+| Email/phishing | `email_activity` | See delivery chain, recipients, attachment metadata |
+| Cloud/API abuse | `api_activity` | See actual API calls, who made them, from where |
+| DLL sideloading/injection | `module_activity` | See DLL loads, image load events |
+| Registry persistence | `evidence_info` | See registry key changes (from XDR connectors) |
+
+### The Pivot Pattern
+
+```
+-- Step 1: You have a detection finding about PowerShell on BD-3263
+--         (from Gate 1 intake)
+
+-- Step 2: PIVOT — query process_activity for actual PS execution on that host
+QUERY process_activity.message, process_activity.time,
+      process_activity.process.name, process_activity.process.cmd_line,
+      process_activity.actor.process.name, process_activity.device.hostname
+WITH process_activity.device.hostname = 'BD-3263'
+AND %process_name = 'powershell.exe' AFTER 7d
+
+-- Step 3: EXPAND — what else ran on that host around the same time?
+QUERY process_activity.message, process_activity.time,
+      process_activity.process.name, process_activity.process.cmd_line,
+      process_activity.actor.process.name
+WITH process_activity.device.hostname = 'BD-3263' AFTER 24h
+
+-- Step 4: CORRELATE — check file drops too
+QUERY file_activity.message, file_activity.time,
+      file_activity.file.name, file_activity.file.path,
+      file_activity.device.hostname
+WITH file_activity.device.hostname = 'BD-3263' AFTER 24h
+```
+
+---
+
+## Event-Type Query Patterns by Investigation Need
+
+### Endpoint / Process Investigation
+
+**When to use:** Any alert involving process execution, script activity, suspicious commands, fileless attacks, LOLBins.
+
+**Available data:** 4 connectors provide `process_activity` (CarbonBlack, XDR, Kalibr SYSLOG).
+
+**Key observables:** `%process_name`, `%command_line`, `%script_content`, `%file_name`
+
+```
+-- Process execution by name on a host
+QUERY process_activity.message, process_activity.time,
+      process_activity.process.name, process_activity.process.cmd_line,
+      process_activity.actor.process.name, process_activity.device.hostname
+WITH process_activity.device.hostname = 'BD-3263'
+AND %process_name = 'powershell.exe' AFTER 7d
+
+-- Suspicious command line patterns (encoded commands, download cradles)
+QUERY process_activity.message, process_activity.time,
+      process_activity.process.cmd_line, process_activity.device.hostname
+WITH %command_line ICONTAINS '-encodedcommand' AFTER 24h
+
+QUERY process_activity.message, process_activity.time,
+      process_activity.process.cmd_line, process_activity.device.hostname
+WITH %command_line ICONTAINS 'downloadstring' AFTER 24h
+
+-- Who launched what? (parent process analysis)
+QUERY process_activity.message, process_activity.time,
+      process_activity.process.name, process_activity.process.cmd_line,
+      process_activity.actor.process.name
+WITH process_activity.device.hostname = 'BD-3263'
+AND process_activity.actor.process.name = 'cmd.exe' AFTER 24h
+
+-- All process activity on a host (scoped — ** OK for single host)
+QUERY process_activity.** WITH process_activity.device.hostname = 'BD-3263' AFTER 24h
+```
+
+**File activity (file drops, malware staging):**
+
+Available data: 2 connectors (CarbonBlack, XDR).
+
+```
+-- Files created/modified on a host
+QUERY file_activity.message, file_activity.time,
+      file_activity.file.name, file_activity.file.path,
+      file_activity.device.hostname
+WITH file_activity.device.hostname = 'BD-3263' AFTER 24h
+
+-- Search for a specific file by name
+QUERY file_activity.message, file_activity.time,
+      file_activity.file.name, file_activity.file.path,
+      file_activity.device.hostname
+WITH %file_name ICONTAINS 'ContentServer.exe' AFTER 7d
+
+-- Search for a file by hash
+QUERY file_activity.message, file_activity.time,
+      file_activity.file.name, file_activity.device.hostname
+WITH %hash = 'e7fc03267e47814e23e004e5f3a1205b' AFTER 7d
+```
+
+**Module/DLL activity (sideloading, injection):**
+
+Available data: 1 connector (XDR DevImgLoad).
+
+```
+QUERY module_activity.message, module_activity.time,
+      module_activity.module.file.name, module_activity.device.hostname
+WITH module_activity.device.hostname = 'BD-3263' AFTER 24h
+```
+
+**Registry activity (persistence, IFEO, AppCertDLLs):**
+
+Available data: 1 connector (XDR DevRegEvts) via `evidence_info`.
+
+```
+QUERY evidence_info.message, evidence_info.time,
+      evidence_info.device.hostname
+WITH evidence_info.device.hostname = 'BD-3263' AFTER 7d
+```
+
+### Identity / Authentication Investigation
+
+**When to use:** Unfamiliar sign-in, brute force, account compromise, privilege escalation alerts.
+
+**Available data:** 5+ connectors (Entra ID, Okta, device logon events).
+
+**Key observables:** `%username`, `%email`, `%ip`
+
+```
+-- Login history for a user (success and failure)
+QUERY authentication.message, authentication.time, authentication.status_id,
+      authentication.src_endpoint.ip, authentication.user.username,
+      authentication.http_request.user_agent
+WITH authentication.user.username = 'jsmith' AFTER 7d
+
+-- Failed logins only (brute force detection)
+QUERY authentication.message, authentication.time, authentication.status_id,
+      authentication.src_endpoint.ip, authentication.user.username
+WITH authentication.user.username = 'jsmith'
+AND authentication.status_id = FAILURE AFTER 7d
+
+-- All logins from a suspicious IP
+QUERY authentication.message, authentication.time,
+      authentication.user.username, authentication.status_id
+WITH %ip = '136.179.10.135' AFTER 7d
+
+-- Account changes (privilege escalation, group membership)
+QUERY account_change.message, account_change.time,
+      account_change.user.username, account_change.type_name
+WITH %username = 'jsmith' AFTER 7d
+```
+
+### Network Investigation
+
+**When to use:** C2 communication, lateral movement, port scanning, data exfiltration alerts.
+
+**Available data:** `network_activity` (2 connectors: VPC Flow, IPS/IDS), `dns_activity` (1: Route53), `http_activity` (4: WAF, URL filtering, Cribl).
+
+**Key observables:** `%ip`, `%domain`, `%url`, `%http_user_agent`
+
+```
+-- Network flows from/to a suspicious IP
+QUERY network_activity.message, network_activity.time,
+      network_activity.src_endpoint.ip, network_activity.dst_endpoint.ip,
+      network_activity.dst_endpoint.port, network_activity.traffic.bytes_in,
+      network_activity.traffic.bytes_out
+WITH %ip = '10.100.21.239' AFTER 7d
+
+-- Using category selector for all network event types at once
+QUERY #network.src_endpoint.ip, #network.dst_endpoint.ip,
+      #network.dst_endpoint.port, #network.message, #network.time
+WITH #network.src_endpoint.ip = '172.16.16.58' AFTER 48h
+
+-- DNS lookups from a host (beaconing, C2 domains)
+QUERY dns_activity.message, dns_activity.time,
+      dns_activity.query.hostname, dns_activity.src_endpoint.ip
+WITH dns_activity.src_endpoint.ip = '172.16.16.58' AFTER 7d
+
+-- DNS lookups for a specific domain
+QUERY dns_activity.message, dns_activity.time,
+      dns_activity.query.hostname, dns_activity.src_endpoint.ip
+WITH %domain ICONTAINS 'evil.com' AFTER 7d
+
+-- HTTP activity (C2 callbacks, download URLs)
+QUERY http_activity.message, http_activity.time,
+      http_activity.src_endpoint.ip, http_activity.dst_endpoint.ip,
+      http_activity.http_request.url.text
+WITH %ip = '52.39.83.27' AFTER 7d
+
+-- Suspicious user agents
+QUERY http_activity.message, http_activity.time,
+      http_activity.http_request.user_agent, http_activity.src_endpoint.ip
+WITH %http_user_agent ICONTAINS 'python-requests' AFTER 24h
+```
+
+### Email / Phishing Investigation
+
+**When to use:** Phishing delivery, malicious attachment, BEC alerts.
+
+**Available data:** 3+ connectors (Proofpoint, O365 Email Security).
+
+**Key observables:** `%email`, `%hash`, `%domain`
+
+```
+-- Emails with a specific attachment hash
+QUERY email_activity.message, email_activity.time,
+      email_activity.actor.user.email_addr, email_activity.email.subject
+WITH %hash = 'e7fc03267e47814e23e004e5f3a1205b' AFTER 7d
+
+-- Emails from a sender
+QUERY email_activity.message, email_activity.time,
+      email_activity.actor.user.email_addr, email_activity.email.subject
+WITH %email = 'attacker@evil.com' AFTER 7d
+
+-- Emails to a specific recipient
+QUERY email_activity.message, email_activity.time,
+      email_activity.actor.user.email_addr, email_activity.email.subject
+WITH %email = 'carolyn.carter@directory.query.ai' AFTER 7d
+```
+
+### Cloud / API Investigation
+
+**When to use:** Unusual API calls, cloud resource access, IAM changes, container activity.
+
+**Available data:** 5+ connectors (CloudTrail, EKS Audit, Azure Activity).
+
+**Key observables:** `%username`, `%ip`
+
+```
+-- API calls from a specific user
+QUERY api_activity.message, api_activity.time,
+      api_activity.actor.user.username, api_activity.src_endpoint.ip
+WITH %username = 'admin-service-account' AFTER 7d
+
+-- API calls from a suspicious IP
+QUERY api_activity.message, api_activity.time,
+      api_activity.actor.user.username, api_activity.src_endpoint.ip
+WITH %ip = '136.179.10.135' AFTER 7d
+```
+
+### Enrichment / OSINT Lookup
+
+**When to use:** Checking IOC reputation — hashes, IPs, domains.
+
+**Available data:** 10+ OSINT connectors (VirusTotal, AlienVault, AbuseIPDB, Shodan, etc.)
+
+```
+-- Hash reputation lookup
+QUERY osint_inventory_info.message, osint_inventory_info.time
+WITH %hash = 'e7fc03267e47814e23e004e5f3a1205b' AFTER 30d
+
+-- IP reputation lookup
+QUERY osint_inventory_info.message, osint_inventory_info.time
+WITH %ip = '136.179.10.135' AFTER 30d
+
+-- Domain reputation lookup
+QUERY osint_inventory_info.message, osint_inventory_info.time
+WITH %domain = 'evil.com' AFTER 30d
+```
+
+---
+
+## Observable Quick Reference
+
+Use these `%` observables for cross-event-type searches. They search all matching fields across all event types automatically.
+
+| Observable | Matches | Best For |
+|------------|---------|----------|
+| `%ip` | All IP fields | Network IOCs, source tracking |
+| `%hash` | All hash fields (MD5, SHA1, SHA256) | Malware, file reputation |
+| `%domain` | All domain/hostname fields | C2, DNS, phishing domains |
+| `%email` | All email address fields | Phishing, identity correlation |
+| `%username` | All username fields | Identity investigation |
+| `%process_name` | All process name fields | Endpoint, malware execution |
+| `%command_line` | All command line fields | Script/LOLBin analysis |
+| `%script_content` | All script content fields | Fileless attack analysis |
+| `%file_name` | All file name fields | Malware drops, staging |
+| `%file_path` | All file path fields | File location analysis |
+| `%url` | All URL fields | C2 callbacks, downloads |
+| `%http_user_agent` | All user-agent fields | Bot/tool identification |
+| `%registry_key_path` | All registry key fields | Persistence mechanisms |
+| `%mac` | All MAC address fields | Device tracking |
+| `%port` | All port fields | Network services |
+
+---

package/skills/hunt-pattern-analyzer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: hunt-pattern-analyzer
+description: Use when hunt query results need classification — determines if findings represent active threats, historical threats, suspicious patterns, coverage gaps, or clean results
+---
+
+# Hunt Pattern Analyzer
+
+## Iron Law
+
+**ABSENCE OF EVIDENCE IS NOT EVIDENCE OF ABSENCE.**
+
+A clean result does not mean the environment is safe. It means the hypothesis was tested against available data and no evidence was found. The difference is critical — document what was tested, at what confidence, and what data was unavailable.
+
+## When to Invoke
+
+Called by `threat-hunt` orchestrator at Phase 3 after hunt investigation queries complete.
+
+## Process
+
+### Step 1: Review Hunt Queries
+
+Review the hunt's queries.md — every query executed, every result. Understand what was asked, what came back, and what returned empty.
+
+### Step 2: Review Data Availability
+
+Review the data availability map from Phase 1. Know which connectors, event types, and fields were available and which were not. This defines the ceiling of hunt confidence.
+
+### Step 3: Classify Each Finding
+
+For each finding or query result set, classify using the following table:
+
+| Type | Meaning | Action |
+|------|---------|--------|
+| Active Threat | Ongoing malicious activity | Hand off to alert-investigation immediately |
+| Historical Threat | Past activity, now dormant | Document, generate detections, recommend forensic review |
+| Suspicious Pattern | Anomalous but inconclusive | Document, recommend monitoring |
+| Coverage Gap | Data needed doesn't exist | Document gap + impact, recommend data source |
+| Clean | Hypothesis tested, no evidence | Document what was tested, note confidence |
+
+### Step 4: Map to MITRE ATT&CK
+
+Map each finding to MITRE ATT&CK techniques. This feeds detection engineering and coverage tracking. Every finding gets a technique mapping — no exceptions.
+
+### Step 5: Build Behavioral Patterns
+
+Build behavioral pattern descriptions for detection-engineer — what does this look like as a repeatable detection? Describe the observable behavior, not just the IOC.
+
+### Step 6: Cross-Reference for Kill Chains
+
+Cross-reference findings against each other — do multiple findings form a kill chain? Individual findings may look benign. Together they may form an attack chain. Map correlated findings to ATT&CK stages.
+
+### Step 7: Check for Active Threats
+
+Check for active threat indicators — if ANY finding suggests ongoing compromise:
+
+1. Immediately flag for hand-off to alert-investigation
+2. Package the evidence (queries, results, timeline, affected systems)
+3. The hunt PAUSES — active threats take priority
+
+### Step 8: Identify Coverage Gaps
+
+For each TTP in the hypothesis that could NOT be tested:
+
+1. What data was missing?
+2. Which connector/event type would fill the gap?
+3. What's the risk of the gap? (what threats are invisible?)
+
+### Step 9: Assess Hunt Confidence
+
+Assess overall hunt confidence against the Phase 1 targets: data coverage, TTP coverage, and enrichment depth.
+
+### Step 10: Assess HMM Maturity
+
+Assess HMM maturity level this hunt demonstrates. Document the justification.
+
+## Output
+
+```
+HUNT FINDINGS ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━
+Hypothesis: [hypothesis statement]
+Hunt Tier: [Focused/Broad]
+Overall Confidence: [percentage] — [above/below] 90% threshold
+
+FINDINGS:
+
+Finding 1: [title]
+  Classification: [Active Threat / Historical / Suspicious / Coverage Gap / Clean]
+  MITRE ATT&CK: [technique ID] — [technique name]
+  Evidence: [summary of supporting queries and results]
+  Behavioral Pattern: [description for detection engineering]
+  Affected Systems: [hosts/users/segments]
+  Timeline: [when activity occurred]
+  Action: [specific next step]
+
+Finding 2: [...]
+
+COVERAGE GAPS:
+  Gap 1: [description]
+    Missing: [event type / field / connector]
+    Blocks: [MITRE techniques that cannot be tested]
+    Impact: [HIGH/MEDIUM/LOW] — [what's invisible]
+    Remediation: [specific action]
+
+  Gap 2: [...]
+
+KILL CHAIN ASSESSMENT:
+  [Do the findings form a coherent attack chain? Map to ATT&CK stages]
+  [Or are they isolated, unrelated findings?]
+
+HUNT CONFIDENCE:
+  Data Coverage: [X]% — [N/M] mapped data sources queried
+  TTP Coverage: [X]% — [N/M] hypothesis behaviors tested
+  Enrichment Depth: [X]% — findings enriched with TI/context
+  Overall: [X]% — [PASS/BELOW THRESHOLD]
+
+HMM ASSESSMENT:
+  This hunt demonstrates HMM Level [N]: [brief justification]
+```
+
+**Active Threat Escalation (if applicable):**
+
+```
+ACTIVE THREAT DETECTED — Recommending hunt pause
+
+Evidence:
+  [summary of findings indicating ongoing compromise]
+
+Affected Systems: [list]
+Timeline: Active as of [most recent evidence timestamp]
+
+Recommended Action: Hand off to alert-investigation for formal triage.
+Evidence package assembled in [hunt artifact directory].
+
+Awaiting analyst decision: "escalate" to hand off, or "continue hunting" to proceed.
+```
+
+**Return findings analysis to the threat-hunt orchestrator and continue. Do not present to the user or wait for input. Exception: Active threat detection — present the escalation prompt and await analyst decision.**
+
+## Red Flags
+
+| Red Flag | Correct Action |
+|----------|---------------|
+| "No findings, the environment is clean" | STOP. Clean means the hypothesis was tested and no evidence was found. It does NOT mean the environment is safe. Document what was tested and at what confidence. |
+| Classifying a coverage gap as "clean" | STOP. If data doesn't exist to test a TTP, that's a gap, not a clean result. The difference matters for the gap remediation plan. |
+| Ignoring low-confidence findings | STOP. A suspicious pattern with 60% confidence is still a finding. Document it. Recommend monitoring. |
+| Not checking for kill chain patterns | STOP. Individual findings may look benign. Together they may form an attack chain. Always cross-reference. |
+| Skipping ATT&CK mapping | STOP. Every finding maps to a technique. This feeds detection engineering and coverage tracking. |
+| Detecting active threat and continuing the hunt | STOP. Active threats get immediate escalation to alert-investigation. The hunt pauses. |
+| Not documenting what was tested for clean results | STOP. "Clean" without documentation is meaningless. Future analysts need to know what was checked. |