@query-ai/digital-workers 1.0.0

package/skills/threat-intel-enricher/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: threat-intel-enricher
+description: Use when IOCs (IP addresses, file hashes, domains, URLs) need reputation checks, campaign correlation, or threat actor attribution
+---
+
+# Threat Intel Enricher
+
+## Iron Law
+
+**REPUTATION IS CONTEXT, NOT VERDICT.**
+
+A "clean" reputation does not mean safe. A "malicious" reputation does not mean confirmed compromise. Reputation informs the investigation — it does not conclude it.
+
+## When to Invoke
+
+Called by `alert-investigation` or any investigator skill when IOCs need enrichment:
+- IP addresses (source or destination)
+- File hashes (MD5, SHA1, SHA256)
+- Domain names
+- URLs
+- Email addresses (sender reputation)
+
+## Process
+
+### Step 1: Categorize IOCs
+
+Group extracted IOCs by type:
+- **IP addresses**: Source IPs, destination IPs, intermediate IPs
+- **Hashes**: File hashes from process activity, email attachments
+- **Domains**: DNS queries, email sender domains, URL hostnames
+- **Email addresses**: Sender addresses from phishing investigations
+
+### Step 1.5: Assess IOC Availability
+
+Before querying, check whether expected IOC types are actually available in the investigation data:
+
+1. **Malware detections without file hashes**: If findings reference malware families but all hash fields are empty, document: "File hashes not available in detection findings — hash-based threat intel lookup not possible."
+2. **Network detections without external IPs**: If findings reference network activity but only internal IPs are present, document: "No external IPs in detection findings — IP reputation lookup limited to internal context."
+3. **State the confidence ceiling**: "Without [IOC type], independent verification is limited to vendor labels. Attribution confidence cannot exceed MEDIUM."
+
+If no enrichable IOCs exist at all, state this as an explicit finding rather than silently returning nothing:
+
+```
+THREAT INTELLIGENCE:
+  Result: ENRICHMENT NOT POSSIBLE
+  Reason: No enrichable IOCs available (file hashes empty, no external IPs, no domains)
+  Impact: Investigation cannot independently verify vendor detection labels.
+         Attribution confidence is capped at MEDIUM.
+  Attempted: [list of field paths checked and their values]
+```
+
+### Step 2: Query the Mesh for Threat Intel
+
+Use `digital-workers:fsql-expert` to search for IOC context within the mesh:
+
+```
+-- Layer 1a: Discovery scan — find which event types contain the IOC (never overflows)
+QUERY *.message, *.time WITH %ip = '<ioc_ip>' AFTER 30d
+QUERY *.message, *.time WITH %hash = '<ioc_hash>' AFTER 7d
+QUERY *.message, *.time WITH %domain = '<ioc_domain>' AFTER 7d
+
+-- Layer 1b: Targeted detail — query specific event types found in Layer 1a
+QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id,
+      detection_finding.time, detection_finding.observables
+WITH %ip = '<ioc_ip>' AND detection_finding.status_id = NEW AFTER 30d
+```
+
+### Step 3: Assess Reputation
+
+For each IOC, determine:
+- **Known malicious**: Appears in threat intel feeds, associated with known campaigns
+- **Suspicious**: Limited negative indicators, no positive reputation
+- **Unknown**: No intelligence available (which is itself noteworthy)
+- **Known good**: Recognized legitimate service, CDN, cloud provider
+
+### Step 4: Campaign Correlation
+
+If IOCs match known threat intelligence:
+- Identify the threat actor or campaign name
+- Document associated TTPs (MITRE ATT&CK)
+- List other IOCs associated with the same campaign
+- Search the mesh for those additional IOCs:
+
+```
+QUERY %ip IN '<related_ip_1>', '<related_ip_2>' AFTER 30d
+```
+
+### Step 5: Historical Context
+
+For each IOC, check if it has been seen before in this environment:
+- First seen date
+- Frequency of occurrence
+- Which systems have interacted with it
+- Whether it's been previously investigated
+
+## Output
+
+```
+THREAT INTELLIGENCE:
+  IOC: [value] ([type])
+  Reputation: [Known Malicious / Suspicious / Unknown / Known Good]
+  Confidence: [High / Medium / Low]
+
+  Campaign Association: [campaign name or "None identified"]
+  Threat Actor: [actor name or "Unknown"]
+  Associated TTPs: [MITRE technique IDs]
+  Related IOCs: [list of associated indicators]
+
+  Historical Context:
+    First seen in environment: [date or "Never"]
+    Frequency: [count over time period]
+    Systems affected: [list]
+    Previously investigated: [Yes/No — reference if yes]
+
+  Assessment: [Plain language summary of what this IOC means for the investigation]
+```
+
+**Return this enrichment output to the calling orchestrator and continue. Do not present to the user or wait for input.**
+
+## Red Flags
+
+| Red Flag | Correct Action |
+|----------|---------------|
+| "IP is clean on reputation, so it's safe" | STOP. Reputation is one signal. New C2 infrastructure won't have reputation yet. |
+| "No threat intel available, skip enrichment" | STOP. Unknown reputation IS a finding. Document it. An unknown IP connecting to internal systems is noteworthy. |
+| "This is a known cloud provider IP, it's fine" | STOP. Cloud IPs host malicious infrastructure too. Check what specific service/resource it points to. |
+| "No IOCs to enrich, skipping" without documenting the gap | STOP. Inability to enrich is itself a finding. Document what IOC types are missing, why, and how it limits conclusions. |

