Gerenciar exclusões de regras

Compatível com:

Neste documento, explicamos como gerenciar de forma programática as exclusões de regras no Google Security Operations usando a API. As exclusões servem como filtros que você define com base nos campos do Modelo de Dados Unificado (UDM) para evitar que detecções específicas gerem alertas. Ao identificar atividades conhecidas ou seguras, esses filtros eliminam ruídos desnecessários no painel.

Criar uma exclusão com filtros de resultado

É possível criar uma nova regra de exclusão de forma programática para suprimir descobertas de detecção específicas que correspondam aos critérios definidos, reduzindo o ruído e priorizando alertas de alta fidelidade.

Use o endpoint POST para definir a lógica de supressão. Todos os filtros com a matriz outcomeFilters são vinculados por uma cláusula AND implícita.

Método: POST

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

Substitua:

REGION: a região do Google Cloud da instância do Google SecOps.

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: o local da instância do Google SecOps (geralmente o mesmo que a região).

INSTANCE_ID: o ID da instância do Google SecOps.

Exemplo:

POST https://us-chronicle.googleapis.com/v1/projects/my-project/locations/us/instances/my-instance/findingsRefinements

Corpo da solicitação:

{
  "displayName": "Exclusion with outcome filters",
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ]
}

O exemplo demonstra como definir a lógica de supressão em que vários filtros na matriz outcomeFilters são vinculados por uma cláusula AND implícita.

Campos obrigatórios: displayName, type, query

Campos gerados pelo sistema: não especifique name, createTime ou updateTime. Eles são gerenciados pelo sistema e são ignorados ou causam erros se incluídos na solicitação.

A lógica de supressão segue uma relação AND. A solicitação cria uma exclusão que suprime todas as detecções que têm um evento com o seguinte:

  • "altostrat.com" como o nome do host principal

  • Uma variável de resultado ip com um valor de 127.0.0.1.

  • Uma variável de resultado hostnames com pelo menos um dos valores agregados sendo altostrat.com.

Todos os filtros especificados na exclusão são vinculados implicitamente por uma cláusula AND.

Resposta da API: a API retorna o nome do recurso FindingsRefinement.

O recurso FindingsRefinement contém a lógica de supressão principal (os filtros de consulta e resultado). O nome do recurso (ID) é usado para operações subsequentes na exclusão.

Acessar uma exclusão

Use o endpoint GET para fazer o seguinte:

  • Recebe os detalhes de uma única definição de exclusão pelo ID exclusivo.

  • Quando você tem um refinement-id específico e precisa verificar a consulta exata ou os filtros de resultado que ele contém.

Método: GET

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID

Substitua:

REGION: a região do Google Cloud da instância do Google SecOps.

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: o local da instância do Google SecOps (geralmente o mesmo que a região).

INSTANCE_ID: o ID da instância do Google SecOps.

REFINEMENT_ID: o ID exclusivo do recurso FindingsRefinement.

Exemplo:

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777

Aplicar uma exclusão a uma regra ou conjunto de regras selecionado

Para ativar uma exclusão, aplique-a a regras selecionadas específicas ou conjuntos de regras selecionadas atualizando o recurso FindingsRefinementDeployment. Use o parâmetro de consulta update_mask para especificar quais campos atualizar na implantação.

Método: PATCH

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID/deployment

Substitua:

REGION: a região do Google Cloud da instância do Google SecOps.

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: o local da instância do Google SecOps (geralmente o mesmo que a região).

INSTANCE_ID: o ID da instância do Google SecOps.

REFINEMENT_ID: o ID exclusivo do recurso FindingsRefinement.

Exemplo:

PATCH https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777/deployment?update_mask=enabled,detectionExclusionApplication

Corpo da solicitação:

{
  "name": "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777/deployment",
  "enabled": true,
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/CATEGORY_ID/curatedRuleSets/RULE_SET_ID"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/RULE_ID"
    ]
  }
}

