/crowdsentinel-investigation

name: crowdsentinel-investigation
description: Use when conducting threat hunting or incident response with CrowdSentinel MCP tools. MANDATORY for any investigation involving Elasticsearch, EQL, ES|QL, or detection rules. Enforces proper use of analysis and reporting tools.

CrowdSentinel Investigation Workflow

When This Skill Applies

Use this skill when:

• Conducting threat hunting on Elasticsearch logs
• Running detection rules (EQL, ES|QL, Lucene)
• Investigating security incidents
• Analyzing Windows/Linux logs for threats
• Presenting investigation findings to user

The Iron Laws

1. EVERY INVESTIGATION ENDS WITH generate_investigation_report — INCLUDING ITS EXECUTIVE SUMMARY
2. NO INVESTIGATION IS COMPLETE WITHOUT ANALYSIS TOOLS
3. NO INVESTIGATION IS COMPLETE UNTIL THE ADJACENCY LOOP IS CLOSED

**Law 1 (always report — no exceptions)** — There is no "quick" exemption. EVERY investigation — even a one-query "quick and sweet" hunt — MUST end with `generate_investigation_report`, which carries BOTH the **executive summary** (prose) and the structured **report/summary** (aggregated IoCs, techniques, timeline, severity, recommendations). "Quick" means fewer hunts, NOT skipping the report. `create_investigation` is *recommended* — especially for multi-query cases, so IoCs aggregate under one investigation_id — but it is OPTIONAL; the report can be built from analysis results alone. If you presented findings without the report + executive summary, it is INCOMPLETE.

**Law 2** — If you collected data but didn't run analysis tools, it's INCOMPLETE.

**Law 3** — After `analyze_kill_chain_stage`, it hands you `hunt_previous_stage` / `hunt_next_stage` queries and hunts return `recommended_followups`. You MUST run them — via `hunt_adjacent_stages`, the returned queries, or `get_host_activity_timeline` — until **every adjacent stage is confirmed or excluded**. `generate_investigation_report` is the *summary of a closed loop*, not the stop signal. Stopping after one analysis pass is the #1 investigation failure.

Mandatory Workflow

Phase 1: Data Collection

Use hunting tools to gather evidence:

| Tool | Use Case | |------|----------| | `threat_hunt_search` | IR-focused search with auto IoC extraction (PREFERRED) | | `smart_search` | Token-efficient search with summarization | | `execute_detection_rule` | Run EQL/Lucene detection rules | | `execute_esql_hunt` | Run ES|QL hunting queries | | `esql_query` | Ad-hoc ES|QL queries | | `eql_search` | Ad-hoc EQL queries |

Phase 2: Analysis (MANDATORY - DO NOT SKIP)

After EVERY search/hunt query, you MUST analyze the results:

┌─────────────────────────────────────────────────────────────────┐
│  AFTER collecting data, you MUST use these analysis tools:      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. analyze_search_results(results, context)                    │
│     → Extracts IoCs, maps MITRE ATT&CK, assesses severity       │
│     → Provides recommended follow-up queries                    │
│                                                                 │
│  2. analyze_kill_chain_stage(iocs, include_hunting_suggestions) │
│     → Positions attack in Cyber Kill Chain                      │
│     → Suggests previous/next stage hunting                      │
│                                                                 │
│  3. map_events_to_kill_chain(events)                           │
│     → Maps event timeline to kill chain stages                  │
│     → Shows attack progression                                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Phase 2.5: Close the Adjacency Loop (DO NOT stop after one pass)

Iron Law 2. Drive the hunt outward from the current stage until adjacent stages are confirmed or excluded:

| Tool | Use Case | |------|----------| | `hunt_adjacent_stages` | Hunt the stages immediately before/after the current one | | `hunt_by_kill_chain_stage` | Targeted hunt for a specific kill-chain stage | | `get_host_activity_timeline` | Time-ordered activity for one host | | `get_kill_chain_overview` | Where each stage stands across the investigation | | `correlate_by_time` | Co-occurring SIEM+endpoint activity in a window (no VR) | | `build_unified_timeline` | Merge ES/osquery/Chainsaw/Wireshark into one chronology (no VR) | | `iterative_hunt`, `get_next_step`, `start_guided_investigation` | Server-driven next-step engine |

**Exit criterion:** each identified stage has its adjacent stages hunted, and pagination/coverage is complete or explicitly logged as capped.

Phase 2.6: Endpoint Validation (Velociraptor OR osquery)

Validate SIEM findings against the live host. Use Velociraptor when configured; otherwise **osquery is the fallback for the same step — do not skip it**.

| Tool | Use Case | |------|----------| | `velociraptor_pslist` / `velociraptor_netstat` / `velociraptor_*` | Live forensics (when VR configured) | | `osquery_processes` | Live process list (join with sockets to pin C2 owners) | | `osquery_sockets` | Listening/established sockets ⋈ processes | | `osquery_users` / `osquery_query` | Accounts / ad-hoc SQL over any table | | `endpoint_to_siem_pivot`, `endpoint_hunt_from_ioc` | Pivot endpoint IoCs back into Elastic (VR) |

**LIVE state ≠ what HAPPENED — collect retrospective execution evidence, not just `pslist`.** `pslist`/`netstat` only show what is alive RIGHT NOW. An ephemeral or cleaned attack (payloads that run and exit in seconds; persistence reverted; AV-quarantined binaries) leaves NOTHING in live state — so a "clean live host" is NOT "nothing happened". For WHAT EXECUTED, hunt the SIEM and collect VR's forensic artifacts:

| Tool / artifact | What it proves (survives process exit + cleanup) | |-----------------|----------------------------------