Security Detection Rule Management

ElasticOfficialCreated by elastic

Skill
Tool integration
Security
Apache-2.0
Low risk
Has scripts

From the author

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.

— the description by elastic

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to managing Elastic Security detection rules, including SIEM and Endpoint behavior rules. It enables users to identify noisy rules, investigate false positives, and apply tuning strategies such as adding exceptions, patching queries, or adjusting thresholds. The skill utilizes the Kibana Detection Engine API to perform operations, ensuring consistent rule management and coverage maintenance.

What it does

Finds and lists existing detection rules using KQL filters.
Analyzes noisy rules to identify false positive patterns.
Creates new detection rules with custom queries and MITRE ATT&CK mappings.
Patches existing rules to update queries, severity, or risk scores.
Adds scoped exceptions to SIEM and Endpoint behavior rules.
Validates query syntax locally before applying changes to the cluster.

When to use it

When you need to reduce alert fatigue by tuning noisy detection rules.
When you need to create new detection rules for emerging threats or coverage gaps.
When you need to add specific exceptions for known-legitimate processes or users.
When you need to manage rule lifecycle operations like enabling, disabling, or deleting rules via API.

Advantages

Automates repetitive rule management tasks via the Kibana API.
Provides a consistent workflow for investigating and tuning false positives.
Includes validation tools to prevent invalid query syntax in production.
Supports both standard SIEM rules and specialized Endpoint behavior exceptions.

Usage examples

“Find the noisiest detection rules from the last 7 days and help me tune one.”: The agent will list the top noisy rules by alert volume and guide you through investigating the alerts to determine the best tuning strategy.
“Add an exception to exclude SCCM from the suspicious PowerShell rule.”: The agent will identify the rule, verify the exception criteria, and apply the exception to the rule to suppress future false positives.
“Create a new detection rule for certutil URL download or decode.”: The agent will validate the provided query and create a new detection rule with the specified severity, risk score, and MITRE tags.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/elastic/security-detection-rule-management/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip security-detection-rule-management.zip -d .agents/skills

Documentation by elastic

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:

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.
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.
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.
Reduce risk score / severity — Downgrade the rule's priority if it generates many low-value alerts but still has some detection value.
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-exception, bulk-action) prompt for confirmation by default. Pass --yes to skip the prompt (required when called by an agent).

Verify with rule-manager.js get --id <rule_uuid>. Update triage cases via the case-management skill.

Workflow: Create new detection rule

Steps 1–2: Define the threat, data sources, and fields

Specify MITRE ATT&CK technique(s), required data sources (Endpoint, Network, Cloud), and malicious vs legitimate behavior. Common indexes: logs-endpoint.events.process-*, logs-endpoint.events.network-*, .alerts-security.alerts-*, logs-windows.*, logs-aws.*. Key fields: process.name, process.command_line, process.parent.name, destination.ip, winlog.event_id, event.action. Verify data with run-query.js:

node skills/security/alert-triage/scripts/run-query.js "process.name:certutil.exe" --index "logs-endpoint.events.process-*" --days 30 --size 5

Step 3: Write and test the query

Rule types: query (KQL field matching), eql (event sequences), esql (aggregations), threshold (volume-based), threat_match (IOC correlation), new_terms (first-seen). Test against Elasticsearch before creating:

node skills/security/alert-triage/scripts/run-query.js "process.name:certutil.exe AND process.command_line:(*urlcache* OR *decode*)" \
  --index "logs-endpoint.events.process-*" --days 30

For EQL, use --query-file to avoid shell escaping issues.

Validate query syntax before creating or patching a rule. The validate-query command catches common errors locally — escaped backslashes, mismatched parentheses, unbalanced quotes, and duplicate boolean operators:

node skills/security/detection-rule-management/scripts/rule-manager.js validate-query \
  --query "process.name:taskkill.exe AND process.command_line:(*chrome.exe* OR *msedge.exe*)" --language kuery

The create and patch commands also run validation automatically and reject invalid queries. Pass --skip-validation only if you are certain the query is correct despite triggering a check.

Common KQL syntax mistakes:

