Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

管理规则排除项

支持范围：

Google SecOps SIEM

本文档介绍了如何使用 API 以编程方式管理 Google Security Operations 中的规则排除项。排除项用作过滤条件，您可以根据统一数据模型 (UDM) 字段定义这些过滤条件，以防止特定检测生成提醒。通过识别已知或安全的活动，这些过滤条件可以阻止信息中心内不必要的干扰。

注意：请勿将规则排除项直接应用于复合规则。您必须将排除规则应用于构成复合规则的基础底层规则。这是因为规则排除项是根据 UDM 字段（例如 principal.user.userid）进行评估的，而复合规则是根据其他检测结果（而非 UDM 字段）触发的。如果您直接将规则排除项应用于复合规则，则排除项将无法匹配，并且事件不会被排除。

如需查找基础规则，您可以在 Google SecOps 控制台中检查复合规则定义（在内容中心 > 精选检测下），并查看 YARA-L 逻辑的 events: 部分，以识别基础规则名称。

创建包含结果过滤条件的排除项

您可以通过编程方式创建新的排除规则，以抑制与您定义的条件匹配的特定检测发现结果，从而减少干扰并优先处理高保真度提醒。

使用 POST 端点定义抑制逻辑。outcomeFilters 数组中的所有过滤条件都通过隐式 AND 子句关联。

方法：POST

端点：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID

替换以下内容：

REGION：Google SecOps 实例的 Google Cloud 区域。

PROJECT_ID：您的 Google Cloud 项目 ID。

LOCATION：Google SecOps 实例的位置（通常与区域相同）。

INSTANCE_ID：Google SecOps 实例的 ID。

示例：

POST https://us-chronicle.googleapis.com/v1/projects/my-project/locations/us/instances/my-instance/findingsRefinements

请求正文：

{
  "displayName": "Exclusion with outcome filters",
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ]
}

该示例演示了如何定义抑制逻辑，其中 outcomeFilters 数组中的多个过滤条件通过隐式 AND 子句关联。

必填字段：displayName、type、query

系统生成的字段：请勿指定 name、createTime 或 updateTime。这些字段由系统管理，如果包含在请求中，则会被忽略或导致错误。

屏蔽逻辑遵循 AND 关系。该请求会创建一个排除项，用于抑制包含以下事件的所有检测：

“altostrat.com”作为主主机名
值为 127.0.0.1 的结果变量 ip
结果变量 hostnames 的至少一个汇总值为 altostrat.com。

排除项中指定的所有过滤条件都会通过 AND 子句隐式关联。

API 响应：API 返回 FindingsRefinement 资源名称。

FindingsRefinement 资源包含核心抑制逻辑（查询和结果过滤条件）。资源名称 (ID) 用于对排除项执行后续操作

访问排除对象

使用 GET 端点执行以下操作：

通过唯一 ID 获取单个排除定义的详细信息。
当您有特定的 refinement-id，并且需要验证其包含的确切查询或结果过滤条件时。

方法：GET

端点：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

替换以下内容：

REGION：Google SecOps 实例的 Google Cloud 区域。

PROJECT_ID：您的 Google Cloud 项目 ID。

LOCATION：Google SecOps 实例的位置（通常与区域相同）。

INSTANCE_ID：Google SecOps 实例的 ID。

示例：

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777

将排除项应用于规则或规则集

您必须将排除项应用于特定规则或精选规则集。将排除项应用于规则或规则集时，系统会创建 FindingsRefinementDeployment 资源。您可以使用此资源来确定适用于 FindingsRefinement 资源的自定义规则、精选规则或精选规则集。然后，您可以在 API 请求中指定 update_mask 参数，以指明要更新 FindingsRefinementDeployment 中的哪些字段。

方法：PATCH

端点：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID

替换以下内容：

REGION：Google SecOps 实例的 Google Cloud 区域。

PROJECT_ID：您的 Google Cloud 项目 ID。

LOCATION：Google SecOps 实例的位置（通常与区域相同）。

INSTANCE_ID：Google SecOps 实例的 ID。

REFINEMENT_ID：发现结果优化条件的唯一 ID。

示例：

 PATCH https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777?update_mask=enabled,detectionExclusionApplication

请求正文：

{
  "name": "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777",
  "enabled": true,
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/<var>CATEGORY_ID</var>/curatedRuleSets/<var>RULE_SET_ID</var>"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/<var>CURATED_RULE_ID</var>"
    ],
    "rules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/rules/<var>RULE_ID</var>"
    ]
  }
}

在请求正文中，通过替换 CATEGORY_ID、RULE_SET_ID、CURATED_RULE_ID 和 RULE_ID，在 curatedRuleSets、curatedRules 和 rules 中指定精选规则集、精选规则和规则资源名称的列表。

将排除项应用于规则或规则集时，系统会创建 FindingsRefinementDeployment 资源。此资源决定了哪些自定义规则、精选规则和精选规则集适用于 FindingsRefinement 资源。您还可以在 API 请求中添加 update_mask 参数，以指定要更新 FindingsRefinementDeployment 中的哪些字段。

