@query-ai/digital-workers 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "name": "digital-workers",
+  "owner": {
+    "name": "Query.ai"
+  },
+  "metadata": {
+    "description": "Autonomous security investigation framework for the Query Data Mesh",
+    "pluginRoot": "./plugins"
+  },
+  "plugins": [
+    {
+      "name": "digital-workers",
+      "sources": [
+        {
+          "type": "npm",
+          "package": "@query-ai/digital-workers",
+          "version": "1.0.0",
+          "registry": "https://registry.npmjs.org/"
+        }
+      ],
+      "description": "Alert triage, investigation, and response-ready reporting using FSQL against the Query Data Mesh",
+      "version": "1.0.0",
+      "keywords": ["security", "investigation", "DFIR", "SOC", "FSQL", "digital-workers", "alert-triage"],
+      "category": "security operations"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "digital-workers",
+  "description": "Autonomous security investigation framework for the Query Data Mesh — alert triage, investigation, and response-ready reporting",
+  "version": "1.0.0",
+  "author": {
+    "name": "Query.ai"
+  },
+  "keywords": ["security", "investigation", "DFIR", "SOC", "FSQL", "digital-workers", "alert-triage"],
+  "skills": "./skills/",
+  "hooks": "./hooks/"
+}

package/README.md

@@ -0,0 +1,430 @@
+# Digital Workers
+
+Autonomous security operations framework for the [Query Data Mesh](https://query.ai). A Claude Code plugin that provides two workflows: **reactive alert investigation** and **proactive threat hunting** — both powered by FSQL queries against federated security data.
+
+## What It Does
+
+### Reactive: Alert Investigation
+
+Tiered Incident Discovery workflow — from a 5-minute triage to a 30-minute deep investigation with specialist analysis and senior review.
+
+```
+Step 0: SELECT TIER           → Triage / Standard / Deep (from your prompt)
+Gate 1: ALERTS INTAKE          → Pull and classify alerts
+Gate 2: GATHER INFORMATION     → Enrich IOCs, pivot to telemetry (Triage stops here)
+Gate 3: ANALYZE SITUATION      → Score severity, route depth
+Gate 4: DECIDE & ACT           → Specialists, disposition
+Gate 5: BUILD & PRIORITIZE     → Assemble evidence
+Gate 6: INCIDENT NOTIFICATION  → Report, senior review (Deep), present to analyst
+```
+
+### Proactive: Threat Hunting
+
+Sqrrl-inspired hunting loop — hypothesis-driven, confidence-based completion, with detection automation and gap remediation.
+
+```
+Phase 0: HYPOTHESIS INTAKE     → Build or receive testable hypothesis, determine hunt tier
+Phase 1: HUNT PLANNING         → Data availability mapping, connector discovery, query strategy
+Phase 2: INVESTIGATION         → Execute hunt queries, pivot, enrich (confidence-based, not query-capped)
+Phase 3: PATTERN DISCOVERY     → Classify findings, detect kill chains, escalate active threats
+Phase 4: DETECTION AUTOMATION  → Generate FSQL detections, Sigma rules, Query recipes, gap remediation
+```
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `using-digital-workers` | Meta skill — injected on session start, routes to investigation skills |
+| `alert-investigation` | Master orchestrator — runs the 6-gate Discovery workflow |
+| `fsql-expert` | Authors, validates, and executes FSQL queries against the mesh |
+| `alert-classifier` | Maps alerts to OCSF category + MITRE ATT&CK technique |
+| `severity-scorer` | Multi-factor risk scoring (5 dimensions) for depth routing |
+| `identity-investigator` | User behavior, auth patterns, privilege analysis |
+| `network-investigator` | Lateral movement, C2 beaconing, traffic analysis |
+| `threat-intel-enricher` | IOC reputation and campaign correlation |
+| `report-writer` | Response-ready reports (technical + business summary) |
+| `evidence-quality-checker` | Data completeness and analytical reasoning validation at gate exits |
+| `senior-analyst-review` | Quality review of completed investigations — evidence, logic, gaps |
+| **Hunting Skills** | |
+| `threat-hunt` | Master orchestrator — runs the 4-phase Sqrrl hunting loop |
+| `hypothesis-builder` | Transforms raw intel, MITRE techniques, or hunches into testable hypotheses |
+| `hunt-pattern-analyzer` | Classifies hunt findings and maps to ATT&CK |
+| `detection-engineer` | Converts findings to FSQL detections, Sigma rules, Query recipes; gap remediation |
+
+## Prerequisites
+
+- [Claude Code](https://claude.com/claude-code) installed
+- Access to a [Query Data Mesh](https://query.ai) deployment with MCP enabled
+- An API token for your Query MCP server
+
+## Installation
+
+### 1. Create your `.mcp.json`
+
+In your working directory (where you'll run Claude Code), create a `.mcp.json` file with your Query MCP endpoint and API token:
+
+```json
+{
+  "mcpServers": {
+    "Query-ai": {
+      "type": "http",
+      "url": "https://mcp.query.ai/mcp",
+      "headers": {
+        "x-token-authorization": "your-api-token-here"
+      }
+    }
+  }
+}
+```
+
+> **Important:** Never commit your `.mcp.json` — it contains your API credentials. Add it to your `.gitignore`.
+
+### 2. Register the plugin marketplace
+
+```bash
+claude plugin marketplace add https://plugins.query.ai/claude/digital-workers/.claude-plugin/marketplace.json
+```
+
+### 3. Install the plugin
+
+```bash
+claude plugin install digital-workers
+```
+
+### 4. Verify installation
+
+```bash
+claude plugin list
+```
+
+You should see:
+```
+❯ digital-workers@digital-workers
+  Version: 0.1.0
+  Scope: user
+  Status: ✔ enabled
+```
+
+## Operator Guide
+
+Start a new Claude Code session in a directory with your `.mcp.json`. The `using-digital-workers` meta skill is automatically injected on session start and routes your request to the investigation orchestrator.
+
+### Investigation Tiers
+
+**Your prompt controls how deep the investigation goes.** The orchestrator selects a tier based on how you phrase your request — no configuration needed.
+
+| Tier | What It Does | Time | Queries |
+|------|-------------|------|---------|
+| **Triage** | Pull alerts, classify, scan IOCs across the mesh. Inline summary, no files. | ~5 min | 3-6 |
+| **Standard** | Full 6-gate investigation with enrichment, telemetry pivots, severity scoring, disposition, report. | ~15 min | 10-15 |
+| **Deep** | Everything in Standard + specialist investigators + senior analyst review + prior investigation cross-reference. | ~30 min | 20-30 |
+
+### What Triggers Each Tier
+
+| How You Phrase It | Tier | Why |
+|-------------------|------|-----|
+| "Any suspicious PowerShell in the last 12 hours?" | Triage | Question/check — you want a quick look |
+| "What alerts fired overnight?" | Triage | Discovery question |
+| "Check for lateral movement" | Triage | Scan request |
+| "Investigate the unfamiliar sign-in alerts" | Standard | "Investigate" = action verb |
+| "Look into this hash across all sources" | Standard | "Look into" = investigation |
+| "Full investigation on the PowerShell alerts" | Deep | "Full" = explicit depth |
+| "Deep dive on BD-3263" | Deep | "Deep dive" = explicit depth |
+
+### Upgrading Mid-Investigation
+
+Tiers upgrade but never downgrade. If Triage finds something hot, it auto-upgrades to Standard:
+
+> "Upgrading to **Standard** — CRITICAL severity indicators found on 3 hosts."
+
+You can also upgrade manually at any time:
+
+```
+go deeper          → upgrades to next tier
+full investigation → upgrades to Deep
+just triage        → stays at current tier (overrides auto-upgrade)
+```
+
+### Example Prompts
+
+```
+# Triage — quick scan (~5 min)
+Any suspicious PowerShell in the last 12 hours?
+What high/critical alerts fired in the past 24 hours?
+Check for any lateral movement activity
+
+# Standard — full investigation (~15 min)
+Investigate the unfamiliar sign-in alerts from the past 24 hours
+Look into hash e7fc03267e47814e23e004e5f3a1205b
+Triage the new critical endpoint alerts
+
+# Deep — comprehensive analysis (~30 min)
+Full investigation on the PowerShell fileless execution findings
+Deep dive on host BD-3263 — possible C2 compromise
+This looks like an incident — investigate everything from the past 48 hours
+
+# Continuous monitoring (uses Triage, auto-upgrades on critical findings)
+/loop 10m Check for new high and critical alerts
+```
+
+### Threat Hunting
+
+**Proactive hunting uses the same prompt-driven approach.** State your hypothesis, provide intel, or ask for suggestions — the orchestrator handles the rest.
+
+| How You Phrase It | Hunt Mode | What Happens |
+|-------------------|-----------|-------------|
+| "Hunt for RDP lateral movement from service accounts" | Direct Hypothesis | Validates, maps to data, hunts |
+| "I read about Volt Typhoon — check our environment" | Intel-Driven | Builds hypothesis from actor TTPs, hunts |
+| "Test our visibility against T1059.001" | TTP-Driven | Maps technique to data sources, hunts |
+| "What should I hunt next?" | Suggest Mode | Analyzes coverage gaps, TI signals, recommends hunts |
+
+**Hunt tiers** (determined by hypothesis complexity, not prompt phrasing):
+
+| Tier | Scope | Circuit Breaker |
+|------|-------|----------------|
+| **Focused** | 1-2 TTPs, narrow scope | Pause at 25 min |
+| **Broad** | 3+ TTPs or environment-wide | Pause at 45 min |
+
+**Hunts use confidence-based completion** (not hard query caps). The hunt runs until it reaches 90% confidence across data coverage, TTP coverage, and enrichment depth. Circuit breakers pause (not stop) the hunt — the analyst decides whether to continue or wrap up.
+
+**Every hunt produces:**
+- Detection package (FSQL queries, Sigma rules, Query recipes)
+- Gap remediation plan (what's missing, what to deploy, prioritized by risk)
+- Full hunt report with MITRE ATT&CK mapping
+
+```
+# Hunting prompts
+Hunt for lateral movement via RDP from service accounts on the finance subnet
+I just read a CISA advisory about Volt Typhoon — test 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]
+```
+
+### Dispositions
+
+Every Standard and Deep investigation produces a **proposed** disposition:
+
+- **Critical Threat** — Confirmed malicious, recommend immediate response and incident escalation
+- **Policy Violation** — Real activity violating policy, remediation needed
+- **False Positive** — Detection logic triggered incorrectly
+- **Benign Activity** — Real but expected/authorized activity
+
+Dispositions are recommendations, not final decisions. For Critical Threats meeting incident criteria, the worker recommends escalation — the analyst decides whether to formally declare an incident.
+
+## Architecture
+
+Digital Workers is a Claude Code plugin following the standard plugin architecture:
+
+```
+digital-workers/
+├── .claude-plugin/
+│   ├── plugin.json          # Plugin manifest
+│   └── marketplace.json     # Local marketplace definition
+├── hooks/
+│   ├── hooks.json           # Session start hook config
+│   ├── run-hook.cmd         # Hook runner
+│   └── session-start        # Injects using-digital-workers on session start
+├── skills/
+│   ├── using-digital-workers/SKILL.md
+│   ├── alert-investigation/SKILL.md
+│   ├── fsql-expert/
+│   │   ├── SKILL.md
+│   │   └── fsql-reference.md
+│   ├── alert-classifier/SKILL.md
+│   ├── severity-scorer/SKILL.md
+│   ├── identity-investigator/SKILL.md
+│   ├── network-investigator/SKILL.md
+│   ├── threat-intel-enricher/SKILL.md
+│   ├── report-writer/SKILL.md
+│   ├── senior-analyst-review/SKILL.md
+│   ├── threat-hunt/SKILL.md
+│   ├── hypothesis-builder/SKILL.md
+│   ├── hunt-pattern-analyzer/SKILL.md
+│   ├── detection-engineer/SKILL.md
+│   └── templates/
+│       ├── org-policy-template.md
+│       └── runbook-template.md
+└── docs/
+    ├── design.md
+    ├── prd.md
+    └── customization-guide.md
+```
+
+### MCP Tools
+
+The Query Data Mesh exposes these tools via MCP:
+
+| Tool | Purpose |
+|------|---------|
+| `Execute_FSQL_Query` | Run a validated FSQL query against the mesh |
+| `Validate_FSQL_Query` | Check query syntax before execution |
+| `Search_FSQL_SCHEMA` | Search the OCSF schema for attributes and event types |
+| `FSQL_Connectors` | List available data source connectors |
+| `FSQL_Query_Generation` | Generate FSQL from natural language |
+| `KQL_TO_FSQL_Query_Generation` | Convert KQL queries to FSQL |
+| `SIGMA_TO_FSQL_Query_Generation` | Convert Sigma detection rules to FSQL |
+
+### FSQL (Federated Search Query Language)
+
+FSQL queries the entire mesh using OCSF-normalized schemas:
+
+```sql
+-- Discovery scan: find where an IOC appears across ALL data sources (lightweight)
+QUERY *.message, *.time WITH %ip = '10.0.0.1' AFTER 24h
+
+-- Pull new high/critical alerts with specific field selectors
+QUERY detection_finding.message, detection_finding.severity_id, detection_finding.status_id,
+      detection_finding.time, detection_finding.observables
+WITH detection_finding.severity_id IN HIGH, CRITICAL
+AND detection_finding.status_id = NEW AFTER 24h
+
+-- Pivot to telemetry: actual process execution 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
+```
+
+See `skills/fsql-expert/fsql-reference.md` for the complete query pattern reference.
+
+## Customizing for Your Organization
+
+Everything in Digital Workers is customizable through skills — no config files, no YAML, no environment variables. See the [Customization Guide](docs/customization-guide.md) for complete documentation.
+
+**Quick start:**
+
+1. Copy `skills/templates/org-policy-template.md` to `skills/your-org-policy/SKILL.md`
+2. Customize the sections you need (severity weights, crown jewels, escalation targets, etc.)
+3. The core skills automatically check for your org-policy at every gate
+
+**What you can customize:**
+
+- Alert intake scope (severities, time ranges, connectors)
+- Severity scoring weights and depth routing thresholds
+- Crown jewels / asset criticality lists
+- Incident criteria and autonomy level (auto-close vs. recommend-close)
+- Custom dispositions beyond the standard four
+- Escalation targets and notification routing
+- Report format preferences
+- Senior analyst review trigger level
+- Custom investigation runbooks for specific alert types
+
+**Templates:**
+
+| Template | Purpose |
+|----------|---------|
+| `skills/templates/org-policy-template.md` | All org-level settings — copy and customize |
+| `skills/templates/runbook-template.md` | Custom investigation SOPs — one per scenario |
+
+### Writing Custom Skills
+
+Skills are Markdown files with YAML frontmatter. Place them at `skills/<skill-name>/SKILL.md` and they're available via `digital-workers:<skill-name>`.
+
+```markdown
+---
+name: acme-vpn-investigation
+description: Use when VPN alerts fire from contractor accounts
+---
+
+# VPN Alert Investigation
+
+## Iron Law
+
+**NEVER CLOSE A VPN ALERT WITHOUT CHECKING THE CONTRACTOR SCHEDULE.**
+
+## Investigation Steps
+
+[Your org-specific investigation process]
+```
+
+### `RECIPE_FROM_FSQL_Query_Generation`
+
+The hunting workflow adds a new MCP tool to the repertoire:
+
+| Tool | Purpose |
+|------|---------|
+| `RECIPE_FROM_FSQL_Query_Generation` | Generate Query platform hunting recipes from validated FSQL queries |
+
+This tool is called by `detection-engineer` in Phase 4 to create deployable Query platform recipes from hunt findings.
+
+## Iteration History
+
+Digital Workers has been refined through real-world investigation use. Every change below is backed by specific proof points from investigations run against live security data.
+
+### v0.2.0 — Proactive Threat Hunting (March 2026)
+
+Added a complete Sqrrl-inspired threat hunting workflow alongside the existing reactive investigation capability. Designed by the CISO, built to target **Hunting Maturity Model Level 3 (HMM3)** — the system creates analytical direction, not just follows playbooks.
+
+**New skills (4):**
+- `threat-hunt` — Master orchestrator for the 4-phase Sqrrl hunting loop
+- `hypothesis-builder` — Transforms raw intel into testable hypotheses with tier determination and suggest mode
+- `hunt-pattern-analyzer` — Classifies findings (Active Threat / Historical / Suspicious / Coverage Gap / Clean)
+- `detection-engineer` — Generates FSQL detections, Sigma rules, Query recipes, and gap remediation plans
+
+**Key design decisions:**
+- **Confidence-based completion** replaces hard query caps — hunts run to 90% confidence, not an arbitrary query count
+- **Connector documentation awareness** — static vs. dynamic schema connectors handled differently, with assumptions documented
+- **MCP tools as collaborators** — iterative interaction model, not fire-and-forget
+- **Gap remediation as first-class output** — every hunt produces both detections and visibility improvement recommendations
+- **Suggest mode (HMM3)** — system recommends what to hunt based on coverage gaps, ATT&CK analysis, TI signals, and environment changes
+- **Runtime connector discovery** — no hardcoded vendor names; deploys to any Query tenant
+
+### v0.1.1 — Investigation Quality Improvements (March 2026)
+
+Based on analysis of **12 real investigations** (~100+ queries, 7 overflows, 1 false escalation), systematic improvements were made across all skills.
+
+**Query patterns**
+
+- **Layer 1a discovery pattern** — `QUERY *.message, *.time WITH %observable` replaced bare observable scans that overflowed. Proven: 264 records inline vs 1.5M char overflows. The `__event` field reveals which event types contain data — this is how the unfamiliar-signin investigation discovered 66 missed `email_activity` records showing phishing payload delivery.
+- **Narrow field selectors** — All specialists replaced broad `**` queries with specific field selectors. 0 critical findings were missed; 7 queries that used `**` or bare observables overflowed and had to be re-run.
+- **Schema-first rule** — `Search_FSQL_SCHEMA` required before querying unfamiliar event types, not after a query fails.
+- **Query budgets** — Tier-based caps (Triage: 6, Standard: 15, Deep: 30) prevent runaway investigations.
+
+**Investigation quality**
+
+- **Evidence quality checker** (new skill) — Inline quality gate at Gate 2 and Gate 3 exits. Verifies status filtering, data completeness, and analytical reasoning before proceeding.
+- **Status-aware lookbacks** — Historical alert queries now require `status_id` filtering. The YTTRIUM investigation false escalation was caused by citing ~53 RESOLVED/Benign alerts as active APT threats.
+- **Senior analyst review expanded** — Three new checks: status verification, attribution integrity, specialist invocation audit.
+- **Telemetry pivot required** — Findings alone are insufficient. Pivoting to process, network, or auth telemetry is now a hard gate requirement at Gate 2.
+
+**Reliability**
+
+- **No-stall gate transitions** — Every sub-skill now has explicit "return to orchestrator and continue" instructions, fixing investigations that stalled waiting for user input.
+- **Batch IOC discovery** — All IOCs from Gate 1 are scanned before starting targeted queries, giving the full landscape before drilling into any single indicator.
+- **Per-host deep dives** — After identifying suspicious hosts, each gets an individual 7-day lookback. This is where multi-day persistence patterns emerge.
+- **Parallel specialists** — Independent investigators (identity + network) and threat intel enrichment run concurrently.
+
+**Investigation artifacts**
+
+All investigation evidence is saved to `docs/investigations/` as a durable audit trail. Each investigation produces: `report.md` (final report), `queries.md` (every query with result counts), `iocs.md` (every IOC with type and reputation), and optionally `review.md` (senior analyst review).
+
+| Investigation | Date | Key Learning |
+|---|---|---|
+| BD-2773 compromise | Mar 11 | Scoped `**` on single-host IP was the breakthrough query |
+| High-critical alerts | Mar 11 | Hit 50-record limit on broad intake; per-host deep dives found multi-day patterns |
+| YTTRIUM APT | Mar 11 | False escalation — 30-day lookback without `status_id` filter cited RESOLVED alerts as active threats |
+| ContentServer C2 | Mar 11 | Good IOC registry and ATT&CK mapping; confirmed scoped `**` works for single-host process activity |
+| Nation-state intrusion | Mar 11 | Needs status_id verification; may share YTTRIUM false-escalation pattern |
+| Unfamiliar sign-in properties | Mar 12-13 | 4 hash scans overflowed (1.5M chars each); Layer 1a pattern would have prevented all 4; email_activity evidence missed entirely |
+| High-critical alerts 24h | Mar 13 | Query budget enforcement validated at Standard tier |
+| PowerShell fileless execution | Mar 13 | Telemetry pivot requirement caught execution patterns missed by findings alone |
+| Unfamiliar sign-in (3 runs) | Mar 13 | Efficiency testing confirmed Layer 1a + narrow selectors reduce query count by ~40% with no loss of findings |
+
+### v0.1.0 — Initial Release (March 2026)
+
+- 11-skill plugin architecture with 6-gate Discovery workflow
+- Three investigation tiers (Triage / Standard / Deep) with auto-upgrade
+- FSQL expert with layered query approach
+- Specialist investigators for identity, network, and threat intel
+- Senior analyst review with automated trigger on HIGH/CRITICAL
+- Customization via org-policy skills and runbook templates
+
+## Roadmap
+
+- **V1 (Current):** Claude Code plugin — interactive investigation with analyst in the loop
+- **V2:** Claude API integration — programmatic access, follow-up mode, configurable analyst-in-the-loop checkpoints
+- **Future:** Autonomous response actions (account disable, IOC blocking) with tiered approval model
+
+

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/run-hook.cmd

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+exec "$SCRIPT_DIR/$1"

package/hooks/session-start

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+using_dw_content=$(cat "${PLUGIN_ROOT}/skills/using-digital-workers/SKILL.md" 2>&1 || echo "Error reading using-digital-workers skill")
+
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+using_dw_escaped=$(escape_for_json "$using_dw_content")
+session_context="<IMPORTANT>\nYou have Digital Workers skills for security investigation.\n\n**Below is the 'digital-workers:using-digital-workers' skill. For all investigation skills, use the Skill tool:**\n\n${using_dw_escaped}\n</IMPORTANT>"
+
+cat <<EOF
+{
+  "additional_context": "${session_context}",
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "${session_context}"
+  }
+}
+EOF
+
+exit 0

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@query-ai/digital-workers",
+  "version": "1.0.0",
+  "description": "Autonomous security operations framework for reactive alert investigation and proactive threat hunting.",
+  "homepage": "https://plugins.query.ai/claude/digital-workers",
+  "license": "MIT",
+  "files": [
+    ".claude-plugin",
+    "skills",
+    "hooks",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/alert-classifier/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: alert-classifier
+description: Use when a security alert needs to be classified by OCSF category, MITRE ATT&CK technique, and alert type to determine investigation path
+---
+
+# Alert Classifier
+
+## Iron Law
+
+**NO INVESTIGATION PROCEEDS WITHOUT CLASSIFICATION.**
+
+Every alert must be classified before enrichment or analysis begins. Classification determines which specialized skills are invoked and what investigation path to follow.
+
+## When to Invoke
+
+Called by `alert-investigation` at Gate 1 (Alerts Intake) for every new alert.
+
+## Process
+
+### Step 1: Extract Alert Metadata
+
+From the `detection_finding` record, extract:
+- **Finding title/message** — what the detection claims happened
+- **Severity** — as reported by the source (raw, not yet scored)
+- **Source connector** — which tool generated the alert
+- **Timestamp** — when the event occurred
+- **Status** — NEW, IN_PROGRESS, etc.
+- **Any IOCs present** — IPs, hashes, domains, usernames, hostnames
+
+### Step 2: Map to OCSF Category
+
+Based on the alert content, determine which OCSF event categories are relevant:
+
+| Alert Involves | Primary OCSF Category | Key Event Types |
+|---------------|----------------------|-----------------|
+| Login failures, credential abuse, MFA bypass | Identity & Access (3) | `authentication`, `account_change` |
+| Malware, suspicious process, persistence | System Activity (1) | `process_activity`, `file_activity` |
+| Network scan, C2 beacon, lateral movement | Network Activity (4) | `network_activity`, `dns_activity`, `ssh_activity` |
+| Cloud config change, API abuse | Application Activity (6) | `api_activity`, `web_resource_activity` |
+| Email-based attack, phishing | Network Activity (4) | `email_activity` |
+| Vulnerability exploitation | Findings (2) | `vulnerability_finding` |
+| Policy violation, compliance drift | Findings (2) | `compliance_finding` |
+
+### Step 3: Map to MITRE ATT&CK Technique
+
+Based on alert content, identify the most specific ATT&CK technique:
+
+| Alert Pattern | Likely Technique | ID |
+|--------------|-----------------|-----|
+| Failed logins, credential stuffing | Valid Accounts | T1078 |
+| Phishing email detected | Phishing | T1566 |
+| Suspicious PowerShell/cmd execution | Command and Scripting Interpreter | T1059 |
+| LSASS access, credential dumping | OS Credential Dumping | T1003 |
+| New scheduled task/service | Scheduled Task/Job | T1053 |
+| Registry modification for persistence | Boot or Logon Autostart Execution | T1547 |
+| Unusual outbound connections | Application Layer Protocol (C2) | T1071 |
+| Large data transfer outbound | Exfiltration Over Web Service | T1567 |
+| Account creation/privilege escalation | Create Account / Valid Accounts | T1136/T1078 |
+| DNS tunneling, unusual DNS | Protocol Tunneling | T1572 |
+
+Use sub-techniques (T1059.001 for PowerShell) when the alert is specific enough. Use the parent technique when ambiguous.
+
+### Step 4: Determine Alert Type
+
+Classify into one of these types, which determines the investigation path:
+
+| Alert Type | Description | Primary Investigators Needed |
+|-----------|-------------|------------------------------|
+| **Identity/Access** | Auth failures, privilege escalation, account compromise | `identity-investigator` |
+| **Malware/Endpoint** | Suspicious process, file activity, persistence | (future: `endpoint-investigator`) |
+| **Network/Lateral** | Lateral movement, C2, scanning, exfiltration | `network-investigator` |
+| **Phishing/Email** | Email-based attacks, BEC, credential harvesting | (future: `email-investigator`) |
+| **Cloud/Application** | Cloud config changes, API abuse, SaaS compromise | (future: `cloud-investigator`) |
+| **Policy/Compliance** | Policy violations, compliance drift | Report only |
+
+### Step 5: Identify Initial IOCs
+
+Extract any indicators of compromise present in the alert:
+- IP addresses (source, destination)
+- File hashes (MD5, SHA1, SHA256)
+- Domain names / URLs
+- Email addresses
+- User accounts / service accounts
+- Hostnames / device names
+- Process names / command lines
+
+These IOCs will be passed to `threat-intel-enricher` and used for follow-up FSQL queries.
+
+## Output
+
+Return to the orchestrator:
+
+```
+CLASSIFICATION:
+  OCSF Category: [category name and ID]
+  MITRE ATT&CK: [technique name and ID, sub-technique if applicable]
+  Alert Type: [Identity/Access | Malware/Endpoint | Network/Lateral | Phishing/Email | Cloud/Application | Policy/Compliance]
+  Source Severity: [as reported by detection tool]
+  Initial IOCs: [list of extracted indicators]
+  Recommended Investigators: [list of specialized skills to invoke]
+```
+
+**Return this classification to the calling orchestrator and continue. Do not present to the user or wait for input — the orchestrator will use it to route the investigation.**
+
+## Red Flags
+
+| Red Flag | Correct Action |
+|----------|---------------|
+| "I can't determine the category" | Use the alert title + any field names to make best determination. Note low confidence. |
+| "This could be multiple types" | Pick the primary type. Note secondary types for the orchestrator to consider. |
+| "Skipping ATT&CK mapping, it's obvious" | STOP. Every alert gets mapped. Even obvious ones need documentation. |