使用 Rules API 管理统一规则

支持的平台：

Google SecOps SIEM

Rules API 提供程序化端点来管理自定义规则和精选规则。本文档概述了如何使用 Rules API 以编程方式管理自定义规则和精选规则。

使用 Rules API 可执行以下任务：

搜索和列出规则：执行结构化搜索、对结果进行排序，以及检索扩展的规则资源。
查看精选规则详情：获取 Google 编写的规则的只读元数据、应用的标记和原始文本逻辑。
批量修改规则配置：同步更新多个规则的实时状态、提醒状态、归档状态和标记分配。

使用 list rules 搜索规则

rules.list 方法支持扩展的规则资源和结构化搜索。如需查询这些详细资源，请使用以下视图之一：

CONFIG_ONLY
TRENDS

这两种视图都提供展开后的信息，其中包括以下内容：

规则部署信息（有效规则启用状态、提醒启用状态、归档状态、执行状态）
关联的规则标记
有权访问 CONFIG_ONLY 视图中的精选规则资源
CONFIG_ONLY 视图中更大的页面大小（5,000 条结果）
强大的结构化搜索功能。

使用 rules.list 请求中的 order_by 对规则资源字段中的搜索结果进行排序。支持以下规则字段：

alerting_enabled
archived
author
create_time
display_name
execution_state
live_mode_enabled
revision_create_time
rule_id
rule_owner
severity
type
update_time

示例请求：

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules?filter=archived%3Dfalse&pageSize=100&pageToken=&view=TRENDS

示例响应：

JSON

{
  "rules": [
    {
      "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_fd3fe28c-2d7b-4f7e-9fca-4fdd6029d228",

      "revisionId": "v_1719339990_701951000",

      "displayName": "SomaMaglevProberRule",

      "author": "test@google.com",

      "metadata": {
        "description": "enabled live rule used for maglev rules latency prober"

      },

      "createTime": "2024-06-25T18:26:30.701951Z",

      "revisionCreateTime": "2024-06-25T18:26:30.701951Z",

      "type": "SINGLE_EVENT",

      "etag": "CNaX7LMGEJjY284C",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "CUSTOMER",

      "alertingEnabled": true,

      "liveModeEnabled": true,

      "runFrequency": "LIVE",

      "currentDayDetectionCount": 10000,

      "executionState": "DEFAULT"

    },
    {
      "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_fbf56bf1-ea5f-4b5b-bbe9-e91e13f3b3b3",

      "revisionId": "v_1696452642_197471000",

      "displayName": "LoadTestingRule",

      "author": "loadtesting@google.com",

      "createTime": "2023-10-04T20:50:42.197471Z",

      "revisionCreateTime": "2023-10-04T20:50:42.197471Z",

      "type": "SINGLE_EVENT",

      "etag": "CKKg96gGEJjWlF4=",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "CUSTOMER",

      "alertingEnabled": true,

      "liveModeEnabled": true,

      "runFrequency": "LIVE",

      "executionState": "DEFAULT"
    }
  ]
}

使用 getRule 和 listRules 查看精选的规则详细信息

rules.getRule 和 rule.listRules 支持提取精选规则的详细信息。可以使用 rule_owner: "GOOGLE" 过滤条件，仅显示精选规则的 rule.listRules 响应。如需详细了解 rule_owner 过滤条件的用法，请参阅规则搜索语法部分。

用于读取精选规则的 listRules 请求示例：

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules?filter=rule_owner%3A%22GOOGLE%22pageSize=1&view=TRENDS

示例响应：

JSON

{
  "rules": [
    {
      "name": "projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c",

      "revisionId": "v_1755272664_971453000",

      "displayName": "Example Curated Rule",

      "severity": {
        "displayName": "Info"
      },

      "metadata": {
        "technique": "T1136.003",
        "rule_name": "Example Curated Rule",
        "description": "Example Curated Rule Description",
        "tactic": "TA0003"
      },

      "createTime": "2024-10-02T18:10:43.647897Z",

      "revisionCreateTime": "2025-08-15T15:44:24.971453Z",

      "type": "SINGLE_EVENT",

      "etag": "CNir/cQGEMjknM8D",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "GOOGLE",

      "tags": [
        "google.mitre.tactic.ta0003",
        "google.mitre.technique.t1136.003"
      ],

      "executionState": "DEFAULT"
    }
  ]
}