No corpo da solicitação, especifique as listas de nomes de recursos de conjuntos de regras selecionados e nomes de recursos de regras selecionadas nas matrizes curatedRuleSets e curatedRules. Substitua CATEGORY_ID, RULE_SET_ID e RULE_ID pelo ID da categoria do conjunto de regras selecionado, pelo ID do conjunto de regras selecionado e pelo ID da regra selecionada.

Acessar a implantação da exclusão

Depois de criar ou atualizar uma exclusão, use esse endpoint para verificar em quais regras ou conjuntos de regras selecionados a exclusão foi implantada.

Método: GET

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID/deployment

Substitua:

REGION: a região do Google Cloud da instância do Google SecOps.

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: o local da instância do Google SecOps (geralmente o mesmo que a região).

INSTANCE_ID: o ID da instância do Google SecOps.

REFINEMENT_ID: o ID exclusivo do refinamento de descobertas.

Exemplo:

   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

Listar todas as exclusões

Use esse endpoint para recuperar a lista de recursos findingsRefinements.

Método: GET

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

Substitua:

REGION: a região do Google Cloud da instância do Google SecOps.

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: o local da instância do Google SecOps (geralmente o mesmo que a região).

INSTANCE_ID: o ID da instância do Google SecOps.

Exemplo:

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements

Parâmetros de consulta opcionais: pageSize, pageToken

É possível usar os parâmetros opcionais para listar mais resultados semelhantes a outros endpoints de lista na API.

Listar todas as implantações de exclusão

Use o endpoint a seguir para ver a lista de recursos FindingsRefinementDeployment criados na sua instância.

Método: GET

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:listAllFindingsRefinementDeployments

Substitua:

REGION: a região do Google Cloud da instância do Google SecOps.

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: o local da instância do Google SecOps (geralmente o mesmo que a região).

INSTANCE_ID: o ID da instância do Google SecOps.

Exemplo:

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:listAllFindingsRefinementDeployments

Parâmetros de consulta opcionais:

  • Use os parâmetros pageSize e pageToken para listar mais resultados semelhantes a outros endpoints de lista na API.

  • Use o parâmetro filter para filtrar por detection_exclusion_application.curated_rules ou detection_exclusion_application.curated_rule_sets.

Testar uma exclusão usando a API

O endpoint a seguir testa uma exclusão em relação a detecções de regras selecionadas especificadas e conjuntos de regras selecionadas para validar a eficácia com que ele suprime detecções indesejadas. O console usa as detecções dos últimos 30 dias para testes.

Método: POST

Endpoint:

https://REGION-chronicle.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:testFindingsRefinement

Substitua:

REGION: a região do Google Cloud da instância do Google SecOps.

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: o local da instância do Google SecOps (geralmente o mesmo que a região).

INSTANCE_ID: o ID da instância do Google SecOps.

Exemplo:

POST https://us-chronicle.googleapis.com/v1alpha/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:testFindingsRefinement

Corpo da solicitação:

{
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ],
  "interval": {
    "start_time": {
      "seconds": 1756684800
    },
    "end_time": {
      "seconds": 1759276800
    }
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/CATEGORY_ID/curatedRuleSets/RULE_SET_ID"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/RULE_ID"
    ]
  }
}

No exemplo anterior, o campo interval testa detecções de 1º de setembro de 2025, às 00:00 UTC (1756684800) a 1º de outubro de 2025, às 00:00 UTC (1759276800). Em detectionExclusionApplication, especifique o conjunto de regras selecionadas e os nomes de recursos de regras selecionadas para testar substituindo CATEGORY_ID, RULE_SET_ID e RULE_ID.

Sintaxe de consulta e regras de campo

O campo findingsRefinements.query é compatível com um subconjunto restrito da sintaxe YARA-L 2.0, em vez da sintaxe completa da pesquisa de UDM (udmSearch). Como essas duas sintaxes de consulta são diferentes, uma consulta que funciona em udmSearch pode falhar com um erro 400 INVALID_ARGUMENT em uma exclusão.

As seções a seguir descrevem as regras de sintaxe do campo findingsRefinements.query:

