security-detection-rule-management
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDetection 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针对新型威胁和检测覆盖缺口创建新的检测规则,同时调优现有规则以减少误报。
所有操作均通过调用Kibana检测引擎API完成。
rule-manager.jsExecution 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 directory:
skills/securitybash
cd skills/security && npm installSet the required environment variables (or add them to a file in the workspace root):
.envbash
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/securitybash
cd skills/security && npm install设置必要的环境变量(或添加到工作区根目录的文件中):
.envbash
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 | |
| Add endpoint behavior exception | |
| Create new detection rule | |
| Investigate rule alert volume | |
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 before tuning.
run_queryCritical: For endpoint behavior rules, always use (not or direct script calls) to get
the rule definition, then use to add the exception. These are dedicated tools — do not invoke
the underlying scripts manually.
fetch_endpoint_ruleshelladd_endpoint_exception| 任务 | 调用工具(按顺序) |
|---|---|
| 调优高噪音SIEM规则 | |
| 添加终端行为例外 | |
| 创建新检测规则 | |
| 调查规则警报量 | |
对于终端行为规则,在添加例外之前,务必先获取规则定义以了解查询逻辑和现有排除项。对于SIEM规则,在调优之前务必使用调查警报模式。
run_query关键注意事项: 对于终端行为规则,务必使用(而非或直接调用脚本)获取规则定义,然后使用添加例外。这些是专用工具——不要手动调用底层脚本。
fetch_endpoint_ruleshelladd_endpoint_exceptionWorkflow: Tune a rule for false positives
工作流:调优规则以处理误报
Steps 1–2: Identify noisy rules and analyze false positives
步骤1–2:识别高噪音规则并分析误报
Find noisy rules with or , then get the rule definition and investigate alerts:
noisy-rulesfindbash
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 --fullLook for patterns: same process/user/host → exception candidate; broad pattern → tighten query; legitimate software →
exception; too broad → rewrite or adjust threshold.
使用或查找高噪音规则,然后获取规则定义并调查警报:
noisy-rulesfindbash
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:
-
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
步骤4–5:应用调优、验证并记录
Add exception (single/multi-condition, wildcard via ):
matchesbash
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" --yesPatch 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> --yesWrite operations (, , , , , ) prompt for confirmation by
default. Pass to skip the prompt (required when called by an agent).
patchenabledisabledeleteadd-exceptionbulk-action--yesVerify with . Update triage cases via the skill.
rule-manager.js get --id <rule_uuid>case-management添加例外(单/多条件,通过使用通配符):
matchesbash
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写入操作(、、、、、)默认会提示确认。通过参数跳过确认(由agent调用时必填)。
patchenabledisabledeleteadd-exceptionbulk-action--yes使用验证。通过技能更新分类案例。
rule-manager.js get --id <rule_uuid>case-managementWorkflow: 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: , ,
, , . Key fields: , ,
, , , . Verify data with :
logs-endpoint.events.process-*logs-endpoint.events.network-*.alerts-security.alerts-*logs-windows.*logs-aws.*process.nameprocess.command_lineprocess.parent.namedestination.ipwinlog.event_idevent.actionrun-query.jsbash
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.nameprocess.command_lineprocess.parent.namedestination.ipwinlog.event_idevent.actionrun-query.jsbash
node skills/security/alert-triage/scripts/run-query.js "process.name:certutil.exe" --index "logs-endpoint.events.process-*" --days 30 --size 5Step 3: Write and test the query
步骤3:编写并测试查询
Rule types: (KQL field matching), (event sequences), (aggregations), (volume-based),
(IOC correlation), (first-seen). Test against Elasticsearch before creating:
queryeqlesqlthresholdthreat_matchnew_termsbash
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 30For EQL, use to avoid shell escaping issues.
--query-fileValidate query syntax before creating or patching a rule. The command catches common errors locally
— escaped backslashes, mismatched parentheses, unbalanced quotes, and duplicate boolean operators:
validate-querybash
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 kueryThe and commands also run validation automatically and reject invalid queries. Pass
only if you are certain the query is correct despite triggering a check.
createpatch--skip-validationCommon KQL syntax mistakes:
- Escaped forward-slashes — KQL wildcards use plain text. Write , not
*/IM chrome.exe*.*\/IM chrome.exe* - Mismatched parentheses — every must have a matching
(.) - Unbalanced quotes — every must be paired.
" - Duplicate operators — or
AND ANDis always an error.OR OR
规则类型:(KQL字段匹配)、(事件序列)、(聚合)、(基于数量)、(IOC关联)、(首次出现)。创建前先在Elasticsearch中测试:
queryeqlesqlthresholdthreat_matchnew_termsbash
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,使用避免shell转义问题。
--query-file创建或修改规则前验证查询语法。 命令可在本地捕获常见错误——转义反斜杠、不匹配的括号、不平衡的引号以及重复的布尔运算符:
validate-querybash
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 kuerycreatepatch--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 --disabledFor complex rules (EQL sequences, MITRE mappings, alert suppression), use and
. See references/detection-api-reference.md for schema.
create --from-file rule_definition.json--threat-filebash
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映射、警报抑制),使用和。架构详情请见references/detection-api-reference.md。
create --from-file rule_definition.json--threat-fileStep 5: Monitor and iterate
步骤5:监控与迭代
Monitor alert volume with and tune false positives as needed.
noisy-rules --days 3 --top 10使用监控警报量,并根据需要调优误报。
noisy-rules --days 3 --top 10Workflow: 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 ( or ). 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.
rule.idrule.nameScripts: (get rule TOML by id), (add to Endpoint
Exception List; rule.id/rule.name required), .
fetch-endpoint-rule-from-github.jsadd-endpoint-exception.jscheck-exclusion-best-practices.jsFor 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获取规则定义。始终将例外范围限定到规则(或)。使用完整路径而非进程名称。在添加任何例外前运行强制的实体交叉检查(步骤4b)。模拟影响(步骤5b)并目标实现≥60%的噪音减少。
rule.idrule.name脚本: (通过ID获取规则TOML)、(添加到终端例外列表;需指定rule.id/rule.name)、。
fetch-endpoint-rule-from-github.jsadd-endpoint-exception.jscheck-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.
| Command | Description |
|---|---|
| Search/list rules with optional KQL filter |
| Get a rule by |
| Create a rule (inline flags or |
| Patch specific fields on a rule |
| Enable a rule |
| Disable a rule |
| Delete a rule |
| Export rules as NDJSON |
| Bulk enable/disable/delete/duplicate/edit |
| Add an exception item to a rule |
| List items on an exception list |
| Create a shared exception list |
| Find noisiest rules by alert volume |
| Check query syntax before create/patch |
Endpoint behavior tuning: (get rule TOML by id),
(add to Endpoint Exception List; rule.id/rule.name required), .
fetch-endpoint-rule-from-github.jsadd-endpoint-exception.jscheck-exclusion-best-practices.js所有命令均从工作区根目录运行。所有输出默认为JSON格式,除非另有说明。
| 命令 | 描述 |
|---|---|
| 使用可选KQL过滤器搜索/列出规则 |
| 通过 |
| 创建规则(通过内联参数或 |
| 修改规则的特定字段 |
| 启用规则 |
| 禁用规则 |
| 删除规则 |
| 将规则导出为NDJSON格式 |
| 批量启用/禁用/删除/复制/编辑规则 |
| 为规则添加例外项 |
| 列出例外列表中的项 |
| 创建共享例外列表 |
| 根据警报量查找高噪音规则 |
| 在创建/修改规则前检查查询语法 |
终端行为调优: (通过ID获取规则TOML)、(添加到终端例外列表;需指定rule.id/rule.name)、。
fetch-endpoint-rule-from-github.jsadd-endpoint-exception.jscheck-exclusion-best-practices.jsException entry format
例外项格式
Pass entries as . Operators: , , , , ,
, , . Example: ,
.
field:operator:valueisis_notis_one_ofis_not_one_ofexistsdoes_not_existmatchesdoes_not_matchprocess.name:is:svchost.exefile.path:matches:C:\\Program Files\\*以格式传递例外项。运算符包括:、、、、、、、。示例:、。
field:operator:valueisis_notis_one_ofis_not_one_ofexistsdoes_not_existmatchesdoes_not_matchprocess.name:is:svchost.exefile.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 skill
alert-triage - For documenting tuning actions in cases, use the skill
case-management
- API架构详情请见references/detection-api-reference.md
- 终端行为调优相关:references/endpoint-exceptions-guide.md、references/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) prompt for confirmation. Passadd-endpoint-exceptionor--yesto skip when called by an agent.-y - Endpoint exceptions suppress detections globally. Always scope exceptions to a specific rule using or
rule.idin the entries. A broad, unscoped exception can silently reduce detection coverage.rule.name - Verify environment variables point to the intended cluster before running any script.
- Use with
--dry-runto preview impact before executing bulk changes.bulk-action
- 所有写入操作(、
create、patch、enable、disable、delete、add-exception、bulk-action)都会提示确认。由agent调用时,传递add-endpoint-exception或--yes跳过确认。-y - 终端例外会全局抑制检测。始终在例外项中使用或
rule.id将例外范围限定到特定规则。宽泛的无范围例外可能会悄无声息地降低检测覆盖范围。rule.name - 运行任何脚本前,验证环境变量指向目标集群。
- 使用时搭配
bulk-action,在执行批量更改前预览影响。--dry-run
Environment variables
环境变量
| Variable | Required | Description |
|---|---|---|
| Yes | Elasticsearch URL (for noisy-rules aggregation) |
| Yes | Elasticsearch API key |
| Yes | Kibana URL (for rules API) |
| Yes | Kibana API key |
| 变量 | 是否必填 | 描述 |
|---|---|---|
| 是 | Elasticsearch URL(用于高噪音规则聚合) |
| 是 | Elasticsearch API密钥 |
| 是 | Kibana URL(用于规则API) |
| 是 | Kibana API密钥 |