访问排除项的部署

创建或更新排除项后，使用此端点验证该特定排除项部署到了哪些规则或规则集。

方法：GET

端点：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID

替换以下内容：

REGION：Google SecOps 实例的 Google Cloud 区域。

PROJECT_ID：您的 Google Cloud 项目 ID。

LOCATION：Google SecOps 实例的位置（通常与区域相同）。

INSTANCE_ID：Google SecOps 实例的 ID。

REFINEMENT_ID：发现结果优化条件的唯一 ID。

示例：

   GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777/deployment

列出所有排除对象

使用此端点可检索 findingsRefinements 资源列表。

方法：GET

端点：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

替换以下内容：

REGION：Google SecOps 实例的 Google Cloud 区域。

PROJECT_ID：您的 Google Cloud 项目 ID。

LOCATION：Google SecOps 实例的位置（通常与区域相同）。

INSTANCE_ID：Google SecOps 实例的 ID。

示例：

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements

可选查询参数：pageSize、pageToken

您可以使用可选参数列出更多结果，类似于 API 中的其他列表端点。

列出所有排除项部署

使用以下端点获取在实例中创建的 FindingsRefinement 资源列表。

方法：GET

端点：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

替换以下内容：

REGION：Google SecOps 实例的 Google Cloud 区域。

PROJECT_ID：您的 Google Cloud 项目 ID。

LOCATION：Google SecOps 实例的位置（通常与区域相同）。

INSTANCE_ID：Google SecOps 实例的 ID。

示例：

  GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:listAllFindingsRefinementDeployments

可选查询参数：

使用 pageSize 和 pageToken 参数列出更多结果，类似于 API 中的其他列表端点。
使用 filter 参数可过滤应用了排除项的规则或规则集。

使用 API 测试排除项

以下端点会根据指定规则和规则集的检测结果测试排除项，然后验证排除项在抑制不必要的检测方面的有效性。界面会使用过去 30 天的检测结果进行测试。

方法：POST

端点：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:testFindingsRefinement

替换以下内容：

REGION：Google SecOps 实例的 Google Cloud 区域。

PROJECT_ID：您的 Google Cloud 项目 ID。

LOCATION：Google SecOps 实例的位置（通常与区域相同）。

INSTANCE_ID：Google SecOps 实例的 ID。

示例：

POST https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:testFindingsRefinement

请求正文：

{
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ],
  "interval": {
    "start_time": {
      "seconds": 1756684800
    },
    "end_time": {
      "seconds": 1759276800
    }
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/<var>CATEGORY_ID</var>/curatedRuleSets/<var>RULE_SET_ID</var>"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/<var>CURATED_RULE_ID</var>"
    ],
    "rules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/rules/<var>RULE_ID</var>"
    ]
  }
}

此端点会针对请求中指定的规则和规则集中生成的检测结果测试排除项。这有助于确定排除项在抑制不应生成的检测结果方面的效果。系统会使用过去 30 天的检测结果作为测试排除项的时间范围。在前面的示例中，interval 字段测试 2025 年 9 月 1 日 00:00 UTC (1756684800) 到 2025 年 10 月 1 日 00:00 UTC (1759276800) 之间的检测结果，detectionExclusionApplication 通过替换 CATEGORY_ID、RULE_SET_ID、CURATED_RULE_ID 和 RULE_ID 来指定要测试的资源名称。

查询语法和字段规则

findingsRefinements.query 字段支持 YARA-L 2.0 语法的受限子集，而不是完整的 UDM 搜索 (udmSearch) 语法。由于这两种查询语法不同，在 udmSearch 中成功的查询可能会在排除项中失败并出现 400 INVALID_ARGUMENT 错误。

以下部分介绍了 findingsRefinements.query 字段的语法规则：

布尔值语法
支持的运算符和字面量
支持的 UDM 字段和路径深度限制

如需在部署前验证排除查询，请调用 testFindingsRefinement 端点，而不是 udmSearch。

布尔语法

findingsRefinements.query 字段需要使用扁平合取范式 (CNF) 布尔值语法。在扁平 CNF 中，您可以使用 AND 联接一个或多个子句，并且每个带括号的子句仅包含扁平 OR 比较，不含嵌套括号。

findingsRefinements.query 字段支持以下布尔值结构：

单个比较或 OR 比较的平面序列，例如 field_a = "val_1" OR field_b = "val_2"。
由 AND（或隐式空格 AND）联接的多个子句，其中每个带括号的子句仅包含扁平 OR 比较。例如 field_a = "val_1" AND (field_b = "val_2" OR field_c = "val_3")。
在单个比较之前添加前缀 NOT，例如 NOT principal.hostname = "scanner.example.com"。

findingsRefinements.query 字段会拒绝以下布尔值结构，并显示 400 INVALID_ARGUMENT 错误：

嵌套括号，例如 A AND (B OR (C AND D))。
带括号的子句之间的逻辑 OR 运算符，例如 (A AND B) OR (C AND D)。