Escaped forward-slashes — KQL wildcards use plain text. Write */IM chrome.exe*, not *\/IM chrome.exe*.
Mismatched parentheses — every ( must have a matching ).
Unbalanced quotes — every " must be paired.
Duplicate operators — AND AND or OR OR is always an error.

Step 4: Create the rule

node skills/security/detection-rule-management/scripts/rule-manager.js create \
  --name "Certutil URL Download or Decode" \
  --description "Detects certutil.exe used to download files or decode Base64 payloads, a common LOLBin technique." \
  --type query \
  --query "process.name:certutil.exe AND process.command_line:(*urlcache* OR *decode*)" \
  --index "logs-endpoint.events.process-*" \
  --severity medium --risk-score 47 \
  --tags "OS:Windows" "Tactic:Defense Evasion" "Tactic:Command and Control" \
  --false-positives "IT administrators using certutil for legitimate certificate operations" \
  --references "https://attack.mitre.org/techniques/T1140/" \
  --interval 5m --disabled

For complex rules (EQL sequences, MITRE mappings, alert suppression), use create --from-file rule_definition.json and --threat-file. See references/detection-api-reference.md for schema.

Step 5: Monitor and iterate

Monitor alert volume with noisy-rules --days 3 --top 10 and tune false positives as needed.

Workflow: Endpoint behavior rules tuning

Tune Elastic Endpoint behavior rules by adding Endpoint exceptions scoped to specific rules. Endpoint exceptions live in Security → Exceptions → Endpoint Security Exception List, not under individual SIEM rules.

Key principles: Always fetch the rule definition from protections-artifacts first. Always scope exceptions to the rule (rule.id or rule.name). Use full paths over process names. Run the mandatory entity cross-check (Step 4b) before any exception. Simulate impact (Step 5b) and aim for ≥60% noise reduction.

Scripts: fetch-endpoint-rule-from-github.js (get rule TOML by id), add-endpoint-exception.js (add to Endpoint Exception List; rule.id/rule.name required), check-exclusion-best-practices.js.

For the full step-by-step workflow (Steps 1–6), queries, and simulation templates, see references/endpoint-behavior-tuning-workflow.md. For exclusion best practices, see references/endpoint-rule-exclusion-best-practices.md.

Tool reference

rule-manager.js

All commands are run from the workspace root. All output is JSON unless noted.

Command	Description
`find`	Search/list rules with optional KQL filter
`get`	Get a rule by `--id` or `--rule-id`
`create`	Create a rule (inline flags or `--from-file`)
`patch`	Patch specific fields on a rule
`enable`	Enable a rule
`disable`	Disable a rule
`delete`	Delete a rule
`export`	Export rules as NDJSON
`bulk-action`	Bulk enable/disable/delete/duplicate/edit
`add-exception`	Add an exception item to a rule
`list-exceptions`	List items on an exception list
`create-shared-list`	Create a shared exception list
`noisy-rules`	Find noisiest rules by alert volume
`validate-query`	Check query syntax before create/patch

Endpoint behavior tuning: fetch-endpoint-rule-from-github.js (get rule TOML by id), add-endpoint-exception.js (add to Endpoint Exception List; rule.id/rule.name required), check-exclusion-best-practices.js.

Exception entry format

Pass entries as field:operator:value. Operators: is, is_not, is_one_of, is_not_one_of, exists, does_not_exist, matches, does_not_match. Example: process.name:is:svchost.exe, file.path:matches:C:\\Program Files\\*.

Additional resources

For full API schema details, see references/detection-api-reference.md
For endpoint behavior tuning: references/endpoint-exceptions-guide.md, references/endpoint-rule-exclusion-best-practices.md
For alert investigation during tuning, use the alert-triage skill
For documenting tuning actions in cases, use the case-management skill

Examples

"Find the noisiest detection rules from the last 7 days and help me tune one"
"Add an exception to exclude SCCM from the suspicious PowerShell rule"
"Create a new detection rule for certutil URL download or decode"

Guidelines