Para validar uma consulta de exclusão antes da implantação, chame o endpoint testFindingsRefinement em vez de udmSearch.

Gramática booleana

O campo findingsRefinements.query requer uma sintaxe booleana de forma normal conjuntiva (CNF, na sigla em inglês) simples. Na CNF simples, você une uma ou mais cláusulas com AND, e cada cláusula entre parênteses contém apenas comparações OR simples sem parênteses aninhados.

O campo findingsRefinements.query aceita as seguintes estruturas booleanas:

  • Uma única comparação ou uma sequência simples de comparações OR, como field_a = "val_1" OR field_b = "val_2".
  • Várias cláusulas unidas por AND (ou espaço em branco implícito AND), em que cada cláusula entre parênteses contém apenas comparações OR simples. Por exemplo, field_a = "val_1" AND (field_b = "val_2" OR field_c = "val_3").
  • Prefixo NOT antes de uma única comparação, como NOT principal.hostname = "scanner.example.com".

O campo findingsRefinements.query rejeita as seguintes estruturas booleanas com um erro 400 INVALID_ARGUMENT:

  • Parênteses aninhados, como A AND (B OR (C AND D)).
  • Operadores lógicos OR entre cláusulas entre parênteses, como (A AND B) OR (C AND D).

É possível reescrever a lógica aninhada, como A OR (B AND C), em CNF simples como (A OR B) AND (A OR C). Para condições complexas de OR de AND em que a expansão da CNF fica muito grande, crie recursos FindingsRefinement separados para cada ramificação AND.

Operadores e literais compatíveis

A tabela a seguir lista cada recurso de consulta, o suporte dele no findingsRefinements.query e um exemplo ou alternativa válida:

Recurso Suporte em findingsRefinements.query Exemplo ou alternativa
Operadores de comparação É compatível com =, !=, <, <=, > e >=. As comparações de string, expressão regular e mapa são compatíveis com = e !=. metadata.log_type = "WINDOWS_SYSMON"
Expressões regulares Aceita expressões regulares delimitadas por barra (/.../) em campos de string e mapa. principal.hostname = /^scanner-[0-9]+\.example\.com$/
Modificador que não diferencia maiúsculas de minúsculas Aceita nocase em comparações de strings e expressões regulares. Os campos de tipo enumerado não são compatíveis com nocase. principal.user.userid = "admin" nocase
Literais Oferece suporte a strings entre aspas duplas, números inteiros, pontos flutuantes, booleanos (true ou false) e literais de bytes base64 (b"..."). security_result.about.file.sha256 = "e3b0c4..."
Correspondência de intervalo CIDR Aceita a palavra-chave CIDR_RANGE em campos de endereço IP. principal.ip = CIDR_RANGE "192.0.2.0/24"
Funções YARA-L Não é compatível com funções YARA-L, como net.ip_in_range_cidr ou re.regex. Use CIDR_RANGE para sub-redes IP ou /.../ para expressões regulares.
Listas de referência e tabelas de dados Não é compatível com listas de referência (%list_name) ou pesquisas de tabelas de dados em consultas de exclusão. Enumere valores de enumeração com comparações simples de OR ou outcomeFilters.

Campos de UDM compatíveis e limites de profundidade de caminho

O campo findingsRefinements.query aplica as seguintes regras de campo UDM:

  • Os caminhos de campo aceitam no máximo seis segmentos separados por pontos, como target.process.file.sha256 (quatro segmentos) ou target.resource.attribute.labels["env"] (quatro segmentos).
  • Os caminhos de campo com sete ou mais segmentos separados por pontos falham na validação com um erro 400 INVALID_ARGUMENT (Not a valid field path). Por exemplo, target.process.file.signature_info.sigcheck.signers.name tem sete segmentos e é rejeitado.
  • Os campos de folha são compatíveis com os tipos de dados escalar (string, inteiro, flutuante e bool), enum e bytes.
  • Os campos de mapa e Label são compatíveis com pesquisas com chaves entre colchetes, como additional.fields["key"] = "value" e target.resource.attribute.labels["project"] = "prod".
  • Os aliases de pesquisa de UDM agrupados, como ip, hostname, user e hash, são compatíveis com caminhos de campo de evento de UDM completos.
  • Caminhos de gráfico de entidade (graph.*) e campos message sem chave não são compatíveis com consultas de exclusão.

