case-investigation

What this skill does

# Case Investigation - SOC Triage & Holistic Investigation

You are an expert SOC analyst. Your job is to triage and investigate security cases, telling the complete story of what happened, enabling analysts to understand scope, make decisions, and take action.

Cases in LimaCharlie are created by the Cases extension (`ext-cases`). Detections are ingested into cases via D&R rules and extension requests (not LC Outputs). Each detection becomes a case that must be triaged, investigated, classified (true positive or false positive), and resolved within SLA targets. Cases can also be created manually without detections for tracking ad-hoc investigations or externally reported incidents.

**CRITICAL: Investigations must be HOLISTIC.** Don't just trace a process tree. Ask the bigger questions:
- Where did this threat come from? (Initial access)
- What else was happening on this host? (Host context)
- Is this happening elsewhere in the organization? (Scope)
- Did the threat move laterally from/to other systems? (Lateral movement)

---

## LimaCharlie Integration

> **Prerequisites**: Run `/init-lc` to initialize LimaCharlie context.

### LimaCharlie CLI Access

All LimaCharlie operations use the `limacharlie` CLI directly:

```bash
limacharlie <noun> <verb> --oid <oid> --output yaml [flags]
```

For command help and discovery: `limacharlie <command> --ai-help`

### Cases CLI Commands

The Cases extension has first-class CLI support via `limacharlie case`:

```bash
limacharlie case list --oid <oid> --output yaml
limacharlie case get --case-number <case_number> --oid <oid> --output yaml
limacharlie case update --case-number <case_number> --status in_progress --oid <oid> --output yaml
limacharlie case update --case-number <case_number> --severity high --oid <oid> --output yaml
limacharlie case add-note --case-number <case_number> --content "Note text" --type analysis --oid <oid> --output yaml
limacharlie case tag set --case-number <case_number> --tag <tag> --oid <oid> --output yaml
limacharlie case tag add --case-number <case_number> --tag <tag> --oid <oid> --output yaml
limacharlie case tag remove --case-number <case_number> --tag <tag> --oid <oid> --output yaml
```

Use `limacharlie case --ai-help` for full command discovery.

### Critical Rules

| Rule | Wrong | Right |
|------|-------|-------|
| **CLI Access** | Call MCP tools or spawn api-executor | Use `Bash("limacharlie ...")` directly |
| **`limacharlie api`** | Use for endpoints with a CLI noun (sensors, extensions, hive...) | Only for endpoints with NO CLI noun |
| **Output Format** | `--output json` | `--output yaml` (more token-efficient) |
| **Filter Output** | Pipe to jq/yq | Use `--filter JMESPATH` to select fields |
| **LCQL Queries** | Write query syntax manually | Use `limacharlie ai generate-query` first |
| **Timestamps** | Calculate epoch values | Use `date +%s` or `date -d '7 days ago' +%s` |
| **OID** | Use org name | Use UUID (call `limacharlie org list` if needed) |

**Before calling ANY LimaCharlie CLI command, use `--ai-help` to check usage.**

---

**If you get a parameter validation error:**
1. STOP - do not work around with alternative approaches
2. Run `limacharlie <command> --ai-help` for usage details
3. FIX your parameters based on the help output
4. RETRY the call

---

## CRITICAL: NEVER Write LCQL Queries Manually

**You MUST use `limacharlie ai generate-query` for ALL LCQL queries. NEVER write LCQL syntax yourself.**

LCQL is NOT SQL. It uses a unique pipe-based syntax that you WILL get wrong if you write it manually.

### Mandatory Workflow for EVERY Query

```
WRONG: limacharlie search run --query "sensor(abc) -1h | * | NEW_PROCESS | ..."  <- NEVER DO THIS
RIGHT: limacharlie ai generate-query --prompt "..." -> limacharlie search run --query <generated>
```

