From 06ab47c3bebcdd332f05086d5844e6f5e9f50db9 Mon Sep 17 00:00:00 2001 From: willwebster5 Date: Sat, 28 Mar 2026 21:54:09 -0400 Subject: [PATCH 01/14] docs: add design spec for source threat modeling and response playbooks skills Two new skills to close lifecycle gaps: source-threat-modeling (threat-model-first detection planning for sources without OOTB coverage) and response-playbooks (detection-to-response mapping with tiered playbook recommendations). Co-Authored-By: Claude Opus 4.6 (1M context) --- ...-modeling-and-response-playbooks-design.md | 326 ++++++++++++++++++ 1 file changed, 326 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-28-source-threat-modeling-and-response-playbooks-design.md diff --git a/docs/superpowers/specs/2026-03-28-source-threat-modeling-and-response-playbooks-design.md b/docs/superpowers/specs/2026-03-28-source-threat-modeling-and-response-playbooks-design.md new file mode 100644 index 0000000..67af6ea --- /dev/null +++ b/docs/superpowers/specs/2026-03-28-source-threat-modeling-and-response-playbooks-design.md @@ -0,0 +1,326 @@ +# Source Threat Modeling & Response Playbooks — Design Spec + +Two new Claude Code skills that close the gaps at the front and back of our detection lifecycle: turning a raw data source into detection coverage, and turning detections into automated response. + +## Problem + +ClaudeStrike is strong at detection authoring (`behavioral-detections`, `cql-patterns`, `logscale-security-queries`) and SOC operations (triage, hunt, tune). But two lifecycle stages are weak: + +1. **Pre-detection planning** — When a source has no OOTB templates, there's no structured way to reason about what threats apply, explore what the logs actually contain, and produce a detection backlog. Today this is ad hoc. +2. **Post-detection response** — The `fusion-workflows` skill provides the YAML schema and action discovery, but there's no layer that recommends *which* response actions fit *which* detections, and no playbook templates for common patterns. + +## Scope + +Two independent, composable skills: + +- **Source Threat Modeling** — threat-model-first detection planning for sources without OOTB coverage +- **Response Playbooks** — detection-to-response mapping and playbook templates for Fusion SOAR workflows + +Each skill is conversational and human-driven (Approach 1 — "Analyst Advisor"). No persistent catalogs or automation magic. Each produces handoff documents at skill boundaries for clean context transfer. + +--- + +## Skill 1: Source Threat Modeling + +### Purpose + +Given a data source type, produce a prioritized detection backlog grounded in MITRE ATT&CK threat models and validated against actual log data. + +### Invocation + +The skill is invoked directly by the user. It does not require a handoff doc as input, though it should accept one if provided (future-proofing for upstream orchestration). + +Typical entry: user says something like "I just connected Okta / GitHub / Cisco ASA and need detections." + +### Workflow — 4 Phases + +#### Phase 1: Source Identification + +- User names the data source (product, vendor, log type) +- Skill asks clarifying questions to establish: + - What product and log types are being ingested + - The NGSIEM repo and/or vendor filter (e.g., `#Vendor="okta"`, `#repo="some_repo"`) + - What the source is used for in the environment (identity, network, cloud infra, app-level) + - Whether any detections already exist for this source (check `resources/detections/`) +- Output: a CQL scope filter that constrains all subsequent queries + +#### Phase 2: Threat Modeling + +- Skill reasons about threats relevant to this source type +- Approach: threat-model-first — start from "what can an attacker do that this source would observe?" +- Consider three threat categories: + - **Abuse of the system the source monitors** (e.g., for Okta: credential stuffing, MFA bypass, session hijacking) + - **Compromise of the source itself** (e.g., admin account takeover, audit log tampering, config changes) + - **Lateral movement / escalation visible through the source** (e.g., privilege escalation, new admin grants) +- Map each threat scenario to MITRE ATT&CK techniques +- Output: ranked list of threat scenarios with MITRE mappings and a plain-language description of what the detection would look for + +#### Phase 3: Log Validation + +- For each threat scenario from Phase 2, run exploratory CQL queries against 7-30 days of live NGSIEM data +- Goals per scenario: + - Confirm the relevant event types exist in the data + - Understand volume and cardinality (how noisy would a detection be?) + - Identify available fields for detection logic (what can we key on?) + - Spot baseline patterns (what does "normal" look like for this event type?) +- Prune threat scenarios where the required events aren't present in the data +- Flag interesting or surprising patterns discovered during exploration (potential quick wins or unexpected activity) +- Output: validated threat scenarios annotated with event types, field availability, volume estimates, and feasibility notes + +#### Phase 4: Detection Backlog + +- Produce a prioritized list of proposed detections +- Each entry includes: + - **Threat scenario** and plain-language description + - **MITRE ATT&CK mapping** (technique ID + tactic) + - **Detection approach**: simple threshold, anomaly/baseline, or behavioral correlation (`correlate()`) + - **Estimated complexity**: low (single event match), medium (aggregation/threshold), high (multi-event correlation) + - **Key fields and event types** from log validation + - **Recommended authoring skill**: `behavioral-detections` for correlation rules, `cql-patterns` or `logscale-security-queries` for simpler queries + - **Priority rationale**: why this detection matters relative to the others +- User reviews and selects which detections to pursue +- For each selected detection, skill produces a **handoff document** for the authoring skill + +### Handoff Output (Producer) + +When handing off to a detection authoring skill, the skill writes a handoff doc to `docs/handoffs/` with the following structure: + +```yaml +source_skill: source-threat-modeling +target_skill: behavioral-detections | cql-patterns | logscale-security-queries +objective: "Author a detection for [threat scenario]" +context: + data_source: "Okta" + cql_scope_filter: '#Vendor="okta"' + threat_scenario: "MFA fatigue attack — repeated MFA push denials followed by a successful auth" + mitre_technique: "T1621 — Multi-Factor Authentication Request Generation" + mitre_tactic: "Credential Access" + detection_approach: "behavioral correlation" + key_event_types: + - "authentication.auth_via_mfa" + - "user.authentication.auth_via_mfa_deny" + key_fields: + - "actor.displayName" + - "outcome.result" + - "client.ipAddress" + volume_notes: "~200 MFA events/day, deny rate ~2%. Threshold of 5+ denials in 10 min should be low-noise." +decisions_made: + - "User approved this detection for authoring" + - "Correlation approach chosen over simple threshold — need to detect deny-then-success pattern" +constraints: + - "120s query timeout — keep correlation window under 15 minutes" + - "Enrich with $enrich_entra_user() if actor maps to EntraID" +artifacts: [] +``` + +The handoff doc is a markdown file. The receiving skill reads it as its starting context. + +### Interaction with Existing Skills + +This skill is the **strategist**. It decides *what* to detect. Existing skills are the **craftsmen** — they decide *how* to write it: + +- `behavioral-detections` — for multi-event correlation rules using `correlate()` +- `cql-patterns` — for pattern-based queries (aggregation, scoring, thresholds) +- `logscale-security-queries` — for general CQL development and investigation queries +- `detection-tuning` — downstream, once detections are deployed and need FP tuning + +The skill does NOT write CQL or detection YAML itself. It produces the backlog and handoff docs; authoring is delegated. + +--- + +## Skill 2: Response Playbooks + +### Purpose + +Given a detection (existing or newly proposed), recommend appropriate response actions and help wire them up as Fusion SOAR workflows. Provides a library of common response patterns and the intelligence to map detections to appropriate response tiers. + +### Invocation + +The skill is invoked directly by the user, or via a handoff doc from source-threat-modeling (or any other skill). Typical entries: + +- "What response should I set up for this detection?" +- "I have these 5 new detections, what playbooks do they need?" +- Handoff doc from source-threat-modeling with detection context + +### Workflow — 3 Phases + +#### Phase 1: Detection Intake + +- User points at one or more detections (by name, resource file path, or description) +- If a handoff doc is provided, read context from it +- For each detection, skill reads/understands: + - The detection CQL and what it looks for + - Severity level + - MITRE ATT&CK mapping + - **Center entity**: what's the primary subject? (user account, host, IP, cloud resource, application) + - **Blast radius**: if this fires as a true positive, how bad is it? +- Asks clarifying questions if any of the above can't be inferred + +#### Phase 2: Response Recommendation + +- For each detection, propose a tiered response plan based on severity, entity type, and threat category +- Response tiers: + - **Tier 1 — Observe**: create case, log to SIEM, notify via Slack/email. Always safe to automate. + - **Tier 2 — Investigate**: enrich alert with additional context (host details, user history, related alerts). Safe to automate. + - **Tier 3 — Contain**: disable user account, isolate host, revoke session, block IP. Requires human approval gate. + - **Tier 4 — Remediate**: reset credentials, remove persistence, restore from backup. Always requires human action. +- Use `fusion-workflows` action discovery (`action_search.py`) to confirm which actions are actually available in the tenant +- Present recommendations with rationale for each tier +- Clearly distinguish: + - "Always auto-fire" actions (Tier 1-2: case creation, notification, enrichment) + - "Require approval" actions (Tier 3: containment actions) + - "Manual only" actions (Tier 4: remediation) +- User reviews and approves the response plan + +#### Phase 3: Workflow Generation + +- For each approved response plan, produce a **handoff document** for the `fusion-workflows` skill +- The handoff doc contains everything needed to generate the workflow YAML: + - Detection trigger (which detection fires this workflow) + - Actions to execute, in order + - Conditions and approval gates + - Variables to pass between steps +- User invokes `fusion-workflows` with the handoff doc to generate and deploy the workflow + +### Handoff Output (Producer) + +When handing off to fusion-workflows: + +```yaml +source_skill: response-playbooks +target_skill: fusion-workflows +objective: "Create a Fusion workflow for [detection name] response" +context: + detection_name: "Okta MFA Fatigue Attack" + detection_resource_id: "okta_mfa_fatigue" + severity: "critical" + center_entity: "user" + mitre_technique: "T1621" +decisions_made: + - "User approved tiered response plan" + - "Tier 1 (auto): Create case with severity Critical, notify #soc-alerts Slack channel" + - "Tier 2 (auto): Enrich with user's recent auth history (last 24h)" + - "Tier 3 (approval required): Disable user in EntraID, revoke active sessions" + - "Tier 4 (manual): Credential reset — SOC contacts user directly" +constraints: + - "Tier 3 actions must have human approval gate — do not auto-execute containment" + - "Slack notification must include: detection name, affected user, source IP, event count" +workflow_structure: + trigger: "detection" + actions: + - type: "create_case" + auto: true + - type: "slack_notify" + auto: true + channel: "#soc-alerts" + - type: "enrich_user_history" + auto: true + - type: "disable_entra_user" + auto: false + requires_approval: true + - type: "revoke_sessions" + auto: false + requires_approval: true +artifacts: [] +``` + +### Handoff Input (Consumer) + +The skill accepts handoff docs from source-threat-modeling or direct user input. When consuming a handoff doc, it reads the detection context and skips Phase 1 questions that are already answered. + +### Response Pattern Library + +The skill carries knowledge of common response patterns. These are not persisted files — they're built into the skill's reasoning. Examples: + +| Detection Type | Entity | Severity | Recommended Response | +|---|---|---|---| +| Credential attack (brute force, stuffing, MFA fatigue) | User | Critical | Case + notify + enrich + disable user (approval) | +| Privilege escalation (new admin, role change) | User | High | Case + notify + enrich + review access (manual) | +| Data exfiltration (bulk download, unusual export) | User/App | Critical | Case + notify + enrich + revoke sessions (approval) | +| Suspicious network activity (C2 beacon, unusual destination) | Host | High | Case + notify + enrich + isolate host (approval) | +| Cloud config change (security group, IAM policy) | Cloud Resource | Medium | Case + notify + enrich + revert change (manual) | +| Anomalous login (impossible travel, new device) | User | Medium | Case + notify + enrich | + +These patterns inform recommendations but don't override human judgment. The skill presents them as starting points. + +--- + +## Handoff Document Specification + +Both skills produce and consume handoff documents. Standard structure: + +### Format + +Markdown file stored in `docs/handoffs/`. Filename convention: `YYYY-MM-DD--to--.md` + +This directory is gitignored — handoff docs are ephemeral working artifacts, not permanent records. + +### Required Fields + +| Field | Description | +|---|---| +| `source_skill` | Which skill produced this handoff | +| `target_skill` | Which skill should consume it | +| `objective` | One-line description of what the receiving skill should accomplish | +| `context` | Structured data the receiving skill needs (source-specific) | +| `decisions_made` | List of decisions the human already approved — receiving skill should not re-ask these | +| `constraints` | Anything the receiving skill must respect | +| `artifacts` | Paths to any files created by the source skill (detection YAML, query results, etc.) | + +### Lifecycle + +- Handoff docs are created by the producing skill at the end of a phase +- The user invokes the receiving skill and points it at the handoff doc +- Handoff docs are working artifacts, not permanent records — they can be cleaned up after the receiving skill completes +- If the receiving skill needs to hand off further (e.g., response-playbooks → fusion-workflows), it creates a new handoff doc + +--- + +## What's NOT In Scope + +- **Data source/connector provisioning** — ingestion configuration is outside NGSIEM's API surface. The threat modeling skill assumes data is already flowing. +- **OOTB template management** — the `review-templates` command already covers this. The threat modeling skill is for sources *without* OOTB coverage. +- **Detection authoring** — delegated to existing skills via handoff docs. +- **Workflow YAML generation** — delegated to `fusion-workflows` via handoff docs. +- **Persistent source catalogs or playbook libraries** — per user decision, these are conversational skills, not knowledge-base builders. +- **Automated deployment** — both skills produce recommendations and handoff docs, not deployed resources. Deployment goes through the existing IaC pipeline. + +## Relationship to Existing Skills + +``` + source-threat-modeling (NEW) + "what to detect" + | + handoff docs + | + +----------------+----------------+ + | | | + behavioral- cql-patterns logscale-security- + detections "how to write" queries + "how to write" "how to write" + | | | + +-------+--------+--------+-------+ + | | + detection-tuning response-playbooks (NEW) + "how to tune" "what response" + | + handoff doc + | + fusion-workflows + "how to build workflow" + | + IaC pipeline + "deploy to tenant" +``` + +## Skill File Structure + +``` +.claude/skills/ +├── source-threat-modeling/ +│ └── source-threat-modeling.md # Main skill file +├── response-playbooks/ +│ └── response-playbooks.md # Main skill file +``` + +Each skill is a single markdown file with the skill definition — no supporting scripts or data files needed. They're conversational advisors that leverage existing infrastructure. \ No newline at end of file From ace6628279a29e42c938d4c29d83672058d7bfab Mon Sep 17 00:00:00 2001 From: willwebster5 Date: Sat, 28 Mar 2026 22:28:43 -0400 Subject: [PATCH 02/14] Add threat hunting skill design spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Design for a standalone, autonomous threat hunting skill implementing the PEAK framework (Prepare → Execute → Act) with three hunt types, structured outputs, and detection lifecycle integration. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-03-28-threat-hunting-skill-design.md | 395 ++++++++++++++++++ 1 file changed, 395 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md diff --git a/docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md b/docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md new file mode 100644 index 0000000..7d25a04 --- /dev/null +++ b/docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md @@ -0,0 +1,395 @@ +# Threat Hunting Skill — Design Spec + +An autonomous, agentic threat hunting skill for ClaudeStrike's Agentic SOC. Implements the PEAK framework (Prepare → Execute → Act) across three hunt types with self-evaluation, structured outputs, and integration into the detection lifecycle. + +## Problem + +ClaudeStrike's current hunting capability is a 6-step subcommand (`/soc hunt`) — user provides IOCs or a hypothesis, agent runs CQL, presents results. No structured preparation, no post-hunt outputs, no feedback loop into detection engineering, no institutional knowledge accumulation across hunts. + +The research literature (threat-hunting-research.md) establishes that hunting's compounding value comes from the **hunting → detection engineering pipeline**: every manual discovery encoded as an automated rule permanently improves defenses. Organizations at HM4 maturity systematize this. ClaudeStrike has all the downstream skills (`behavioral-detections`, `cql-patterns`, `detection-tuning`) but no structured upstream hunting practice feeding them. + +This skill is an experiment in **agentic threat hunting** — the agent drives the full PEAK lifecycle autonomously, with humans surfaced primarily for threat escalation and final review. + +## Scope + +A standalone Claude Code skill that: + +- Executes structured threat hunts across three types (hypothesis-driven, intelligence-driven, baseline/anomaly) +- Runs autonomously through Prepare → Execute → Act phases with minimal human-in-the-loop +- Produces three outputs: hunt report, detection backlog (with handoff docs), visibility gap report +- Self-evaluates and suggests next hunts based on ATT&CK coverage gaps +- Maintains lightweight living documents (hunt log, coverage map) +- Escalates to the SOC skill when active threats are discovered + +## Design Decisions + +| Decision | Choice | Rationale | +|---|---|---| +| Relationship to `/soc hunt` | Standalone skill — independent, not a subcommand | Clean separation of concerns. `/soc hunt` remains a quick ad-hoc mode; this skill handles the full PEAK lifecycle. | +| Hunt types | All three: hypothesis, intelligence, baseline | PEAK framework structures them cleanly. CrowdStrike NGSIEM supports all three (CQL handles stacking natively for baseline). | +| Human-in-the-loop | Minimal — agentic execution, escalation is the interrupt | Experiment in autonomous hunting. Humans provide the trigger and review outputs, not gate phases. | +| Outputs | Hunt report + detection backlog + gap report | Full Act phase. Detection backlog closes the feedback loop. Gap report enables HM3/HM4 maturity. | +| Living documents | Lightweight — hunt log + ATT&CK coverage map | Prevents redundant hunts, informs prioritization. Baselines expressed as CQL/detections, not memory files. | +| Threat escalation | Tiered — continue for suspected, hard stop for active compromise | Matches real hunt team operations. "Does this need containment?" is the decision boundary. | +| Phase architecture | PEAK-aligned, fluid execution, no human gates between phases | Hunting is exploratory. Rigid gates fight the nature of the activity. | +| Self-evaluation | Part of Act phase, feeds coverage map and next-hunt suggestions | Embodies HM4 maturity ideal — systematic improvement of the hunting cycle. | + +--- + +## Skill Identity + +**Name:** `threat-hunting` +**Location:** `.claude/skills/threat-hunting/` +**Persona:** Autonomous threat hunter operating inside a CrowdStrike NG-SIEM environment. Assumes breach. Follows leads. Produces actionable outputs. + +**Sub-skills loaded:** `logscale-security-queries` (CQL reference), `cql-patterns` (query patterns), `behavioral-detections` (correlation patterns for detection backlog output). + +--- + +## Invocation + +| Command | Hunt Type | Example | +|---|---|---| +| `/hunt hypothesis ""` | Hypothesis-driven | `/hunt hypothesis "Adversary may be using DNS tunneling for C2 from production servers"` | +| `/hunt intel ""` | Intelligence-driven | `/hunt intel "CVE-2025-55241 — undocumented Microsoft tokens bypassing MFA"` | +| `/hunt baseline ""` | Baseline/anomaly | `/hunt baseline "scheduled tasks across all Windows endpoints"` | +| `/hunt` | Agent-suggested | Reads coverage map, suggests high-value targets based on ATT&CK gaps | +| `/hunt log` | Utility | Display hunt log summary | +| `/hunt coverage` | Utility | Display ATT&CK coverage map with gaps | + +--- + +## Phase Architecture + +Three PEAK-aligned phases, executed autonomously. No human gates between phases. Human is surfaced only for threat escalation or at hunt completion. + +### Prepare Phase + +Scopes the hunt before running any queries. + +**All hunt types:** +1. Load living docs — `memory/hunt-log.md`, `memory/coverage-map.md` +2. Load `environmental-context.md` for org baselines +3. Load `memory/investigation-techniques.md` for repo mapping and field gotchas +4. Cross-reference `resources/detections/` MITRE mappings to understand existing automated detection coverage for the target techniques +5. Determine ATT&CK technique mapping for the hunt +6. Establish CQL scope filter (repos, time range, entity constraints) +7. Define success/failure criteria — what would confirm or refute? + +**Hypothesis-driven additions:** +- Parse the hypothesis into testable components +- Identify required data sources and confirm they exist (quick `ngsiem_query` to validate repo/field availability) +- If data sources are insufficient, log the gap and either pivot to what's available or abort with a gap report + +**Intelligence-driven additions:** +- Extract IOCs and TTPs from the provided intel context +- Escalate IOCs to behavioral patterns (Pyramid of Pain — move up from hashes/IPs to TTPs) +- Map TTPs to CQL-queryable telemetry + +**Baseline additions:** +- Identify the entity/behavior class to baseline +- Determine the stacking attributes (what to group by, what to count) +- Establish time window for baseline (7-30 days depending on data volume) + +### Execute Phase + +Fluid, exploratory. The agent follows leads, pivots, and adapts. + +**Hypothesis-driven:** +1. Run primary hypothesis test queries +2. Analyze results — does the data support or refute? +3. If leads emerge, pivot: correlate across data sources, expand scope +4. If no leads, attempt alternative detection angles for the same TTP +5. Document evidence chain as investigation progresses + +**Intelligence-driven:** +1. Sweep for IOCs first (quick wins) +2. Pivot from any IOC hits to behavioral patterns — what else did that actor/IP/hash do? +3. Hunt for the TTPs described in the intel even without IOC matches (IOCs may have rotated but behavior persists) +4. Cross-correlate across data sources (CloudTrail + EntraID + endpoint + network) + +**Baseline:** +1. Run stacking queries — frequency counts across the target attribute +2. Identify statistical outliers (entities appearing on 1-2 systems, unusual values, low-frequency entries) +3. Investigate outliers — context queries to determine if anomalous = malicious +4. Establish documented baseline for future comparison + +**Threat escalation interrupt (all types):** +- **Suspected threat:** Continue hunting to establish scope. Flag finding but don't stop. +- **Confirmed active compromise** (C2, exfiltration, active lateral movement): Stop hunting. Produce immediate escalation package with IOCs, affected systems, timeline. Create handoff doc for SOC skill. Surface to human. + +### Act Phase + +Produce all outputs and self-evaluate. + +1. **Hunt Report** — structured findings document (persisted to `docs/hunts/`) +2. **Detection Backlog** — proposed detections with handoff docs to authoring skills +3. **Gap Report** — visibility gaps, missing telemetry, ATT&CK coverage holes +4. **Self-evaluation** — hypothesis quality, data sufficiency, investigation efficiency +5. **Update living docs** — append to hunt log, update coverage map +6. **Suggest next hunt** — based on coverage gaps, findings, and staleness + +--- + +## MCP Tools + +| Activity | MCP Tools | Usage Pattern | +|---|---|---| +| Hypothesis testing | `ngsiem_query` | Ad-hoc CQL — the workhorse. Multiple queries per hunt, pivoting between repos. | +| Stacking/baselining | `ngsiem_query` | `groupBy()` + `count()` + `sort()` across large time windows. Long-tail analysis. | +| IOC sweeps | `ngsiem_query` | Multi-repo searches for hashes, IPs, domains across all telemetry. | +| Host context | `host_lookup`, `host_login_history`, `host_network_history` | When an endpoint surfaces during a hunt. | +| Cloud context | `cloud_query_assets`, `cloud_get_risks`, `cloud_get_iom_detections` | When cloud resources or IAM activity surfaces. | +| Alert correlation | `get_alerts`, `alert_analysis` | Check if existing detections already fired for discovered entities. | +| Escalation | `case_create`, `case_add_event_evidence`, `case_add_tags` | Only on confirmed active compromise. | + +### Key CQL Patterns + +Beyond what `cql-patterns` and `logscale-security-queries` provide, the skill carries knowledge of hunting-specific query patterns: + +- **Stacking:** `groupBy([field], function=count()) | sort(_count, order=asc) | tail(50)` — find rare values +- **Temporal clustering:** `bucket(span=5m)` + `groupBy()` — detect bursts of activity +- **Cross-source correlation:** Same entity (user, IP, hostname) across multiple repos within the same time window +- **Process tree reconstruction:** Parent-child PID chaining via `ngsiem_query` against EDR telemetry +- **Beacon detection:** Periodic callback patterns via time-delta analysis on network connections + +--- + +## Outputs + +### Hunt Report + +Produced after every hunt. Persisted to `docs/hunts/YYYY-MM-DD-.md`. This directory is committed to git — hunt reports are permanent archival records (unlike `docs/handoffs/` which is gitignored). + +```markdown +## Hunt Report: +**Date**: YYYY-MM-DD +**Type**: Hypothesis | Intelligence | Baseline +**ATT&CK Techniques**: T1234, T5678 +**Duration**: <approximate> +**Outcome**: Threat Found | No Threat — Coverage Validated | Inconclusive + +### Hypothesis / Objective +<What we were looking for and why> + +### Scope +- **Data sources**: <repos queried> +- **Time range**: <start — end> +- **Entities**: <users, hosts, IPs, services examined> + +### Findings +<Chronological investigation narrative> + +### IOCs +| Indicator | Type | Context | +|-----------|------|---------| +<only if threat discovered> + +### Conclusion +<2-3 sentences: what did we learn?> + +### Self-Evaluation +- **Hypothesis quality**: <Was it testable? Too broad? Too narrow?> +- **Data sufficiency**: <Did we have what we needed?> +- **Investigation efficiency**: <Dead ends? Better paths in hindsight?> +- **Suggested next hunt**: <Based on gaps found or leads not fully pursued> +``` + +### Detection Backlog + +Produced when the hunt reveals detectable patterns. + +```markdown +## Proposed Detections from Hunt: <title> + +| # | Detection | ATT&CK | Approach | Complexity | Target Skill | Priority | +|---|-----------|--------|----------|------------|-------------|----------| +``` + +Each entry gets a handoff doc to `docs/handoffs/` following the standard handoff spec: + +```yaml +source_skill: threat-hunting +target_skill: behavioral-detections | cql-patterns | logscale-security-queries +objective: "Author a detection for [pattern discovered during hunt]" +context: + hunt_title: "<title>" + hunt_date: "YYYY-MM-DD" + threat_scenario: "<what the detection should find>" + mitre_technique: "<technique ID>" + mitre_tactic: "<tactic>" + detection_approach: "<simple threshold | stacking anomaly | behavioral correlation>" + key_event_types: [...] + key_fields: [...] + volume_notes: "<expected signal volume and noise characteristics>" + sample_query: "<CQL query from the hunt that surfaced this pattern>" +decisions_made: + - "Pattern discovered during [hunt type] hunt" + - "<any context about why this detection matters>" +constraints: + - "120s query timeout" + - "<any data source limitations noted during hunt>" +artifacts: + - "docs/hunts/YYYY-MM-DD-<slug>.md" +``` + +### Gap Report + +Documents what the hunter couldn't see. + +```markdown +## Visibility Gap Report: <hunt title> + +### Gaps Identified +| Gap | Impact | ATT&CK Techniques Affected | Recommendation | +|-----|--------|---------------------------|----------------| + +### ATT&CK Coverage Delta +<Techniques in scope but untestable, with reasons> +``` + +--- + +## Living Documents + +Two files in `.claude/skills/threat-hunting/memory/`. + +### `hunt-log.md` + +Append-only log of completed hunts. One entry per hunt. + +```markdown +# Hunt Log + +| Date | Type | Title | ATT&CK | Outcome | Detections Proposed | +|------|------|-------|--------|---------|-------------------| +``` + +### `coverage-map.md` + +ATT&CK technique coverage tracker, updated after every hunt. Tracks the **hunt layer** — what has been proactively hunted. Cross-referenced during Prepare against deployed detection MITRE mappings from `resources/detections/` to identify high-value targets. + +```markdown +# ATT&CK Hunt Coverage Map + +## Hunted +| Technique | Tactic | Last Hunted | Result | Data Quality | +|-----------|--------|-------------|--------|-------------| + +## Known Gaps +| Technique | Tactic | Reason | Recommendation | +|-----------|--------|--------|----------------| + +## Suggested Priority Hunts +<Auto-generated from: gaps, staleness (90+ days since last hunt), techniques with detections but no hunting validation> +``` + +The coverage map tracks techniques the skill has engaged with or identified as gaps. It grows organically through use. During Prepare, the skill cross-references this against deployed detection MITRE mappings to surface three categories of high-value hunt targets: + +1. **Blind spots** — techniques with no detections AND no hunting (highest priority) +2. **Untested assumptions** — techniques with deployed detections but never hunted (are the detections actually catching things?) +3. **Stale coverage** — techniques hunted 90+ days ago (the environment may have changed) + +--- + +## Integration & Handoffs + +### Upstream Triggers + +| Source | How | Example | +|---|---|---| +| Human | Direct invocation via `/hunt` | "Hunt for lateral movement in the cloud accounts" | +| Coverage map | Agent suggests when invoked with no args | "T1078 Valid Accounts hasn't been hunted and has 3 detections — worth validating" | +| Source-threat-modeling | Handoff doc — threat scenarios not yet hunted | "Okta session hijacking was modeled but never validated against live data" | +| SOC skill | Finding during triage warrants deeper investigation | Analyst spots suspicious pattern, spins up a hunt | +| External intel | User provides CVE, campaign report, ISAC advisory | "CrowdStrike blog on SCATTERED SPIDER new TTPs" | + +### Downstream Outputs + +| Output | Target | Mechanism | +|---|---|---| +| Detection backlog entries | `behavioral-detections`, `cql-patterns`, `logscale-security-queries` | Handoff docs to `docs/handoffs/` | +| Escalation package | SOC skill (`/soc`) | Handoff doc with IOCs, timeline, affected systems | +| Gap report | `source-threat-modeling` | Visibility gaps feed back into detection planning | +| Hunt report | `docs/hunts/` | Persistent record (archival, not a handoff) | +| Living doc updates | Own `memory/` | Hunt log + coverage map | + +### Handoff Doc Format + +Same spec as source-threat-modeling and response-playbooks. Standard fields: `source_skill`, `target_skill`, `objective`, `context`, `decisions_made`, `constraints`, `artifacts`. + +### Relationship to Deployed Detection Coverage + +During Prepare, the skill reads MITRE mappings from `resources/detections/` to understand existing automated detection coverage. This informs hunt prioritization but the skill never modifies detection files directly. Detection authoring is always delegated via handoff docs. + +--- + +## File Structure + +``` +.claude/skills/threat-hunting/ +├── SKILL.md # Main skill definition +├── DESIGN.md # Architecture rationale +└── memory/ + ├── hunt-log.md # Completed hunts log + └── coverage-map.md # ATT&CK hunt coverage tracker + +.claude/commands/ +└── hunt.md # /hunt command routing to skill +``` + +### Context Loading at Invocation + +1. `SKILL.md` (always) +2. `memory/hunt-log.md` (always — what's been done) +3. `memory/coverage-map.md` (always — informs prioritization) +4. `environmental-context.md` (always — org baselines) +5. `memory/investigation-techniques.md` (Prepare phase — repo mappings, field gotchas) +6. Sub-skills on demand: `logscale-security-queries`, `cql-patterns`, `behavioral-detections` + +--- + +## What's NOT In Scope + +- **Replacing `/soc hunt`** — the SOC skill's hunt mode stays as a quick ad-hoc option. This skill is the full PEAK lifecycle. +- **Detection authoring** — delegated to existing skills via handoff docs. The skill proposes detections, it doesn't write CQL or YAML. +- **Incident response** — on active compromise, the skill produces an escalation package and hands off to the SOC skill. It doesn't contain or remediate. +- **UEBA/ML** — the skill uses CQL-native stacking and statistical analysis for baseline hunts. It doesn't integrate external ML models or UEBA platforms. +- **Campaign orchestration** — each invocation is a single hunt. Multi-hunt campaigns can be layered on later if single hunts prove effective. + +## Relationship to Existing Skills + +``` + threat-hunting (NEW) + "what's hiding" + | + +---------------+---------------+ + | | | + hunt report detection backlog gap report + | | | + docs/hunts/ handoff docs feeds back to + (archival) | source-threat-modeling + | + +-------------+-------------+ + | | | + behavioral- cql-patterns logscale-security- + detections "how to write" queries + "how to write" "how to write" + | | | + +------+------+------+------+ + | | + detection-tuning response-playbooks + "how to tune" "what response" +``` + +## Research Foundation + +This skill's design is grounded in the threat hunting research survey (`/home/will/projects/agent-skills/threat-hunting-research.md`). Key concepts incorporated: + +- **PEAK framework** (Bianco et al., 2023) — Prepare → Execute → Act phase structure +- **Hunting Maturity Model** — targeting HM4 (systematic automation of hunting discoveries into detections) +- **Pyramid of Pain** (Bianco, 2013) — intelligence-driven hunts escalate from IOCs to TTPs +- **Stacking/long-tail analysis** — core technique for baseline hunts +- **Hunt → detection engineering feedback loop** — the detection backlog output systematizes this +- **"A hunt that finds no threats is not a failure"** — the gap report and coverage validation capture value from clean hunts +- **Self-evaluation** — Approach 3 element enabling continuous improvement of the hunting practice From 42cfd9bd7f0e377268f80886c45c48096fccd286 Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:38:03 -0400 Subject: [PATCH 03/14] Add threat hunting skill implementation plan 10-task plan covering scaffold, living docs, DESIGN.md, SKILL.md (persona/tools/Prepare/Execute/Act/utility modes), /hunt command router, and CLAUDE.md integration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --- .../plans/2026-03-28-threat-hunting-skill.md | 1079 +++++++++++++++++ 1 file changed, 1079 insertions(+) create mode 100644 docs/superpowers/plans/2026-03-28-threat-hunting-skill.md diff --git a/docs/superpowers/plans/2026-03-28-threat-hunting-skill.md b/docs/superpowers/plans/2026-03-28-threat-hunting-skill.md new file mode 100644 index 0000000..6cd1365 --- /dev/null +++ b/docs/superpowers/plans/2026-03-28-threat-hunting-skill.md @@ -0,0 +1,1079 @@ +# Threat Hunting Skill Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Implement a standalone, autonomous threat hunting Claude Code skill that executes the PEAK framework (Prepare → Execute → Act) across three hunt types, producing hunt reports, detection backlogs, and visibility gap reports. + +**Architecture:** Single skill file (SKILL.md) with a `/hunt` command router, two living documents (hunt log, ATT&CK coverage map), and integration into the existing detection lifecycle via handoff docs. The skill runs autonomously through all three PEAK phases with human touchpoints only at escalation and final review. + +**Tech Stack:** Claude Code skill (markdown), CrowdStrike MCP tools, CQL queries, YAML handoff docs. + +**Spec:** `docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md` + +--- + +### Task 1: Scaffold directories and gitignore + +**Files:** +- Create: `.claude/skills/threat-hunting/` (directory) +- Create: `.claude/skills/threat-hunting/memory/` (directory) +- Create: `docs/hunts/.gitkeep` +- Create: `docs/handoffs/.gitignore` +- Modify: `.gitignore` + +- [ ] **Step 1: Create the skill directory structure** + +```bash +mkdir -p .claude/skills/threat-hunting/memory +``` + +- [ ] **Step 2: Create docs/hunts/ with .gitkeep** + +Hunt reports are permanent archival records — this directory is committed to git. + +```bash +mkdir -p docs/hunts +``` + +Write `docs/hunts/.gitkeep` as an empty file: + +``` +``` + +- [ ] **Step 3: Create docs/handoffs/ with its own .gitignore** + +Handoff docs are ephemeral working artifacts. The directory itself is tracked, but its contents are gitignored. + +```bash +mkdir -p docs/handoffs +``` + +Write `docs/handoffs/.gitignore`: + +``` +# Handoff docs are ephemeral working artifacts — not permanent records. +# They are created by one skill and consumed by another, then cleaned up. +* +!.gitignore +``` + +- [ ] **Step 4: Verify directory structure** + +Run: `find .claude/skills/threat-hunting docs/hunts docs/handoffs -type f -o -type d | sort` + +Expected: +``` +.claude/skills/threat-hunting +.claude/skills/threat-hunting/memory +docs/handoffs +docs/handoffs/.gitignore +docs/hunts +docs/hunts/.gitkeep +``` + +- [ ] **Step 5: Commit** + +```bash +git add .claude/skills/threat-hunting docs/hunts/.gitkeep docs/handoffs/.gitignore +git commit -m "scaffold: threat-hunting skill directories and docs/hunts, docs/handoffs" +``` + +--- + +### Task 2: Living document templates + +**Files:** +- Create: `.claude/skills/threat-hunting/memory/hunt-log.md` +- Create: `.claude/skills/threat-hunting/memory/coverage-map.md` + +- [ ] **Step 1: Write hunt-log.md** + +Write `.claude/skills/threat-hunting/memory/hunt-log.md`: + +```markdown +<!-- LIVING DOCUMENT +Updated by the threat-hunting skill after every completed hunt. +Append-only — one row per hunt. Do not delete entries. +Used during Prepare phase to avoid redundant hunts and during +/hunt (no args) to summarize hunting activity. --> + +# Hunt Log + +| Date | Type | Title | ATT&CK | Outcome | Detections Proposed | +|------|------|-------|--------|---------|---------------------| +``` + +- [ ] **Step 2: Write coverage-map.md** + +Write `.claude/skills/threat-hunting/memory/coverage-map.md`: + +```markdown +<!-- LIVING DOCUMENT +Updated by the threat-hunting skill after every completed hunt. +Tracks the HUNT LAYER — what has been proactively hunted. +Cross-referenced during Prepare against deployed detection MITRE +mappings from resources/detections/ to identify high-value targets. + +Three categories of high-value hunt targets: +1. Blind spots — no detections AND no hunting (highest priority) +2. Untested assumptions — detections exist but never hunted +3. Stale coverage — not hunted in 90+ days --> + +# ATT&CK Hunt Coverage Map + +## Hunted + +| Technique | Tactic | Last Hunted | Result | Data Quality | +|-----------|--------|-------------|--------|--------------| + +## Known Gaps + +| Technique | Tactic | Reason | Recommendation | +|-----------|--------|--------|----------------| + +## Suggested Priority Hunts + +_No hunts completed yet. After the first hunt, this section will be populated with recommendations based on gaps, staleness, and untested detection coverage._ +``` + +- [ ] **Step 3: Verify files exist and read correctly** + +Run: `cat .claude/skills/threat-hunting/memory/hunt-log.md && echo "---" && cat .claude/skills/threat-hunting/memory/coverage-map.md` + +Expected: Both files display with correct markdown table headers and HTML comments. + +- [ ] **Step 4: Commit** + +```bash +git add .claude/skills/threat-hunting/memory/hunt-log.md .claude/skills/threat-hunting/memory/coverage-map.md +git commit -m "feat: add threat-hunting living document templates (hunt log + coverage map)" +``` + +--- + +### Task 3: DESIGN.md — architecture rationale + +**Files:** +- Create: `.claude/skills/threat-hunting/DESIGN.md` + +- [ ] **Step 1: Write DESIGN.md** + +Write `.claude/skills/threat-hunting/DESIGN.md`: + +```markdown +# Threat Hunting Skill — Architecture Rationale + +## Problem + +ClaudeStrike's hunting capability is a 6-step subcommand (`/soc hunt`) with no structured preparation, no post-hunt outputs, no feedback loop into detection engineering, and no institutional knowledge accumulation. The research literature establishes that hunting's compounding value comes from the hunting → detection engineering pipeline. ClaudeStrike has the downstream skills (`behavioral-detections`, `cql-patterns`, `detection-tuning`) but no structured upstream practice feeding them. + +## Architecture: Autonomous PEAK Framework + +This skill implements the PEAK framework (Prepare → Execute → Act) as an autonomous agent — minimal human-in-the-loop, with escalation as the primary interrupt. + +### Why Autonomous (vs. Phased with Human Gates) + +The SOC skill uses phased architecture with human checkpoints to prevent confirmation bias during triage. Hunting has a different dynamic — the agent is exploring, not reacting to an alert. Rigid gates fight the exploratory nature of hunting. The agent drives end-to-end; humans provide the trigger and review outputs. + +### Why Three Hunt Types + +PEAK recognizes three types: hypothesis-driven, baseline (anomaly), and model-assisted (intelligence-driven in our case). CrowdStrike's NGSIEM supports all three — CQL handles stacking natively for baseline hunts, `ngsiem_query` supports ad-hoc hypothesis testing, and IOC/TTP sweeps work for intelligence-driven hunts. + +### Why Standalone (vs. Replacing /soc hunt) + +Clean separation of concerns. `/soc hunt` stays as a quick ad-hoc mode for simple IOC sweeps during triage. This skill handles the full PEAK lifecycle — scoping, execution, detection backlog, gap reporting, self-evaluation. + +### Why Lightweight Living Documents + +A hunt log prevents redundant work. An ATT&CK coverage map enables gap-based prioritization. Baselines are better expressed as saved CQL queries or detection rules than memory files. Hypothesis backlogs are project management, not skill memory. + +### Why Tiered Escalation + +Real hunt teams don't stop investigating at the first suspicious finding. They establish scope first. But confirmed active compromise (C2, exfiltration, lateral movement) demands immediate containment. "Does this need containment?" is the decision boundary. + +## Key Design Decisions + +| Decision | Choice | +|---|---| +| Relationship to `/soc hunt` | Standalone — independent skill | +| Hunt types | Hypothesis, intelligence, baseline | +| Human-in-the-loop | Minimal — agentic, escalation is the interrupt | +| Outputs | Hunt report + detection backlog + gap report | +| Living documents | Hunt log + ATT&CK coverage map | +| Escalation | Tiered — continue for suspected, hard stop for active compromise | +| Self-evaluation | Part of Act phase, feeds coverage map | + +## Integration Points + +- **Upstream:** Human invocation, coverage map suggestions, source-threat-modeling handoffs, SOC triage findings, external intel +- **Downstream:** Detection authoring skills (via handoff docs), SOC skill (via escalation handoff), source-threat-modeling (via gap reports) +- **Shared context:** `environmental-context.md` and `investigation-techniques.md` from the SOC skill + +## Research Foundation + +Design grounded in the threat hunting research survey. Key concepts: PEAK framework (Bianco et al., 2023), Hunting Maturity Model (targeting HM4), Pyramid of Pain, stacking/long-tail analysis, hunt → detection engineering feedback loop. + +## Full Spec + +`docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md` +``` + +- [ ] **Step 2: Verify file reads correctly** + +Run: `head -20 .claude/skills/threat-hunting/DESIGN.md` + +Expected: Title and Problem section display correctly. + +- [ ] **Step 3: Commit** + +```bash +git add .claude/skills/threat-hunting/DESIGN.md +git commit -m "docs: add threat-hunting skill architecture rationale" +``` + +--- + +### Task 4: SKILL.md — frontmatter, persona, tools, CQL patterns + +**Files:** +- Create: `.claude/skills/threat-hunting/SKILL.md` + +This task creates the first portion of SKILL.md — the skill identity, persona, principles, MCP tool reference, and hunting-specific CQL patterns. Subsequent tasks append the phase architecture. + +- [ ] **Step 1: Write SKILL.md with frontmatter, persona, tools, and CQL patterns** + +Write `.claude/skills/threat-hunting/SKILL.md`: + +```markdown +--- +name: threat-hunting +description: Autonomous threat hunting using the PEAK framework (Prepare → Execute → Act). Executes hypothesis-driven, intelligence-driven, and baseline hunts against CrowdStrike NG-SIEM. Produces hunt reports, detection backlogs, and visibility gap reports. Use when proactively hunting for threats, validating detection coverage, or responding to new threat intelligence. +--- + +> Threat hunting skill loaded — PEAK framework (Prepare → Execute → Act). Sub-skills: `logscale-security-queries` (CQL), `cql-patterns` (query patterns), `behavioral-detections` (correlation rules). + +# Threat Hunting — Autonomous PEAK-Based Hunting + +Autonomous threat hunter operating inside a CrowdStrike NG-SIEM environment. Assumes breach. Follows leads. Produces actionable outputs. + +## Persona & Principles + +You are an autonomous threat hunter. You drive the full PEAK lifecycle without human gates between phases. The human provides the trigger and reviews your outputs. + +- **Assume breach.** The environment is compromised until proven otherwise. Your job is to find what automated defenses missed. +- **Follow leads.** When you find something interesting, pivot — correlate across data sources, expand scope, dig deeper. Don't stop at the first query. +- **No hunt fails.** A hunt that finds no threats validates coverage, identifies visibility gaps, and strengthens baselines. Every hunt produces value. +- **IOCs are ephemeral, TTPs are durable.** When hunting from intelligence, escalate from indicators (hashes, IPs, domains) to behaviors (process chains, persistence patterns, lateral movement). Climb the Pyramid of Pain. +- **Feed the pipeline.** Every pattern you discover that could be automated should become a proposed detection. The hunting → detection engineering feedback loop is where compounding value lives. +- **Know your data.** Before running queries, confirm the data source exists and the fields are correct. Consult `investigation-techniques.md` for repo mappings and field gotchas. A query against the wrong repo returns 0 results silently. +- **Escalate active threats immediately.** If you discover confirmed active compromise (C2, exfiltration, lateral movement in progress), stop hunting and produce an escalation package. "Does this need containment?" is the decision boundary. + +## Available Tools + +**CrowdStrike MCP tools** — call these directly as MCP tool invocations. Do NOT write Python scripts or wrapper code. + +### Hunting & Investigation +| MCP Tool | Purpose | +|----------|---------| +| `mcp__crowdstrike__ngsiem_query` | Execute CQL queries — the primary hunting tool. Multiple queries per hunt. | +| `mcp__crowdstrike__get_alerts` | Check if existing detections already fired for entities discovered during hunt | +| `mcp__crowdstrike__alert_analysis` | Deep dive on a specific alert found during correlation | + +### Host Context +| MCP Tool | Purpose | +|----------|---------| +| `mcp__crowdstrike__host_lookup` | Device posture: OS, containment status, policies, agent version | +| `mcp__crowdstrike__host_login_history` | Recent logins on a device (local, remote, interactive) | +| `mcp__crowdstrike__host_network_history` | IP changes, VPN connections, network interface history | + +### Cloud Context +| MCP Tool | Purpose | +|----------|---------| +| `mcp__crowdstrike__cloud_query_assets` | Look up cloud resource by resource_id — config, exposure, tags | +| `mcp__crowdstrike__cloud_get_iom_detections` | CSPM compliance evaluations with MITRE, CIS, NIST mapping | +| `mcp__crowdstrike__cloud_get_risks` | Cloud risks ranked by score — misconfigs, unused identities | + +### Escalation (confirmed active compromise only) +| MCP Tool | Purpose | +|----------|---------| +| `mcp__crowdstrike__case_create` | Create case for confirmed threat | +| `mcp__crowdstrike__case_add_event_evidence` | Attach hunt findings as evidence | +| `mcp__crowdstrike__case_add_tags` | Tag case for classification and routing | + +### Local Tools +| Tool | Purpose | +|------|---------| +| File tools (Read, Grep, Glob) | Read detection templates, search for MITRE mappings, read memory files | + +## Key CQL Hunting Patterns + +Beyond `cql-patterns` and `logscale-security-queries`, these patterns are specific to hunting: + +### Stacking (Long-Tail Analysis) +Find rare values — the workhorse hunting technique: +```cql +// Stack by attribute, sort ascending to surface outliers at the bottom +groupBy([field], function=count()) | sort(_count, order=asc) | tail(50) + +// Multi-attribute stacking — catches malware with legitimate names in suspicious paths +groupBy([ServiceName, ServicePath], function=count()) | sort(_count, order=asc) | tail(50) +``` + +### Temporal Clustering +Detect bursts of activity in time windows: +```cql +bucket(span=5m) +| groupBy([_bucket, user.email], function=count()) +| where(_count > 20) +``` + +### Cross-Source Correlation +Same entity across multiple repos in the same time window: +```cql +// Query 1: Find suspicious IP in CloudTrail +(#repo="cloudtrail" OR #repo="fcs_csp_events") source.ip="<suspicious_ip>" +| groupBy([event.action, Vendor.userIdentity.arn]) + +// Query 2: Same IP in EntraID sign-in logs +(#repo="microsoft_graphapi" OR #repo="3pi_microsoft_entra_id" OR #repo="fcs_csp_events") +#event.dataset=/entraid/ source.ip="<suspicious_ip>" +| groupBy([user.email, #event.outcome]) +``` + +### Process Tree Reconstruction +Parent-child PID chaining for endpoint telemetry: +```cql +#event_simpleName=ProcessRollup2 aid=<device_id> +| ParentProcessId=<target_pid> OR TargetProcessId=<target_pid> +| table([@timestamp, FileName, CommandLine, ParentBaseFileName, TargetProcessId, ParentProcessId]) +| sort(@timestamp, order=asc) +``` + +### Beacon Detection +Periodic callback patterns via time-delta analysis: +```cql +#event_simpleName=DnsRequest aid=<device_id> +| DomainName=<suspect_domain> +| sort(@timestamp, order=asc) +| timeDelta(@timestamp, as=delta_ms) +| stats([avg(delta_ms, as=avg_interval), stddev(delta_ms, as=jitter), count()]) +// Low jitter + regular interval = likely beacon +``` +``` + +- [ ] **Step 2: Verify frontmatter parses correctly** + +Run: `head -5 .claude/skills/threat-hunting/SKILL.md` + +Expected: +``` +--- +name: threat-hunting +description: Autonomous threat hunting using the PEAK framework... +--- +``` + +- [ ] **Step 3: Commit** + +```bash +git add .claude/skills/threat-hunting/SKILL.md +git commit -m "feat: add threat-hunting SKILL.md — persona, tools, CQL patterns" +``` + +--- + +### Task 5: SKILL.md — phase dispatcher, context loading, and Prepare phase + +**Files:** +- Modify: `.claude/skills/threat-hunting/SKILL.md` (append after the beacon detection CQL block) + +- [ ] **Step 1: Append phase dispatcher, context loading, and Prepare phase** + +Append to `.claude/skills/threat-hunting/SKILL.md` after the last line: + +```markdown + +## Phase Dispatcher + +Route based on invocation: + +| Command | Action | +|---------|--------| +| `/hunt hypothesis "<statement>"` | Full PEAK cycle — hypothesis-driven hunt | +| `/hunt intel "<context>"` | Full PEAK cycle — intelligence-driven hunt | +| `/hunt baseline "<entity>"` | Full PEAK cycle — baseline/anomaly hunt | +| `/hunt` | Read coverage map, suggest high-value hunt targets | +| `/hunt log` | Display hunt log summary | +| `/hunt coverage` | Display ATT&CK coverage map with gap analysis | + +## Context Loading + +Load at skill invocation (all hunt types): + +1. Read `memory/hunt-log.md` — what hunts have been completed +2. Read `memory/coverage-map.md` — ATT&CK technique coverage and gaps +3. Read `.claude/skills/soc/environmental-context.md` — org baselines, known accounts, infrastructure +4. Read `.claude/skills/soc/memory/investigation-techniques.md` — repo mappings, field gotchas + +Load during Prepare phase: +5. Scan `resources/detections/` for `mitre_attack` fields — existing automated detection coverage +6. Check `resources/saved_searches/hunting/` — existing hunting queries that may be relevant + +Sub-skills loaded on demand: +- `logscale-security-queries` — when writing CQL queries +- `cql-patterns` — when designing detection backlog entries +- `behavioral-detections` — when proposing correlation-based detections + +--- + +## Prepare Phase + +Scope the hunt before running any queries. This phase runs autonomously. + +### All Hunt Types + +1. **Identify ATT&CK techniques** — map the hunt objective to specific MITRE ATT&CK technique IDs. + +2. **Cross-reference detection coverage** — scan `resources/detections/` for templates with matching `mitre_attack` fields. Grep for the technique ID: + ```bash + grep -rl "T1234" resources/detections/ + ``` + Note the coverage category: + - Technique with deployed detections but never hunted = **untested assumption** + - Technique with no detections AND never hunted = **blind spot** + - Technique hunted 90+ days ago = **stale coverage** + +3. **Check hunt log** — has this technique been hunted before? When? What was found? Avoid redundant work, but re-hunting after 90 days is valid. + +4. **Check existing hunting queries** — scan `resources/saved_searches/hunting/` for relevant saved searches. These may provide ready-made CQL for the target technique. + +5. **Establish CQL scope filter** — determine which NGSIEM repos to query using the repo mapping table from `investigation-techniques.md`. Validate the data source exists: + ```cql + <scope_filter> | count() + ``` + If 0 results, the data source may not be ingested. Log the gap. + +6. **Define time range** — 7 days default for hypothesis and intel hunts. 30 days for baseline hunts. Adjust based on data volume. + +7. **Define success/failure criteria** — what evidence would confirm or refute? What constitutes a meaningful anomaly? + +### Hypothesis-Driven Additions + +- Parse the hypothesis into testable components. A good hypothesis is narrow enough to prove or disprove within bounded effort. +- Identify the specific event types and fields needed to test each component. +- If required data sources are missing, log the gap and either: + - Pivot to what's available (test a related hypothesis against available data) + - Abort early with a gap report if the hunt is fundamentally blocked + +### Intelligence-Driven Additions + +- Extract IOCs from the provided intel: IP addresses, domains, file hashes, user agents, tool names. +- Extract TTPs: what techniques and procedures does the intel describe? +- **Pyramid of Pain escalation plan:** start with IOC sweeps (quick wins), then escalate to TTP hunting (durable value). Map each TTP to CQL-queryable telemetry. +- If the intel references specific threat actors, note their known TTPs for broader behavioral hunting. + +### Baseline Additions + +- Identify the entity/behavior class: scheduled tasks, services, autorun entries, user-agent strings, DNS queries, process names, network connections. +- Determine stacking attributes — what to `groupBy()` and what to `count()`. Choose attribute groupings carefully: stacking only on name misses malware with legitimate names in suspicious paths. Combine name + path + host. +- Establish time window: 7 days minimum, 30 days preferred for stable environments. +- Rule of thumb: any single stack review should take no more than 10 minutes of analysis. If results are overwhelming, narrow context. +``` + +- [ ] **Step 2: Verify the section was appended correctly** + +Run: `grep -n "## Prepare Phase" .claude/skills/threat-hunting/SKILL.md` + +Expected: One match, at a line number after the CQL patterns section. + +- [ ] **Step 3: Commit** + +```bash +git add .claude/skills/threat-hunting/SKILL.md +git commit -m "feat: add phase dispatcher, context loading, and Prepare phase to SKILL.md" +``` + +--- + +### Task 6: SKILL.md — Execute phase + +**Files:** +- Modify: `.claude/skills/threat-hunting/SKILL.md` (append after the Baseline Additions section) + +- [ ] **Step 1: Append Execute phase** + +Append to `.claude/skills/threat-hunting/SKILL.md` after the last line: + +```markdown + +--- + +## Execute Phase + +Fluid and exploratory. Follow leads, pivot, adapt. Document the investigation chain as you go — this narrative feeds the hunt report. + +### Hypothesis-Driven Execution + +1. **Run primary hypothesis test queries** — direct CQL queries against the scoped data sources and time range. +2. **Analyze results:** + - Results support the hypothesis → dig deeper. What's the scope? Which systems/users are affected? + - Results refute the hypothesis → attempt alternative detection angles for the same TTP. Different event types, different fields, different time windows. + - Inconclusive → broaden scope or pivot to adjacent techniques. +3. **Pivot on leads** — when an interesting entity (user, IP, host) surfaces: + - Cross-correlate across data sources (CloudTrail + EntraID + endpoint + DNS) + - Alert correlation: `get_alerts` for the entity — have existing detections already fired? + - Pull host/cloud context for interesting endpoints or resources +4. **Document evidence chain** — record each query, what it found, and why you pivoted. This becomes the Findings section of the hunt report. + +### Intelligence-Driven Execution + +1. **IOC sweep** — search for known indicators across all relevant repos. Fast, concrete results. + ```cql + // Example: sweep for suspicious IP across all data sources + source.ip="<ioc_ip>" OR destination.ip="<ioc_ip>" + | groupBy([#repo, event.action, source.ip, destination.ip], function=count()) + ``` +2. **Pivot from IOC hits** — if any IOC matches: + - What else did that actor/IP/hash do? Expand the query to all activity from that entity. + - Timeline analysis: what happened in the 30 minutes before and after the IOC match? + - Scope assessment: how many systems/users are affected? +3. **TTP hunting (even without IOC matches)** — IOCs rotate trivially; behaviors persist. + - Hunt for the behavioral patterns described in the intel regardless of IOC results. + - Use process tree analysis, login correlation, network pattern analysis. + - This is where durable detection value lives. +4. **Cross-correlate across data sources** — adversaries don't stay in one log source. Check the repo mapping table and query every relevant source for the entities under investigation. + +### Baseline Execution + +1. **Run stacking queries** — frequency counts across the target attribute grouping. + ```cql + // Example: stack scheduled tasks across all Windows endpoints + #event_simpleName=ScheduledTaskRegistered + | groupBy([TaskName, TaskExecCommand], function=[count(), collect(ComputerName)]) + | sort(_count, order=asc) + | tail(50) + ``` +2. **Identify statistical outliers:** + - Entities on only 1-2 systems (vs. hundreds) — investigate. + - Unusual values — names that don't fit the pattern, paths in unexpected locations. + - Low-frequency entries at the tail of the distribution. +3. **Investigate outliers** — for each outlier: + - Context queries: host lookup, user lookup, process tree reconstruction. + - Environmental context check: is this a known application, service account, or infrastructure component? + - If anomalous AND unexplained → potential finding. Document it. +4. **Establish baseline documentation** — record what "normal" looks like. This is valuable even if no threats are found — it informs future hunts and detection tuning. + +### Threat Escalation Interrupt + +Applies to all hunt types. Two tiers based on "does this need containment?": + +**Suspected threat** — interesting but not confirmed: +- Flag the finding in your investigation notes. +- **Continue hunting** to establish scope and gather more evidence. +- Present in the hunt report findings section. +- Do NOT stop the hunt. + +**Confirmed active compromise** — evidence of C2, data exfiltration, or lateral movement in progress: +- **STOP the hunt immediately.** +- Produce an escalation package: + +```markdown +## ESCALATION: Active Threat Discovered During Hunt + +**Hunt**: <title> +**Discovery Time**: <timestamp> +**Threat Type**: <C2 | Exfiltration | Lateral Movement | Other> + +### Evidence +<What was found — specific IOCs and timestamps> + +### Affected Systems +| System | Type | Evidence | +|--------|------|----------| + +### IOCs +| Indicator | Type | Context | +|-----------|------|---------| + +### Immediate Risk Assessment +<Is this ongoing? Blast radius? Next likely adversary action?> + +### Recommended Immediate Actions +1. <Containment action> +2. <Investigation action> +3. <Communication action> +``` + +- Create a handoff doc at `docs/handoffs/YYYY-MM-DD-threat-hunting-to-soc-escalation.md`: + +```yaml +source_skill: threat-hunting +target_skill: soc +objective: "Incident response for active threat discovered during hunt" +context: + hunt_title: "<title>" + threat_type: "<C2 | Exfiltration | Lateral Movement>" + discovery_time: "<timestamp>" + affected_systems: [<list>] + iocs: [<list>] +decisions_made: + - "Active threat confirmed during hunt — escalation required" + - "Hunt paused at escalation point" +constraints: + - "Time-sensitive — containment actions needed" +artifacts: + - "docs/hunts/YYYY-MM-DD-<slug>.md" +``` + +- Create a case: `case_create` → `case_add_event_evidence` → `case_add_tags(tags=["true_positive", "hunt_escalation", "<mitre_tactic>"])` +- **Surface to human** — this is the primary human-in-the-loop touchpoint. +- The hunt report is still produced (Act phase) with findings up to the escalation point. +``` + +- [ ] **Step 2: Verify section appended correctly** + +Run: `grep -n "## Execute Phase" .claude/skills/threat-hunting/SKILL.md` + +Expected: One match, at a line number after the Prepare phase. + +- [ ] **Step 3: Commit** + +```bash +git add .claude/skills/threat-hunting/SKILL.md +git commit -m "feat: add Execute phase to SKILL.md — three hunt types + escalation" +``` + +--- + +### Task 7: SKILL.md — Act phase + +**Files:** +- Modify: `.claude/skills/threat-hunting/SKILL.md` (append after the escalation section) + +- [ ] **Step 1: Append Act phase** + +Append to `.claude/skills/threat-hunting/SKILL.md` after the last line: + +```markdown + +--- + +## Act Phase + +Produce all outputs after Execute completes. Runs autonomously. + +### 1. Hunt Report + +Write the hunt report to `docs/hunts/YYYY-MM-DD-<slug>.md`. This directory is committed to git — hunt reports are permanent archival records. + +```markdown +## Hunt Report: <title> +**Date**: YYYY-MM-DD +**Type**: Hypothesis | Intelligence | Baseline +**ATT&CK Techniques**: T1234, T5678 +**Duration**: <approximate> +**Outcome**: Threat Found | No Threat — Coverage Validated | Inconclusive + +### Hypothesis / Objective +<What we were looking for and why> + +### Scope +- **Data sources**: <repos queried> +- **Time range**: <start — end> +- **Entities**: <users, hosts, IPs, services examined> + +### Findings +<Chronological investigation narrative — what was queried, what was found, what pivots were taken. Include CQL queries that produced significant results.> + +### IOCs +| Indicator | Type | Context | +|-----------|------|---------| +<Only if threat discovered. Omit this section for clean hunts.> + +### Conclusion +<2-3 sentences: what did we learn?> + +### Self-Evaluation +- **Hypothesis quality**: <Was it testable? Too broad? Too narrow?> +- **Data sufficiency**: <Did we have what we needed? What was missing?> +- **Investigation efficiency**: <Dead ends? Better paths in hindsight?> +- **Suggested next hunt**: <Based on gaps found or leads not fully pursued> +``` + +### 2. Detection Backlog + +Produced when the hunt reveals patterns that could be automated as detections. Include even for clean hunts — baseline knowledge often surfaces detectable patterns. + +Present the backlog in the hunt report, then write individual handoff docs: + +```markdown +## Proposed Detections from Hunt: <title> + +| # | Detection | ATT&CK | Approach | Complexity | Target Skill | Priority | +|---|-----------|--------|----------|------------|-------------|----------| +| 1 | <description> | T1234 | <threshold / stacking / correlation> | <Low / Medium / High> | <behavioral-detections / cql-patterns / logscale-security-queries> | <High / Medium / Low> | +``` + +For each proposed detection, write a handoff doc to `docs/handoffs/YYYY-MM-DD-threat-hunting-to-<target-skill>-<slug>.md`: + +```yaml +source_skill: threat-hunting +target_skill: behavioral-detections | cql-patterns | logscale-security-queries +objective: "Author a detection for [pattern discovered during hunt]" +context: + hunt_title: "<title>" + hunt_date: "YYYY-MM-DD" + threat_scenario: "<what the detection should find>" + mitre_technique: "<technique ID>" + mitre_tactic: "<tactic>" + detection_approach: "<simple threshold | stacking anomaly | behavioral correlation>" + key_event_types: [<event types observed during hunt>] + key_fields: [<fields used in hunt queries>] + volume_notes: "<signal volume and noise characteristics from hunt data>" + sample_query: "<CQL query from the hunt that surfaced this pattern>" +decisions_made: + - "Pattern discovered during [hunt type] hunt" + - "<context about why this detection matters>" +constraints: + - "120s query timeout" + - "<data source limitations noted during hunt>" +artifacts: + - "docs/hunts/YYYY-MM-DD-<slug>.md" +``` + +If no detectable patterns were found, skip the backlog — not every hunt produces detection opportunities. + +### 3. Gap Report + +Produced when the hunt identified visibility gaps. Append to the hunt report: + +```markdown +## Visibility Gap Report + +### Gaps Identified +| Gap | Impact | ATT&CK Techniques Affected | Recommendation | +|-----|--------|---------------------------|----------------| +| <missing data source or field> | <what can't be detected> | T1234, T5678 | <onboard source / enable logging / add field> | + +### ATT&CK Coverage Delta +<Techniques that were in scope but couldn't be tested, with reasons> +``` + +If no gaps were identified, note that all required data was available — this is valuable coverage validation. + +### 4. Update Living Documents + +After producing all outputs: + +**Hunt log** — append one row to `memory/hunt-log.md`: + +``` +| YYYY-MM-DD | <Type> | <Title> | T1234, T5678 | <Outcome> | <N detections proposed> | +``` + +**Coverage map** — update `memory/coverage-map.md`: +- Add or update entries in **Hunted** for techniques covered by this hunt. +- Add entries to **Known Gaps** for visibility gaps discovered. +- Regenerate **Suggested Priority Hunts** based on: + - **Blind spots** — techniques with no detections AND no hunting (scan `resources/detections/` for `mitre_attack` fields, compare against Hunted table) + - **Untested assumptions** — techniques with deployed detections but not in the Hunted table + - **Stale coverage** — techniques in Hunted with Last Hunted date 90+ days ago + +### 5. Suggest Next Hunt + +Based on the self-evaluation, coverage map, and findings, recommend what to hunt next: + +- Leads that weren't fully pursued during this hunt +- Adjacent ATT&CK techniques revealed by findings +- High-priority gaps from the updated coverage map +- Techniques whose detections were validated but could be tested with different data sources + +Present as: "Based on this hunt, consider hunting next: **<suggestion>** — <rationale>." +``` + +- [ ] **Step 2: Verify section appended correctly** + +Run: `grep -n "## Act Phase" .claude/skills/threat-hunting/SKILL.md` + +Expected: One match, at a line number after the Execute phase. + +- [ ] **Step 3: Commit** + +```bash +git add .claude/skills/threat-hunting/SKILL.md +git commit -m "feat: add Act phase to SKILL.md — outputs, living docs, next-hunt suggestions" +``` + +--- + +### Task 8: SKILL.md — utility modes + +**Files:** +- Modify: `.claude/skills/threat-hunting/SKILL.md` (append after the Act phase) + +- [ ] **Step 1: Append utility modes** + +Append to `.claude/skills/threat-hunting/SKILL.md` after the last line: + +```markdown + +--- + +## Utility Modes + +### `/hunt` (no arguments) — Agent-Suggested Hunting + +When invoked without arguments, analyze coverage and suggest high-value hunt targets: + +1. Read `memory/coverage-map.md` and `memory/hunt-log.md`. +2. Scan `resources/detections/` for `mitre_attack` fields to build detection coverage picture. +3. Cross-reference to surface three categories: + + | Category | Definition | Priority | + |----------|-----------|----------| + | **Blind spots** | No detections AND never hunted | Highest | + | **Untested assumptions** | Detections deployed but never hunted | High | + | **Stale coverage** | Last hunted 90+ days ago | Medium | + +4. Present the top 3-5 recommended hunts: + ``` + ## Suggested Hunts + + | # | Technique | Tactic | Category | Suggested Type | Draft Hypothesis | + |---|-----------|--------|----------|---------------|-----------------| + | 1 | T1078 Valid Accounts | Defense Evasion | Untested — 3 detections, never hunted | Baseline | Stack authentication patterns across EntraID | + ``` + +5. Wait for user to select, then proceed through Prepare → Execute → Act. + +### `/hunt log` — Display Hunt Log + +Read and present `memory/hunt-log.md` with summary statistics: +- Total hunts completed +- Breakdown by type (hypothesis / intelligence / baseline) +- Breakdown by outcome (threat found / coverage validated / inconclusive) +- Total detections proposed across all hunts +- Most recently hunted ATT&CK techniques + +### `/hunt coverage` — Display Coverage Map + +Read `memory/coverage-map.md` and cross-reference with `resources/detections/`: +- **Hunted techniques** with last hunt date, result, and data quality +- **Known gaps** with impact and recommendations +- **Detection coverage overlay** — for each hunted technique, note whether automated detections exist +- **Suggested priority hunts** with rationale +``` + +- [ ] **Step 2: Verify full SKILL.md structure** + +Run: `grep -n "^## " .claude/skills/threat-hunting/SKILL.md` + +Expected output showing all major sections in order: +``` +## Persona & Principles +## Available Tools +## Key CQL Hunting Patterns +## Phase Dispatcher +## Context Loading +## Prepare Phase +## Execute Phase +## Act Phase +## Utility Modes +``` + +- [ ] **Step 3: Check total line count** + +Run: `wc -l .claude/skills/threat-hunting/SKILL.md` + +Expected: approximately 400-500 lines. + +- [ ] **Step 4: Commit** + +```bash +git add .claude/skills/threat-hunting/SKILL.md +git commit -m "feat: add utility modes to SKILL.md — /hunt, /hunt log, /hunt coverage" +``` + +--- + +### Task 9: /hunt command router + +**Files:** +- Create: `.claude/commands/hunt.md` + +- [ ] **Step 1: Write the /hunt command file** + +Write `.claude/commands/hunt.md`: + +```xml +<command name="hunt"> + <description>Threat hunting: $ARGUMENTS</description> + + <rules priority="critical"> + <rule>Always invoke the threat-hunting skill for processing</rule> + <rule>Update .claude/skills/threat-hunting/memory/ files after every completed hunt per the Living Documents protocol</rule> + <rule>Escalate immediately on confirmed active compromise — create case, handoff doc, surface to human</rule> + <rule>Produce all three outputs (hunt report, detection backlog, gap report) in the Act phase</rule> + <rule>Never modify detection templates directly — produce handoff docs for authoring skills</rule> + </rules> + + <actions> + <action trigger="starts-with:hypothesis"> + Run a hypothesis-driven threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). + </action> + + <action trigger="starts-with:intel"> + Run an intelligence-driven threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). + </action> + + <action trigger="starts-with:baseline"> + Run a baseline/anomaly threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). + </action> + + <action trigger="starts-with:log"> + Display the hunt log. Read and summarize .claude/skills/threat-hunting/memory/hunt-log.md. + </action> + + <action trigger="starts-with:coverage"> + Display the ATT&CK coverage map. Read .claude/skills/threat-hunting/memory/coverage-map.md and cross-reference with resources/detections/. + </action> + + <action trigger="default"> + No hunt type specified. Read the coverage map and suggest high-value hunt targets. + If no arguments at all, follow the /hunt (no arguments) utility mode in the threat-hunting skill. + If arguments don't match a known subcommand, treat as a hypothesis and route to hypothesis-driven hunting. + </action> + </actions> +</command> +``` + +- [ ] **Step 2: Verify command file structure matches existing commands** + +Run: `diff <(grep -o '<[^>]*>' .claude/commands/soc.md | sort -u) <(grep -o '<[^>]*>' .claude/commands/hunt.md | sort -u)` + +Expected: Same XML elements used in both files (command, description, rules, rule, actions, action). + +- [ ] **Step 3: Commit** + +```bash +git add .claude/commands/hunt.md +git commit -m "feat: add /hunt command router" +``` + +--- + +### Task 10: Update CLAUDE.md with threat-hunting skill + +**Files:** +- Modify: `CLAUDE.md` + +- [ ] **Step 1: Add threat-hunting to the Available Skills table** + +In `CLAUDE.md`, find the skills table: + +```markdown +| `detection-tuning` | FP tuning patterns with enrichment function catalog | Stable | +``` + +Add after the last skill row: + +```markdown +| `threat-hunting` | Autonomous PEAK-based threat hunting — hypothesis, intel, baseline hunts | Experimental | +``` + +- [ ] **Step 2: Add /hunt to the Commands table** + +In `CLAUDE.md`, find the commands table: + +```markdown +| `/discuss` | Exploratory discussion mode (read-only, no changes) | +``` + +Add after: + +```markdown +| `/hunt` | Autonomous threat hunting — hypothesis, intel, baseline, coverage analysis | +``` + +- [ ] **Step 3: Add hunt subcommands section** + +In `CLAUDE.md`, find the SOC Subcommands section. Add after it: + +```markdown +### Hunt Subcommands + +``` +/hunt hypothesis "<statement>" — Hypothesis-driven hunt +/hunt intel "<context>" — Intelligence-driven hunt +/hunt baseline "<entity>" — Baseline/anomaly hunt +/hunt — Suggest hunts from coverage gaps +/hunt log — View hunt history +/hunt coverage — View ATT&CK hunt coverage map +``` +``` + +- [ ] **Step 4: Verify CLAUDE.md changes** + +Run: `grep -A1 "threat-hunting" CLAUDE.md` + +Expected: The skill table row and command table row are visible. + +- [ ] **Step 5: Commit** + +```bash +git add CLAUDE.md +git commit -m "docs: add threat-hunting skill and /hunt command to CLAUDE.md" +``` + +--- + +## Self-Review + +### Spec Coverage Check + +| Spec Section | Implementing Task | +|---|---| +| Skill Identity (name, location, persona) | Task 4 — frontmatter + persona | +| Invocation (6 command variants) | Task 5 — phase dispatcher, Task 9 — command router | +| Phase Architecture — Prepare | Task 5 | +| Phase Architecture — Execute | Task 6 | +| Phase Architecture — Act | Task 7 | +| Threat Escalation Interrupt | Task 6 — inline in Execute phase | +| MCP Tools | Task 4 — tool reference tables | +| Key CQL Patterns | Task 4 — 5 hunting-specific patterns | +| Outputs — Hunt Report | Task 7 — template in Act phase | +| Outputs — Detection Backlog | Task 7 — template + handoff doc format | +| Outputs — Gap Report | Task 7 — template in Act phase | +| Living Documents — hunt-log.md | Task 2 | +| Living Documents — coverage-map.md | Task 2 | +| Living Documents — update protocol | Task 7 — Act phase step 4 | +| Self-Evaluation | Task 7 — in hunt report template | +| Suggest Next Hunt | Task 7 — Act phase step 5, Task 8 — /hunt no-args mode | +| Coverage Map Cross-Reference | Task 5 (Prepare), Task 7 (Act), Task 8 (utility modes) | +| Integration — handoff docs | Task 7 — detection backlog handoff format | +| Integration — escalation handoff | Task 6 — escalation interrupt | +| File Structure | Task 1 (scaffold), Task 3 (DESIGN.md) | +| Context Loading Order | Task 5 | +| docs/hunts/ (committed) | Task 1 — .gitkeep | +| docs/handoffs/ (gitignored) | Task 1 — .gitignore | +| CLAUDE.md updates | Task 10 | + +All spec sections are covered. + +### Placeholder Scan + +No TBDs, TODOs, "implement later", or "similar to Task N" found. + +### Type/Name Consistency + +- `memory/hunt-log.md` — consistent across Tasks 2, 5, 7, 8 +- `memory/coverage-map.md` — consistent across Tasks 2, 5, 7, 8 +- `environmental-context.md` path — `.claude/skills/soc/environmental-context.md` in Task 5 +- `investigation-techniques.md` path — `.claude/skills/soc/memory/investigation-techniques.md` in Task 5 +- `resources/detections/` + `mitre_attack` field — consistent across Tasks 5, 7, 8 +- `resources/saved_searches/hunting/` — referenced in Task 5 (Prepare) +- `docs/hunts/YYYY-MM-DD-<slug>.md` — consistent across Tasks 1, 6, 7 +- `docs/handoffs/YYYY-MM-DD-threat-hunting-to-<skill>-<slug>.md` — consistent across Tasks 6, 7 +- Handoff doc field names (`source_skill`, `target_skill`, `objective`, `context`, `decisions_made`, `constraints`, `artifacts`) — consistent with source-threat-modeling spec +- MCP tool names — match exactly what SOC skill SKILL.md uses +- Command name `/hunt` — consistent across Tasks 5, 8, 9, 10 From cc1e0b502d89d1377d1cbea68d7c4ee2c8eac315 Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:45:01 -0400 Subject: [PATCH 04/14] scaffold: threat-hunting skill directories and docs/hunts, docs/handoffs --- docs/handoffs/.gitignore | 4 ++++ docs/hunts/.gitkeep | 0 2 files changed, 4 insertions(+) create mode 100644 docs/handoffs/.gitignore create mode 100644 docs/hunts/.gitkeep diff --git a/docs/handoffs/.gitignore b/docs/handoffs/.gitignore new file mode 100644 index 0000000..fe2dd9a --- /dev/null +++ b/docs/handoffs/.gitignore @@ -0,0 +1,4 @@ +# Handoff docs are ephemeral working artifacts — not permanent records. +# They are created by one skill and consumed by another, then cleaned up. +* +!.gitignore diff --git a/docs/hunts/.gitkeep b/docs/hunts/.gitkeep new file mode 100644 index 0000000..e69de29 From 66ed88e605054c1218096cd8b0dd1e2c50036163 Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:47:29 -0400 Subject: [PATCH 05/14] feat: add threat-hunting living document templates (hunt log + coverage map) --- .../threat-hunting/memory/coverage-map.md | 26 +++++++++++++++++++ .../skills/threat-hunting/memory/hunt-log.md | 10 +++++++ 2 files changed, 36 insertions(+) create mode 100644 .claude/skills/threat-hunting/memory/coverage-map.md create mode 100644 .claude/skills/threat-hunting/memory/hunt-log.md diff --git a/.claude/skills/threat-hunting/memory/coverage-map.md b/.claude/skills/threat-hunting/memory/coverage-map.md new file mode 100644 index 0000000..bb49fea --- /dev/null +++ b/.claude/skills/threat-hunting/memory/coverage-map.md @@ -0,0 +1,26 @@ +<!-- LIVING DOCUMENT +Updated by the threat-hunting skill after every completed hunt. +Tracks the HUNT LAYER — what has been proactively hunted. +Cross-referenced during Prepare against deployed detection MITRE +mappings from resources/detections/ to identify high-value targets. + +Three categories of high-value hunt targets: +1. Blind spots — no detections AND no hunting (highest priority) +2. Untested assumptions — detections exist but never hunted +3. Stale coverage — not hunted in 90+ days --> + +# ATT&CK Hunt Coverage Map + +## Hunted + +| Technique | Tactic | Last Hunted | Result | Data Quality | +|-----------|--------|-------------|--------|--------------| + +## Known Gaps + +| Technique | Tactic | Reason | Recommendation | +|-----------|--------|--------|----------------| + +## Suggested Priority Hunts + +_No hunts completed yet. After the first hunt, this section will be populated with recommendations based on gaps, staleness, and untested detection coverage._ diff --git a/.claude/skills/threat-hunting/memory/hunt-log.md b/.claude/skills/threat-hunting/memory/hunt-log.md new file mode 100644 index 0000000..566a525 --- /dev/null +++ b/.claude/skills/threat-hunting/memory/hunt-log.md @@ -0,0 +1,10 @@ +<!-- LIVING DOCUMENT +Updated by the threat-hunting skill after every completed hunt. +Append-only — one row per hunt. Do not delete entries. +Used during Prepare phase to avoid redundant hunts and during +/hunt (no args) to summarize hunting activity. --> + +# Hunt Log + +| Date | Type | Title | ATT&CK | Outcome | Detections Proposed | +|------|------|-------|--------|---------|---------------------| From 7e524bbf78eaacb137bc25ac6a38172fe8990e5b Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:48:37 -0400 Subject: [PATCH 06/14] docs: add threat-hunting skill architecture rationale --- .claude/skills/threat-hunting/DESIGN.md | 55 +++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .claude/skills/threat-hunting/DESIGN.md diff --git a/.claude/skills/threat-hunting/DESIGN.md b/.claude/skills/threat-hunting/DESIGN.md new file mode 100644 index 0000000..f1401e3 --- /dev/null +++ b/.claude/skills/threat-hunting/DESIGN.md @@ -0,0 +1,55 @@ +# Threat Hunting Skill — Architecture Rationale + +## Problem + +ClaudeStrike's hunting capability is a 6-step subcommand (`/soc hunt`) with no structured preparation, no post-hunt outputs, no feedback loop into detection engineering, and no institutional knowledge accumulation. The research literature establishes that hunting's compounding value comes from the hunting → detection engineering pipeline. ClaudeStrike has the downstream skills (`behavioral-detections`, `cql-patterns`, `detection-tuning`) but no structured upstream practice feeding them. + +## Architecture: Autonomous PEAK Framework + +This skill implements the PEAK framework (Prepare → Execute → Act) as an autonomous agent — minimal human-in-the-loop, with escalation as the primary interrupt. + +### Why Autonomous (vs. Phased with Human Gates) + +The SOC skill uses phased architecture with human checkpoints to prevent confirmation bias during triage. Hunting has a different dynamic — the agent is exploring, not reacting to an alert. Rigid gates fight the exploratory nature of hunting. The agent drives end-to-end; humans provide the trigger and review outputs. + +### Why Three Hunt Types + +PEAK recognizes three types: hypothesis-driven, baseline (anomaly), and model-assisted (intelligence-driven in our case). CrowdStrike's NGSIEM supports all three — CQL handles stacking natively for baseline hunts, `ngsiem_query` supports ad-hoc hypothesis testing, and IOC/TTP sweeps work for intelligence-driven hunts. + +### Why Standalone (vs. Replacing /soc hunt) + +Clean separation of concerns. `/soc hunt` stays as a quick ad-hoc mode for simple IOC sweeps during triage. This skill handles the full PEAK lifecycle — scoping, execution, detection backlog, gap reporting, self-evaluation. + +### Why Lightweight Living Documents + +A hunt log prevents redundant work. An ATT&CK coverage map enables gap-based prioritization. Baselines are better expressed as saved CQL queries or detection rules than memory files. Hypothesis backlogs are project management, not skill memory. + +### Why Tiered Escalation + +Real hunt teams don't stop investigating at the first suspicious finding. They establish scope first. But confirmed active compromise (C2, exfiltration, lateral movement) demands immediate containment. "Does this need containment?" is the decision boundary. + +## Key Design Decisions + +| Decision | Choice | +|---|---| +| Relationship to `/soc hunt` | Standalone — independent skill | +| Hunt types | Hypothesis, intelligence, baseline | +| Human-in-the-loop | Minimal — agentic, escalation is the interrupt | +| Outputs | Hunt report + detection backlog + gap report | +| Living documents | Hunt log + ATT&CK coverage map | +| Escalation | Tiered — continue for suspected, hard stop for active compromise | +| Self-evaluation | Part of Act phase, feeds coverage map | + +## Integration Points + +- **Upstream:** Human invocation, coverage map suggestions, source-threat-modeling handoffs, SOC triage findings, external intel +- **Downstream:** Detection authoring skills (via handoff docs), SOC skill (via escalation handoff), source-threat-modeling (via gap reports) +- **Shared context:** `environmental-context.md` and `investigation-techniques.md` from the SOC skill + +## Research Foundation + +Design grounded in the threat hunting research survey. Key concepts: PEAK framework (Bianco et al., 2023), Hunting Maturity Model (targeting HM4), Pyramid of Pain, stacking/long-tail analysis, hunt → detection engineering feedback loop. + +## Full Spec + +`docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md` From cae28b32cf29362d7326fee4c5bead91dd7a0aa7 Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:51:23 -0400 Subject: [PATCH 07/14] =?UTF-8?q?feat:=20add=20threat-hunting=20SKILL.md?= =?UTF-8?q?=20=E2=80=94=20persona,=20tools,=20CQL=20patterns?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/skills/threat-hunting/SKILL.md | 114 +++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 .claude/skills/threat-hunting/SKILL.md diff --git a/.claude/skills/threat-hunting/SKILL.md b/.claude/skills/threat-hunting/SKILL.md new file mode 100644 index 0000000..87d960f --- /dev/null +++ b/.claude/skills/threat-hunting/SKILL.md @@ -0,0 +1,114 @@ +--- +name: threat-hunting +description: Autonomous threat hunting using the PEAK framework (Prepare → Execute → Act). Executes hypothesis-driven, intelligence-driven, and baseline hunts against CrowdStrike NG-SIEM. Produces hunt reports, detection backlogs, and visibility gap reports. Use when proactively hunting for threats, validating detection coverage, or responding to new threat intelligence. +--- + +> Threat hunting skill loaded — PEAK framework (Prepare → Execute → Act). Sub-skills: `logscale-security-queries` (CQL), `cql-patterns` (query patterns), `behavioral-detections` (correlation rules). + +# Threat Hunting — Autonomous PEAK-Based Hunting + +Autonomous threat hunter operating inside a CrowdStrike NG-SIEM environment. Assumes breach. Follows leads. Produces actionable outputs. + +## Persona & Principles + +You are an autonomous threat hunter. You drive the full PEAK lifecycle without human gates between phases. The human provides the trigger and reviews your outputs. + +- **Assume breach.** The environment is compromised until proven otherwise. Your job is to find what automated defenses missed. +- **Follow leads.** When you find something interesting, pivot — correlate across data sources, expand scope, dig deeper. Don't stop at the first query. +- **No hunt fails.** A hunt that finds no threats validates coverage, identifies visibility gaps, and strengthens baselines. Every hunt produces value. +- **IOCs are ephemeral, TTPs are durable.** When hunting from intelligence, escalate from indicators (hashes, IPs, domains) to behaviors (process chains, persistence patterns, lateral movement). Climb the Pyramid of Pain. +- **Feed the pipeline.** Every pattern you discover that could be automated should become a proposed detection. The hunting → detection engineering feedback loop is where compounding value lives. +- **Know your data.** Before running queries, confirm the data source exists and the fields are correct. Consult `investigation-techniques.md` for repo mappings and field gotchas. A query against the wrong repo returns 0 results silently. +- **Escalate active threats immediately.** If you discover confirmed active compromise (C2, exfiltration, lateral movement in progress), stop hunting and produce an escalation package. "Does this need containment?" is the decision boundary. + +## Available Tools + +**CrowdStrike MCP tools** — call these directly as MCP tool invocations. Do NOT write Python scripts or wrapper code. + +### Hunting & Investigation +| MCP Tool | Purpose | +|----------|---------| +| `mcp__crowdstrike__ngsiem_query` | Execute CQL queries — the primary hunting tool. Multiple queries per hunt. | +| `mcp__crowdstrike__get_alerts` | Check if existing detections already fired for entities discovered during hunt | +| `mcp__crowdstrike__alert_analysis` | Deep dive on a specific alert found during correlation | + +### Host Context +| MCP Tool | Purpose | +|----------|---------| +| `mcp__crowdstrike__host_lookup` | Device posture: OS, containment status, policies, agent version | +| `mcp__crowdstrike__host_login_history` | Recent logins on a device (local, remote, interactive) | +| `mcp__crowdstrike__host_network_history` | IP changes, VPN connections, network interface history | + +### Cloud Context +| MCP Tool | Purpose | +|----------|---------| +| `mcp__crowdstrike__cloud_query_assets` | Look up cloud resource by resource_id — config, exposure, tags | +| `mcp__crowdstrike__cloud_get_iom_detections` | CSPM compliance evaluations with MITRE, CIS, NIST mapping | +| `mcp__crowdstrike__cloud_get_risks` | Cloud risks ranked by score — misconfigs, unused identities | + +### Escalation (confirmed active compromise only) +| MCP Tool | Purpose | +|----------|---------| +| `mcp__crowdstrike__case_create` | Create case for confirmed threat | +| `mcp__crowdstrike__case_add_event_evidence` | Attach hunt findings as evidence | +| `mcp__crowdstrike__case_add_tags` | Tag case for classification and routing | + +### Local Tools +| Tool | Purpose | +|------|---------| +| File tools (Read, Grep, Glob) | Read detection templates, search for MITRE mappings, read memory files | + +## Key CQL Hunting Patterns + +Beyond `cql-patterns` and `logscale-security-queries`, these patterns are specific to hunting: + +### Stacking (Long-Tail Analysis) +Find rare values — the workhorse hunting technique: +```cql +// Stack by attribute, sort ascending to surface outliers at the bottom +groupBy([field], function=count()) | sort(_count, order=asc) | tail(50) + +// Multi-attribute stacking — catches malware with legitimate names in suspicious paths +groupBy([ServiceName, ServicePath], function=count()) | sort(_count, order=asc) | tail(50) +``` + +### Temporal Clustering +Detect bursts of activity in time windows: +```cql +bucket(span=5m) +| groupBy([_bucket, user.email], function=count()) +| where(_count > 20) +``` + +### Cross-Source Correlation +Same entity across multiple repos in the same time window: +```cql +// Query 1: Find suspicious IP in CloudTrail +(#repo="cloudtrail" OR #repo="fcs_csp_events") source.ip="<suspicious_ip>" +| groupBy([event.action, Vendor.userIdentity.arn]) + +// Query 2: Same IP in EntraID sign-in logs +(#repo="microsoft_graphapi" OR #repo="3pi_microsoft_entra_id" OR #repo="fcs_csp_events") +#event.dataset=/entraid/ source.ip="<suspicious_ip>" +| groupBy([user.email, #event.outcome]) +``` + +### Process Tree Reconstruction +Parent-child PID chaining for endpoint telemetry: +```cql +#event_simpleName=ProcessRollup2 aid=<device_id> +| ParentProcessId=<target_pid> OR TargetProcessId=<target_pid> +| table([@timestamp, FileName, CommandLine, ParentBaseFileName, TargetProcessId, ParentProcessId]) +| sort(@timestamp, order=asc) +``` + +### Beacon Detection +Periodic callback patterns via time-delta analysis: +```cql +#event_simpleName=DnsRequest aid=<device_id> +| DomainName=<suspect_domain> +| sort(@timestamp, order=asc) +| timeDelta(@timestamp, as=delta_ms) +| stats([avg(delta_ms, as=avg_interval), stddev(delta_ms, as=jitter), count()]) +// Low jitter + regular interval = likely beacon +``` From d6a46239eda9d3678233dd773cb69b7d2715bb6d Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:52:24 -0400 Subject: [PATCH 08/14] feat: add phase dispatcher, context loading, and Prepare phase to SKILL.md --- .claude/skills/threat-hunting/SKILL.md | 86 ++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/.claude/skills/threat-hunting/SKILL.md b/.claude/skills/threat-hunting/SKILL.md index 87d960f..c1a0ac7 100644 --- a/.claude/skills/threat-hunting/SKILL.md +++ b/.claude/skills/threat-hunting/SKILL.md @@ -112,3 +112,89 @@ Periodic callback patterns via time-delta analysis: | stats([avg(delta_ms, as=avg_interval), stddev(delta_ms, as=jitter), count()]) // Low jitter + regular interval = likely beacon ``` + +## Phase Dispatcher + +Route based on invocation: + +| Command | Action | +|---------|--------| +| `/hunt hypothesis "<statement>"` | Full PEAK cycle — hypothesis-driven hunt | +| `/hunt intel "<context>"` | Full PEAK cycle — intelligence-driven hunt | +| `/hunt baseline "<entity>"` | Full PEAK cycle — baseline/anomaly hunt | +| `/hunt` | Read coverage map, suggest high-value hunt targets | +| `/hunt log` | Display hunt log summary | +| `/hunt coverage` | Display ATT&CK coverage map with gap analysis | + +## Context Loading + +Load at skill invocation (all hunt types): + +1. Read `memory/hunt-log.md` — what hunts have been completed +2. Read `memory/coverage-map.md` — ATT&CK technique coverage and gaps +3. Read `.claude/skills/soc/environmental-context.md` — org baselines, known accounts, infrastructure +4. Read `.claude/skills/soc/memory/investigation-techniques.md` — repo mappings, field gotchas + +Load during Prepare phase: +5. Scan `resources/detections/` for `mitre_attack` fields — existing automated detection coverage +6. Check `resources/saved_searches/hunting/` — existing hunting queries that may be relevant + +Sub-skills loaded on demand: +- `logscale-security-queries` — when writing CQL queries +- `cql-patterns` — when designing detection backlog entries +- `behavioral-detections` — when proposing correlation-based detections + +--- + +## Prepare Phase + +Scope the hunt before running any queries. This phase runs autonomously. + +### All Hunt Types + +1. **Identify ATT&CK techniques** — map the hunt objective to specific MITRE ATT&CK technique IDs. + +2. **Cross-reference detection coverage** — scan `resources/detections/` for templates with matching `mitre_attack` fields. Grep for the technique ID: + ```bash + grep -rl "T1234" resources/detections/ + ``` + Note the coverage category: + - Technique with deployed detections but never hunted = **untested assumption** + - Technique with no detections AND never hunted = **blind spot** + - Technique hunted 90+ days ago = **stale coverage** + +3. **Check hunt log** — has this technique been hunted before? When? What was found? Avoid redundant work, but re-hunting after 90 days is valid. + +4. **Check existing hunting queries** — scan `resources/saved_searches/hunting/` for relevant saved searches. These may provide ready-made CQL for the target technique. + +5. **Establish CQL scope filter** — determine which NGSIEM repos to query using the repo mapping table from `investigation-techniques.md`. Validate the data source exists: + ```cql + <scope_filter> | count() + ``` + If 0 results, the data source may not be ingested. Log the gap. + +6. **Define time range** — 7 days default for hypothesis and intel hunts. 30 days for baseline hunts. Adjust based on data volume. + +7. **Define success/failure criteria** — what evidence would confirm or refute? What constitutes a meaningful anomaly? + +### Hypothesis-Driven Additions + +- Parse the hypothesis into testable components. A good hypothesis is narrow enough to prove or disprove within bounded effort. +- Identify the specific event types and fields needed to test each component. +- If required data sources are missing, log the gap and either: + - Pivot to what's available (test a related hypothesis against available data) + - Abort early with a gap report if the hunt is fundamentally blocked + +### Intelligence-Driven Additions + +- Extract IOCs from the provided intel: IP addresses, domains, file hashes, user agents, tool names. +- Extract TTPs: what techniques and procedures does the intel describe? +- **Pyramid of Pain escalation plan:** start with IOC sweeps (quick wins), then escalate to TTP hunting (durable value). Map each TTP to CQL-queryable telemetry. +- If the intel references specific threat actors, note their known TTPs for broader behavioral hunting. + +### Baseline Additions + +- Identify the entity/behavior class: scheduled tasks, services, autorun entries, user-agent strings, DNS queries, process names, network connections. +- Determine stacking attributes — what to `groupBy()` and what to `count()`. Choose attribute groupings carefully: stacking only on name misses malware with legitimate names in suspicious paths. Combine name + path + host. +- Establish time window: 7 days minimum, 30 days preferred for stable environments. +- Rule of thumb: any single stack review should take no more than 10 minutes of analysis. If results are overwhelming, narrow context. From a52d5a418b6de79597bf95f0aa3854bdec81d277 Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:53:40 -0400 Subject: [PATCH 09/14] =?UTF-8?q?feat:=20add=20Execute=20phase=20to=20SKIL?= =?UTF-8?q?L.md=20=E2=80=94=20three=20hunt=20types=20+=20escalation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/skills/threat-hunting/SKILL.md | 123 +++++++++++++++++++++++++ 1 file changed, 123 insertions(+) diff --git a/.claude/skills/threat-hunting/SKILL.md b/.claude/skills/threat-hunting/SKILL.md index c1a0ac7..c6a5be9 100644 --- a/.claude/skills/threat-hunting/SKILL.md +++ b/.claude/skills/threat-hunting/SKILL.md @@ -198,3 +198,126 @@ Scope the hunt before running any queries. This phase runs autonomously. - Determine stacking attributes — what to `groupBy()` and what to `count()`. Choose attribute groupings carefully: stacking only on name misses malware with legitimate names in suspicious paths. Combine name + path + host. - Establish time window: 7 days minimum, 30 days preferred for stable environments. - Rule of thumb: any single stack review should take no more than 10 minutes of analysis. If results are overwhelming, narrow context. + +--- + +## Execute Phase + +Fluid and exploratory. Follow leads, pivot, adapt. Document the investigation chain as you go — this narrative feeds the hunt report. + +### Hypothesis-Driven Execution + +1. **Run primary hypothesis test queries** — direct CQL queries against the scoped data sources and time range. +2. **Analyze results:** + - Results support the hypothesis → dig deeper. What's the scope? Which systems/users are affected? + - Results refute the hypothesis → attempt alternative detection angles for the same TTP. Different event types, different fields, different time windows. + - Inconclusive → broaden scope or pivot to adjacent techniques. +3. **Pivot on leads** — when an interesting entity (user, IP, host) surfaces: + - Cross-correlate across data sources (CloudTrail + EntraID + endpoint + DNS) + - Alert correlation: `get_alerts` for the entity — have existing detections already fired? + - Pull host/cloud context for interesting endpoints or resources +4. **Document evidence chain** — record each query, what it found, and why you pivoted. This becomes the Findings section of the hunt report. + +### Intelligence-Driven Execution + +1. **IOC sweep** — search for known indicators across all relevant repos. Fast, concrete results. + ```cql + // Example: sweep for suspicious IP across all data sources + source.ip="<ioc_ip>" OR destination.ip="<ioc_ip>" + | groupBy([#repo, event.action, source.ip, destination.ip], function=count()) + ``` +2. **Pivot from IOC hits** — if any IOC matches: + - What else did that actor/IP/hash do? Expand the query to all activity from that entity. + - Timeline analysis: what happened in the 30 minutes before and after the IOC match? + - Scope assessment: how many systems/users are affected? +3. **TTP hunting (even without IOC matches)** — IOCs rotate trivially; behaviors persist. + - Hunt for the behavioral patterns described in the intel regardless of IOC results. + - Use process tree analysis, login correlation, network pattern analysis. + - This is where durable detection value lives. +4. **Cross-correlate across data sources** — adversaries don't stay in one log source. Check the repo mapping table and query every relevant source for the entities under investigation. + +### Baseline Execution + +1. **Run stacking queries** — frequency counts across the target attribute grouping. + ```cql + // Example: stack scheduled tasks across all Windows endpoints + #event_simpleName=ScheduledTaskRegistered + | groupBy([TaskName, TaskExecCommand], function=[count(), collect(ComputerName)]) + | sort(_count, order=asc) + | tail(50) + ``` +2. **Identify statistical outliers:** + - Entities on only 1-2 systems (vs. hundreds) — investigate. + - Unusual values — names that don't fit the pattern, paths in unexpected locations. + - Low-frequency entries at the tail of the distribution. +3. **Investigate outliers** — for each outlier: + - Context queries: host lookup, user lookup, process tree reconstruction. + - Environmental context check: is this a known application, service account, or infrastructure component? + - If anomalous AND unexplained → potential finding. Document it. +4. **Establish baseline documentation** — record what "normal" looks like. This is valuable even if no threats are found — it informs future hunts and detection tuning. + +### Threat Escalation Interrupt + +Applies to all hunt types. Two tiers based on "does this need containment?": + +**Suspected threat** — interesting but not confirmed: +- Flag the finding in your investigation notes. +- **Continue hunting** to establish scope and gather more evidence. +- Present in the hunt report findings section. +- Do NOT stop the hunt. + +**Confirmed active compromise** — evidence of C2, data exfiltration, or lateral movement in progress: +- **STOP the hunt immediately.** +- Produce an escalation package: + +```markdown +## ESCALATION: Active Threat Discovered During Hunt + +**Hunt**: <title> +**Discovery Time**: <timestamp> +**Threat Type**: <C2 | Exfiltration | Lateral Movement | Other> + +### Evidence +<What was found — specific IOCs and timestamps> + +### Affected Systems +| System | Type | Evidence | +|--------|------|----------| + +### IOCs +| Indicator | Type | Context | +|-----------|------|---------| + +### Immediate Risk Assessment +<Is this ongoing? Blast radius? Next likely adversary action?> + +### Recommended Immediate Actions +1. <Containment action> +2. <Investigation action> +3. <Communication action> +``` + +- Create a handoff doc at `docs/handoffs/YYYY-MM-DD-threat-hunting-to-soc-escalation.md`: + +```yaml +source_skill: threat-hunting +target_skill: soc +objective: "Incident response for active threat discovered during hunt" +context: + hunt_title: "<title>" + threat_type: "<C2 | Exfiltration | Lateral Movement>" + discovery_time: "<timestamp>" + affected_systems: [<list>] + iocs: [<list>] +decisions_made: + - "Active threat confirmed during hunt — escalation required" + - "Hunt paused at escalation point" +constraints: + - "Time-sensitive — containment actions needed" +artifacts: + - "docs/hunts/YYYY-MM-DD-<slug>.md" +``` + +- Create a case: `case_create` → `case_add_event_evidence` → `case_add_tags(tags=["true_positive", "hunt_escalation", "<mitre_tactic>"])` +- **Surface to human** — this is the primary human-in-the-loop touchpoint. +- The hunt report is still produced (Act phase) with findings up to the escalation point. From 2ab3d80b2b1271fc71939e7ab22d758121b7e45c Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:54:43 -0400 Subject: [PATCH 10/14] =?UTF-8?q?feat:=20add=20Act=20phase=20to=20SKILL.md?= =?UTF-8?q?=20=E2=80=94=20outputs,=20living=20docs,=20next-hunt=20suggesti?= =?UTF-8?q?ons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/skills/threat-hunting/SKILL.md | 134 +++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/.claude/skills/threat-hunting/SKILL.md b/.claude/skills/threat-hunting/SKILL.md index c6a5be9..cae0b1a 100644 --- a/.claude/skills/threat-hunting/SKILL.md +++ b/.claude/skills/threat-hunting/SKILL.md @@ -321,3 +321,137 @@ artifacts: - Create a case: `case_create` → `case_add_event_evidence` → `case_add_tags(tags=["true_positive", "hunt_escalation", "<mitre_tactic>"])` - **Surface to human** — this is the primary human-in-the-loop touchpoint. - The hunt report is still produced (Act phase) with findings up to the escalation point. + +--- + +## Act Phase + +Produce all outputs after Execute completes. Runs autonomously. + +### 1. Hunt Report + +Write the hunt report to `docs/hunts/YYYY-MM-DD-<slug>.md`. This directory is committed to git — hunt reports are permanent archival records. + +```markdown +## Hunt Report: <title> +**Date**: YYYY-MM-DD +**Type**: Hypothesis | Intelligence | Baseline +**ATT&CK Techniques**: T1234, T5678 +**Duration**: <approximate> +**Outcome**: Threat Found | No Threat — Coverage Validated | Inconclusive + +### Hypothesis / Objective +<What we were looking for and why> + +### Scope +- **Data sources**: <repos queried> +- **Time range**: <start — end> +- **Entities**: <users, hosts, IPs, services examined> + +### Findings +<Chronological investigation narrative — what was queried, what was found, what pivots were taken. Include CQL queries that produced significant results.> + +### IOCs +| Indicator | Type | Context | +|-----------|------|---------| +<Only if threat discovered. Omit this section for clean hunts.> + +### Conclusion +<2-3 sentences: what did we learn?> + +### Self-Evaluation +- **Hypothesis quality**: <Was it testable? Too broad? Too narrow?> +- **Data sufficiency**: <Did we have what we needed? What was missing?> +- **Investigation efficiency**: <Dead ends? Better paths in hindsight?> +- **Suggested next hunt**: <Based on gaps found or leads not fully pursued> +``` + +### 2. Detection Backlog + +Produced when the hunt reveals patterns that could be automated as detections. Include even for clean hunts — baseline knowledge often surfaces detectable patterns. + +Present the backlog in the hunt report, then write individual handoff docs: + +```markdown +## Proposed Detections from Hunt: <title> + +| # | Detection | ATT&CK | Approach | Complexity | Target Skill | Priority | +|---|-----------|--------|----------|------------|-------------|----------| +| 1 | <description> | T1234 | <threshold / stacking / correlation> | <Low / Medium / High> | <behavioral-detections / cql-patterns / logscale-security-queries> | <High / Medium / Low> | +``` + +For each proposed detection, write a handoff doc to `docs/handoffs/YYYY-MM-DD-threat-hunting-to-<target-skill>-<slug>.md`: + +```yaml +source_skill: threat-hunting +target_skill: behavioral-detections | cql-patterns | logscale-security-queries +objective: "Author a detection for [pattern discovered during hunt]" +context: + hunt_title: "<title>" + hunt_date: "YYYY-MM-DD" + threat_scenario: "<what the detection should find>" + mitre_technique: "<technique ID>" + mitre_tactic: "<tactic>" + detection_approach: "<simple threshold | stacking anomaly | behavioral correlation>" + key_event_types: [<event types observed during hunt>] + key_fields: [<fields used in hunt queries>] + volume_notes: "<signal volume and noise characteristics from hunt data>" + sample_query: "<CQL query from the hunt that surfaced this pattern>" +decisions_made: + - "Pattern discovered during [hunt type] hunt" + - "<context about why this detection matters>" +constraints: + - "120s query timeout" + - "<data source limitations noted during hunt>" +artifacts: + - "docs/hunts/YYYY-MM-DD-<slug>.md" +``` + +If no detectable patterns were found, skip the backlog — not every hunt produces detection opportunities. + +### 3. Gap Report + +Produced when the hunt identified visibility gaps. Append to the hunt report: + +```markdown +## Visibility Gap Report + +### Gaps Identified +| Gap | Impact | ATT&CK Techniques Affected | Recommendation | +|-----|--------|---------------------------|----------------| +| <missing data source or field> | <what can't be detected> | T1234, T5678 | <onboard source / enable logging / add field> | + +### ATT&CK Coverage Delta +<Techniques that were in scope but couldn't be tested, with reasons> +``` + +If no gaps were identified, note that all required data was available — this is valuable coverage validation. + +### 4. Update Living Documents + +After producing all outputs: + +**Hunt log** — append one row to `memory/hunt-log.md`: + +``` +| YYYY-MM-DD | <Type> | <Title> | T1234, T5678 | <Outcome> | <N detections proposed> | +``` + +**Coverage map** — update `memory/coverage-map.md`: +- Add or update entries in **Hunted** for techniques covered by this hunt. +- Add entries to **Known Gaps** for visibility gaps discovered. +- Regenerate **Suggested Priority Hunts** based on: + - **Blind spots** — techniques with no detections AND no hunting (scan `resources/detections/` for `mitre_attack` fields, compare against Hunted table) + - **Untested assumptions** — techniques with deployed detections but not in the Hunted table + - **Stale coverage** — techniques in Hunted with Last Hunted date 90+ days ago + +### 5. Suggest Next Hunt + +Based on the self-evaluation, coverage map, and findings, recommend what to hunt next: + +- Leads that weren't fully pursued during this hunt +- Adjacent ATT&CK techniques revealed by findings +- High-priority gaps from the updated coverage map +- Techniques whose detections were validated but could be tested with different data sources + +Present as: "Based on this hunt, consider hunting next: **<suggestion>** — <rationale>." From c87a3a4e81fccf0fc783f9d0f1def2e50f2fa28c Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:56:14 -0400 Subject: [PATCH 11/14] =?UTF-8?q?feat:=20add=20utility=20modes=20to=20SKIL?= =?UTF-8?q?L.md=20=E2=80=94=20/hunt,=20/hunt=20log,=20/hunt=20coverage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/skills/threat-hunting/SKILL.md | 46 ++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/.claude/skills/threat-hunting/SKILL.md b/.claude/skills/threat-hunting/SKILL.md index cae0b1a..0166218 100644 --- a/.claude/skills/threat-hunting/SKILL.md +++ b/.claude/skills/threat-hunting/SKILL.md @@ -455,3 +455,49 @@ Based on the self-evaluation, coverage map, and findings, recommend what to hunt - Techniques whose detections were validated but could be tested with different data sources Present as: "Based on this hunt, consider hunting next: **<suggestion>** — <rationale>." + +--- + +## Utility Modes + +### `/hunt` (no arguments) — Agent-Suggested Hunting + +When invoked without arguments, analyze coverage and suggest high-value hunt targets: + +1. Read `memory/coverage-map.md` and `memory/hunt-log.md`. +2. Scan `resources/detections/` for `mitre_attack` fields to build detection coverage picture. +3. Cross-reference to surface three categories: + + | Category | Definition | Priority | + |----------|-----------|----------| + | **Blind spots** | No detections AND never hunted | Highest | + | **Untested assumptions** | Detections deployed but never hunted | High | + | **Stale coverage** | Last hunted 90+ days ago | Medium | + +4. Present the top 3-5 recommended hunts: + ``` + ## Suggested Hunts + + | # | Technique | Tactic | Category | Suggested Type | Draft Hypothesis | + |---|-----------|--------|----------|---------------|-----------------| + | 1 | T1078 Valid Accounts | Defense Evasion | Untested — 3 detections, never hunted | Baseline | Stack authentication patterns across EntraID | + ``` + +5. Wait for user to select, then proceed through Prepare → Execute → Act. + +### `/hunt log` — Display Hunt Log + +Read and present `memory/hunt-log.md` with summary statistics: +- Total hunts completed +- Breakdown by type (hypothesis / intelligence / baseline) +- Breakdown by outcome (threat found / coverage validated / inconclusive) +- Total detections proposed across all hunts +- Most recently hunted ATT&CK techniques + +### `/hunt coverage` — Display Coverage Map + +Read `memory/coverage-map.md` and cross-reference with `resources/detections/`: +- **Hunted techniques** with last hunt date, result, and data quality +- **Known gaps** with impact and recommendations +- **Detection coverage overlay** — for each hunted technique, note whether automated detections exist +- **Suggested priority hunts** with rationale From 33357af61e28dbaf12ff6370a4724e1c9fbef851 Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:56:54 -0400 Subject: [PATCH 12/14] feat: add /hunt command router --- .claude/commands/hunt.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 .claude/commands/hunt.md diff --git a/.claude/commands/hunt.md b/.claude/commands/hunt.md new file mode 100644 index 0000000..1dd06e2 --- /dev/null +++ b/.claude/commands/hunt.md @@ -0,0 +1,39 @@ +<command name="hunt"> + <description>Threat hunting: $ARGUMENTS</description> + + <rules priority="critical"> + <rule>Always invoke the threat-hunting skill for processing</rule> + <rule>Update .claude/skills/threat-hunting/memory/ files after every completed hunt per the Living Documents protocol</rule> + <rule>Escalate immediately on confirmed active compromise — create case, handoff doc, surface to human</rule> + <rule>Produce all three outputs (hunt report, detection backlog, gap report) in the Act phase</rule> + <rule>Never modify detection templates directly — produce handoff docs for authoring skills</rule> + </rules> + + <actions> + <action trigger="starts-with:hypothesis"> + Run a hypothesis-driven threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). + </action> + + <action trigger="starts-with:intel"> + Run an intelligence-driven threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). + </action> + + <action trigger="starts-with:baseline"> + Run a baseline/anomaly threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). + </action> + + <action trigger="starts-with:log"> + Display the hunt log. Read and summarize .claude/skills/threat-hunting/memory/hunt-log.md. + </action> + + <action trigger="starts-with:coverage"> + Display the ATT&CK coverage map. Read .claude/skills/threat-hunting/memory/coverage-map.md and cross-reference with resources/detections/. + </action> + + <action trigger="default"> + No hunt type specified. Read the coverage map and suggest high-value hunt targets. + If no arguments at all, follow the /hunt (no arguments) utility mode in the threat-hunting skill. + If arguments don't match a known subcommand, treat as a hypothesis and route to hypothesis-driven hunting. + </action> + </actions> +</command> From 8c298e2935d184b51239998806f879ce54b44381 Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 22:58:07 -0400 Subject: [PATCH 13/14] docs: add threat-hunting skill and /hunt command to CLAUDE.md --- CLAUDE.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 4a4e7db..46589fc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,6 +65,7 @@ Skills live in `.claude/skills/` and are invoked via Claude Code commands. | `logscale-security-queries` | LogScale/NGSIEM query reference and investigation playbooks | Stable | | `fusion-workflows` | Falcon Fusion workflow templates and YAML schema | Stable | | `detection-tuning` | FP tuning patterns with enrichment function catalog | Stable | +| `threat-hunting` | Autonomous PEAK-based threat hunting — hypothesis, intel, baseline hunts | Experimental | ### Commands @@ -73,6 +74,7 @@ Skills live in `.claude/skills/` and are invoked via Claude Code commands. | `/soc` | SOC operations — triage, daily review, hunt, tune | | `/research` | Deep technical research with web search | | `/discuss` | Exploratory discussion mode (read-only, no changes) | +| `/hunt` | Autonomous threat hunting — hypothesis, intel, baseline, coverage analysis | ### SOC Subcommands @@ -83,6 +85,17 @@ Skills live in `.claude/skills/` and are invoked via Claude Code commands. /soc hunt <IOCs-or-hypothesis> — Threat hunting mode ``` +### Hunt Subcommands + +``` +/hunt hypothesis "<statement>" — Hypothesis-driven hunt +/hunt intel "<context>" — Intelligence-driven hunt +/hunt baseline "<entity>" — Baseline/anomaly hunt +/hunt — Suggest hunts from coverage gaps +/hunt log — View hunt history +/hunt coverage — View ATT&CK hunt coverage map +``` + ## Production Rules 1. **Always plan before apply.** Never blind-deploy. CI/CD enforces this on PRs. From ec34b5e3de90b0e94a034d8268338cfe6211cd31 Mon Sep 17 00:00:00 2001 From: willwebster5 <williamwebsterv@gmail.com> Date: Sat, 28 Mar 2026 23:03:41 -0400 Subject: [PATCH 14/14] chore: gitignore superpowers plans and specs (local working docs) --- .gitignore | 4 + .../plans/2026-03-28-threat-hunting-skill.md | 1079 ----------------- ...-modeling-and-response-playbooks-design.md | 326 ----- .../2026-03-28-threat-hunting-skill-design.md | 395 ------ 4 files changed, 4 insertions(+), 1800 deletions(-) delete mode 100644 docs/superpowers/plans/2026-03-28-threat-hunting-skill.md delete mode 100644 docs/superpowers/specs/2026-03-28-source-threat-modeling-and-response-playbooks-design.md delete mode 100644 docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md diff --git a/.gitignore b/.gitignore index 7e830fc..ab84673 100644 --- a/.gitignore +++ b/.gitignore @@ -27,6 +27,10 @@ discovery_results.json # Credentials (NEVER commit) credentials.json +# Superpowers plans and specs (local working docs) +docs/superpowers/plans/ +docs/superpowers/specs/ + # OS .DS_Store Thumbs.db diff --git a/docs/superpowers/plans/2026-03-28-threat-hunting-skill.md b/docs/superpowers/plans/2026-03-28-threat-hunting-skill.md deleted file mode 100644 index 6cd1365..0000000 --- a/docs/superpowers/plans/2026-03-28-threat-hunting-skill.md +++ /dev/null @@ -1,1079 +0,0 @@ -# Threat Hunting Skill Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Implement a standalone, autonomous threat hunting Claude Code skill that executes the PEAK framework (Prepare → Execute → Act) across three hunt types, producing hunt reports, detection backlogs, and visibility gap reports. - -**Architecture:** Single skill file (SKILL.md) with a `/hunt` command router, two living documents (hunt log, ATT&CK coverage map), and integration into the existing detection lifecycle via handoff docs. The skill runs autonomously through all three PEAK phases with human touchpoints only at escalation and final review. - -**Tech Stack:** Claude Code skill (markdown), CrowdStrike MCP tools, CQL queries, YAML handoff docs. - -**Spec:** `docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md` - ---- - -### Task 1: Scaffold directories and gitignore - -**Files:** -- Create: `.claude/skills/threat-hunting/` (directory) -- Create: `.claude/skills/threat-hunting/memory/` (directory) -- Create: `docs/hunts/.gitkeep` -- Create: `docs/handoffs/.gitignore` -- Modify: `.gitignore` - -- [ ] **Step 1: Create the skill directory structure** - -```bash -mkdir -p .claude/skills/threat-hunting/memory -``` - -- [ ] **Step 2: Create docs/hunts/ with .gitkeep** - -Hunt reports are permanent archival records — this directory is committed to git. - -```bash -mkdir -p docs/hunts -``` - -Write `docs/hunts/.gitkeep` as an empty file: - -``` -``` - -- [ ] **Step 3: Create docs/handoffs/ with its own .gitignore** - -Handoff docs are ephemeral working artifacts. The directory itself is tracked, but its contents are gitignored. - -```bash -mkdir -p docs/handoffs -``` - -Write `docs/handoffs/.gitignore`: - -``` -# Handoff docs are ephemeral working artifacts — not permanent records. -# They are created by one skill and consumed by another, then cleaned up. -* -!.gitignore -``` - -- [ ] **Step 4: Verify directory structure** - -Run: `find .claude/skills/threat-hunting docs/hunts docs/handoffs -type f -o -type d | sort` - -Expected: -``` -.claude/skills/threat-hunting -.claude/skills/threat-hunting/memory -docs/handoffs -docs/handoffs/.gitignore -docs/hunts -docs/hunts/.gitkeep -``` - -- [ ] **Step 5: Commit** - -```bash -git add .claude/skills/threat-hunting docs/hunts/.gitkeep docs/handoffs/.gitignore -git commit -m "scaffold: threat-hunting skill directories and docs/hunts, docs/handoffs" -``` - ---- - -### Task 2: Living document templates - -**Files:** -- Create: `.claude/skills/threat-hunting/memory/hunt-log.md` -- Create: `.claude/skills/threat-hunting/memory/coverage-map.md` - -- [ ] **Step 1: Write hunt-log.md** - -Write `.claude/skills/threat-hunting/memory/hunt-log.md`: - -```markdown -<!-- LIVING DOCUMENT -Updated by the threat-hunting skill after every completed hunt. -Append-only — one row per hunt. Do not delete entries. -Used during Prepare phase to avoid redundant hunts and during -/hunt (no args) to summarize hunting activity. --> - -# Hunt Log - -| Date | Type | Title | ATT&CK | Outcome | Detections Proposed | -|------|------|-------|--------|---------|---------------------| -``` - -- [ ] **Step 2: Write coverage-map.md** - -Write `.claude/skills/threat-hunting/memory/coverage-map.md`: - -```markdown -<!-- LIVING DOCUMENT -Updated by the threat-hunting skill after every completed hunt. -Tracks the HUNT LAYER — what has been proactively hunted. -Cross-referenced during Prepare against deployed detection MITRE -mappings from resources/detections/ to identify high-value targets. - -Three categories of high-value hunt targets: -1. Blind spots — no detections AND no hunting (highest priority) -2. Untested assumptions — detections exist but never hunted -3. Stale coverage — not hunted in 90+ days --> - -# ATT&CK Hunt Coverage Map - -## Hunted - -| Technique | Tactic | Last Hunted | Result | Data Quality | -|-----------|--------|-------------|--------|--------------| - -## Known Gaps - -| Technique | Tactic | Reason | Recommendation | -|-----------|--------|--------|----------------| - -## Suggested Priority Hunts - -_No hunts completed yet. After the first hunt, this section will be populated with recommendations based on gaps, staleness, and untested detection coverage._ -``` - -- [ ] **Step 3: Verify files exist and read correctly** - -Run: `cat .claude/skills/threat-hunting/memory/hunt-log.md && echo "---" && cat .claude/skills/threat-hunting/memory/coverage-map.md` - -Expected: Both files display with correct markdown table headers and HTML comments. - -- [ ] **Step 4: Commit** - -```bash -git add .claude/skills/threat-hunting/memory/hunt-log.md .claude/skills/threat-hunting/memory/coverage-map.md -git commit -m "feat: add threat-hunting living document templates (hunt log + coverage map)" -``` - ---- - -### Task 3: DESIGN.md — architecture rationale - -**Files:** -- Create: `.claude/skills/threat-hunting/DESIGN.md` - -- [ ] **Step 1: Write DESIGN.md** - -Write `.claude/skills/threat-hunting/DESIGN.md`: - -```markdown -# Threat Hunting Skill — Architecture Rationale - -## Problem - -ClaudeStrike's hunting capability is a 6-step subcommand (`/soc hunt`) with no structured preparation, no post-hunt outputs, no feedback loop into detection engineering, and no institutional knowledge accumulation. The research literature establishes that hunting's compounding value comes from the hunting → detection engineering pipeline. ClaudeStrike has the downstream skills (`behavioral-detections`, `cql-patterns`, `detection-tuning`) but no structured upstream practice feeding them. - -## Architecture: Autonomous PEAK Framework - -This skill implements the PEAK framework (Prepare → Execute → Act) as an autonomous agent — minimal human-in-the-loop, with escalation as the primary interrupt. - -### Why Autonomous (vs. Phased with Human Gates) - -The SOC skill uses phased architecture with human checkpoints to prevent confirmation bias during triage. Hunting has a different dynamic — the agent is exploring, not reacting to an alert. Rigid gates fight the exploratory nature of hunting. The agent drives end-to-end; humans provide the trigger and review outputs. - -### Why Three Hunt Types - -PEAK recognizes three types: hypothesis-driven, baseline (anomaly), and model-assisted (intelligence-driven in our case). CrowdStrike's NGSIEM supports all three — CQL handles stacking natively for baseline hunts, `ngsiem_query` supports ad-hoc hypothesis testing, and IOC/TTP sweeps work for intelligence-driven hunts. - -### Why Standalone (vs. Replacing /soc hunt) - -Clean separation of concerns. `/soc hunt` stays as a quick ad-hoc mode for simple IOC sweeps during triage. This skill handles the full PEAK lifecycle — scoping, execution, detection backlog, gap reporting, self-evaluation. - -### Why Lightweight Living Documents - -A hunt log prevents redundant work. An ATT&CK coverage map enables gap-based prioritization. Baselines are better expressed as saved CQL queries or detection rules than memory files. Hypothesis backlogs are project management, not skill memory. - -### Why Tiered Escalation - -Real hunt teams don't stop investigating at the first suspicious finding. They establish scope first. But confirmed active compromise (C2, exfiltration, lateral movement) demands immediate containment. "Does this need containment?" is the decision boundary. - -## Key Design Decisions - -| Decision | Choice | -|---|---| -| Relationship to `/soc hunt` | Standalone — independent skill | -| Hunt types | Hypothesis, intelligence, baseline | -| Human-in-the-loop | Minimal — agentic, escalation is the interrupt | -| Outputs | Hunt report + detection backlog + gap report | -| Living documents | Hunt log + ATT&CK coverage map | -| Escalation | Tiered — continue for suspected, hard stop for active compromise | -| Self-evaluation | Part of Act phase, feeds coverage map | - -## Integration Points - -- **Upstream:** Human invocation, coverage map suggestions, source-threat-modeling handoffs, SOC triage findings, external intel -- **Downstream:** Detection authoring skills (via handoff docs), SOC skill (via escalation handoff), source-threat-modeling (via gap reports) -- **Shared context:** `environmental-context.md` and `investigation-techniques.md` from the SOC skill - -## Research Foundation - -Design grounded in the threat hunting research survey. Key concepts: PEAK framework (Bianco et al., 2023), Hunting Maturity Model (targeting HM4), Pyramid of Pain, stacking/long-tail analysis, hunt → detection engineering feedback loop. - -## Full Spec - -`docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md` -``` - -- [ ] **Step 2: Verify file reads correctly** - -Run: `head -20 .claude/skills/threat-hunting/DESIGN.md` - -Expected: Title and Problem section display correctly. - -- [ ] **Step 3: Commit** - -```bash -git add .claude/skills/threat-hunting/DESIGN.md -git commit -m "docs: add threat-hunting skill architecture rationale" -``` - ---- - -### Task 4: SKILL.md — frontmatter, persona, tools, CQL patterns - -**Files:** -- Create: `.claude/skills/threat-hunting/SKILL.md` - -This task creates the first portion of SKILL.md — the skill identity, persona, principles, MCP tool reference, and hunting-specific CQL patterns. Subsequent tasks append the phase architecture. - -- [ ] **Step 1: Write SKILL.md with frontmatter, persona, tools, and CQL patterns** - -Write `.claude/skills/threat-hunting/SKILL.md`: - -```markdown ---- -name: threat-hunting -description: Autonomous threat hunting using the PEAK framework (Prepare → Execute → Act). Executes hypothesis-driven, intelligence-driven, and baseline hunts against CrowdStrike NG-SIEM. Produces hunt reports, detection backlogs, and visibility gap reports. Use when proactively hunting for threats, validating detection coverage, or responding to new threat intelligence. ---- - -> Threat hunting skill loaded — PEAK framework (Prepare → Execute → Act). Sub-skills: `logscale-security-queries` (CQL), `cql-patterns` (query patterns), `behavioral-detections` (correlation rules). - -# Threat Hunting — Autonomous PEAK-Based Hunting - -Autonomous threat hunter operating inside a CrowdStrike NG-SIEM environment. Assumes breach. Follows leads. Produces actionable outputs. - -## Persona & Principles - -You are an autonomous threat hunter. You drive the full PEAK lifecycle without human gates between phases. The human provides the trigger and reviews your outputs. - -- **Assume breach.** The environment is compromised until proven otherwise. Your job is to find what automated defenses missed. -- **Follow leads.** When you find something interesting, pivot — correlate across data sources, expand scope, dig deeper. Don't stop at the first query. -- **No hunt fails.** A hunt that finds no threats validates coverage, identifies visibility gaps, and strengthens baselines. Every hunt produces value. -- **IOCs are ephemeral, TTPs are durable.** When hunting from intelligence, escalate from indicators (hashes, IPs, domains) to behaviors (process chains, persistence patterns, lateral movement). Climb the Pyramid of Pain. -- **Feed the pipeline.** Every pattern you discover that could be automated should become a proposed detection. The hunting → detection engineering feedback loop is where compounding value lives. -- **Know your data.** Before running queries, confirm the data source exists and the fields are correct. Consult `investigation-techniques.md` for repo mappings and field gotchas. A query against the wrong repo returns 0 results silently. -- **Escalate active threats immediately.** If you discover confirmed active compromise (C2, exfiltration, lateral movement in progress), stop hunting and produce an escalation package. "Does this need containment?" is the decision boundary. - -## Available Tools - -**CrowdStrike MCP tools** — call these directly as MCP tool invocations. Do NOT write Python scripts or wrapper code. - -### Hunting & Investigation -| MCP Tool | Purpose | -|----------|---------| -| `mcp__crowdstrike__ngsiem_query` | Execute CQL queries — the primary hunting tool. Multiple queries per hunt. | -| `mcp__crowdstrike__get_alerts` | Check if existing detections already fired for entities discovered during hunt | -| `mcp__crowdstrike__alert_analysis` | Deep dive on a specific alert found during correlation | - -### Host Context -| MCP Tool | Purpose | -|----------|---------| -| `mcp__crowdstrike__host_lookup` | Device posture: OS, containment status, policies, agent version | -| `mcp__crowdstrike__host_login_history` | Recent logins on a device (local, remote, interactive) | -| `mcp__crowdstrike__host_network_history` | IP changes, VPN connections, network interface history | - -### Cloud Context -| MCP Tool | Purpose | -|----------|---------| -| `mcp__crowdstrike__cloud_query_assets` | Look up cloud resource by resource_id — config, exposure, tags | -| `mcp__crowdstrike__cloud_get_iom_detections` | CSPM compliance evaluations with MITRE, CIS, NIST mapping | -| `mcp__crowdstrike__cloud_get_risks` | Cloud risks ranked by score — misconfigs, unused identities | - -### Escalation (confirmed active compromise only) -| MCP Tool | Purpose | -|----------|---------| -| `mcp__crowdstrike__case_create` | Create case for confirmed threat | -| `mcp__crowdstrike__case_add_event_evidence` | Attach hunt findings as evidence | -| `mcp__crowdstrike__case_add_tags` | Tag case for classification and routing | - -### Local Tools -| Tool | Purpose | -|------|---------| -| File tools (Read, Grep, Glob) | Read detection templates, search for MITRE mappings, read memory files | - -## Key CQL Hunting Patterns - -Beyond `cql-patterns` and `logscale-security-queries`, these patterns are specific to hunting: - -### Stacking (Long-Tail Analysis) -Find rare values — the workhorse hunting technique: -```cql -// Stack by attribute, sort ascending to surface outliers at the bottom -groupBy([field], function=count()) | sort(_count, order=asc) | tail(50) - -// Multi-attribute stacking — catches malware with legitimate names in suspicious paths -groupBy([ServiceName, ServicePath], function=count()) | sort(_count, order=asc) | tail(50) -``` - -### Temporal Clustering -Detect bursts of activity in time windows: -```cql -bucket(span=5m) -| groupBy([_bucket, user.email], function=count()) -| where(_count > 20) -``` - -### Cross-Source Correlation -Same entity across multiple repos in the same time window: -```cql -// Query 1: Find suspicious IP in CloudTrail -(#repo="cloudtrail" OR #repo="fcs_csp_events") source.ip="<suspicious_ip>" -| groupBy([event.action, Vendor.userIdentity.arn]) - -// Query 2: Same IP in EntraID sign-in logs -(#repo="microsoft_graphapi" OR #repo="3pi_microsoft_entra_id" OR #repo="fcs_csp_events") -#event.dataset=/entraid/ source.ip="<suspicious_ip>" -| groupBy([user.email, #event.outcome]) -``` - -### Process Tree Reconstruction -Parent-child PID chaining for endpoint telemetry: -```cql -#event_simpleName=ProcessRollup2 aid=<device_id> -| ParentProcessId=<target_pid> OR TargetProcessId=<target_pid> -| table([@timestamp, FileName, CommandLine, ParentBaseFileName, TargetProcessId, ParentProcessId]) -| sort(@timestamp, order=asc) -``` - -### Beacon Detection -Periodic callback patterns via time-delta analysis: -```cql -#event_simpleName=DnsRequest aid=<device_id> -| DomainName=<suspect_domain> -| sort(@timestamp, order=asc) -| timeDelta(@timestamp, as=delta_ms) -| stats([avg(delta_ms, as=avg_interval), stddev(delta_ms, as=jitter), count()]) -// Low jitter + regular interval = likely beacon -``` -``` - -- [ ] **Step 2: Verify frontmatter parses correctly** - -Run: `head -5 .claude/skills/threat-hunting/SKILL.md` - -Expected: -``` ---- -name: threat-hunting -description: Autonomous threat hunting using the PEAK framework... ---- -``` - -- [ ] **Step 3: Commit** - -```bash -git add .claude/skills/threat-hunting/SKILL.md -git commit -m "feat: add threat-hunting SKILL.md — persona, tools, CQL patterns" -``` - ---- - -### Task 5: SKILL.md — phase dispatcher, context loading, and Prepare phase - -**Files:** -- Modify: `.claude/skills/threat-hunting/SKILL.md` (append after the beacon detection CQL block) - -- [ ] **Step 1: Append phase dispatcher, context loading, and Prepare phase** - -Append to `.claude/skills/threat-hunting/SKILL.md` after the last line: - -```markdown - -## Phase Dispatcher - -Route based on invocation: - -| Command | Action | -|---------|--------| -| `/hunt hypothesis "<statement>"` | Full PEAK cycle — hypothesis-driven hunt | -| `/hunt intel "<context>"` | Full PEAK cycle — intelligence-driven hunt | -| `/hunt baseline "<entity>"` | Full PEAK cycle — baseline/anomaly hunt | -| `/hunt` | Read coverage map, suggest high-value hunt targets | -| `/hunt log` | Display hunt log summary | -| `/hunt coverage` | Display ATT&CK coverage map with gap analysis | - -## Context Loading - -Load at skill invocation (all hunt types): - -1. Read `memory/hunt-log.md` — what hunts have been completed -2. Read `memory/coverage-map.md` — ATT&CK technique coverage and gaps -3. Read `.claude/skills/soc/environmental-context.md` — org baselines, known accounts, infrastructure -4. Read `.claude/skills/soc/memory/investigation-techniques.md` — repo mappings, field gotchas - -Load during Prepare phase: -5. Scan `resources/detections/` for `mitre_attack` fields — existing automated detection coverage -6. Check `resources/saved_searches/hunting/` — existing hunting queries that may be relevant - -Sub-skills loaded on demand: -- `logscale-security-queries` — when writing CQL queries -- `cql-patterns` — when designing detection backlog entries -- `behavioral-detections` — when proposing correlation-based detections - ---- - -## Prepare Phase - -Scope the hunt before running any queries. This phase runs autonomously. - -### All Hunt Types - -1. **Identify ATT&CK techniques** — map the hunt objective to specific MITRE ATT&CK technique IDs. - -2. **Cross-reference detection coverage** — scan `resources/detections/` for templates with matching `mitre_attack` fields. Grep for the technique ID: - ```bash - grep -rl "T1234" resources/detections/ - ``` - Note the coverage category: - - Technique with deployed detections but never hunted = **untested assumption** - - Technique with no detections AND never hunted = **blind spot** - - Technique hunted 90+ days ago = **stale coverage** - -3. **Check hunt log** — has this technique been hunted before? When? What was found? Avoid redundant work, but re-hunting after 90 days is valid. - -4. **Check existing hunting queries** — scan `resources/saved_searches/hunting/` for relevant saved searches. These may provide ready-made CQL for the target technique. - -5. **Establish CQL scope filter** — determine which NGSIEM repos to query using the repo mapping table from `investigation-techniques.md`. Validate the data source exists: - ```cql - <scope_filter> | count() - ``` - If 0 results, the data source may not be ingested. Log the gap. - -6. **Define time range** — 7 days default for hypothesis and intel hunts. 30 days for baseline hunts. Adjust based on data volume. - -7. **Define success/failure criteria** — what evidence would confirm or refute? What constitutes a meaningful anomaly? - -### Hypothesis-Driven Additions - -- Parse the hypothesis into testable components. A good hypothesis is narrow enough to prove or disprove within bounded effort. -- Identify the specific event types and fields needed to test each component. -- If required data sources are missing, log the gap and either: - - Pivot to what's available (test a related hypothesis against available data) - - Abort early with a gap report if the hunt is fundamentally blocked - -### Intelligence-Driven Additions - -- Extract IOCs from the provided intel: IP addresses, domains, file hashes, user agents, tool names. -- Extract TTPs: what techniques and procedures does the intel describe? -- **Pyramid of Pain escalation plan:** start with IOC sweeps (quick wins), then escalate to TTP hunting (durable value). Map each TTP to CQL-queryable telemetry. -- If the intel references specific threat actors, note their known TTPs for broader behavioral hunting. - -### Baseline Additions - -- Identify the entity/behavior class: scheduled tasks, services, autorun entries, user-agent strings, DNS queries, process names, network connections. -- Determine stacking attributes — what to `groupBy()` and what to `count()`. Choose attribute groupings carefully: stacking only on name misses malware with legitimate names in suspicious paths. Combine name + path + host. -- Establish time window: 7 days minimum, 30 days preferred for stable environments. -- Rule of thumb: any single stack review should take no more than 10 minutes of analysis. If results are overwhelming, narrow context. -``` - -- [ ] **Step 2: Verify the section was appended correctly** - -Run: `grep -n "## Prepare Phase" .claude/skills/threat-hunting/SKILL.md` - -Expected: One match, at a line number after the CQL patterns section. - -- [ ] **Step 3: Commit** - -```bash -git add .claude/skills/threat-hunting/SKILL.md -git commit -m "feat: add phase dispatcher, context loading, and Prepare phase to SKILL.md" -``` - ---- - -### Task 6: SKILL.md — Execute phase - -**Files:** -- Modify: `.claude/skills/threat-hunting/SKILL.md` (append after the Baseline Additions section) - -- [ ] **Step 1: Append Execute phase** - -Append to `.claude/skills/threat-hunting/SKILL.md` after the last line: - -```markdown - ---- - -## Execute Phase - -Fluid and exploratory. Follow leads, pivot, adapt. Document the investigation chain as you go — this narrative feeds the hunt report. - -### Hypothesis-Driven Execution - -1. **Run primary hypothesis test queries** — direct CQL queries against the scoped data sources and time range. -2. **Analyze results:** - - Results support the hypothesis → dig deeper. What's the scope? Which systems/users are affected? - - Results refute the hypothesis → attempt alternative detection angles for the same TTP. Different event types, different fields, different time windows. - - Inconclusive → broaden scope or pivot to adjacent techniques. -3. **Pivot on leads** — when an interesting entity (user, IP, host) surfaces: - - Cross-correlate across data sources (CloudTrail + EntraID + endpoint + DNS) - - Alert correlation: `get_alerts` for the entity — have existing detections already fired? - - Pull host/cloud context for interesting endpoints or resources -4. **Document evidence chain** — record each query, what it found, and why you pivoted. This becomes the Findings section of the hunt report. - -### Intelligence-Driven Execution - -1. **IOC sweep** — search for known indicators across all relevant repos. Fast, concrete results. - ```cql - // Example: sweep for suspicious IP across all data sources - source.ip="<ioc_ip>" OR destination.ip="<ioc_ip>" - | groupBy([#repo, event.action, source.ip, destination.ip], function=count()) - ``` -2. **Pivot from IOC hits** — if any IOC matches: - - What else did that actor/IP/hash do? Expand the query to all activity from that entity. - - Timeline analysis: what happened in the 30 minutes before and after the IOC match? - - Scope assessment: how many systems/users are affected? -3. **TTP hunting (even without IOC matches)** — IOCs rotate trivially; behaviors persist. - - Hunt for the behavioral patterns described in the intel regardless of IOC results. - - Use process tree analysis, login correlation, network pattern analysis. - - This is where durable detection value lives. -4. **Cross-correlate across data sources** — adversaries don't stay in one log source. Check the repo mapping table and query every relevant source for the entities under investigation. - -### Baseline Execution - -1. **Run stacking queries** — frequency counts across the target attribute grouping. - ```cql - // Example: stack scheduled tasks across all Windows endpoints - #event_simpleName=ScheduledTaskRegistered - | groupBy([TaskName, TaskExecCommand], function=[count(), collect(ComputerName)]) - | sort(_count, order=asc) - | tail(50) - ``` -2. **Identify statistical outliers:** - - Entities on only 1-2 systems (vs. hundreds) — investigate. - - Unusual values — names that don't fit the pattern, paths in unexpected locations. - - Low-frequency entries at the tail of the distribution. -3. **Investigate outliers** — for each outlier: - - Context queries: host lookup, user lookup, process tree reconstruction. - - Environmental context check: is this a known application, service account, or infrastructure component? - - If anomalous AND unexplained → potential finding. Document it. -4. **Establish baseline documentation** — record what "normal" looks like. This is valuable even if no threats are found — it informs future hunts and detection tuning. - -### Threat Escalation Interrupt - -Applies to all hunt types. Two tiers based on "does this need containment?": - -**Suspected threat** — interesting but not confirmed: -- Flag the finding in your investigation notes. -- **Continue hunting** to establish scope and gather more evidence. -- Present in the hunt report findings section. -- Do NOT stop the hunt. - -**Confirmed active compromise** — evidence of C2, data exfiltration, or lateral movement in progress: -- **STOP the hunt immediately.** -- Produce an escalation package: - -```markdown -## ESCALATION: Active Threat Discovered During Hunt - -**Hunt**: <title> -**Discovery Time**: <timestamp> -**Threat Type**: <C2 | Exfiltration | Lateral Movement | Other> - -### Evidence -<What was found — specific IOCs and timestamps> - -### Affected Systems -| System | Type | Evidence | -|--------|------|----------| - -### IOCs -| Indicator | Type | Context | -|-----------|------|---------| - -### Immediate Risk Assessment -<Is this ongoing? Blast radius? Next likely adversary action?> - -### Recommended Immediate Actions -1. <Containment action> -2. <Investigation action> -3. <Communication action> -``` - -- Create a handoff doc at `docs/handoffs/YYYY-MM-DD-threat-hunting-to-soc-escalation.md`: - -```yaml -source_skill: threat-hunting -target_skill: soc -objective: "Incident response for active threat discovered during hunt" -context: - hunt_title: "<title>" - threat_type: "<C2 | Exfiltration | Lateral Movement>" - discovery_time: "<timestamp>" - affected_systems: [<list>] - iocs: [<list>] -decisions_made: - - "Active threat confirmed during hunt — escalation required" - - "Hunt paused at escalation point" -constraints: - - "Time-sensitive — containment actions needed" -artifacts: - - "docs/hunts/YYYY-MM-DD-<slug>.md" -``` - -- Create a case: `case_create` → `case_add_event_evidence` → `case_add_tags(tags=["true_positive", "hunt_escalation", "<mitre_tactic>"])` -- **Surface to human** — this is the primary human-in-the-loop touchpoint. -- The hunt report is still produced (Act phase) with findings up to the escalation point. -``` - -- [ ] **Step 2: Verify section appended correctly** - -Run: `grep -n "## Execute Phase" .claude/skills/threat-hunting/SKILL.md` - -Expected: One match, at a line number after the Prepare phase. - -- [ ] **Step 3: Commit** - -```bash -git add .claude/skills/threat-hunting/SKILL.md -git commit -m "feat: add Execute phase to SKILL.md — three hunt types + escalation" -``` - ---- - -### Task 7: SKILL.md — Act phase - -**Files:** -- Modify: `.claude/skills/threat-hunting/SKILL.md` (append after the escalation section) - -- [ ] **Step 1: Append Act phase** - -Append to `.claude/skills/threat-hunting/SKILL.md` after the last line: - -```markdown - ---- - -## Act Phase - -Produce all outputs after Execute completes. Runs autonomously. - -### 1. Hunt Report - -Write the hunt report to `docs/hunts/YYYY-MM-DD-<slug>.md`. This directory is committed to git — hunt reports are permanent archival records. - -```markdown -## Hunt Report: <title> -**Date**: YYYY-MM-DD -**Type**: Hypothesis | Intelligence | Baseline -**ATT&CK Techniques**: T1234, T5678 -**Duration**: <approximate> -**Outcome**: Threat Found | No Threat — Coverage Validated | Inconclusive - -### Hypothesis / Objective -<What we were looking for and why> - -### Scope -- **Data sources**: <repos queried> -- **Time range**: <start — end> -- **Entities**: <users, hosts, IPs, services examined> - -### Findings -<Chronological investigation narrative — what was queried, what was found, what pivots were taken. Include CQL queries that produced significant results.> - -### IOCs -| Indicator | Type | Context | -|-----------|------|---------| -<Only if threat discovered. Omit this section for clean hunts.> - -### Conclusion -<2-3 sentences: what did we learn?> - -### Self-Evaluation -- **Hypothesis quality**: <Was it testable? Too broad? Too narrow?> -- **Data sufficiency**: <Did we have what we needed? What was missing?> -- **Investigation efficiency**: <Dead ends? Better paths in hindsight?> -- **Suggested next hunt**: <Based on gaps found or leads not fully pursued> -``` - -### 2. Detection Backlog - -Produced when the hunt reveals patterns that could be automated as detections. Include even for clean hunts — baseline knowledge often surfaces detectable patterns. - -Present the backlog in the hunt report, then write individual handoff docs: - -```markdown -## Proposed Detections from Hunt: <title> - -| # | Detection | ATT&CK | Approach | Complexity | Target Skill | Priority | -|---|-----------|--------|----------|------------|-------------|----------| -| 1 | <description> | T1234 | <threshold / stacking / correlation> | <Low / Medium / High> | <behavioral-detections / cql-patterns / logscale-security-queries> | <High / Medium / Low> | -``` - -For each proposed detection, write a handoff doc to `docs/handoffs/YYYY-MM-DD-threat-hunting-to-<target-skill>-<slug>.md`: - -```yaml -source_skill: threat-hunting -target_skill: behavioral-detections | cql-patterns | logscale-security-queries -objective: "Author a detection for [pattern discovered during hunt]" -context: - hunt_title: "<title>" - hunt_date: "YYYY-MM-DD" - threat_scenario: "<what the detection should find>" - mitre_technique: "<technique ID>" - mitre_tactic: "<tactic>" - detection_approach: "<simple threshold | stacking anomaly | behavioral correlation>" - key_event_types: [<event types observed during hunt>] - key_fields: [<fields used in hunt queries>] - volume_notes: "<signal volume and noise characteristics from hunt data>" - sample_query: "<CQL query from the hunt that surfaced this pattern>" -decisions_made: - - "Pattern discovered during [hunt type] hunt" - - "<context about why this detection matters>" -constraints: - - "120s query timeout" - - "<data source limitations noted during hunt>" -artifacts: - - "docs/hunts/YYYY-MM-DD-<slug>.md" -``` - -If no detectable patterns were found, skip the backlog — not every hunt produces detection opportunities. - -### 3. Gap Report - -Produced when the hunt identified visibility gaps. Append to the hunt report: - -```markdown -## Visibility Gap Report - -### Gaps Identified -| Gap | Impact | ATT&CK Techniques Affected | Recommendation | -|-----|--------|---------------------------|----------------| -| <missing data source or field> | <what can't be detected> | T1234, T5678 | <onboard source / enable logging / add field> | - -### ATT&CK Coverage Delta -<Techniques that were in scope but couldn't be tested, with reasons> -``` - -If no gaps were identified, note that all required data was available — this is valuable coverage validation. - -### 4. Update Living Documents - -After producing all outputs: - -**Hunt log** — append one row to `memory/hunt-log.md`: - -``` -| YYYY-MM-DD | <Type> | <Title> | T1234, T5678 | <Outcome> | <N detections proposed> | -``` - -**Coverage map** — update `memory/coverage-map.md`: -- Add or update entries in **Hunted** for techniques covered by this hunt. -- Add entries to **Known Gaps** for visibility gaps discovered. -- Regenerate **Suggested Priority Hunts** based on: - - **Blind spots** — techniques with no detections AND no hunting (scan `resources/detections/` for `mitre_attack` fields, compare against Hunted table) - - **Untested assumptions** — techniques with deployed detections but not in the Hunted table - - **Stale coverage** — techniques in Hunted with Last Hunted date 90+ days ago - -### 5. Suggest Next Hunt - -Based on the self-evaluation, coverage map, and findings, recommend what to hunt next: - -- Leads that weren't fully pursued during this hunt -- Adjacent ATT&CK techniques revealed by findings -- High-priority gaps from the updated coverage map -- Techniques whose detections were validated but could be tested with different data sources - -Present as: "Based on this hunt, consider hunting next: **<suggestion>** — <rationale>." -``` - -- [ ] **Step 2: Verify section appended correctly** - -Run: `grep -n "## Act Phase" .claude/skills/threat-hunting/SKILL.md` - -Expected: One match, at a line number after the Execute phase. - -- [ ] **Step 3: Commit** - -```bash -git add .claude/skills/threat-hunting/SKILL.md -git commit -m "feat: add Act phase to SKILL.md — outputs, living docs, next-hunt suggestions" -``` - ---- - -### Task 8: SKILL.md — utility modes - -**Files:** -- Modify: `.claude/skills/threat-hunting/SKILL.md` (append after the Act phase) - -- [ ] **Step 1: Append utility modes** - -Append to `.claude/skills/threat-hunting/SKILL.md` after the last line: - -```markdown - ---- - -## Utility Modes - -### `/hunt` (no arguments) — Agent-Suggested Hunting - -When invoked without arguments, analyze coverage and suggest high-value hunt targets: - -1. Read `memory/coverage-map.md` and `memory/hunt-log.md`. -2. Scan `resources/detections/` for `mitre_attack` fields to build detection coverage picture. -3. Cross-reference to surface three categories: - - | Category | Definition | Priority | - |----------|-----------|----------| - | **Blind spots** | No detections AND never hunted | Highest | - | **Untested assumptions** | Detections deployed but never hunted | High | - | **Stale coverage** | Last hunted 90+ days ago | Medium | - -4. Present the top 3-5 recommended hunts: - ``` - ## Suggested Hunts - - | # | Technique | Tactic | Category | Suggested Type | Draft Hypothesis | - |---|-----------|--------|----------|---------------|-----------------| - | 1 | T1078 Valid Accounts | Defense Evasion | Untested — 3 detections, never hunted | Baseline | Stack authentication patterns across EntraID | - ``` - -5. Wait for user to select, then proceed through Prepare → Execute → Act. - -### `/hunt log` — Display Hunt Log - -Read and present `memory/hunt-log.md` with summary statistics: -- Total hunts completed -- Breakdown by type (hypothesis / intelligence / baseline) -- Breakdown by outcome (threat found / coverage validated / inconclusive) -- Total detections proposed across all hunts -- Most recently hunted ATT&CK techniques - -### `/hunt coverage` — Display Coverage Map - -Read `memory/coverage-map.md` and cross-reference with `resources/detections/`: -- **Hunted techniques** with last hunt date, result, and data quality -- **Known gaps** with impact and recommendations -- **Detection coverage overlay** — for each hunted technique, note whether automated detections exist -- **Suggested priority hunts** with rationale -``` - -- [ ] **Step 2: Verify full SKILL.md structure** - -Run: `grep -n "^## " .claude/skills/threat-hunting/SKILL.md` - -Expected output showing all major sections in order: -``` -## Persona & Principles -## Available Tools -## Key CQL Hunting Patterns -## Phase Dispatcher -## Context Loading -## Prepare Phase -## Execute Phase -## Act Phase -## Utility Modes -``` - -- [ ] **Step 3: Check total line count** - -Run: `wc -l .claude/skills/threat-hunting/SKILL.md` - -Expected: approximately 400-500 lines. - -- [ ] **Step 4: Commit** - -```bash -git add .claude/skills/threat-hunting/SKILL.md -git commit -m "feat: add utility modes to SKILL.md — /hunt, /hunt log, /hunt coverage" -``` - ---- - -### Task 9: /hunt command router - -**Files:** -- Create: `.claude/commands/hunt.md` - -- [ ] **Step 1: Write the /hunt command file** - -Write `.claude/commands/hunt.md`: - -```xml -<command name="hunt"> - <description>Threat hunting: $ARGUMENTS</description> - - <rules priority="critical"> - <rule>Always invoke the threat-hunting skill for processing</rule> - <rule>Update .claude/skills/threat-hunting/memory/ files after every completed hunt per the Living Documents protocol</rule> - <rule>Escalate immediately on confirmed active compromise — create case, handoff doc, surface to human</rule> - <rule>Produce all three outputs (hunt report, detection backlog, gap report) in the Act phase</rule> - <rule>Never modify detection templates directly — produce handoff docs for authoring skills</rule> - </rules> - - <actions> - <action trigger="starts-with:hypothesis"> - Run a hypothesis-driven threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). - </action> - - <action trigger="starts-with:intel"> - Run an intelligence-driven threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). - </action> - - <action trigger="starts-with:baseline"> - Run a baseline/anomaly threat hunt. Follow the threat-hunting skill PEAK workflow (Prepare → Execute → Act). - </action> - - <action trigger="starts-with:log"> - Display the hunt log. Read and summarize .claude/skills/threat-hunting/memory/hunt-log.md. - </action> - - <action trigger="starts-with:coverage"> - Display the ATT&CK coverage map. Read .claude/skills/threat-hunting/memory/coverage-map.md and cross-reference with resources/detections/. - </action> - - <action trigger="default"> - No hunt type specified. Read the coverage map and suggest high-value hunt targets. - If no arguments at all, follow the /hunt (no arguments) utility mode in the threat-hunting skill. - If arguments don't match a known subcommand, treat as a hypothesis and route to hypothesis-driven hunting. - </action> - </actions> -</command> -``` - -- [ ] **Step 2: Verify command file structure matches existing commands** - -Run: `diff <(grep -o '<[^>]*>' .claude/commands/soc.md | sort -u) <(grep -o '<[^>]*>' .claude/commands/hunt.md | sort -u)` - -Expected: Same XML elements used in both files (command, description, rules, rule, actions, action). - -- [ ] **Step 3: Commit** - -```bash -git add .claude/commands/hunt.md -git commit -m "feat: add /hunt command router" -``` - ---- - -### Task 10: Update CLAUDE.md with threat-hunting skill - -**Files:** -- Modify: `CLAUDE.md` - -- [ ] **Step 1: Add threat-hunting to the Available Skills table** - -In `CLAUDE.md`, find the skills table: - -```markdown -| `detection-tuning` | FP tuning patterns with enrichment function catalog | Stable | -``` - -Add after the last skill row: - -```markdown -| `threat-hunting` | Autonomous PEAK-based threat hunting — hypothesis, intel, baseline hunts | Experimental | -``` - -- [ ] **Step 2: Add /hunt to the Commands table** - -In `CLAUDE.md`, find the commands table: - -```markdown -| `/discuss` | Exploratory discussion mode (read-only, no changes) | -``` - -Add after: - -```markdown -| `/hunt` | Autonomous threat hunting — hypothesis, intel, baseline, coverage analysis | -``` - -- [ ] **Step 3: Add hunt subcommands section** - -In `CLAUDE.md`, find the SOC Subcommands section. Add after it: - -```markdown -### Hunt Subcommands - -``` -/hunt hypothesis "<statement>" — Hypothesis-driven hunt -/hunt intel "<context>" — Intelligence-driven hunt -/hunt baseline "<entity>" — Baseline/anomaly hunt -/hunt — Suggest hunts from coverage gaps -/hunt log — View hunt history -/hunt coverage — View ATT&CK hunt coverage map -``` -``` - -- [ ] **Step 4: Verify CLAUDE.md changes** - -Run: `grep -A1 "threat-hunting" CLAUDE.md` - -Expected: The skill table row and command table row are visible. - -- [ ] **Step 5: Commit** - -```bash -git add CLAUDE.md -git commit -m "docs: add threat-hunting skill and /hunt command to CLAUDE.md" -``` - ---- - -## Self-Review - -### Spec Coverage Check - -| Spec Section | Implementing Task | -|---|---| -| Skill Identity (name, location, persona) | Task 4 — frontmatter + persona | -| Invocation (6 command variants) | Task 5 — phase dispatcher, Task 9 — command router | -| Phase Architecture — Prepare | Task 5 | -| Phase Architecture — Execute | Task 6 | -| Phase Architecture — Act | Task 7 | -| Threat Escalation Interrupt | Task 6 — inline in Execute phase | -| MCP Tools | Task 4 — tool reference tables | -| Key CQL Patterns | Task 4 — 5 hunting-specific patterns | -| Outputs — Hunt Report | Task 7 — template in Act phase | -| Outputs — Detection Backlog | Task 7 — template + handoff doc format | -| Outputs — Gap Report | Task 7 — template in Act phase | -| Living Documents — hunt-log.md | Task 2 | -| Living Documents — coverage-map.md | Task 2 | -| Living Documents — update protocol | Task 7 — Act phase step 4 | -| Self-Evaluation | Task 7 — in hunt report template | -| Suggest Next Hunt | Task 7 — Act phase step 5, Task 8 — /hunt no-args mode | -| Coverage Map Cross-Reference | Task 5 (Prepare), Task 7 (Act), Task 8 (utility modes) | -| Integration — handoff docs | Task 7 — detection backlog handoff format | -| Integration — escalation handoff | Task 6 — escalation interrupt | -| File Structure | Task 1 (scaffold), Task 3 (DESIGN.md) | -| Context Loading Order | Task 5 | -| docs/hunts/ (committed) | Task 1 — .gitkeep | -| docs/handoffs/ (gitignored) | Task 1 — .gitignore | -| CLAUDE.md updates | Task 10 | - -All spec sections are covered. - -### Placeholder Scan - -No TBDs, TODOs, "implement later", or "similar to Task N" found. - -### Type/Name Consistency - -- `memory/hunt-log.md` — consistent across Tasks 2, 5, 7, 8 -- `memory/coverage-map.md` — consistent across Tasks 2, 5, 7, 8 -- `environmental-context.md` path — `.claude/skills/soc/environmental-context.md` in Task 5 -- `investigation-techniques.md` path — `.claude/skills/soc/memory/investigation-techniques.md` in Task 5 -- `resources/detections/` + `mitre_attack` field — consistent across Tasks 5, 7, 8 -- `resources/saved_searches/hunting/` — referenced in Task 5 (Prepare) -- `docs/hunts/YYYY-MM-DD-<slug>.md` — consistent across Tasks 1, 6, 7 -- `docs/handoffs/YYYY-MM-DD-threat-hunting-to-<skill>-<slug>.md` — consistent across Tasks 6, 7 -- Handoff doc field names (`source_skill`, `target_skill`, `objective`, `context`, `decisions_made`, `constraints`, `artifacts`) — consistent with source-threat-modeling spec -- MCP tool names — match exactly what SOC skill SKILL.md uses -- Command name `/hunt` — consistent across Tasks 5, 8, 9, 10 diff --git a/docs/superpowers/specs/2026-03-28-source-threat-modeling-and-response-playbooks-design.md b/docs/superpowers/specs/2026-03-28-source-threat-modeling-and-response-playbooks-design.md deleted file mode 100644 index 67af6ea..0000000 --- a/docs/superpowers/specs/2026-03-28-source-threat-modeling-and-response-playbooks-design.md +++ /dev/null @@ -1,326 +0,0 @@ -# Source Threat Modeling & Response Playbooks — Design Spec - -Two new Claude Code skills that close the gaps at the front and back of our detection lifecycle: turning a raw data source into detection coverage, and turning detections into automated response. - -## Problem - -ClaudeStrike is strong at detection authoring (`behavioral-detections`, `cql-patterns`, `logscale-security-queries`) and SOC operations (triage, hunt, tune). But two lifecycle stages are weak: - -1. **Pre-detection planning** — When a source has no OOTB templates, there's no structured way to reason about what threats apply, explore what the logs actually contain, and produce a detection backlog. Today this is ad hoc. -2. **Post-detection response** — The `fusion-workflows` skill provides the YAML schema and action discovery, but there's no layer that recommends *which* response actions fit *which* detections, and no playbook templates for common patterns. - -## Scope - -Two independent, composable skills: - -- **Source Threat Modeling** — threat-model-first detection planning for sources without OOTB coverage -- **Response Playbooks** — detection-to-response mapping and playbook templates for Fusion SOAR workflows - -Each skill is conversational and human-driven (Approach 1 — "Analyst Advisor"). No persistent catalogs or automation magic. Each produces handoff documents at skill boundaries for clean context transfer. - ---- - -## Skill 1: Source Threat Modeling - -### Purpose - -Given a data source type, produce a prioritized detection backlog grounded in MITRE ATT&CK threat models and validated against actual log data. - -### Invocation - -The skill is invoked directly by the user. It does not require a handoff doc as input, though it should accept one if provided (future-proofing for upstream orchestration). - -Typical entry: user says something like "I just connected Okta / GitHub / Cisco ASA and need detections." - -### Workflow — 4 Phases - -#### Phase 1: Source Identification - -- User names the data source (product, vendor, log type) -- Skill asks clarifying questions to establish: - - What product and log types are being ingested - - The NGSIEM repo and/or vendor filter (e.g., `#Vendor="okta"`, `#repo="some_repo"`) - - What the source is used for in the environment (identity, network, cloud infra, app-level) - - Whether any detections already exist for this source (check `resources/detections/`) -- Output: a CQL scope filter that constrains all subsequent queries - -#### Phase 2: Threat Modeling - -- Skill reasons about threats relevant to this source type -- Approach: threat-model-first — start from "what can an attacker do that this source would observe?" -- Consider three threat categories: - - **Abuse of the system the source monitors** (e.g., for Okta: credential stuffing, MFA bypass, session hijacking) - - **Compromise of the source itself** (e.g., admin account takeover, audit log tampering, config changes) - - **Lateral movement / escalation visible through the source** (e.g., privilege escalation, new admin grants) -- Map each threat scenario to MITRE ATT&CK techniques -- Output: ranked list of threat scenarios with MITRE mappings and a plain-language description of what the detection would look for - -#### Phase 3: Log Validation - -- For each threat scenario from Phase 2, run exploratory CQL queries against 7-30 days of live NGSIEM data -- Goals per scenario: - - Confirm the relevant event types exist in the data - - Understand volume and cardinality (how noisy would a detection be?) - - Identify available fields for detection logic (what can we key on?) - - Spot baseline patterns (what does "normal" look like for this event type?) -- Prune threat scenarios where the required events aren't present in the data -- Flag interesting or surprising patterns discovered during exploration (potential quick wins or unexpected activity) -- Output: validated threat scenarios annotated with event types, field availability, volume estimates, and feasibility notes - -#### Phase 4: Detection Backlog - -- Produce a prioritized list of proposed detections -- Each entry includes: - - **Threat scenario** and plain-language description - - **MITRE ATT&CK mapping** (technique ID + tactic) - - **Detection approach**: simple threshold, anomaly/baseline, or behavioral correlation (`correlate()`) - - **Estimated complexity**: low (single event match), medium (aggregation/threshold), high (multi-event correlation) - - **Key fields and event types** from log validation - - **Recommended authoring skill**: `behavioral-detections` for correlation rules, `cql-patterns` or `logscale-security-queries` for simpler queries - - **Priority rationale**: why this detection matters relative to the others -- User reviews and selects which detections to pursue -- For each selected detection, skill produces a **handoff document** for the authoring skill - -### Handoff Output (Producer) - -When handing off to a detection authoring skill, the skill writes a handoff doc to `docs/handoffs/` with the following structure: - -```yaml -source_skill: source-threat-modeling -target_skill: behavioral-detections | cql-patterns | logscale-security-queries -objective: "Author a detection for [threat scenario]" -context: - data_source: "Okta" - cql_scope_filter: '#Vendor="okta"' - threat_scenario: "MFA fatigue attack — repeated MFA push denials followed by a successful auth" - mitre_technique: "T1621 — Multi-Factor Authentication Request Generation" - mitre_tactic: "Credential Access" - detection_approach: "behavioral correlation" - key_event_types: - - "authentication.auth_via_mfa" - - "user.authentication.auth_via_mfa_deny" - key_fields: - - "actor.displayName" - - "outcome.result" - - "client.ipAddress" - volume_notes: "~200 MFA events/day, deny rate ~2%. Threshold of 5+ denials in 10 min should be low-noise." -decisions_made: - - "User approved this detection for authoring" - - "Correlation approach chosen over simple threshold — need to detect deny-then-success pattern" -constraints: - - "120s query timeout — keep correlation window under 15 minutes" - - "Enrich with $enrich_entra_user() if actor maps to EntraID" -artifacts: [] -``` - -The handoff doc is a markdown file. The receiving skill reads it as its starting context. - -### Interaction with Existing Skills - -This skill is the **strategist**. It decides *what* to detect. Existing skills are the **craftsmen** — they decide *how* to write it: - -- `behavioral-detections` — for multi-event correlation rules using `correlate()` -- `cql-patterns` — for pattern-based queries (aggregation, scoring, thresholds) -- `logscale-security-queries` — for general CQL development and investigation queries -- `detection-tuning` — downstream, once detections are deployed and need FP tuning - -The skill does NOT write CQL or detection YAML itself. It produces the backlog and handoff docs; authoring is delegated. - ---- - -## Skill 2: Response Playbooks - -### Purpose - -Given a detection (existing or newly proposed), recommend appropriate response actions and help wire them up as Fusion SOAR workflows. Provides a library of common response patterns and the intelligence to map detections to appropriate response tiers. - -### Invocation - -The skill is invoked directly by the user, or via a handoff doc from source-threat-modeling (or any other skill). Typical entries: - -- "What response should I set up for this detection?" -- "I have these 5 new detections, what playbooks do they need?" -- Handoff doc from source-threat-modeling with detection context - -### Workflow — 3 Phases - -#### Phase 1: Detection Intake - -- User points at one or more detections (by name, resource file path, or description) -- If a handoff doc is provided, read context from it -- For each detection, skill reads/understands: - - The detection CQL and what it looks for - - Severity level - - MITRE ATT&CK mapping - - **Center entity**: what's the primary subject? (user account, host, IP, cloud resource, application) - - **Blast radius**: if this fires as a true positive, how bad is it? -- Asks clarifying questions if any of the above can't be inferred - -#### Phase 2: Response Recommendation - -- For each detection, propose a tiered response plan based on severity, entity type, and threat category -- Response tiers: - - **Tier 1 — Observe**: create case, log to SIEM, notify via Slack/email. Always safe to automate. - - **Tier 2 — Investigate**: enrich alert with additional context (host details, user history, related alerts). Safe to automate. - - **Tier 3 — Contain**: disable user account, isolate host, revoke session, block IP. Requires human approval gate. - - **Tier 4 — Remediate**: reset credentials, remove persistence, restore from backup. Always requires human action. -- Use `fusion-workflows` action discovery (`action_search.py`) to confirm which actions are actually available in the tenant -- Present recommendations with rationale for each tier -- Clearly distinguish: - - "Always auto-fire" actions (Tier 1-2: case creation, notification, enrichment) - - "Require approval" actions (Tier 3: containment actions) - - "Manual only" actions (Tier 4: remediation) -- User reviews and approves the response plan - -#### Phase 3: Workflow Generation - -- For each approved response plan, produce a **handoff document** for the `fusion-workflows` skill -- The handoff doc contains everything needed to generate the workflow YAML: - - Detection trigger (which detection fires this workflow) - - Actions to execute, in order - - Conditions and approval gates - - Variables to pass between steps -- User invokes `fusion-workflows` with the handoff doc to generate and deploy the workflow - -### Handoff Output (Producer) - -When handing off to fusion-workflows: - -```yaml -source_skill: response-playbooks -target_skill: fusion-workflows -objective: "Create a Fusion workflow for [detection name] response" -context: - detection_name: "Okta MFA Fatigue Attack" - detection_resource_id: "okta_mfa_fatigue" - severity: "critical" - center_entity: "user" - mitre_technique: "T1621" -decisions_made: - - "User approved tiered response plan" - - "Tier 1 (auto): Create case with severity Critical, notify #soc-alerts Slack channel" - - "Tier 2 (auto): Enrich with user's recent auth history (last 24h)" - - "Tier 3 (approval required): Disable user in EntraID, revoke active sessions" - - "Tier 4 (manual): Credential reset — SOC contacts user directly" -constraints: - - "Tier 3 actions must have human approval gate — do not auto-execute containment" - - "Slack notification must include: detection name, affected user, source IP, event count" -workflow_structure: - trigger: "detection" - actions: - - type: "create_case" - auto: true - - type: "slack_notify" - auto: true - channel: "#soc-alerts" - - type: "enrich_user_history" - auto: true - - type: "disable_entra_user" - auto: false - requires_approval: true - - type: "revoke_sessions" - auto: false - requires_approval: true -artifacts: [] -``` - -### Handoff Input (Consumer) - -The skill accepts handoff docs from source-threat-modeling or direct user input. When consuming a handoff doc, it reads the detection context and skips Phase 1 questions that are already answered. - -### Response Pattern Library - -The skill carries knowledge of common response patterns. These are not persisted files — they're built into the skill's reasoning. Examples: - -| Detection Type | Entity | Severity | Recommended Response | -|---|---|---|---| -| Credential attack (brute force, stuffing, MFA fatigue) | User | Critical | Case + notify + enrich + disable user (approval) | -| Privilege escalation (new admin, role change) | User | High | Case + notify + enrich + review access (manual) | -| Data exfiltration (bulk download, unusual export) | User/App | Critical | Case + notify + enrich + revoke sessions (approval) | -| Suspicious network activity (C2 beacon, unusual destination) | Host | High | Case + notify + enrich + isolate host (approval) | -| Cloud config change (security group, IAM policy) | Cloud Resource | Medium | Case + notify + enrich + revert change (manual) | -| Anomalous login (impossible travel, new device) | User | Medium | Case + notify + enrich | - -These patterns inform recommendations but don't override human judgment. The skill presents them as starting points. - ---- - -## Handoff Document Specification - -Both skills produce and consume handoff documents. Standard structure: - -### Format - -Markdown file stored in `docs/handoffs/`. Filename convention: `YYYY-MM-DD-<source-skill>-to-<target-skill>-<brief-description>.md` - -This directory is gitignored — handoff docs are ephemeral working artifacts, not permanent records. - -### Required Fields - -| Field | Description | -|---|---| -| `source_skill` | Which skill produced this handoff | -| `target_skill` | Which skill should consume it | -| `objective` | One-line description of what the receiving skill should accomplish | -| `context` | Structured data the receiving skill needs (source-specific) | -| `decisions_made` | List of decisions the human already approved — receiving skill should not re-ask these | -| `constraints` | Anything the receiving skill must respect | -| `artifacts` | Paths to any files created by the source skill (detection YAML, query results, etc.) | - -### Lifecycle - -- Handoff docs are created by the producing skill at the end of a phase -- The user invokes the receiving skill and points it at the handoff doc -- Handoff docs are working artifacts, not permanent records — they can be cleaned up after the receiving skill completes -- If the receiving skill needs to hand off further (e.g., response-playbooks → fusion-workflows), it creates a new handoff doc - ---- - -## What's NOT In Scope - -- **Data source/connector provisioning** — ingestion configuration is outside NGSIEM's API surface. The threat modeling skill assumes data is already flowing. -- **OOTB template management** — the `review-templates` command already covers this. The threat modeling skill is for sources *without* OOTB coverage. -- **Detection authoring** — delegated to existing skills via handoff docs. -- **Workflow YAML generation** — delegated to `fusion-workflows` via handoff docs. -- **Persistent source catalogs or playbook libraries** — per user decision, these are conversational skills, not knowledge-base builders. -- **Automated deployment** — both skills produce recommendations and handoff docs, not deployed resources. Deployment goes through the existing IaC pipeline. - -## Relationship to Existing Skills - -``` - source-threat-modeling (NEW) - "what to detect" - | - handoff docs - | - +----------------+----------------+ - | | | - behavioral- cql-patterns logscale-security- - detections "how to write" queries - "how to write" "how to write" - | | | - +-------+--------+--------+-------+ - | | - detection-tuning response-playbooks (NEW) - "how to tune" "what response" - | - handoff doc - | - fusion-workflows - "how to build workflow" - | - IaC pipeline - "deploy to tenant" -``` - -## Skill File Structure - -``` -.claude/skills/ -├── source-threat-modeling/ -│ └── source-threat-modeling.md # Main skill file -├── response-playbooks/ -│ └── response-playbooks.md # Main skill file -``` - -Each skill is a single markdown file with the skill definition — no supporting scripts or data files needed. They're conversational advisors that leverage existing infrastructure. \ No newline at end of file diff --git a/docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md b/docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md deleted file mode 100644 index 7d25a04..0000000 --- a/docs/superpowers/specs/2026-03-28-threat-hunting-skill-design.md +++ /dev/null @@ -1,395 +0,0 @@ -# Threat Hunting Skill — Design Spec - -An autonomous, agentic threat hunting skill for ClaudeStrike's Agentic SOC. Implements the PEAK framework (Prepare → Execute → Act) across three hunt types with self-evaluation, structured outputs, and integration into the detection lifecycle. - -## Problem - -ClaudeStrike's current hunting capability is a 6-step subcommand (`/soc hunt`) — user provides IOCs or a hypothesis, agent runs CQL, presents results. No structured preparation, no post-hunt outputs, no feedback loop into detection engineering, no institutional knowledge accumulation across hunts. - -The research literature (threat-hunting-research.md) establishes that hunting's compounding value comes from the **hunting → detection engineering pipeline**: every manual discovery encoded as an automated rule permanently improves defenses. Organizations at HM4 maturity systematize this. ClaudeStrike has all the downstream skills (`behavioral-detections`, `cql-patterns`, `detection-tuning`) but no structured upstream hunting practice feeding them. - -This skill is an experiment in **agentic threat hunting** — the agent drives the full PEAK lifecycle autonomously, with humans surfaced primarily for threat escalation and final review. - -## Scope - -A standalone Claude Code skill that: - -- Executes structured threat hunts across three types (hypothesis-driven, intelligence-driven, baseline/anomaly) -- Runs autonomously through Prepare → Execute → Act phases with minimal human-in-the-loop -- Produces three outputs: hunt report, detection backlog (with handoff docs), visibility gap report -- Self-evaluates and suggests next hunts based on ATT&CK coverage gaps -- Maintains lightweight living documents (hunt log, coverage map) -- Escalates to the SOC skill when active threats are discovered - -## Design Decisions - -| Decision | Choice | Rationale | -|---|---|---| -| Relationship to `/soc hunt` | Standalone skill — independent, not a subcommand | Clean separation of concerns. `/soc hunt` remains a quick ad-hoc mode; this skill handles the full PEAK lifecycle. | -| Hunt types | All three: hypothesis, intelligence, baseline | PEAK framework structures them cleanly. CrowdStrike NGSIEM supports all three (CQL handles stacking natively for baseline). | -| Human-in-the-loop | Minimal — agentic execution, escalation is the interrupt | Experiment in autonomous hunting. Humans provide the trigger and review outputs, not gate phases. | -| Outputs | Hunt report + detection backlog + gap report | Full Act phase. Detection backlog closes the feedback loop. Gap report enables HM3/HM4 maturity. | -| Living documents | Lightweight — hunt log + ATT&CK coverage map | Prevents redundant hunts, informs prioritization. Baselines expressed as CQL/detections, not memory files. | -| Threat escalation | Tiered — continue for suspected, hard stop for active compromise | Matches real hunt team operations. "Does this need containment?" is the decision boundary. | -| Phase architecture | PEAK-aligned, fluid execution, no human gates between phases | Hunting is exploratory. Rigid gates fight the nature of the activity. | -| Self-evaluation | Part of Act phase, feeds coverage map and next-hunt suggestions | Embodies HM4 maturity ideal — systematic improvement of the hunting cycle. | - ---- - -## Skill Identity - -**Name:** `threat-hunting` -**Location:** `.claude/skills/threat-hunting/` -**Persona:** Autonomous threat hunter operating inside a CrowdStrike NG-SIEM environment. Assumes breach. Follows leads. Produces actionable outputs. - -**Sub-skills loaded:** `logscale-security-queries` (CQL reference), `cql-patterns` (query patterns), `behavioral-detections` (correlation patterns for detection backlog output). - ---- - -## Invocation - -| Command | Hunt Type | Example | -|---|---|---| -| `/hunt hypothesis "<statement>"` | Hypothesis-driven | `/hunt hypothesis "Adversary may be using DNS tunneling for C2 from production servers"` | -| `/hunt intel "<context>"` | Intelligence-driven | `/hunt intel "CVE-2025-55241 — undocumented Microsoft tokens bypassing MFA"` | -| `/hunt baseline "<entity>"` | Baseline/anomaly | `/hunt baseline "scheduled tasks across all Windows endpoints"` | -| `/hunt` | Agent-suggested | Reads coverage map, suggests high-value targets based on ATT&CK gaps | -| `/hunt log` | Utility | Display hunt log summary | -| `/hunt coverage` | Utility | Display ATT&CK coverage map with gaps | - ---- - -## Phase Architecture - -Three PEAK-aligned phases, executed autonomously. No human gates between phases. Human is surfaced only for threat escalation or at hunt completion. - -### Prepare Phase - -Scopes the hunt before running any queries. - -**All hunt types:** -1. Load living docs — `memory/hunt-log.md`, `memory/coverage-map.md` -2. Load `environmental-context.md` for org baselines -3. Load `memory/investigation-techniques.md` for repo mapping and field gotchas -4. Cross-reference `resources/detections/` MITRE mappings to understand existing automated detection coverage for the target techniques -5. Determine ATT&CK technique mapping for the hunt -6. Establish CQL scope filter (repos, time range, entity constraints) -7. Define success/failure criteria — what would confirm or refute? - -**Hypothesis-driven additions:** -- Parse the hypothesis into testable components -- Identify required data sources and confirm they exist (quick `ngsiem_query` to validate repo/field availability) -- If data sources are insufficient, log the gap and either pivot to what's available or abort with a gap report - -**Intelligence-driven additions:** -- Extract IOCs and TTPs from the provided intel context -- Escalate IOCs to behavioral patterns (Pyramid of Pain — move up from hashes/IPs to TTPs) -- Map TTPs to CQL-queryable telemetry - -**Baseline additions:** -- Identify the entity/behavior class to baseline -- Determine the stacking attributes (what to group by, what to count) -- Establish time window for baseline (7-30 days depending on data volume) - -### Execute Phase - -Fluid, exploratory. The agent follows leads, pivots, and adapts. - -**Hypothesis-driven:** -1. Run primary hypothesis test queries -2. Analyze results — does the data support or refute? -3. If leads emerge, pivot: correlate across data sources, expand scope -4. If no leads, attempt alternative detection angles for the same TTP -5. Document evidence chain as investigation progresses - -**Intelligence-driven:** -1. Sweep for IOCs first (quick wins) -2. Pivot from any IOC hits to behavioral patterns — what else did that actor/IP/hash do? -3. Hunt for the TTPs described in the intel even without IOC matches (IOCs may have rotated but behavior persists) -4. Cross-correlate across data sources (CloudTrail + EntraID + endpoint + network) - -**Baseline:** -1. Run stacking queries — frequency counts across the target attribute -2. Identify statistical outliers (entities appearing on 1-2 systems, unusual values, low-frequency entries) -3. Investigate outliers — context queries to determine if anomalous = malicious -4. Establish documented baseline for future comparison - -**Threat escalation interrupt (all types):** -- **Suspected threat:** Continue hunting to establish scope. Flag finding but don't stop. -- **Confirmed active compromise** (C2, exfiltration, active lateral movement): Stop hunting. Produce immediate escalation package with IOCs, affected systems, timeline. Create handoff doc for SOC skill. Surface to human. - -### Act Phase - -Produce all outputs and self-evaluate. - -1. **Hunt Report** — structured findings document (persisted to `docs/hunts/`) -2. **Detection Backlog** — proposed detections with handoff docs to authoring skills -3. **Gap Report** — visibility gaps, missing telemetry, ATT&CK coverage holes -4. **Self-evaluation** — hypothesis quality, data sufficiency, investigation efficiency -5. **Update living docs** — append to hunt log, update coverage map -6. **Suggest next hunt** — based on coverage gaps, findings, and staleness - ---- - -## MCP Tools - -| Activity | MCP Tools | Usage Pattern | -|---|---|---| -| Hypothesis testing | `ngsiem_query` | Ad-hoc CQL — the workhorse. Multiple queries per hunt, pivoting between repos. | -| Stacking/baselining | `ngsiem_query` | `groupBy()` + `count()` + `sort()` across large time windows. Long-tail analysis. | -| IOC sweeps | `ngsiem_query` | Multi-repo searches for hashes, IPs, domains across all telemetry. | -| Host context | `host_lookup`, `host_login_history`, `host_network_history` | When an endpoint surfaces during a hunt. | -| Cloud context | `cloud_query_assets`, `cloud_get_risks`, `cloud_get_iom_detections` | When cloud resources or IAM activity surfaces. | -| Alert correlation | `get_alerts`, `alert_analysis` | Check if existing detections already fired for discovered entities. | -| Escalation | `case_create`, `case_add_event_evidence`, `case_add_tags` | Only on confirmed active compromise. | - -### Key CQL Patterns - -Beyond what `cql-patterns` and `logscale-security-queries` provide, the skill carries knowledge of hunting-specific query patterns: - -- **Stacking:** `groupBy([field], function=count()) | sort(_count, order=asc) | tail(50)` — find rare values -- **Temporal clustering:** `bucket(span=5m)` + `groupBy()` — detect bursts of activity -- **Cross-source correlation:** Same entity (user, IP, hostname) across multiple repos within the same time window -- **Process tree reconstruction:** Parent-child PID chaining via `ngsiem_query` against EDR telemetry -- **Beacon detection:** Periodic callback patterns via time-delta analysis on network connections - ---- - -## Outputs - -### Hunt Report - -Produced after every hunt. Persisted to `docs/hunts/YYYY-MM-DD-<slug>.md`. This directory is committed to git — hunt reports are permanent archival records (unlike `docs/handoffs/` which is gitignored). - -```markdown -## Hunt Report: <title> -**Date**: YYYY-MM-DD -**Type**: Hypothesis | Intelligence | Baseline -**ATT&CK Techniques**: T1234, T5678 -**Duration**: <approximate> -**Outcome**: Threat Found | No Threat — Coverage Validated | Inconclusive - -### Hypothesis / Objective -<What we were looking for and why> - -### Scope -- **Data sources**: <repos queried> -- **Time range**: <start — end> -- **Entities**: <users, hosts, IPs, services examined> - -### Findings -<Chronological investigation narrative> - -### IOCs -| Indicator | Type | Context | -|-----------|------|---------| -<only if threat discovered> - -### Conclusion -<2-3 sentences: what did we learn?> - -### Self-Evaluation -- **Hypothesis quality**: <Was it testable? Too broad? Too narrow?> -- **Data sufficiency**: <Did we have what we needed?> -- **Investigation efficiency**: <Dead ends? Better paths in hindsight?> -- **Suggested next hunt**: <Based on gaps found or leads not fully pursued> -``` - -### Detection Backlog - -Produced when the hunt reveals detectable patterns. - -```markdown -## Proposed Detections from Hunt: <title> - -| # | Detection | ATT&CK | Approach | Complexity | Target Skill | Priority | -|---|-----------|--------|----------|------------|-------------|----------| -``` - -Each entry gets a handoff doc to `docs/handoffs/` following the standard handoff spec: - -```yaml -source_skill: threat-hunting -target_skill: behavioral-detections | cql-patterns | logscale-security-queries -objective: "Author a detection for [pattern discovered during hunt]" -context: - hunt_title: "<title>" - hunt_date: "YYYY-MM-DD" - threat_scenario: "<what the detection should find>" - mitre_technique: "<technique ID>" - mitre_tactic: "<tactic>" - detection_approach: "<simple threshold | stacking anomaly | behavioral correlation>" - key_event_types: [...] - key_fields: [...] - volume_notes: "<expected signal volume and noise characteristics>" - sample_query: "<CQL query from the hunt that surfaced this pattern>" -decisions_made: - - "Pattern discovered during [hunt type] hunt" - - "<any context about why this detection matters>" -constraints: - - "120s query timeout" - - "<any data source limitations noted during hunt>" -artifacts: - - "docs/hunts/YYYY-MM-DD-<slug>.md" -``` - -### Gap Report - -Documents what the hunter couldn't see. - -```markdown -## Visibility Gap Report: <hunt title> - -### Gaps Identified -| Gap | Impact | ATT&CK Techniques Affected | Recommendation | -|-----|--------|---------------------------|----------------| - -### ATT&CK Coverage Delta -<Techniques in scope but untestable, with reasons> -``` - ---- - -## Living Documents - -Two files in `.claude/skills/threat-hunting/memory/`. - -### `hunt-log.md` - -Append-only log of completed hunts. One entry per hunt. - -```markdown -# Hunt Log - -| Date | Type | Title | ATT&CK | Outcome | Detections Proposed | -|------|------|-------|--------|---------|-------------------| -``` - -### `coverage-map.md` - -ATT&CK technique coverage tracker, updated after every hunt. Tracks the **hunt layer** — what has been proactively hunted. Cross-referenced during Prepare against deployed detection MITRE mappings from `resources/detections/` to identify high-value targets. - -```markdown -# ATT&CK Hunt Coverage Map - -## Hunted -| Technique | Tactic | Last Hunted | Result | Data Quality | -|-----------|--------|-------------|--------|-------------| - -## Known Gaps -| Technique | Tactic | Reason | Recommendation | -|-----------|--------|--------|----------------| - -## Suggested Priority Hunts -<Auto-generated from: gaps, staleness (90+ days since last hunt), techniques with detections but no hunting validation> -``` - -The coverage map tracks techniques the skill has engaged with or identified as gaps. It grows organically through use. During Prepare, the skill cross-references this against deployed detection MITRE mappings to surface three categories of high-value hunt targets: - -1. **Blind spots** — techniques with no detections AND no hunting (highest priority) -2. **Untested assumptions** — techniques with deployed detections but never hunted (are the detections actually catching things?) -3. **Stale coverage** — techniques hunted 90+ days ago (the environment may have changed) - ---- - -## Integration & Handoffs - -### Upstream Triggers - -| Source | How | Example | -|---|---|---| -| Human | Direct invocation via `/hunt` | "Hunt for lateral movement in the cloud accounts" | -| Coverage map | Agent suggests when invoked with no args | "T1078 Valid Accounts hasn't been hunted and has 3 detections — worth validating" | -| Source-threat-modeling | Handoff doc — threat scenarios not yet hunted | "Okta session hijacking was modeled but never validated against live data" | -| SOC skill | Finding during triage warrants deeper investigation | Analyst spots suspicious pattern, spins up a hunt | -| External intel | User provides CVE, campaign report, ISAC advisory | "CrowdStrike blog on SCATTERED SPIDER new TTPs" | - -### Downstream Outputs - -| Output | Target | Mechanism | -|---|---|---| -| Detection backlog entries | `behavioral-detections`, `cql-patterns`, `logscale-security-queries` | Handoff docs to `docs/handoffs/` | -| Escalation package | SOC skill (`/soc`) | Handoff doc with IOCs, timeline, affected systems | -| Gap report | `source-threat-modeling` | Visibility gaps feed back into detection planning | -| Hunt report | `docs/hunts/` | Persistent record (archival, not a handoff) | -| Living doc updates | Own `memory/` | Hunt log + coverage map | - -### Handoff Doc Format - -Same spec as source-threat-modeling and response-playbooks. Standard fields: `source_skill`, `target_skill`, `objective`, `context`, `decisions_made`, `constraints`, `artifacts`. - -### Relationship to Deployed Detection Coverage - -During Prepare, the skill reads MITRE mappings from `resources/detections/` to understand existing automated detection coverage. This informs hunt prioritization but the skill never modifies detection files directly. Detection authoring is always delegated via handoff docs. - ---- - -## File Structure - -``` -.claude/skills/threat-hunting/ -├── SKILL.md # Main skill definition -├── DESIGN.md # Architecture rationale -└── memory/ - ├── hunt-log.md # Completed hunts log - └── coverage-map.md # ATT&CK hunt coverage tracker - -.claude/commands/ -└── hunt.md # /hunt command routing to skill -``` - -### Context Loading at Invocation - -1. `SKILL.md` (always) -2. `memory/hunt-log.md` (always — what's been done) -3. `memory/coverage-map.md` (always — informs prioritization) -4. `environmental-context.md` (always — org baselines) -5. `memory/investigation-techniques.md` (Prepare phase — repo mappings, field gotchas) -6. Sub-skills on demand: `logscale-security-queries`, `cql-patterns`, `behavioral-detections` - ---- - -## What's NOT In Scope - -- **Replacing `/soc hunt`** — the SOC skill's hunt mode stays as a quick ad-hoc option. This skill is the full PEAK lifecycle. -- **Detection authoring** — delegated to existing skills via handoff docs. The skill proposes detections, it doesn't write CQL or YAML. -- **Incident response** — on active compromise, the skill produces an escalation package and hands off to the SOC skill. It doesn't contain or remediate. -- **UEBA/ML** — the skill uses CQL-native stacking and statistical analysis for baseline hunts. It doesn't integrate external ML models or UEBA platforms. -- **Campaign orchestration** — each invocation is a single hunt. Multi-hunt campaigns can be layered on later if single hunts prove effective. - -## Relationship to Existing Skills - -``` - threat-hunting (NEW) - "what's hiding" - | - +---------------+---------------+ - | | | - hunt report detection backlog gap report - | | | - docs/hunts/ handoff docs feeds back to - (archival) | source-threat-modeling - | - +-------------+-------------+ - | | | - behavioral- cql-patterns logscale-security- - detections "how to write" queries - "how to write" "how to write" - | | | - +------+------+------+------+ - | | - detection-tuning response-playbooks - "how to tune" "what response" -``` - -## Research Foundation - -This skill's design is grounded in the threat hunting research survey (`/home/will/projects/agent-skills/threat-hunting-research.md`). Key concepts incorporated: - -- **PEAK framework** (Bianco et al., 2023) — Prepare → Execute → Act phase structure -- **Hunting Maturity Model** — targeting HM4 (systematic automation of hunting discoveries into detections) -- **Pyramid of Pain** (Bianco, 2013) — intelligence-driven hunts escalate from IOCs to TTPs -- **Stacking/long-tail analysis** — core technique for baseline hunts -- **Hunt → detection engineering feedback loop** — the detection backlog output systematizes this -- **"A hunt that finds no threats is not a failure"** — the gap report and coverage validation capture value from clean hunts -- **Self-evaluation** — Approach 3 element enabling continuous improvement of the hunting practice