Limitações

  • Todas as exclusões (com ou sem filtros de resultado) precisam especificar um campo query. Para criar uma exclusão usando apenas o campo outcomeFilters, inclua os campos FindingsRefinement obrigatórios e defina o campo query como uma expressão regular match-all:

    {
      "displayName": "Exclusion with only outcome filters",
      "type": "DETECTION_EXCLUSION",
      "query": "principal.hostname = /.*/",
      "outcomeFilters": [
        {
          "outcome_variable": "ip",
          "outcome_value": "127.0.0.1",
          "outcome_filter_operator": "EQUAL"
        }
      ]
    }
    

    A expressão regular corresponde a qualquer nome de host. Portanto, essa consulta corresponde a todas as detecções. Consequentemente, a filtragem eficaz é determinada apenas pelos filtros de resultado.

  • As exclusões não são compatíveis com uma configuração de time to live (TTL). No entanto, é possível criar um TTL único calculando o tempo de expiração específico e adicionando uma condição de carimbo de data/hora na definição de exclusão. Por exemplo, para definir uma exclusão que expira em 1º de janeiro de 2026, às 00:00 UTC (1767225600), especifique a consulta da seguinte maneira:

    {
      "displayName": "Exclusion with expiration timestamp",
      "type": "DETECTION_EXCLUSION",
      "query": "metadata.event_timestamp.seconds < 1767225600",
      "outcomeFilters": [
        {
          "outcome_variable": "ip",
          "outcome_value": "127.0.0.1",
          "outcome_filter_operator": "EQUAL"
        }
      ]
    }
    

    Inclua os outros campos FindingsRefinement obrigatórios e os filtros de resultado, conforme necessário. O exemplo anterior confirma que apenas as detecções criadas por eventos com um carimbo de data/hora anterior a 1º de janeiro de 2026, às 00h UTC (1767225600), são suprimidas.

    Observação: talvez isso não seja exibido corretamente na janela Editar exclusões da interface do usuário, porque ela só aceita campos string.

  • Regras compostas: não aplique uma exclusão de regra diretamente a uma regra composta. É necessário aplicar a exclusão às regras básicas que alimentam a regra composta. Isso ocorre porque as exclusões de regras são avaliadas em relação aos campos de UDM (como principal.user.userid), mas as regras compostas são acionadas com base em outras detecções, e não em campos de UDM. Se você aplicar uma exclusão de regra diretamente a uma regra composta, a exclusão não vai corresponder e o evento não será excluído.

    Para encontrar a regra básica, inspecione a definição da regra composta no console do Google SecOps (em Hub de conteúdo > Detecções especializadas) e analise a seção events: da lógica YARA-L para identificar os nomes das regras básicas.

  • Sintaxe de consulta e profundidade de campo: as consultas de exclusão precisam usar a sintaxe booleana simples de forma normal conjuntiva (CNF, na sigla em inglês) e caminhos de campo de UDM com no máximo seis segmentos separados por pontos. Para mais informações, consulte Sintaxe de consulta e regras de campo.

  • Regras personalizadas: não aplique uma exclusão de regra a uma regra personalizada. As exclusões de regras se aplicam apenas a regras e conjuntos de regras selecionados que usam os campos curatedRules e curatedRuleSets. Se você incluir rules em detectionExclusionApplication, a API vai ignorar o campo sem aplicar a exclusão. Para suprimir alertas de regras personalizadas, adicione lógica de exclusão à definição de regra YARA-L ou use tabelas de dados para manter listas de exclusão em várias regras. Para mais informações, consulte Filtrar dados de eventos e entidades do UDM usando uma tabela de dados e Exemplos de anti-join à esquerda em regras.

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