security-detection-rule-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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
.
针对新型威胁和检测覆盖缺口创建新的检测规则,同时调优现有规则以减少误报。 所有操作均通过
rule-manager.js
调用Kibana检测引擎API完成。

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.
  • 立即执行工具操作——不要先阅读SKILL.md、浏览工作区或列出文件。
  • 如实报告工具输出。完全按照API返回的内容复制规则ID、名称、警报数量、例外ID和错误信息。不要缩写规则UUID、虚构规则名称或四舍五入警报计数。
  • 当工具返回错误(规则未找到、API调用失败)时,报告确切的错误信息——不要猜测替代方案。

Prerequisites

前置条件

Install dependencies before first use from the
skills/security
directory:
bash
cd skills/security && npm install
Set the required environment variables (or add them to a
.env
file in the workspace root):
bash
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"
首次使用前,从
skills/security
目录安装依赖:
bash
cd skills/security && npm install
设置必要的环境变量(或添加到工作区根目录的
.env
文件中):
bash
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

常见多步骤工作流

TaskTools 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.
任务调用工具(按顺序)
调优高噪音SIEM规则
rule_manager
find/noisy-rules →
run_query
(调查误报)→
rule_manager
patch或add-exception
添加终端行为例外
fetch_endpoint_rule
(从GitHub获取规则定义)→
add_endpoint_exception
(按rule.id范围设置)
创建新检测规则
run_query
(针对数据测试查询语句)→
rule_manager
create
调查规则警报量
rule_manager
get →
run_query
(查询警报索引)
对于终端行为规则,在添加例外之前,务必先获取规则定义以了解查询逻辑和现有排除项。对于SIEM规则,在调优之前务必使用
run_query
调查警报模式。
关键注意事项: 对于终端行为规则,务必使用
fetch_endpoint_rule
(而非
shell
或直接调用脚本)获取规则定义,然后使用
add_endpoint_exception
添加例外。这些是专用工具——不要手动调用底层脚本。

Workflow: Tune a rule for false positives

工作流:调优规则以处理误报

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

步骤1–2:识别高噪音规则并分析误报

Find noisy rules with
noisy-rules
or
find
, then get the rule definition and investigate alerts:
bash
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.
使用
noisy-rules
find
查找高噪音规则,然后获取规则定义并调查警报:
bash
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
寻找模式:相同进程/用户/主机→例外候选;宽泛模式→收紧查询;合法软件→添加例外;过于宽泛→重写或调整阈值。

Step 3: Choose a tuning strategy

步骤3:选择调优策略

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.
优先顺序:
  1. 添加例外 — 最适合特定已知合法的进程、用户或主机。不会修改规则查询。适用于规则整体正确,但会对已知合法活动触发警报的场景。
  2. 收紧查询 — 修改规则的查询语句以排除误报模式。最适合误报源于查询范围过宽的场景。
  3. 调整阈值/警报抑制 — 对于阈值规则,提高阈值数值。对于任何规则类型,启用警报抑制以减少同一实体的重复警报。
  4. 降低风险评分/严重级别 — 如果规则生成大量低价值警报但仍有一定检测价值,降低规则的优先级。
  5. 禁用规则 — 最后手段。仅当规则无任何价值或与其他规则完全冗余时使用。

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

步骤4–5:应用调优、验证并记录

Add exception (single/multi-condition, wildcard via
matches
):
bash
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:
bash
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.

添加例外(单/多条件,通过
matches
使用通配符):
bash
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
修改查询、阈值、严重级别或禁用规则:
bash
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
写入操作(
patch
enable
disable
delete
add-exception
bulk-action
)默认会提示确认。通过
--yes
参数跳过确认(由agent调用时必填)。
使用
rule-manager.js get --id <rule_uuid>
验证。通过
case-management
技能更新分类案例。

Workflow: Create new detection rule

工作流:创建新检测规则

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

步骤1–2:定义威胁、数据源和字段

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
:
bash
node skills/security/alert-triage/scripts/run-query.js "process.name:certutil.exe" --index "logs-endpoint.events.process-*" --days 30 --size 5
指定MITRE ATT&CK技术、所需数据源(终端、网络、云)以及恶意与合法行为。常见索引:
logs-endpoint.events.process-*
logs-endpoint.events.network-*
.alerts-security.alerts-*
logs-windows.*
logs-aws.*
。关键字段:
process.name
process.command_line
process.parent.name
destination.ip
winlog.event_id
event.action
。使用
run-query.js
验证数据:
bash
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

步骤3:编写并测试查询

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:
bash
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:
bash
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.
规则类型:
query
(KQL字段匹配)、
eql
(事件序列)、
esql
(聚合)、
threshold
(基于数量)、
threat_match
(IOC关联)、
new_terms
(首次出现)。创建前先在Elasticsearch中测试:
bash
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
对于EQL,使用
--query-file
避免shell转义问题。
创建或修改规则前验证查询语法。
validate-query
命令可在本地捕获常见错误——转义反斜杠、不匹配的括号、不平衡的引号以及重复的布尔运算符:
bash
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
create
patch
命令也会自动运行验证并拒绝无效查询。仅当你确定查询正确但触发检查时,才使用
--skip-validation
常见KQL语法错误:
  • 转义正斜杠 — KQL通配符使用纯文本。应写
    */IM chrome.exe*
    ,而非
    *\/IM chrome.exe*
  • 括号不匹配 — 每个
    (
    必须有对应的
    )
  • 引号不平衡 — 每个
    "
    必须成对出现。
  • 重复运算符
    AND AND
    OR OR
    始终是错误。