Report only tool output. When summarizing results, quote or paraphrase only what the tools returned. Do not invent IDs, hostnames, IPs, scores, process trees, or other details not present in the tool response.
Preserve identifiers from the request. If the user provides specific hostnames, agent IDs, case IDs, or other values, use those exact values in tool calls and responses — do not substitute different identifiers.
Confirm actions concisely. After executing a tool, confirm what was done using the tool's return data. Do not fabricate internal IDs, metadata, or status details unless they appear in the tool response.
Distinguish facts from inference. If you draw conclusions beyond what the tools returned (e.g., suggesting a MITRE technique based on observed behavior), clearly label those as your assessment rather than presenting them as tool output.
Start executing tools immediately. Do not read SKILL.md, browse directories, or list files before acting.
Report tool output verbatim. Copy rule IDs, names, alert counts, and error messages exactly as returned. Do not abbreviate UUIDs or round numbers.

Production use

All write operations (create, patch, enable, disable, delete, add-exception, bulk-action, add-endpoint-exception) prompt for confirmation. Pass --yes or -y to skip when called by an agent.
Endpoint exceptions suppress detections globally. Always scope exceptions to a specific rule using rule.id or rule.name in the entries. A broad, unscoped exception can silently reduce detection coverage.
Verify environment variables point to the intended cluster before running any script.
Use --dry-run with bulk-action to preview impact before executing bulk changes.

Environment variables

Variable	Required	Description
`ELASTICSEARCH_URL`	Yes	Elasticsearch URL (for noisy-rules aggregation)
`ELASTICSEARCH_API_KEY`	Yes	Elasticsearch API key
`KIBANA_URL`	Yes	Kibana URL (for rules API)
`KIBANA_API_KEY`	Yes	Kibana API key

Files

ATTRIBUTION.mdAdded by AutoGineer997 B
LICENSELicence file added by AutoGineer11.1 KiB
SKILL.md15.2 KiB
references/detection-api-reference.md7.9 KiB
references/endpoint-behavior-tuning-workflow.md6.3 KiB
references/endpoint-exceptions-guide.md3.8 KiB
references/endpoint-rule-exclusion-best-practices.md6.3 KiB
scripts/add-endpoint-exception.jsScript5.5 KiB
scripts/check-exclusion-best-practices.jsScript2.1 KiB
scripts/es-client.jsScript1.8 KiB
scripts/fetch-endpoint-rule-from-github.jsScript3.8 KiB
scripts/kibana-client.jsScript6.7 KiB
scripts/rule-manager.jsScript21.1 KiB

scripts/add-endpoint-exception.js

#!/usr/bin/env node
/**
 * Add an exception item to the Endpoint Security Exception List.
 *
 * Endpoint exceptions are stored in the Endpoint Security Exception List
 * (Security → Exceptions → Endpoint Security Exception List, /app/security/exceptions).
 * They are separate from SIEM/detection rule exceptions. This script uses
 * POST /api/endpoint_list/items to add an item directly to that list.
 *
 * See: https://www.elastic.co/docs/solutions/security/detect-and-alert/add-manage-exceptions#endpoint-rule-exceptions
 * API: https://www.elastic.co/docs/api/doc/kibana/operation/operation-createexceptionlistitem
 */

import { kibanaPost, kibanaDelete as kibanaDeleteReq } from "./kibana-client.js";
import { createInterface } from "readline";

const ENDPOINT_LIST_ITEMS_API = "/api/endpoint_list/items";

function promptConfirm(message) {
  const rl = createInterface({ input: process.stdin, output: process.stderr });
  return new Promise((resolve) => {
    rl.question(`${message} [y/N] `, (answer) => {
      rl.close();
      resolve(answer.trim().toLowerCase() === "y");
    });
  });
}

const OP_MAP = {
  is: ["match", "included"],
  is_not: ["match", "excluded"],
  is_one_of: ["match_any", "included"],
  is_not_one_of: ["match_any", "excluded"],
  exists: ["exists", "included"],
  does_not_exist: ["exists", "excluded"],
  matches: ["wildcard", "included"],
  does_not_match: ["wildcard", "excluded"],
};