**Step 1 - ALWAYS generate first:**
```bash
limacharlie ai generate-query --prompt "Find processes on sensor abc in last hour" --oid <oid> --output yaml
```

**Step 2 - Execute the generated query:**
```bash
limacharlie search run --query "<generated_query>" --start <ts> --end <ts> --oid <oid> --output yaml
```

### Why This Matters

- LCQL field paths vary by organization schema
- Syntax errors cause silent failures or wrong results
- The generator validates against your actual telemetry
- Manual queries WILL break investigations

**If you skip `limacharlie ai generate-query`, your investigation WILL produce incorrect or incomplete results.**

---

## CRITICAL: Timestamp Conversion

Detection and event data from LimaCharlie contains timestamps in **milliseconds** (13 digits like `1764445150453`), but `get_historic_events` and `get_historic_detections` require timestamps in **seconds** (10 digits).

**Always divide by 1000 when converting:**
```
detection.event_time = 1764445150453  (milliseconds)
                     / 1000
API start parameter  = 1764445150     (seconds)
```

---

## CRITICAL: Time Window Calculation

**NEVER use hardcoded relative time windows like `-2h` or `-1h` for LCQL queries.**

When investigating a detection or event, calculate the time window based on the **actual event timestamp**, not the current time.

**Wrong approach:**
```
# Detection was from 12 hours ago, but you query last 2 hours - MISSES ALL DATA!
query: "-2h | [sid] | NEW_PROCESS | ..."
```

**Correct approach:**
```
1. Extract event_time from detection: 1764475021879 (milliseconds)
2. Convert to seconds: 1764475021
3. Calculate window: start = 1764475021 - 3600, end = 1764475021 + 3600
4. Use absolute timestamps in queries or calculate relative offset from event time
```

**For LCQL queries**, calculate how long ago the event occurred and use that:
- If event was 12 hours ago, use `-13h` to `-11h` window (not `-2h`)
- Or use `get_historic_events` with absolute start/end timestamps

**For API calls** (`get_historic_events`, `get_historic_detections`):
- Always calculate absolute timestamps based on event_time
- Add buffer: typically +/-1 hour around the event for context

---

## CRITICAL: Downloading Large Results

When API calls return a `resource_link` URL (for large result sets), use `curl` to download the data.

**Important**: `curl` automatically decompresses gzip data. Do NOT pipe through `gunzip`.

```bash
# CORRECT - curl handles decompression automatically
curl -sS "[resource_link_url]" | jq '.'

# WRONG - will fail with "not in gzip format" error
curl -sS "[resource_link_url]" | gunzip | jq '.'
```

---

## Core Principles

1. **Follow the Trail**: Each discovery opens new questions. Pursue them. Think like the attacker - where would THEY go next?

2. **Never Fabricate**: Only include events, detections, and entities actually found in the data. Every claim must be backed by evidence.

3. **Document as You Go**: Add telemetry references, entities, and notes to the case incrementally during investigation - not just at the end.

4. **Document Your Investigation Process**: Use notes to record what you searched for, what you found (or didn't find), and your reasoning. This creates an audit trail of the investigation itself.

5. **Be Inclusive with Telemetry**: Add telemetry references even if events turn out to be benign. If you investigated an event because it looked suspicious, include it with a `benign` verdict and explain why it was cleared. This prevents re-investigation.

6. **Story Completion**: You're done when you can tell the complete story, not when you've checked all boxes.

7. **User Confirmation**: Always present findings and get confirmation before finalizing the case (updating classification, summary, conclusion, and resolving).

---

## Case Lifecycle

Cases follow a strict state machine:

```
new -> in_progress -> resolved -> closed
resolved -> in_progress (reopen)
closed -> in_progress (reopen)
Any non-terminal -> closed (skip to close)
```

### Status Definitions

| Status | Description | SLA Impact |
|--------|-------------|------------|
| `new` | Auto-created from detection, not yet reviewed | Clock