rule.getRule 方法支持使用精选规则的资源名称来提取该规则。

用于获取精选规则的 getRule 请求示例：

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c?view=BASIC

示例响应：

JSON

{
  "rules": [
    {
      "name": "projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c",

      "revisionId": "v_1755272664_971453000",

      "displayName": "Example Curated Rule",

      "severity": {
        "displayName": "Info"
      },

      "metadata": {
        "technique": "T1136.003",
        "rule_name": "Example Curated Rule",
        "description": "Example curated rule description",
        "tactic": "TA0003"
      },

      "createTime": "2024-10-02T18:10:43.647897Z",

      "revisionCreateTime": "2025-08-15T15:44:24.971453Z",

      "text": "Example curated rule text",

      "type": "SINGLE_EVENT",

      "etag": "CNir/cQGEMjknM8D",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "GOOGLE",

      "tags": [
        "google.mitre.tactic.ta0003",
        "google.mitre.technique.t1136.003"
      ],

      "executionState": "DEFAULT"
    }
  ]
}

使用 modifyRules 批量修改规则配置

rules.modifyRules 方法支持对自定义规则和精选规则进行以下批量更新：

更新实时规则状态
更新提醒状态
更新已应用的代码
更新归档状态（仅限自定义规则）

批量更新以同步方式独立执行。该过程是非原子性的，即使出现个别故障也会继续进行。部分失败的详细信息在 failed_requests 字段中，这是一个映射，其中键表示失败请求的索引，值提供失败原因。成功更新记录在 rule_updates 字段中，其中每个请求的结果都位于原始批次中对应的索引处。

示例 modifyRules 请求：

HTTP

POST https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules:modifyRules

JSON

{
  "parent": "projects/<ID>/locations/us/instances/<ID>",
  "requests": [
    {
      "update_mask": "liveModeEnabled",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_aaaaaaaaaaaaaaaaaaaaaaa",
        "liveModeEnabled": true
      }
    },
    {
      "update_mask": "alertingEnabled",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ur_zzzzzzzzzzzzzzzzzzzzz",
        "alertingEnabled": false
      }
    },
    {
      "update_mask": "tags",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_bbbbbbbbbbbbbbbbbbbbbbb",
        "tags": [
          "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.tactic.TA0043",
          "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.technique.T1595"
        ]
      }
    },
    {
      "update_mask": "archived",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_cccccccccccccccccccccc",
        "archived": true
      }
    }
  ]
}

示例响应：

JSON

{
  "failed_requests": {
    "0": {
      "code": 5,
      "message": "rule is already enabled"
    },
    "3": {
      "code": 5,
      "message": "rule is already archived"
    }
  },
  "rule_updates": [
    {},
    { "alerting_state_updated": true },
    { "tagsUpdated": true },
    {}
  ]
}

更新精选规则的指南

修改精选规则的实时状态或提醒状态时，请考虑以下事项：

独立控制：您可以独立于规则的父规则集政策来管理规则的状态。如果规则的状态与父政策不同，您的自定义设置会一直保留，直到父政策收到下一次更新。
授权要求：只有当您的实例已获得父规则包的有效授权时，才能更新这些状态。

更新标记的准则

您可以使用以下方法将标记与规则相关联：

在规则文本的 tactic、technique 或 mitre_ttp 元字段中添加 MITRE T 代码（策略或技术）。
在规则文本的 tags 元字段中指定完整的标记资源名称。
使用 ModifyRule API 请求指定完整的标记资源名称。

ModifyRules API 支持 MITRE tactic 和 technique 标记。API 更新中提供的任何标记都会覆盖现有标记，但直接从规则文本推断出的标记除外。

Google 管理的 MITRE tactic 标记使用 google.mitre.tactic 命名空间前缀。

TA0001 策略代码的完整资源名称示例：


projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.tactic.TA0001