Reorganizamos a estrutura de navegação da documentação para se alinhar diretamente aos seus fluxos de trabalho operacionais. Consulte as notas da versão e o vídeo explicativo para mais informações.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar regras unificadas com a API Rules

Compatível com:

Google SecOps SIEM

A API Rules oferece 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 os resultados e recupere recursos de regras expandidos.
Conferir detalhes de regras selecionadas:busque metadados somente leitura, tags aplicadas e lógica de texto bruto para regras criadas pelo Google.
Modificar configurações de regras em lote:atualize de forma síncrona estados ativos, estados de alerta, status de arquivo e atribuições de tags em várias regras.

Pesquisar regras usando a lista de regras

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

As duas visualizações fornecem informações expandidas, que incluem o seguinte:

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

Classifique os resultados da pesquisa nos campos de recursos de regras usando order_by na solicitação rules.list. Os seguintes campos de regras 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 métodos rules.getRule e rule.listRules oferecem suporte à busca de detalhes para regras selecionadas. As respostas 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 oferece suporte à busca de 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 a configuração de regras em lote com modifyRules

O método rules.modifyRules oferece suporte à 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 arquivo (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 ativos ou de alerta para regras selecionadas, considere o seguinte:

Controle independente:é possível gerenciar o status de uma regra de forma independente da política do conjunto de regras mãe. Se o status de uma regra divergir da política mãe, a 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 ao pacote de regras mãe.

Diretrizes para atualizar tags

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

Inclua códigos T do MITRE (tática ou técnica) nos campos de metadados 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 os nomes completos dos recursos de tag usando solicitações de API ModifyRule.

A API ModifyRules oferece suporte a tags tactic e technique do MITRE. Todas as tags fornecidas em uma atualização da API substituem as tags atuais, exceto aquelas inferidas diretamente do texto da regra.

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

Exemplo de nome completo do 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.