package/skills/using-digital-workers/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: using-digital-workers
+description: Use when starting any session where security investigation may be needed — establishes how to find and invoke Digital Workers skills
+---
+
+# Using Digital Workers
+
+## Overview
+
+Digital Workers is a security operations framework built on the Query Data Mesh. It provides composable skills for two workflows: **reactive alert investigation** (triage, enrich, disposition) and **proactive threat hunting** (hypothesis-driven Sqrrl hunting loop with detection automation).
+
+## Available Skills
+
+| Skill | Invoke When |
+|-------|------------|
+| `digital-workers:alert-investigation` | User asks to investigate alerts, triage findings, or run the Discovery workflow |
+| `digital-workers:fsql-expert` | Any FSQL query needs to be authored, validated, or executed |
+| `digital-workers:alert-classifier` | An alert needs OCSF categorization or MITRE ATT&CK mapping |
+| `digital-workers:severity-scorer` | Alert severity needs multi-factor risk scoring |
+| `digital-workers:identity-investigator` | Investigation involves user accounts, authentication, or identity |
+| `digital-workers:network-investigator` | Investigation involves network activity, lateral movement, or C2 |
+| `digital-workers:threat-intel-enricher` | IOCs (IPs, hashes, domains) need reputation/campaign lookup |
+| `digital-workers:report-writer` | Investigation findings need to be formatted as a response-ready report |
+| `digital-workers:evidence-quality-checker` | Evidence quality checkpoint invoked at Gate 2 and Gate 3 exits — verifies status filtering, data completeness, and analytical reasoning |
+| `digital-workers:senior-analyst-review` | A completed investigation needs quality review (auto on HIGH/CRITICAL, or invoke manually) |
+| `digital-workers:threat-hunt` | User asks to hunt for threats, test a hypothesis, proactively search for TTPs, or asks "what should I hunt?" |
+| `digital-workers:hypothesis-builder` | Convert raw intel, MITRE technique IDs, or analyst hunches into a structured, testable hunting hypothesis |
+| `digital-workers:hunt-pattern-analyzer` | Classify hunt findings — Active Threat, Historical, Suspicious, Coverage Gap, or Clean — and map to ATT&CK |
+| `digital-workers:detection-engineer` | Convert hunt findings to FSQL detections, Sigma rules, and Query platform recipes; produce gap remediation plans |
+| `digital-workers:hunt-quality-checker` | Hunt process checkpoint invoked at Phase 2 exit — verifies hypothesis exists, data map exists, all TTPs tested, confidence tracked, and artifacts current |
+
+## How to Invoke
+
+Use the `Skill` tool: `skill: "digital-workers:alert-investigation"`
+
+## When the User Asks to Investigate
+
+If the user asks to investigate alerts, triage security events, or anything related to reactive security operations:
+
+1. **Invoke `digital-workers:alert-investigation`** — this is the master orchestrator
+2. The orchestrator will invoke specialized skills as needed based on findings
+3. Do NOT invoke specialized skills directly unless the user specifically asks for one
+
+## When the User Asks to Hunt
+
+If the user asks to hunt for threats, test a hypothesis, search for TTPs, check exposure to a threat actor, or asks "what should I hunt?":
+
+1. **Invoke `digital-workers:threat-hunt`** — this is the hunting orchestrator
+2. The orchestrator runs the 4-phase Sqrrl loop: Hypothesis → Investigate → Discover Patterns → Automate Detections
+3. It will invoke `hypothesis-builder`, `hunt-pattern-analyzer`, and `detection-engineer` as needed
+4. Do NOT invoke hunting sub-skills directly unless the user specifically asks for one
+
+**Example hunting prompts:**
+- "Hunt for lateral movement via RDP from service accounts"
+- "I read about Volt Typhoon — check our environment"
+- "Test our visibility against T1059.001 PowerShell fileless execution"
+- "What should I hunt next?"
+- "Here's a threat advisory — build a hunt from it" (paste or URL)
+
+## Key Principles
+
+- **Recommend, don't declare.** The worker proposes dispositions and recommends escalation. It never formally declares incidents or assigns final dispositions — those are human decisions with compliance and business implications.
+- **Evidence before claims.** Every conclusion must cite the FSQL query and data that supports it.
+- **Stage gates are mandatory.** Do not skip steps in the Discovery workflow.
+- **Show confidence.** Label every finding: Confirmed / High / Medium / Low / Insufficient Data.
+- **State unknowns.** Explicitly say what couldn't be determined and why.
+- **Follow the process.** The same investigation workflow runs every time, regardless of perceived simplicity.
+
+## Global Rule: No Bash Processing of Data
+
+**NEVER use Bash, cat, python, jq, or any shell command to process, parse, filter, or extract data from MCP tool results or investigation data.** This applies to the ENTIRE investigation — not just FSQL queries.
+
+- MCP tool results returned inline → analyze directly (you are an LLM, you parse JSON natively)
+- MCP tool results saved to a file (too large for context) → **DO NOT read or process the file.** Re-run the query with specific field selectors instead of `**`. A file-overflow means the query was too broad. Example: replace `QUERY ** WITH %hash = 'abc'` with `QUERY detection_finding.message, detection_finding.severity_id, detection_finding.time WITH %hash = 'abc'`
+
+**Never Bash. Never cat. Never python. Never jq. If results overflow, re-query with narrower selectors.**