Step 4: Create the rule

步骤4:创建规则

bash
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.
bash
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
对于复杂规则(EQL序列、MITRE映射、警报抑制),使用
create --from-file rule_definition.json
--threat-file
。架构详情请见references/detection-api-reference.md

Step 5: Monitor and iterate

步骤5:监控与迭代

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

使用
noisy-rules --days 3 --top 10
监控警报量,并根据需要调优误报。

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.

通过添加针对特定规则的终端例外来调优Elastic终端行为规则。终端例外存储在安全→例外→终端安全例外列表中,而非单个SIEM规则下。
核心原则: 始终先从protections-artifacts获取规则定义。始终将例外范围限定到规则(
rule.id
rule.name
)。使用完整路径而非进程名称。在添加任何例外前运行强制的实体交叉检查(步骤4b)。模拟影响(步骤5b)并目标实现≥60%的噪音减少。
脚本:
fetch-endpoint-rule-from-github.js
(通过ID获取规则TOML)、
add-endpoint-exception.js
(添加到终端例外列表;需指定rule.id/rule.name)、
check-exclusion-best-practices.js
完整的分步工作流(步骤1–6)、查询和模拟模板,请见references/endpoint-behavior-tuning-workflow.md。例外最佳实践请见references/endpoint-rule-exclusion-best-practices.md

Tool reference

工具参考

rule-manager.js

rule-manager.js

All commands are run from the workspace root. All output is JSON unless noted.
CommandDescription
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
.
所有命令均从工作区根目录运行。所有输出默认为JSON格式,除非另有说明。
命令描述
find
使用可选KQL过滤器搜索/列出规则
get
通过
--id
--rule-id
获取规则详情
create
创建规则(通过内联参数或
--from-file
patch
修改规则的特定字段
enable
启用规则
disable
禁用规则
delete
删除规则
export
将规则导出为NDJSON格式
bulk-action
批量启用/禁用/删除/复制/编辑规则
add-exception
为规则添加例外项
list-exceptions
列出例外列表中的项
create-shared-list
创建共享例外列表
noisy-rules
根据警报量查找高噪音规则
validate-query
在创建/修改规则前检查查询语法
终端行为调优:
fetch-endpoint-rule-from-github.js
(通过ID获取规则TOML)、
add-endpoint-exception.js
(添加到终端例外列表;需指定rule.id/rule.name)、
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\\*
.
field:operator:value
格式传递例外项。运算符包括:
is
is_not
is_one_of
is_not_one_of
exists
does_not_exist
matches
does_not_match
。示例:
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
  • API架构详情请见references/detection-api-reference.md
  • 终端行为调优相关:references/endpoint-exceptions-guide.mdreferences/endpoint-rule-exclusion-best-practices.md
  • 调优期间的警报调查,请使用
    alert-triage
    技能
  • 在案例中记录调优操作,请使用
    case-management
    技能

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"
  • "查找过去7天内噪音最高的检测规则,并帮我调优其中一个"
  • "添加例外以将SCCM排除在可疑PowerShell规则之外"
  • "创建一个针对certutil URL下载或解码的新检测规则"

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.
  • 仅报告工具输出。总结结果时,仅引用或转述工具返回的内容。不要虚构ID、主机名、IP、评分、进程树或工具响应中未包含的其他细节。
  • 保留请求中的标识符。如果用户提供了特定的主机名、agent ID、案例ID或其他值,在工具调用和响应中使用这些确切值——不要替换为其他标识符。
  • 简洁确认操作。执行工具后,使用工具返回的数据确认已完成的操作。除非工具响应中包含,否则不要编造内部ID、元数据或状态详情。
  • 区分事实与推论。如果得出超出工具返回内容的结论(例如,根据观察到的行为建议MITRE技术),请明确标记为你的评估,而非作为工具输出呈现。
  • 立即执行工具操作。不要先阅读SKILL.md、浏览目录或列出文件再行动。
  • 如实报告工具输出。完全按照返回内容复制规则ID、名称、警报数量和错误信息。不要缩写UUID或四舍五入数值。

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.
  • 所有写入操作(
    create
    patch
    enable
    disable
    delete
    add-exception
    bulk-action
    add-endpoint-exception
    )都会提示确认。由agent调用时,传递
    --yes
    -y
    跳过确认。
  • 终端例外会全局抑制检测。始终在例外项中使用
    rule.id
    rule.name
    将例外范围限定到特定规则。宽泛的无范围例外可能会悄无声息地降低检测覆盖范围。
  • 运行任何脚本前,验证环境变量指向目标集群。
  • 使用
    bulk-action
    时搭配
    --dry-run
    ,在执行批量更改前预览影响。

Environment variables

环境变量

VariableRequiredDescription
ELASTICSEARCH_URL
YesElasticsearch URL (for noisy-rules aggregation)
ELASTICSEARCH_API_KEY
YesElasticsearch API key
KIBANA_URL
YesKibana URL (for rules API)
KIBANA_API_KEY
YesKibana API key
变量是否必填描述
ELASTICSEARCH_URL
Elasticsearch URL(用于高噪音规则聚合)
ELASTICSEARCH_API_KEY
Elasticsearch API密钥
KIBANA_URL
Kibana URL(用于规则API)
KIBANA_API_KEY
Kibana API密钥