elk-security-hunting

ELK Security Hunting Skill

Core skill for the ELK mode of /hunt. Provides Python helpers and API patterns for hunting directly against a live Elastic Security (SIEM) stack — no evidence ingestion required.

Environment

Read from ~/.claude/.env:

KIBANA_URL=https://your-kibana:5601
KIBANA_API_KEY=your_base64_encoded_api_key   # Authorization: ApiKey <key>
KIBANA_SPACE=default                          # Kibana space ID
HUNT_CYCLE_HOURS=8                            # Continuous mode cycle interval

Auth: API Key only (Authorization: ApiKey <base64_key>). No basic auth.

API Domains Overview

Domain	Base Path	Purpose
Detection Rules	/api/detection_engine/rules	CRUD for EQL/KQL/ES|QL/threshold/ML rules
Alerts/Signals	/api/detection_engine/signals	Search, triage, tag open alerts
Cases	/api/cases	Investigation case lifecycle
Timelines	/api/timeline	Attack timeline construction

Rules

1. kbn-xsrf: true header required on every mutating request
2. version field required for all updates (optimistic locking — prevents overwrites)
3. Space-aware URLs: /s/{space}/api/... when KIBANA_SPACE != default
4. Rate limit: max 10 concurrent Kibana calls (avoid 429s)
5. Alert index: .alerts-security.alerts-* (not logs-*)
6. Content-Type: application/json on all requests
7. Elastic 9.x dataset migration: windows.security does NOT exist in the Windows integration package. Security event logs are in the system package as system.security. use system integration for Security/Application/System event channels.
8. Bulk rule enable batching: avoid enable >20 detection rules in a single API call. The Fleet API returns 400/413 for large payloads. batch into groups of ≤20 rule IDs per PATCH/PUT request.

Scripts Reference

Script	Purpose	Run
scripts/kibana_client.py	Base HTTP client: auth, headers, space URLs, retry	uv run
scripts/alert_triage.py	Search alerts, TP/FP classify, batch status update	uv run
scripts/rule_manager.py	Rule CRUD, preview, bulk actions, MITRE mapping	uv run
scripts/case_manager.py	Case CRUD, comments, alert attachment	uv run
scripts/timeline_manager.py	Create timelines, add notes, pin events	uv run

All scripts load env from ~/.claude/.env via python-dotenv.

Quick Usage

# List open alerts grouped by rule
uv run ${CLAUDE_PLUGIN_ROOT}/skills/elk-security-hunting/scripts/alert_triage.py list

# Triage alerts for a specific rule ID
uv run ${CLAUDE_PLUGIN_ROOT}/skills/elk-security-hunting/scripts/alert_triage.py triage --rule-id <id>

# List detection rules
uv run ${CLAUDE_PLUGIN_ROOT}/skills/elk-security-hunting/scripts/rule_manager.py list

# Create a new EQL rule from file
uv run ${CLAUDE_PLUGIN_ROOT}/skills/elk-security-hunting/scripts/rule_manager.py create --file rule.json

# List open cases
uv run ${CLAUDE_PLUGIN_ROOT}/skills/elk-security-hunting/scripts/case_manager.py list

# Create a timeline
uv run ${CLAUDE_PLUGIN_ROOT}/skills/elk-security-hunting/scripts/timeline_manager.py create --title "Hunt Timeline"

Core Principles

1. Check data freshness — stale indices produce false negatives that look like clean hunts.
2. Hunt with a hypothesis — undirected queries burn time and rarely converge.
3. Correlate across data sources — endpoint + network + auth logs together distinguish noise from intrusion.
4. Honor field mappings — wrong field types silently break aggregations.
5. Save successful queries — the detection rules that graduate to production come from saved hunt queries.

Reference

For linked skills, ELK mode details, and full API endpoint reference, see reference.md.