您可以将嵌套逻辑（例如 A OR (B AND C)）重写为扁平 CNF，如 (A OR B) AND (A OR C)。对于复杂的 OR-of-AND 条件，如果 CNF 扩展过大，请为每个 AND 分支创建单独的 FindingsRefinement 资源。

支持的运算符和字面量

下表列出了每个查询功能、其在 findingsRefinements.query 中的支持情况以及有效示例或替代方案：

功能	`findingsRefinements.query`支持	示例或替代方案
比较运算符	支持 `=`、`!=`、`<`、`<=`、`>` 和 `>=`。字符串、正则表达式和映射比较支持 `=` 和 `!=`。	`metadata.log_type = "WINDOWS_SYSMON"`
正则表达式	支持在字符串和映射字段中使用斜杠分隔的正则表达式 (`/.../`)。	`principal.hostname = /^scanner-[0-9]+\.example\.com$/`
不区分大小写的修饰符	支持对字符串和正则表达式进行 `nocase` 比较。枚举字段不支持 `nocase`。	`principal.user.userid = "admin" nocase`
字面量	支持双引号字符串、整数、浮点数、布尔值（`true` 或 `false`）和 base64 字节字面量 (`b"..."`)。	`security_result.about.file.sha256 = "e3b0c4..."`
CIDR 范围匹配	支持在 IP 地址字段中使用 `CIDR_RANGE` 关键字。	`principal.ip = CIDR_RANGE "192.0.2.0/24"`
YARA-L 函数	不支持 YARA-L 函数，例如 `net.ip_in_range_cidr` 或 `re.regex`。	使用 `CIDR_RANGE` 表示 IP 子网，或使用 `/.../` 表示正则表达式。
参考列表和数据表	不支持在排除查询中进行参考列表 (`%list_name`) 或数据表查找。	使用平面 `OR` 比较或 `outcomeFilters` 枚举值。

支持的 UDM 字段和路径深度限制

findingsRefinements.query 字段强制执行以下 UDM 字段规则：

字段路径最多支持 6 个以英文句点分隔的片段，例如 target.process.file.sha256（4 个片段）或 target.resource.attribute.labels["env"]（4 个片段）。
包含 7 个或更多点分隔段的字段路径无法通过验证，并显示 400 INVALID_ARGUMENT (Not a valid field path) 错误。例如，target.process.file.signature_info.sigcheck.signers.name 有 7 个片段，因此被拒绝。
叶字段支持标量（string、整数、浮点数和 bool）、enum 和 bytes 数据类型。
映射和 Label 字段支持括号键控查找，例如 additional.fields["key"] = "value" 和 target.resource.attribute.labels["project"] = "prod"。
除了完整的 UDM 事件字段路径之外，还支持分组 UDM 搜索别名，例如 ip、hostname、user 和 hash。
排除查询不支持实体图路径 (graph.*) 和无键 message 字段。

限制

所有排除项（无论是否包含结果过滤条件）都必须指定 query 字段。如需仅使用 outcomeFilters 字段创建排除项，请添加必需的 FindingsRefinement 字段，并将 query 字段设置为 match-all 正则表达式：
```
{
  "displayName": "Exclusion with only outcome filters",
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = /.*/",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    }
  ]
}
```
正则表达式与任何主机名匹配。因此，此查询会匹配所有检测结果。因此，有效过滤完全由结果过滤条件决定。
排除项不支持存留时间 (TTL) 配置。不过，您可以通过计算具体的到期时间并在排除定义中添加时间戳条件，来创建一次性 TTL。例如，如需将排除项设置为在 2026 年 1 月 1 日 00:00 UTC (1767225600) 到期，请按如下方式指定查询：
```
{
  "displayName": "Exclusion with expiration timestamp",
  "type": "DETECTION_EXCLUSION",
  "query": "metadata.event_timestamp.seconds < 1767225600",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    }
  ]
}
```
根据需要添加其他必需的 FindingsRefinement 字段和结果过滤条件。上一个示例确认，只有由时间戳早于 2026 年 1 月 1 日 00:00 UTC (1767225600) 的事件创建的检测结果才会被抑制。

注意：此字段可能无法在界面的修改排除对象窗口中正确显示，因为它仅支持 string 字段。
复合规则：请勿直接对复合规则应用规则排除。您必须将排除规则应用于构成复合规则的基础底层规则。这是因为系统会根据 UDM 字段（例如 principal.user.userid）评估规则排除项，但复合规则是根据其他检测结果（而非 UDM 字段）触发的。如果您直接将规则排除项应用于复合规则，则排除项将无法匹配，并且事件不会被排除。

如需查找基础规则，您可以在 Google SecOps 控制台中（依次点击内容中心 > 精选检测）检查复合规则定义，并查看 YARA-L 逻辑的 events: 部分，以确定基础规则名称。
查询语法和字段深度：排除查询必须使用扁平合取范式 (CNF) 布尔语法和 UDM 字段路径，其中最多包含 6 个以英文句点分隔的片段。如需了解详情，请参阅查询语法和字段规则。