thomasxm/crowdsentinels-ai-mcp/crowdsentinel-investigation

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:

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:

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.

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:

NOTE: Windows.Forensics.Prefetch is a DEAD END on Windows Server — Server does not generate .pf files (verified: even with EnablePrefetcher=3 + SysMain, 0 .pf). Use Amcache/Shimcache.

Phase 2.7: Detection Validation

Confirm your detection content actually catches the activity you found:

Phase 3: Investigation State (RECOMMENDED — especially multi-query)

create_investigation is OPTIONAL but recommended, especially when running multiple queries: it returns an investigation_id you thread through the hunt and into the final report so every IoC/timeline event aggregates under one case (a fuller report). Not required — the report can be built from analysis results alone — but using it makes Law 1's report richer.

1. create_investigation(name, description, severity) - Start tracking
2. add_iocs_to_investigation(iocs) - Store discovered IoCs as you find them
3. get_shared_iocs() - Retrieve for cross-correlation
4. get_investigation_summary() - Check current state

Phase 4: Reporting (summary of a CLOSED loop — not the stop signal)

Only after the adjacency loop (Phase 2.5) is closed, summarize:

generate_investigation_report(
    analysis_results=[analysis1, analysis2, ...],
    investigation_context="Description of what was investigated",
    investigation_id="INV-..."   # merges the investigation timeline into the report
)

Returns:

• Executive summary
• All discovered IoCs aggregated
• MITRE ATT&CK techniques (tactics resolved from the ATT&CK map, not "Unknown")
• Affected hosts and users (augmented from the timeline)
• Merged chronological timeline
• Severity assessment
• Synthesized recommendations (next hunts when none were supplied)

If the report surfaces a new stage or unhunted adjacency, go back to Phase 2.5 — reporting is not a reason to stop hunting.

Red Flags - STOP If You're Doing This

Correct Workflow Example

# Step 1: Hunt for suspicious activity
results = threat_hunt_search(
    index="winlogbeat-*",
    query="event.code:4688 AND winlog.event_data.CommandLine:*powershell*",
    timeframe_minutes=60
)
# Step 2: Analyze results (MANDATORY)
analysis = analyze_search_results(
    search_results=results,
    context="Hunting for suspicious PowerShell execution"
)
# Step 3: Position in kill chain
iocs = [{"type": "process", "value": "powershell.exe"}, ...]
kill_chain = analyze_kill_chain_stage(
    iocs=iocs,
    include_hunting_suggestions=True
)
# Step 4: Follow hunting suggestions from kill chain analysis
# (hunt previous/next stages as recommended)
# Step 5: Generate report before concluding
report = generate_investigation_report(
    analysis_results=[analysis],
    investigation_context="Suspicious PowerShell investigation"
)
# Step 6: Present report to user

Correct Workflow Example (Linux / auditbeat)

Linux hosts ship auditbeat (and optionally Linux-Sysmon) — NOT winlogbeat. Hunt the high-signal Linux index and use osquery for endpoint validation: