# Manage unified rules with Rules API

Supported in:

The Rules API provides programmatic endpoints to manage both custom and
curated rules. This document outlines how to use the Rules API to manage
custom and curated rules programmatically.

Use the Rules API to perform the following tasks:

- **Search and list rules:** Execute structured searches, sort results, and
  retrieve expanded rule resources.

- **View curated rule details:** Fetch read-only metadata, applied tags, and
  raw text logic for Google-authored rules.

- **Batch modify rule configurations:** Synchronously update live states,
  alerting states, archive statuses, and tag assignments across multiple rules.

## Search rules using list rules

The `rules.list` method supports expanded rule resources and structured search.
To query these detailed resources, use one of the following views:

- `CONFIG_ONLY`

- `TRENDS`

Both views provide expanded information, which includes the following:

- Rule deployment information (live rule enablement, alerting enablement,
  archived state, execution state)

- Associated rule tags

- Access to curated rule resources in `CONFIG_ONLY` view

- Larger page size of 5,000 results in `CONFIG_ONLY` view

- Robust structured search capabilities.

Sort search results on the rule resource fields using `order_by`
in the `rules.list` request. The following rule fields are supported:

- `alerting_enabled`

- `archived`

- `author`

- `create_time`

- `display_name`

- `execution_state`

- `live_mode_enabled`

- `revision_create_time`

- `rule_id`

- `rule_owner`

- `severity`

- `type`

- `update_time`

Example request:

HTTP

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

Example response:

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"
        }
      ]
    }

## View curated rule details using getRule and listRules

The `rules.getRule` and `rule.listRules` support fetching details for curated rules.
`rule.listRules` responses can be filtered to only curated rules using the
`rule_owner: "GOOGLE"` filter. More details on usage of the `rule_owner` filter
can be found in the rule search syntax section.

Example listRules request to read a curated rule:

HTTP

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

Example response:

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 method supports fetching a curated rule using its resource name.

Example getRule request to fetch curated rules:

HTTP

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

Example response:

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"
        }
      ]
    }

## Batch modify rule configuration with modifyRules

The `rules.modifyRules` method supports the following batch update on custom
rules and curated rules:

- Update live rule status

- Update alerting status

- Update applied tags

- Update archive status (for custom rules only)

Batch updates are executed synchronously and independently. The process is
non-atomic and continues despite individual failures. Partial
failures are detailed in the `failed_requests` field, a map where the key
represents the index of the failed request and the value provides the reason
for failure. Successful updates are documented in the `rule_updates` field,
where the result for each request is placed at its corresponding index
from the original batch.

Example `modifyRules` request:

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
          }
        }
      ]
    }

Example response:

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 },
        {}
      ]
    }

## Guidelines for updating curated rules

When you modify the live or alerting statuses for curated rules, consider the
following:

- **Independent control:** You can manage a rule's status independently from
  its parent rule set policy. If a rule's status diverges from the parent policy,
  your custom setting persists until the parent policy receives its next update.

- **Entitlement requirement:** You can only update these statuses if your
  instance is actively entitled to the parent rule pack.

## Guidelines for updating tags

You can associate tags with your rules using the following methods:

- Include MITRE T-codes (tactic or technique) in the `tactic`, `technique`,
  or `mitre_ttp` meta fields in the rule text.

- Specify the full tag resource names in the `tags` meta field of the rule text.

- Specify full tag resource names using `ModifyRule` API requests.

> [!IMPORTANT]
> **Important:** Tags defined within the rule text are read-only. You can't alter them with the `ModifyRules` API.

The `ModifyRules` API supports MITRE `tactic` and `technique` tags. Any tags
provided in an API update overwrite existing tags, except for those inferred
directly from the rule text.

Google-managed MITRE `tactic` tags use the `google.mitre.tactic` namespace prefix.

Example of a full resource name for the `TA0001` tactic tag:


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

**Need more help?** [Get answers from Community members and Google SecOps professionals.](https://security.googlecloudcommunity.com/)