From b6260c7fbefd395b42eee38fb600c42501205159 Mon Sep 17 00:00:00 2001 From: willwebster5 Date: Sat, 28 Mar 2026 22:51:26 -0400 Subject: [PATCH 1/5] chore: add docs/handoffs/ for ephemeral skill handoff documents Co-Authored-By: Claude Opus 4.6 (1M context) --- .gitignore | 7 +++++++ docs/handoffs/.gitkeep | 0 2 files changed, 7 insertions(+) create mode 100644 docs/handoffs/.gitkeep diff --git a/.gitignore b/.gitignore index 7e830fc..1ede2af 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,10 @@ credentials.json # OS .DS_Store Thumbs.db + +# docs/superpowers +docs/superpowers/ + +# Handoff docs (ephemeral working artifacts between skills) +docs/handoffs/ +!docs/handoffs/.gitkeep diff --git a/docs/handoffs/.gitkeep b/docs/handoffs/.gitkeep new file mode 100644 index 0000000..e69de29 From 39edca3f0c8cef0a0b543c65acc32ed48556a478 Mon Sep 17 00:00:00 2001 From: willwebster5 Date: Sat, 28 Mar 2026 22:59:13 -0400 Subject: [PATCH 2/5] =?UTF-8?q?feat:=20add=20source-threat-modeling=20skil?= =?UTF-8?q?l=20=E2=80=94=20threat-model-first=20detection=20planning?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .../skills/source-threat-modeling/SKILL.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 .claude/skills/source-threat-modeling/SKILL.md diff --git a/.claude/skills/source-threat-modeling/SKILL.md b/.claude/skills/source-threat-modeling/SKILL.md new file mode 100644 index 0000000..a957a47 --- /dev/null +++ b/.claude/skills/source-threat-modeling/SKILL.md @@ -0,0 +1,284 @@ +--- +name: source-threat-modeling +description: > + Threat-model-first detection planning for data sources without OOTB coverage. + Analyzes what threats apply to a source type, validates against live log data, + and produces a prioritized detection backlog with handoff docs for authoring skills. + Use when onboarding a new data source, planning detection coverage for a source + without OOTB templates, or assessing what threats a source can detect. +allowed-tools: Read, Write, Grep, Glob, Bash +--- + +# Source Threat Modeling + +Turn a data source into detection coverage. This skill reasons about what threats are relevant to a source type, validates which are detectable in your actual log data, and produces a prioritized detection backlog. It does NOT write detections — it hands off to authoring skills (`behavioral-detections`, `cql-patterns`, `logscale-security-queries`) via handoff documents. + +> **Orchestrator, not author.** This skill decides *what* to detect. Existing skills decide *how* to write it. + +## When to Use This Skill + +- A new data source is connected to NGSIEM and has no OOTB detection templates +- You want to assess detection coverage gaps for an existing source +- You need a structured threat model before building bespoke detections +- You're onboarding a source type you haven't worked with before + +## Handoff Input + +This skill can be invoked directly or via a handoff document. If a handoff doc is provided, read it first and skip questions already answered. + +--- + +## Phase 1: Source Identification + +**Goal:** Establish what source we're working with and how to query it. + +Ask the user: + +1. **What product/vendor is the data source?** (e.g., Okta, GitHub audit logs, Cisco ASA, Zscaler) +2. **What log types are being ingested?** (authentication, admin activity, network flow, API audit, etc.) +3. **What is the NGSIEM scope filter?** + - e.g., `#Vendor="okta"`, `#repo="some_repo"`, `#event.module="some_module"` + - If the user doesn't know, help discover it: + ``` + * | groupBy([@repo, #Vendor, #event.module], limit=20) + ``` +4. **What role does this source play in the environment?** (identity provider, network perimeter, cloud infrastructure, application-level, endpoint, email/collaboration) + +**Check for existing coverage:** +- Scan `resources/detections/` for any rules already targeting this source +- Note what's covered so we don't duplicate + +**Output:** A CQL scope filter and source profile that constrains all subsequent work. + +**STOP** — Confirm the scope filter and source profile with the user before proceeding to threat modeling. + +--- + +## Phase 2: Threat Modeling + +**Goal:** Enumerate threats this source can observe, mapped to MITRE ATT&CK. + +Work through three threat categories systematically: + +### Category A: Abuse of the monitored system + +What can an attacker do *through* the system this source monitors? + +| Source Role | Example Threats | +|---|---| +| Identity provider | Credential stuffing, MFA bypass, session hijacking, account takeover | +| Network perimeter | C2 communication, lateral movement, data exfiltration, port scanning | +| Cloud infrastructure | Resource abuse, privilege escalation, config tampering, data access | +| Application | Injection, unauthorized access, data theft, API abuse | +| Endpoint | Malware execution, LOLBins, persistence mechanisms, credential dumping | +| Email/collaboration | Phishing, BEC, forwarding rules, delegation abuse | + +### Category B: Compromise of the source itself + +What does it look like when the source system is the target? +- Admin account takeover on the source platform +- Audit log tampering or deletion +- Security configuration changes (weakened settings) +- API key or token compromise +- Integration or connector manipulation + +### Category C: Lateral movement and escalation + +What cross-system activity is visible through this source? +- Privilege escalation (new admin grants, role changes) +- Cross-tenant or cross-account activity +- Service account abuse +- Access to new resources or scopes not previously seen + +**For each threat scenario, document:** + +| Field | Description | +|---|---| +| Threat scenario | Plain-language description of the attack | +| MITRE technique | ATT&CK technique ID (e.g., T1621) | +| MITRE tactic | ATT&CK tactic (e.g., Credential Access) | +| Expected event types | What log events would reveal this activity | +| Expected severity | Critical / High / Medium / Low | + +**Present the threat model to the user as a ranked table.** Rank by severity and likelihood. Discuss and refine before proceeding to log validation. + +**STOP** — Get user approval on the threat model before querying live data. + +--- + +## Phase 3: Log Validation + +**Goal:** Confirm which threats from Phase 2 are actually detectable in the live data. + +For each threat scenario, run exploratory CQL queries using `mcp__crowdstrike__ngsiem_query`: + +### Step 1: Event type discovery + +Map what the source actually emits: + +``` + +| groupBy([event.type, event.action, event.category], limit=50) +``` + +### Step 2: Per-scenario validation + +For each threat scenario from Phase 2: + +**a) Do the required event types exist?** +``` + event.type="" +| count() +``` + +**b) What's the volume?** (informs threshold decisions) +``` + event.type="" +| bucket(span=1d) +| count() +``` + +**c) What fields are available?** (informs detection logic) +``` + event.type="" +| head(10) +``` + +**d) What does "normal" look like?** (informs baselines) +``` + event.type="" +| groupBy([], function=count()) +| sort(_count, order=desc) +| head(20) +``` + +### Step 3: Feasibility classification + +For each threat scenario, classify: + +| Classification | Meaning | Action | +|---|---|---| +| **Detectable** | Required events exist, fields available, reasonable volume | Keep — proceed to backlog | +| **Partially detectable** | Some events present but missing key fields or context | Discuss with user — worth pursuing with limitations? | +| **Not detectable** | Required events don't exist in the data | Prune from backlog | +| **Surprising find** | Unexpected patterns worth investigating | Flag for user — potential quick win or live incident | + +**Present results.** For each scenario, show: classification, event types found, key fields available, daily volume estimate, and any surprising observations. + +**STOP** — Discuss findings with user. Prune not-detectable scenarios. Decide on partial detections. + +--- + +## Phase 4: Detection Backlog & Handoff + +**Goal:** Produce a prioritized detection backlog and hand off selected detections to authoring skills. + +### Build the backlog + +For each validated threat scenario, create a backlog entry: + +| Field | Description | +|---|---| +| **Priority** | 1 (highest) through N — based on severity + feasibility | +| **Threat scenario** | Plain-language description | +| **MITRE mapping** | Technique ID + tactic | +| **Detection approach** | `simple` (single event match), `threshold` (aggregation), `behavioral` (multi-event correlation) | +| **Complexity** | Low (single event) / Medium (aggregation/threshold) / High (multi-event correlation) | +| **Key event types** | From log validation | +| **Key fields** | From log validation | +| **Volume estimate** | Events/day from log validation | +| **Recommended skill** | Which authoring skill should build this | + +### Skill routing + +| Detection Approach | Route To | Why | +|---|---|---| +| Multi-event attack chains (deny-then-success, create-then-escalate) | `behavioral-detections` | Needs `correlate()` function | +| Threshold/aggregation rules (N events in T time) | `cql-patterns` | Pattern-based aggregation | +| Simple event matching or complex field logic | `logscale-security-queries` | General CQL development | + +### Present the backlog + +Show the full backlog as a prioritized table. User selects which detections to pursue. + +### Generate handoff documents + +For each selected detection, write a handoff doc to `docs/handoffs/`. + +**Filename:** `YYYY-MM-DD-threat-model-to--.md` + +**Template:** + +```markdown +# Handoff: Source Threat Modeling → + +## Objective + +Author a detection for: + +## Source + +- **Produced by:** source-threat-modeling skill +- **Date:** +- **Target skill:** + +## Context + +| Field | Value | +|---|---| +| Data source | | +| CQL scope filter | `` | +| Source role | | +| Threat scenario | | +| MITRE technique | — | +| MITRE tactic | | +| Detection approach | | +| Estimated severity | | + +### Key Event Types + +- `` — + +### Key Fields + +- `` — + +### Volume Notes + + + +## Decisions Made + +These have been reviewed and approved by the user. The receiving skill should NOT re-ask: + +- +- + +## Constraints + +- 120s NGSIEM query timeout — keep correlation windows reasonable +- +- + +## Artifacts + +- +``` + +**Tell the user:** "Handoff doc written to ``. Invoke the `` skill and point it at this file to begin authoring." + +--- + +## Reference: Common Source Types + +| Source Category | Examples | Typical Threat Focus | +|---|---|---| +| Identity Provider | Okta, EntraID, Ping, Auth0 | Credential attacks, MFA bypass, admin takeover, privilege escalation | +| Cloud Infrastructure | AWS CloudTrail, GCP Audit, Azure Activity | Resource abuse, IAM escalation, config tampering, data access | +| Network Security | Cisco ASA, Palo Alto, Zscaler, Akamai | C2 comms, lateral movement, exfiltration, scanning | +| Source Code / DevOps | GitHub, GitLab, Bitbucket | Code theft, secret exposure, pipeline compromise, access changes | +| SaaS Applications | Salesforce, Workday, ServiceNow | Data exfiltration, privilege abuse, config changes | +| Endpoint | CrowdStrike EDR, Carbon Black, SentinelOne | Malware, LOLBins, persistence, credential dumping | +| Email / Collaboration | M365, Google Workspace | Phishing, BEC, forwarding rules, delegation abuse | + +This table is a starting point for Phase 2 — reason about threats specific to the actual product, not just the category. From c6391cd3f4d6f082ccdff00a100cd0ec6648f3ea Mon Sep 17 00:00:00 2001 From: willwebster5 Date: Sat, 28 Mar 2026 23:14:45 -0400 Subject: [PATCH 3/5] =?UTF-8?q?feat:=20add=20response-playbooks=20skill=20?= =?UTF-8?q?=E2=80=94=20detection-to-response=20mapping=20and=20SOAR=20play?= =?UTF-8?q?book=20design?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/response-playbooks/SKILL.md | 277 +++++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 .claude/skills/response-playbooks/SKILL.md diff --git a/.claude/skills/response-playbooks/SKILL.md b/.claude/skills/response-playbooks/SKILL.md new file mode 100644 index 0000000..aaecb4c --- /dev/null +++ b/.claude/skills/response-playbooks/SKILL.md @@ -0,0 +1,277 @@ +--- +name: response-playbooks +description: > + Detection-to-response mapping and SOAR playbook design. Analyzes detections, + recommends tiered response actions (observe, investigate, contain, remediate), + and produces handoff docs for fusion-workflows to generate workflow YAML. + Use when planning response automation for detections, designing SOAR playbooks, + or mapping detections to Falcon Fusion workflow actions. +allowed-tools: Read, Write, Grep, Glob, Bash +--- + +# Response Playbooks + +Turn detections into automated response. This skill analyzes what a detection looks for, recommends tiered response actions appropriate to the threat, and hands off to `fusion-workflows` for workflow YAML generation. It bridges the gap between "alert fires" and "something happens." + +> **Response architect, not workflow builder.** This skill decides *what response* fits a detection. The `fusion-workflows` skill builds the actual workflow YAML. + +## When to Use This Skill + +- You have detections deployed (or proposed) and need response automation +- You want to design SOAR playbooks for a set of detections +- You need to map detection severity/type to appropriate response actions +- You're deciding which detections warrant automated containment vs. notification-only + +## Handoff Input + +This skill accepts: +- **Direct invocation** — user points at detections by name, file path, or description +- **Handoff doc from source-threat-modeling** — read the doc and use its context for Phase 1 + +If consuming a handoff doc, skip Phase 1 questions already answered in the doc. + +--- + +## Phase 1: Detection Intake + +**Goal:** Understand what each detection looks for and what's at stake. + +For each detection the user wants response automation for: + +### Step 1: Read the detection + +- If it's a deployed detection: read from `resources/detections/` +- If it's from a handoff doc: read the context provided +- If described verbally: ask enough questions to understand the threat + +Gather: +- Detection name and CQL logic +- Severity level +- MITRE ATT&CK mapping (technique + tactic) + +### Step 2: Identify the center entity + +What is the primary subject of this detection? + +| Entity Type | Examples | +|---|---| +| User account | Identity-based threats — credential attacks, privilege escalation | +| Host/endpoint | Malware, LOLBins, persistence, lateral movement | +| IP address | Network-based threats — C2, scanning, exfiltration | +| Cloud resource | Infrastructure threats — config changes, IAM abuse | +| Application | SaaS/app-level threats — data theft, API abuse | + +### Step 3: Assess blast radius + +If this detection fires as a true positive, how bad is it? + +| Blast Radius | Meaning | Examples | +|---|---|---| +| **Critical** | Active compromise, data loss in progress | Ransomware, active exfiltration, admin account takeover | +| **High** | Escalation or movement underway | Privilege escalation, lateral movement, credential theft | +| **Medium** | Suspicious but contained | Policy violation, anomalous login, config change | +| **Low** | Informational, worth tracking | New device, unusual time of day, minor anomaly | + +**Present the intake summary** (detection, entity, blast radius) and confirm with user before proceeding. + +**STOP** — Get user confirmation on the intake assessment. + +--- + +## Phase 2: Response Recommendation + +**Goal:** Propose a tiered response plan for each detection. + +### Response Tiers + +| Tier | Name | Automation Level | Description | +|---|---|---|---| +| **Tier 1** | Observe | Always auto-fire | Create case, log event, notify Slack/email | +| **Tier 2** | Investigate | Always auto-fire | Enrich alert with host details, user history, related alerts | +| **Tier 3** | Contain | Requires human approval | Disable user, isolate host, revoke session, block IP | +| **Tier 4** | Remediate | Manual only | Reset credentials, remove persistence, restore from backup | + +### Recommendation Process + +For each detection: + +**1. Tier 1 — Observe (every detection gets this)** + +- Create case with appropriate severity +- Notify the relevant channel (Slack, email, PagerDuty based on severity) +- Log to SIEM for correlation + +**2. Tier 2 — Investigate (based on center entity)** + +| Entity Type | Enrichment Actions | +|---|---| +| User account | Recent auth history, group memberships, risk score, MFA status | +| Host/endpoint | Running processes, network connections, login history, installed software | +| IP address | Geo lookup, reputation check, historical connections, associated users | +| Cloud resource | Config change history, access logs, associated IAM roles | +| Application | Recent API calls, data access patterns, admin actions | + +**3. Tier 3 — Contain (based on severity + threat type)** + +| Severity | Threat Type | Containment Recommendation | +|---|---|---| +| Critical | Active attack (exfil, ransomware, admin takeover) | Immediate containment with approval gate | +| Critical | Credential compromise (MFA fatigue, brute force success) | Disable user + revoke sessions with approval gate | +| High | Lateral movement | Isolate host with approval gate | +| High | Privilege escalation | Suspend elevated access with approval gate | +| Medium or below | Any | Skip containment — observe and investigate only | + +**Every Tier 3 action MUST have a human approval gate.** Never auto-execute containment. False positive containment is worse than delayed response. + +**4. Tier 4 — Remediate (always manual, but document it)** + +Document what the SOC should do after containment: +- Credential reset procedures +- Host reimaging steps +- Config rollback process +- Evidence preservation requirements +- Scope assessment (who/what else was affected?) + +### Validate available actions + +Before recommending, confirm what's actually available in the tenant: + +```bash +python .claude/skills/fusion-workflows/scripts/action_search.py --vendor +python .claude/skills/fusion-workflows/scripts/action_search.py --use-case +``` + +Only recommend actions that are available. If a recommended action isn't available, note it as a gap and suggest alternatives. + +### Present the response plan + +For each detection, present: + +``` +Detection: +Severity: | Entity: | Threat: + +Tier 1 (auto): + - Create case (severity: ) + - Notify with: detection name, affected entity, key indicators + +Tier 2 (auto): + - + +Tier 3 (approval required): + - — requires SOC analyst approval + +Tier 4 (manual): + - +``` + +**STOP** — Get user approval on the response plan before generating handoff docs. + +--- + +## Phase 3: Workflow Generation & Handoff + +**Goal:** Produce handoff documents for `fusion-workflows` to build the actual workflow YAML. + +For each approved response plan, write a handoff doc to `docs/handoffs/`. + +**Filename:** `YYYY-MM-DD-response-playbooks-to-fusion-workflows-.md` + +**Template:** + +```markdown +# Handoff: Response Playbooks → Fusion Workflows + +## Objective + +Create a Fusion workflow to automate response for: + +## Source + +- **Produced by:** response-playbooks skill +- **Date:** +- **Target skill:** fusion-workflows + +## Context + +| Field | Value | +|---|---| +| Detection name | | +| Detection resource_id | | +| Severity | | +| Center entity | | +| MITRE technique | — | +| MITRE tactic | | + +## Approved Response Plan + +### Tier 1 — Observe (auto-fire) + +- **Create case** — severity: , title template: " — " +- **Notify** — channel: , include: detection name, affected entity, source IP, event count + +### Tier 2 — Investigate (auto-fire) + +- **Enrich** — + +### Tier 3 — Contain (approval required) + +- **** —
+- **Approval gate:** SOC analyst must approve before execution via + +### Tier 4 — Remediate (manual) + +- + +## Decisions Made + +These have been reviewed and approved by the user. The receiving skill should NOT re-ask: + +- +- + +## Constraints + +- Tier 3 actions MUST have a human approval gate — never auto-execute containment +- Notification must include: +- + +## Workflow Structure + +- **Trigger:** Detection alert (detection name: ) +- **Flow:** Tier 1 actions → Tier 2 enrichment → conditional Tier 3 containment (with approval) +- **Approval mechanism:** + +## Artifacts + +- +``` + +**Tell the user:** "Handoff doc written to ``. Invoke the `fusion-workflows` skill and point it at this file to generate the workflow YAML." + +--- + +## Response Pattern Library + +Common detection-to-response mappings. These inform recommendations but don't override human judgment — use them as starting points. + +| Detection Type | Entity | Severity | Tier 1 | Tier 2 | Tier 3 | Tier 4 | +|---|---|---|---|---|---|---| +| Credential attack (brute force, stuffing, MFA fatigue) | User | Critical | Case + Slack | Auth history, risk score | Disable user, revoke sessions | Credential reset | +| Privilege escalation (new admin, role change) | User | High | Case + Slack | Access audit, change history | — | Review and revert access | +| Data exfiltration (bulk download, unusual export) | User/App | Critical | Case + Slack | Download history, data classification | Revoke sessions, block IP | Audit data exposure | +| Suspicious network (C2 beacon, unusual dest) | Host | High | Case + Slack | Process list, network connections | Isolate host | Reimage, hunt for lateral | +| Cloud config change (SG, IAM policy) | Cloud Resource | Medium | Case + Slack | Config diff, who-changed-what | — | Revert change | +| Anomalous login (impossible travel, new device) | User | Medium | Case + Slack | Login history, device inventory | — | — | +| Audit log tampering | Source | Critical | Case + Slack + page | Log gap analysis | Isolate source, freeze state | Forensic investigation | +| Service account abuse | User | High | Case + Slack | Service account scope, recent API calls | Rotate credentials | Audit all service account access | + +--- + +## Key Principles + +1. **Never auto-execute containment.** Tier 3 actions always require human approval. False positive containment is worse than delayed response. +2. **Every detection gets Tier 1.** At minimum: create a case and notify someone. +3. **Match response to blast radius.** A medium-severity anomalous login doesn't need host isolation. +4. **Validate before recommending.** Use action discovery to confirm what's available in the tenant. +5. **Document Tier 4 even though it's manual.** The SOC needs to know what comes after containment. From b62bc9fc26808d46d1d07ff2ad15251388033538 Mon Sep 17 00:00:00 2001 From: willwebster5 Date: Sat, 28 Mar 2026 23:16:54 -0400 Subject: [PATCH 4/5] docs: add source-threat-modeling and response-playbooks to skill table Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 4a4e7db..059d92e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,6 +65,8 @@ 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 | +| `source-threat-modeling` | Threat-model-first detection planning for new data sources | New | +| `response-playbooks` | Detection-to-response mapping and SOAR playbook design | New | ### Commands From 8dc78c0d3f8e18190c77b56ebcdc008c94052e57 Mon Sep 17 00:00:00 2001 From: willwebster5 Date: Sat, 28 Mar 2026 23:44:55 -0400 Subject: [PATCH 5/5] chore: remove specs/plans from tracking and fix gitignore docs/superpowers/ contains working documents (specs, plans) that should not be committed. Remove tracked files and ensure gitignore covers the directory. Co-Authored-By: Claude Opus 4.6 (1M context) --- .gitignore | 3 +- .../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, 1 insertion(+), 1802 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 1ede2af..e9effbf 100644 --- a/.gitignore +++ b/.gitignore @@ -31,9 +31,8 @@ credentials.json .DS_Store Thumbs.db -# docs/superpowers +# docs/superpowers (specs, plans — working documents, not committed) docs/superpowers/ - # Handoff docs (ephemeral working artifacts between skills) docs/handoffs/ !docs/handoffs/.gitkeep 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 - - -# 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 - - -# 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="" -| 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="" -| groupBy([user.email, #event.outcome]) -``` - -### Process Tree Reconstruction -Parent-child PID chaining for endpoint telemetry: -```cql -#event_simpleName=ProcessRollup2 aid= -| ParentProcessId= OR TargetProcessId= -| 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= -| DomainName= -| 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 ""` | Full PEAK cycle — hypothesis-driven hunt | -| `/hunt intel ""` | Full PEAK cycle — intelligence-driven hunt | -| `/hunt baseline ""` | 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 - | 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="" OR destination.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**: -**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