Gerenciar exclusões de regras
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
ipcom um valor de127.0.0.1.Uma variável de resultado
hostnamescom pelo menos um dos valores agregados sendoaltostrat.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-idespecí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
pageSizeepageTokenpara listar mais resultados semelhantes a outros endpoints de lista na API.Use o parâmetro
filterpara filtrar pordetection_exclusion_application.curated_rulesoudetection_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:
- Gramática booleana
- Operadores e literais compatíveis
- Campos UDM compatíveis e limites de profundidade de caminho
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, comofield_a = "val_1" OR field_b = "val_2". - Várias cláusulas unidas por
AND(ou espaço em branco implícitoAND), em que cada cláusula entre parênteses contém apenas comparaçõesORsimples. Por exemplo,field_a = "val_1" AND (field_b = "val_2" OR field_c = "val_3"). - Prefixo
NOTantes de uma única comparação, comoNOT 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
ORentre 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) outarget.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.nametem sete segmentos e é rejeitado. - Os campos de folha são compatíveis com os tipos de dados escalar (
string, inteiro, flutuante ebool),enumebytes. - Os campos de mapa e
Labelsão compatíveis com pesquisas com chaves entre colchetes, comoadditional.fields["key"] = "value"etarget.resource.attribute.labels["project"] = "prod". - Os aliases de pesquisa de UDM agrupados, como
ip,hostname,userehash, são compatíveis com caminhos de campo de evento de UDM completos. - Caminhos de gráfico de entidade
(
graph.*) e camposmessagesem 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 campooutcomeFilters, inclua os camposFindingsRefinementobrigatórios e defina o campoquerycomo uma expressão regularmatch-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
FindingsRefinementobrigató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
curatedRulesecuratedRuleSets. Se você incluirrulesemdetectionExclusionApplication, 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.