Gerenciar a exclusão de regras usando a API

Compatível com:

Este documento explica como gerenciar exclusões de regras de maneira programática no Google Security Operations usando a API. As exclusões funcionam como filtros que você define com base nos campos do modelo de dados unificado (UDM) para impedir que detecções específicas gerem alertas. Ao identificar atividades conhecidas ou seguras, esses filtros evitam 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

Substitua:

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

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: a localização da instância do Google SecOps (geralmente a mesma da 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.01",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ]
}

O exemplo demonstra como definir uma 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 implicitamente vinculados por uma cláusula AND.

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

O recurso FindingsRefinement contém a lógica principal de supressão (os filtros de consulta e resultado). O nome (ID) do recurso é usado em 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

Substitua:

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

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: a localização da instância do Google SecOps (geralmente a mesma da 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/fr_00001111-2222-3333-4444-555566667777

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

É preciso aplicar a exclusão a regras específicas ou conjuntos de regras selecionados. Quando você aplica a exclusão a uma regra ou conjunto de regras, um recurso FindingsRefinementDeployment é criado. Use esse recurso para determinar as regras personalizadas, selecionadas ou conjuntos de regras selecionadas que se aplicam ao recurso FindingsRefinement. Em seguida, especifique o parâmetro update_mask na solicitação de API para indicar quais campos no FindingsRefinementDeployment atualizar.

Método: PATCH

Endpoint:

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

Substitua:

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

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: a localização da instância do Google SecOps (geralmente a mesma da região).

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

REFINEMENT_ID: o ID exclusivo do refinamento de descobertas.

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?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"
  "enabled": true,
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      ...list curated rule set resource names
    ],
    "curatedRules": [
      ...list curated rule resource names
    ],
    "rules": [
      ...list rule resource names
    ],
  }
}

Quando você aplica a exclusão a uma regra ou um conjunto de regras, o sistema cria um recurso FindingsRefinementDeployment. Esse recurso determina quais regras personalizadas, selecionadas e conjuntos de regras selecionadas se aplicam ao recurso FindingsRefinement. Você também pode incluir o parâmetro update_mask na solicitação de API para especificar quais campos no FindingsRefinementDeployment atualizar.

Acessar a implantação da exclusão

Depois de criar ou atualizar uma exclusão, use este endpoint para verificar em quais regras ou conjuntos de regras essa exclusão específica está implantada.

Método: GET

Endpoint:

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

Substitua:

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

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: a localização da instância do Google SecOps (geralmente a mesma da 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 este endpoint para extrair 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 Google Cloud região da instância do Google SecOps.

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: a localização da instância do Google SecOps (geralmente a mesma da 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

Você pode 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 este endpoint para receber a lista de recursos FindingsRefinement criados na sua instância.

Método: GET

Endpoint:

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

Substitua:

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

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: a localização da instância do Google SecOps (geralmente a mesma da 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 as regras ou conjuntos de regras que têm exclusões aplicadas.

Testar uma exclusão usando a API

Esse endpoint testa a exclusão em relação às detecções das regras e conjuntos de regras especificados e valida a eficácia da exclusão na supressão de detecções indesejadas. A interface usa as detecções dos últimos 30 dias para testes.

Método: POST

Endpoint:

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

Substitua:

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

PROJECT_ID: o ID do projeto do Google Cloud .

LOCATION: a localização da instância do Google SecOps (geralmente a mesma da região).

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

Exemplo:

POST https://us-chronicle.googleapis.com/v1/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.01",
      "outcome_filter_operator": "EQUAL",
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS",
    },
  ]
  "interval": {
    "start_time": {
      "seconds": 1756684800, // Sep. 1 2025 00:00 UTC
    },
    "end_time": {
      "seconds": 1759276800, // Oct. 1 2025 00:00 UTC
    },
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      ...curated rule set resource names
    ],
    "curatedRules": [
      ...curated rule resource names
    ],
    "rules": [
      ...rule resource names
    ],
  }
}

Esse endpoint testa a exclusão em detecções geradas nas regras e conjuntos de regras especificados na solicitação. Ela ajuda a determinar a eficácia da exclusão na supressão de detecções que não deveriam ser geradas. O sistema usa os últimos 30 dias de detecções como o período para testar as exclusões.

Limitações

  • Todas as exclusões (com ou sem filtros de resultado) precisam especificar um campo query. Para criar uma exclusão apenas com outcomeFilters, especifique uma expressão regular match-all.

    
  ...other fields in FindingsRefinement

  query: "principal.hostname = /.*/"

  outcomeFilters: [ your outcome filters ]

    A expressão regular corresponde a qualquer nome de host. Portanto, essa consulta corresponde a todas as detecções. Consequentemente, a filtragem efetiva é 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 prazo de validade 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 expire no final do ano, especifique a consulta da seguinte maneira:

    
  ...other fields in FindingsRefinement

  query: "metadata.event_timestamp.seconds < 1767225600" // Jan 1 2026 00:00 UTC

  outcomeFilters: [your outcome filters]

    Este exemplo confirma que apenas as detecções criadas por eventos com um carimbo de data/hora anterior ao fim do ano são suprimidas.

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

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