security-detection-rule-management

检测规则管理

为新出现的威胁和覆盖缺口创建新的检测规则，并调整现有规则以减少误报。 所有操作都通过 rule-manager.js 使用 Kibana Detection Engine API。

执行规则

• 立即开始执行工具——不要先阅读 SKILL.md、浏览工作区或列出文件。
• 忠实报告工具输出。准确复制 API 返回的规则 ID、名称、告警数量、例外 ID 和错误消息。不要缩写规则 UUID、臆造规则名称或四舍五入告警数量。
• 工具返回错误时（未找到规则、API 失败），准确报告错误——不要猜测其他可能情况。

前置条件

首次使用前，从 skills/security 目录安装依赖：

cd skills/security && npm install

设置所需的环境变量（或将其添加到工作区根目录中的 .env 文件）：

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"

常见的多步骤工作流

任务	调用工具（按顺序）
调整嘈杂的 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 添加例外。这些是专用工具——不要手动调用底层脚本。

工作流：调整规则以减少误报

步骤 1–2：识别嘈杂规则并分析误报

使用 noisy-rules 或 find 查找嘈杂规则，然后获取规则定义并调查告警：

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

留意以下模式：相同的进程/用户/主机 → 可能需要添加例外；模式过于宽泛 → 收紧查询；合法软件 → 添加例外；范围过广 → 重写规则或调整阈值。

步骤 3：选择调整策略

按优先顺序：

1. 添加例外 — 最适合已知可信的特定进程、用户或主机。不会修改规则查询。适用于规则整体正确，但会针对已知的合法活动触发告警的情况。

2. 收紧查询 — 修改规则的查询，以排除误报模式。最适合误报源于查询范围过广的情况。

3. 调整阈值 / 告警抑制 — 对于阈值规则，提高阈值。对于任何类型的规则，启用告警抑制，以减少针对同一实体的重复告警。

4. 降低风险评分 / 严重性 — 如果规则会产生许多价值较低的告警，但仍具有一定检测价值，则降低其优先级。

5. 停用规则 — 最后的手段。仅当规则没有任何价值，或与另一条规则完全重复时才停用。

步骤 4–5：应用调整、验证并记录

添加例外（单个/多个条件，可通过 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

修改查询、阈值、严重性或禁用规则：

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 技能更新分流案例。

---

工作流：创建新的检测规则

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

指定 MITRE ATT&CK 技术、所需数据源（Endpoint、Network、Cloud），以及恶意行为与合法行为。常见索引：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 验证数据：

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

步骤 3：编写并测试查询

规则类型：query（KQL 字段匹配）、eql（事件序列）、esql（聚合）、threshold（基于数量）、threat_match（IOC 关联）、new_terms（首次出现）。创建规则前，先在 Elasticsearch 中测试：

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 命令可在本地捕获常见错误——转义反斜杠、括号不匹配、引号不成对，以及重复的布尔运算符：

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 始终是错误。

步骤 4：创建规则

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。

步骤 5：监控并迭代

使用 noisy-rules --days 3 --top 10 监控告警数量，并根据需要调整误报。

---

工作流：调整 Endpoint 行为规则

通过添加限定到特定规则的 Endpoint 例外，调整 Elastic Endpoint 行为规则。Endpoint 例外位于 Security → Exceptions → Endpoint Security Exception List，而非各个 SIEM 规则下。

**关键原则：**始终先从 protections-artifacts 获取规则定义。例外必须限定到规则（rule.id 或 rule.name）。优先使用完整路径，而非进程名称。添加任何例外前，必须执行实体交叉检查（步骤 4b）。模拟影响（步骤 5b），目标是将噪声降低 ≥60%。

脚本：fetch-endpoint-rule-from-github.js（按 id 获取规则 TOML）、add-endpoint-exception.js（添加到 Endpoint Exception List；必须提供 rule.id/rule.name）、check-exclusion-best-practices.js。

完整的分步工作流（步骤 1–6）、查询和模拟模板，请参阅 references/endpoint-behavior-tuning-workflow.md。有关排除最佳实践，请参阅 references/endpoint-rule-exclusion-best-practices.md。

---

工具参考

rule-manager.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。

例外条目格式

按 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\\*。

其他资源

• 完整的 API 架构详情，请参阅 references/detection-api-reference.md
• 端点行为调优指南：references/endpoint-exceptions-guide.md、 references/endpoint-rule-exclusion-best-practices.md
• 调优期间调查警报，请使用 alert-triage 技能
• 在案例中记录调优操作，请使用 case-management 技能

示例

• “查找过去 7 天中最嘈杂的检测规则，并帮我调优其中一条”
• “向可疑 PowerShell 规则添加例外，以排除 SCCM”
• “创建一条用于检测 certutil URL 下载或解码的新规则”

指南

• 仅报告工具输出。 总结结果时，只引用或转述工具返回的内容。不要编造工具响应中没有的 ID、主机名、IP、分数、进程树或其他详情。
• 保留请求中的标识符。 如果用户提供了特定主机名、Agent ID、案例 ID 或其他值，请在工具调用和响应中使用这些确切值，不要替换为其他标识符。
• 简洁确认操作。 执行工具后，使用工具返回的数据确认已完成的操作。除非工具响应中包含，否则不要编造内部 ID、元数据或状态详情。
• 区分事实与推断。 如果得出的结论超出工具返回的内容（例如，根据观察到的行为推测 MITRE 技术），请明确标注为你的评估，不要将其说成工具输出。
• 立即开始执行工具。 操作前不要读取 SKILL.md、浏览目录或列出文件。
• 逐字报告工具输出。 按原样复制规则 ID、名称、警报数量和错误消息。不要缩写 UUID 或四舍五入数字。

生产环境使用

• 所有写入操作（create、patch、enable、disable、delete、add-exception、bulk-action、 add-endpoint-exception）都会提示确认。由 Agent 调用时，传入 --yes 或 -y 可跳过确认。
• 端点例外会全局抑制检测。 始终在条目中使用 rule.id 或 rule.name，将例外限定到特定规则。范围过宽、未指定规则的例外可能会在不提示的情况下减少检测覆盖范围。
• 运行任何脚本前，请确认环境变量指向预期集群。
• 使用 bulk-action 时，先通过 --dry-run 预览影响，再执行批量更改。

环境变量

变量	必需	说明
ELASTICSEARCH_URL	是	Elasticsearch URL（用于噪声规则聚合）
ELASTICSEARCH_API_KEY	是	Elasticsearch API 密钥
KIBANA_URL	是	Kibana URL（用于规则 API）
KIBANA_API_KEY	是	Kibana API 密钥