/detection-rule-management

name: security-detection-rule-management
description: >
  Create, tune, and manage Elastic Security detection rules (SIEM and Endpoint). Use
  for false positives, exceptions, new coverage, noisy rules, or rule management via
  Kibana API.
compatibility: >
  Requires Node.js 22+, network access to Kibana and Elasticsearch. Environment variables:
  KIBANA_URL plus KIBANA_API_KEY or KIBANA_USERNAME/KIBANA_PASSWORD; ELASTICSEARCH_URL
  or ELASTICSEARCH_CLOUD_ID plus ELASTICSEARCH_API_KEY or ELASTICSEARCH_USERNAME/ELASTICSEARCH_PASSWORD.
metadata:
  author: elastic
  version: 0.1.0

Detection Rule Management

Create new detection rules for emerging threats and coverage gaps, and tune existing rules to reduce false positives. All operations use the Kibana Detection Engine API via `rule-manager.js`.

Execution rules

• Start executing tools immediately — do not read SKILL.md, browse the workspace, or list files first.
• Report tool output faithfully. Copy rule IDs, names, alert counts, exception IDs, and error messages exactly as

returned by the API. Do not abbreviate rule UUIDs, invent rule names, or round alert counts.

• When a tool returns an error (rule not found, API failure), report the exact error — do not guess at alternatives.

Prerequisites

Install dependencies before first use from the `skills/security` directory:

cd skills/security && npm install

Set the required environment variables (or add them to a `.env` file in the workspace root):

export ELASTICSEARCH_URL="https://your-cluster.es.cloud.example.com:443"
export ELASTICSEARCH_API_KEY="your-api-key"
export KIBANA_URL="https://your-cluster.kb.cloud.example.com:443"
export KIBANA_API_KEY="your-kibana-api-key"

Common multi-step workflows

| Task | Tools to call (in order) | | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | | **Tune noisy SIEM rule** | `rule_manager` find/noisy-rules → `run_query` (investigate FPs) → `rule_manager` patch or add-exception | | **Add endpoint behavior exception** | `fetch_endpoint_rule` (get rule definition from GitHub) → `add_endpoint_exception` (scoped to rule.id) | | **Create new detection rule** | `run_query` (test query against data) → `rule_manager` create | | **Investigate rule alert volume** | `rule_manager` get → `run_query` (query alerts index) |

For endpoint behavior rules, always fetch the rule definition first to understand query logic and existing exclusions before adding an exception. For SIEM rules, always investigate alert patterns with `run_query` before tuning.

**Critical:** For endpoint behavior rules, always use `fetch_endpoint_rule` (not `shell` or direct script calls) to get the rule definition, then use `add_endpoint_exception` to add the exception. These are dedicated tools — do not invoke the underlying scripts manually.

Workflow: Tune a rule for false positives

Steps 1–2: Identify noisy rules and analyze false positives

Find noisy rules with `noisy-rules` or `find`, then get the rule definition and investigate alerts:

node skills/security/detection-rule-management/scripts/rule-manager.js noisy-rules --days 7 --top 20
node skills/security/detection-rule-management/scripts/rule-manager.js find --filter "alert.attributes.name:*Suspicious*" --brief
node skills/security/detection-rule-management/scripts/rule-manager.js get --id <rule_uuid>
node skills/security/alert-triage/scripts/run-query.js "kibana.alert.rule.name:\"<rule_name>\"" --index ".alerts-security.alerts-*" --days 7 --full

Look for patterns: same process/user/host → exception candidate; broad pattern → tighten query; legitimate software → exception; too broad → rewrite or adjust threshold.

Step 3: Choose a tuning strategy

**In order of preference:**

1. **Add exception** — Best for specific known-good processes, users, or hosts. Does not modify the rule query. Use when the rule is correct in general but fires on known-legitimate activity.

2. **Tighten the query** — Patch the rule's query to exclude the FP pattern. Best when the false positives stem from the query being too broad.

3. **Adjust threshold / alert suppression** — For threshold rules, increase the threshold value. For any rule type, enable alert suppression to reduce duplicate alerts on the same entity.

4. **Reduce risk score / severity** — Downgrade the rule's priority if it generates many low-value alerts but still has some detection value.

5. **Disable the rule** — Last resort. Only if the rule provides no value or is completely redundant with another rule.

Steps 4–5: Apply tuning, verify, and document

**Add exception** (single/multi-condition, wildcard via `matches`):

node skills/security/detection-rule-management/scripts/rule-manager.js add-exception \
  --rule-uuid <rule_uuid> \
  --entries "process.executable:is:C:\\Program Files\\SCCM\\CcmExec.exe" "process.parent.name:is:CcmExec.exe" \
  --name "Exclude SCCM" --comment "FP: SCCM deployment" --tags "tuning:fp" "source:soc" --yes

**Patch query, threshold, severity, or disable:**

node skills/security/detection-rule-management/scripts/rule-manager.js patch --id <rule_uuid> --query "process.name:powershell.exe AND NOT process.parent.name:CcmExec.exe" --yes
node skills/security/detection-rule-management/scripts/rule-manager.js patch --id <rule_uuid> --max-signals 50 --yes
node skills/security/detection-rule-management/scripts/rule-manager.js patch --id <rule_uuid> --severity low --risk-score 21 --yes
node skills/security/detection-rule-management/scripts/rule-manager.js disable --id <rule_uuid> --yes

Write operations (`patch`, `enable`, `disable`, `delete`, `add-e