Gerenciar regras unificadas com a API Rules

Compatível com:

Google SecOps SIEM

A API Rules fornece endpoints programáticos para gerenciar regras personalizadas e selecionadas. Este documento descreve como usar a API Rules para gerenciar regras personalizadas e selecionadas de forma programática.

Use a API Rules para realizar as seguintes tarefas:

Pesquisar e listar regras:execute pesquisas estruturadas, classifique resultados e recupere recursos de regras expandidas.
Ver detalhes de regras selecionadas:busque metadados somente leitura, tags aplicadas e lógica de texto bruto para regras criadas pelo Google.
Modificar em lote as configurações de regras:atualize de forma síncrona estados ativos, estados de alerta, status de arquivamento e atribuições de tags em várias regras.

Pesquisar regras usando "List rules"

O método rules.list oferece suporte a recursos de regras expandidos e pesquisa estruturada. Para consultar esses recursos detalhados, use uma das seguintes visualizações:

CONFIG_ONLY
TRENDS

Ambas as visualizações fornecem informações detalhadas, incluindo:

Informações de implantação de regras (ativação de regras ativas, ativação de alertas, estado arquivado, estado de execução)
Tags de regra associadas
Acesso a recursos de regras selecionados na visualização CONFIG_ONLY
Tamanho de página maior de 5.000 resultados na visualização CONFIG_ONLY
Recursos robustos de pesquisa estruturada.

Classifique os resultados da pesquisa nos campos de recursos da regra usando order_by na solicitação rules.list. Os seguintes campos de regra são compatíveis:

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

Exemplo de solicitação:

HTTP

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

Exemplo de resposta:

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

Conferir detalhes de regras selecionadas usando getRule e listRules

Os rules.getRule e rule.listRules oferecem suporte à busca de detalhes para regras selecionadas. As respostas do rule.listRules podem ser filtradas para incluir apenas regras selecionadas usando o filtro rule_owner: "GOOGLE". Mais detalhes sobre o uso do filtro rule_owner podem ser encontrados na seção de sintaxe de pesquisa de regras.

Exemplo de solicitação listRules para ler uma regra selecionada:

HTTP

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

Exemplo de resposta:

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

O método "rule.getRule" permite buscar uma regra selecionada usando o nome do recurso.

Exemplo de solicitação "getRule" para buscar regras selecionadas:

HTTP

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

Exemplo de resposta:

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

Modificar em lote a configuração de regras com modifyRules

O método rules.modifyRules aceita a seguinte atualização em lote de regras personalizadas e selecionadas:

Atualizar o status da regra ativa
Atualizar o status de alerta
Atualizar tags aplicadas
Atualizar o status do arquivamento (somente para regras personalizadas)

As atualizações em lote são executadas de forma síncrona e independente. O processo não é atômico e continua apesar de falhas individuais. As falhas parciais são detalhadas no campo failed_requests, um mapa em que a chave representa o índice da solicitação com falha e o valor fornece o motivo da falha. As atualizações bem-sucedidas são documentadas no campo rule_updates, em que o resultado de cada solicitação é colocado no índice correspondente do lote original.

Exemplo de solicitação 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
      }
    }
  ]
}

Exemplo de resposta:

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

Diretrizes para atualizar regras selecionadas

Ao modificar os status de alertas ou em tempo real das regras selecionadas, considere o seguinte:

Controle independente:é possível gerenciar o status de uma regra de maneira independente da política do conjunto de regras principal. Se o status de uma regra divergir da política mãe, sua configuração personalizada vai persistir até que a política mãe receba a próxima atualização.
Requisito de direito:só é possível atualizar esses status se a instância tiver direito ativo ao pacote de regras principal.

Diretrizes para atualizar tags

É possível associar tags às suas regras usando os seguintes métodos:

Inclua códigos T do MITRE (tática ou técnica) nos metacampos tactic, technique ou mitre_ttp no texto da regra.
Especifique os nomes completos dos recursos de tag no campo de metadados tags do texto da regra.
Especifique nomes completos de recursos de tag usando solicitações da API ModifyRule.

A API ModifyRules é compatível com as tags MITRE tactic e technique. Todas as tags fornecidas em uma atualização da API substituem as tags atuais, exceto aquelas inferidas diretamente do texto da regra.

As tags MITRE tactic gerenciadas pelo Google usam o prefixo de namespace google.mitre.tactic.

Exemplo de um nome completo de recurso para a tag de tática TA0001:


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

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.