使用 API 管理规则排除对象

支持的平台：

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

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

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

使用 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.01",
      "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": [
      ...list curated rule set resource names
    ],
    "curatedRules": [
      ...list curated rule resource names
    ],
    "rules": [
      ...list rule resource names
    ],
  }
}

当您将排除项应用于规则或规则集时，系统会创建 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 参数可列出更多结果，这与其他列表端点类似。

  • 使用 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.01",
      "outcome_filter_operator": "EQUAL",
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS",
    },
  ]
  "interval": {
    "start_time": {
      "seconds": 1756684800, // Sep. 1 2025 00:00 UTC
    },
    "end_time": {
      "seconds": 1759276800, // Oct. 1 2025 00:00 UTC
    },
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      ...curated rule set resource names
    ],
    "curatedRules": [
      ...curated rule resource names
    ],
    "rules": [
      ...rule resource names
    ],
  }
}

此端点用于测试对请求中指定的规则和规则集中生成的检测结果的排除情况。这有助于确定排除项在抑制不应生成的检测方面的效果。系统会使用过去 30 天的检测结果作为测试排除项的时间范围。

限制

  • 所有排除对象（无论是否带有效果过滤器）都必须指定 query 字段。如需仅使用 outcomeFilters 创建排除对象，请指定 match-all 正则表达式。

    
  ...other fields in FindingsRefinement

  query: "principal.hostname = /.*/"

  outcomeFilters: [ your outcome filters ]

    该正则表达式与任何主机名匹配。因此，此查询会匹配所有检测结果。因此，有效过滤条件仅由结果过滤条件决定。

  • 排除对象不支持存留时间 (TTL) 配置。不过，您可以计算出具体的到期时间，并在排除对象定义中添加时间戳条件，从而创建一次性 TTL。例如，如需将排除对象的到期时间设置为年末，请按如下方式指定查询：

    
  ...other fields in FindingsRefinement

  query: "metadata.event_timestamp.seconds < 1767225600" // Jan 1 2026 00:00 UTC

  outcomeFilters: [your outcome filters]

    此示例确认，只有时间戳早于年末的事件所创建的检测会被抑制。

    注意：这可能无法在界面的修改排除对象窗口中正确显示，因为该窗口仅支持 string 字段。

需要更多帮助？获得社区成员和 Google SecOps 专业人士的解答。