function parseEntry(entryStr) {
  const parts = entryStr.split(":");
  let field, operator, value;

  if (parts.length >= 3) {
    field = parts[0];
    operator = parts[1];
    value = parts.slice(2).join(":");
  } else if (parts.length === 2) {
    [field, value] = parts;
    operator = "is";
  } else {
    throw new Error(`Invalid entry format '${entryStr}'. Use field:operator:value or field:value`);
  }

  const mapped = OP_MAP[operator];
  if (!mapped) {
    throw new Error(`Unknown operator '${operator}'. Use: ${Object.keys(OP_MAP).join(", ")}`);
  }

  const [entryType, listOperator] = mapped;
  const entry = { field, type: entryType, operator: listOperator };
  if (entryType === "match") entry.value = value;
  else if (entryType === "match_any") entry.value = value.split(",").map((v) => v.trim());
  else if (entryType === "wildcard") entry.value = value;
  return entry;
}

function makeItemId(name) {
  const slug = name
    .toLowerCase()
    .replace(/[^\w-]/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, 40);
  const rand = crypto.randomUUID().slice(0, 8);
  return slug ? `${slug}-${rand}` : `endpoint-exception-${rand}`;
}

function parseArgs(argv) {
  const result = {};
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === "-y") {
      result.yes = true;
    } else if (arg.startsWith("--")) {
      const key = arg.slice(2).replace(/-/g, "_");
      const values = [];
      let j = i + 1;
      while (j < argv.length && !argv[j].startsWith("--") && argv[j] !== "-y") {
        values.push(argv[j]);
        j++;
      }
      result[key] = values.length === 0 ? true : values.length === 1 ? values[0] : values;
      i = j - 1;
    }
  }
  return result;
}

async function main() {
  const args = parseArgs(process.argv.slice(2));
  const yes = args.yes === true;

  if (args.delete) {
    if (!args.item_id && !args.id) {
      console.error("Error: provide --item-id or --id to delete");
      process.exit(1);
    }
    if (!yes) {
      const ok = await promptConfirm(`Delete endpoint exception ${args.item_id || args.id}? This cannot be undone.`);
      if (!ok) {
        console.log("Aborted.");
        process.exit(0);
      }
    }
    const qs = args.item_id ? `?item_id=${args.item_id}` : `?id=${args.id}`;
    const result = await kibanaDeleteReq(`${ENDPOINT_LIST_ITEMS_API}${qs}`, args.space);
    console.log(JSON.stringify(result, null, 2));
    return;
  }

  if (!args.name || !args.entries) {
    console.error("Error: --name and --entries are required when adding an exception");
    console.error("");
    console.error('Usage: node add-endpoint-exception.js --name "Exception name" --entries field:operator:value ...');
    console.error("");
    console.error("IMPORTANT: To limit the exception to a specific rule, always include rule.id or rule.name");
    console.error("as one of the entries: rule.id:is:<uuid> or rule.name:is:<exact rule name>.");
    console.error("");
    console.error("Operators: is, is_not, is_one_of, is_not_one_of, matches, does_not_match, exists, does_not_exist");
    process.exit(1);
  }

  const entryStrs = Array.isArray(args.entries) ? args.entries : [args.entries];
  const parsed = entryStrs.map(parseEntry);

  let desc = args.description || "";
  if (args.comment) {
    desc = desc ? `${desc}\nComment: ${args.comment}` : args.comment;
  }

  const item = {
    name: args.name,
    item_id: args.item_id || makeItemId(args.name),
    description: desc,
    type: "simple",
    entries: parsed,
    namespace_type: "agnostic",
    list_id: "endpoint_list",
  };

  if (args.tags) {
    item.tags = Array.isArray(args.tags) ? args.tags : [args.tags];
  }
  if (args.os_types) {
    const types = Array.isArray(args.os_types) ? args.os_types : [args.os_types];
    item.os_types = types.map((t) => t.trim().toLowerCase());
  }

  if (!yes) {
    const ok = await promptConfirm(`Add endpoint exception "${args.name}"?`);
    if (!ok) {
      console.log("Aborted.");
      process.exit(0);
    }
  }

  const result = await kibanaPost(ENDPOINT_LIST_ITEMS_API, item, args.space);
  console.log(JSON.stringify(result, null, 2));
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Node.js

The author says: 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.

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

elastic

Publisher

Elastic (Official)

Source

elastic/agent-skills · skills/security/detection-rule-management · commit 09d879d

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

Also distributed in

elastic/agent-skills

AutoGineer is not affiliated with or endorsed by elastic or Elastic.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download security-detection-rule-management.zip