Administra la exclusión de reglas con la API

Se admite en los siguientes sistemas operativos:

En este documento, se explica cómo administrar de forma programática las exclusiones de reglas en Google Security Operations con la API. Las exclusiones funcionan como filtros que defines según los campos del Modelo de datos unificado (UDM) para evitar que se generen alertas por detecciones específicas. Al identificar actividades conocidas o seguras, estos filtros detienen el ruido innecesario en tu panel.

Crea una exclusión con filtros de resultados

Puedes crear una nueva regla de exclusión de forma programática para suprimir hallazgos de detección específicos que coincidan con los criterios definidos, lo que reduce el ruido y prioriza las alertas de alta fidelidad.

Usa el extremo POST para definir la lógica de supresión. Todos los filtros con el array outcomeFilters están vinculados por una cláusula AND implícita.

Método: POST

Endpoint:

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

Reemplaza lo siguiente:

REGION: Es la Google Cloud región de la instancia de Google SecOps.

PROJECT_ID: Es el ID del proyecto de Google Cloud .

LOCATION: Es la ubicación de la instancia de Google SecOps (a menudo, es la misma que la región).

INSTANCE_ID: Es el ID de la instancia de Google SecOps.

Ejemplo:

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

Cuerpo de la solicitud:

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

En el ejemplo, se muestra cómo definir la lógica de supresión en la que varios filtros del array outcomeFilters se vinculan con una cláusula AND implícita.

Campos obligatorios: displayName, type, query

Campos generados por el sistema: No especifiques name, createTime ni updateTime. El sistema los administra y se ignoran o causan errores si se incluyen en la solicitud.

La lógica de supresión sigue una relación AND. La solicitud crea una exclusión que suprime cualquier detección que tenga un evento con lo siguiente:

  • "altostrat.com" como el nombre de host principal

  • Una variable de resultado ip con un valor de 127.0.0.1

  • Una variable de resultado hostnames con al menos uno de sus valores agregados igual a altostrat.com.

Todos los filtros especificados en la exclusión se vinculan de forma implícita con una cláusula AND.

Respuesta de la API: La API devuelve el nombre del recurso FindingsRefinement.

El recurso FindingsRefinement contiene la lógica de supresión principal (los filtros de consulta y resultado). El nombre del recurso (ID) se usa para las operaciones posteriores en la exclusión.

Cómo acceder a una exclusión

Usa el extremo GET para hacer lo siguiente:

  • Obtén los detalles de una sola definición de exclusión por su ID único.

  • Cuando tienes un refinement-id específico y necesitas verificar la búsqueda exacta o los filtros de resultados que contiene.

Método: GET

Endpoint: 

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

Reemplaza lo siguiente:

REGION: Es la Google Cloud región de la instancia de Google SecOps.

PROJECT_ID: Es el ID del proyecto de Google Cloud .

LOCATION: Es la ubicación de la instancia de Google SecOps (a menudo, es la misma que la región).

INSTANCE_ID: Es el ID de la instancia de Google SecOps.

Ejemplo:

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

Cómo aplicar una exclusión a una regla o un conjunto de reglas

Debes aplicar la exclusión a reglas específicas o a conjuntos de reglas seleccionados. Cuando aplicas la exclusión a una regla o a un conjunto de reglas, se crea un recurso FindingsRefinementDeployment. Puedes usar este recurso para determinar las reglas personalizadas, las reglas seleccionadas o los conjuntos de reglas seleccionadas que se aplican al recurso FindingsRefinement. Luego, puedes especificar el parámetro update_mask en la solicitud a la API para indicar qué campos del FindingsRefinementDeployment se deben actualizar.

Método: PATCH

Endpoint:

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

Reemplaza lo siguiente:

REGION: Es la Google Cloud región de la instancia de Google SecOps.

PROJECT_ID: Es el ID del proyecto de Google Cloud .

LOCATION: Es la ubicación de la instancia de Google SecOps (a menudo, es la misma que la región).

INSTANCE_ID: Es el ID de la instancia de Google SecOps.

REFINEMENT_ID: ID único del perfeccionamiento de hallazgos.

Ejemplo:

 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

Cuerpo de la solicitud:


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

Cuando aplicas la exclusión a una regla o a un conjunto de reglas, el sistema crea un recurso FindingsRefinementDeployment. Este recurso determina qué reglas personalizadas, reglas seleccionadas y conjuntos de reglas seleccionados se aplican al recurso FindingsRefinement. También puedes incluir el parámetro update_mask en la solicitud a la API para especificar qué campos del FindingsRefinementDeployment se deben actualizar.

Accede a la implementación de la exclusión

Después de crear o actualizar una exclusión, usa este endpoint para verificar en qué reglas o conjuntos de reglas se implementó esa exclusión específica.

Método: GET

Endpoint:

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

Reemplaza lo siguiente:

REGION: Es la Google Cloud región de la instancia de Google SecOps.

PROJECT_ID: Es el ID del proyecto de Google Cloud .

LOCATION: Es la ubicación de la instancia de Google SecOps (a menudo, es la misma que la región).

INSTANCE_ID: Es el ID de la instancia de Google SecOps.

REFINEMENT_ID: ID único del perfeccionamiento de hallazgos.

Ejemplo:

   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

Enumera todas las exclusiones

Usa este endpoint para recuperar la lista de recursos findingsRefinements.

Método: GET

Endpoint:

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

Reemplaza lo siguiente:

REGION: Es la Google Cloud región de la instancia de Google SecOps.

PROJECT_ID: Es el ID del proyecto de Google Cloud .

LOCATION: Es la ubicación de la instancia de Google SecOps (a menudo, es la misma que la región).

INSTANCE_ID: Es el ID de la instancia de Google SecOps.

Ejemplo:

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

Parámetros de consulta opcionales: pageSize, pageToken

Puedes usar los parámetros opcionales para enumerar más resultados similares a otros extremos de lista dentro de la API.

Enumera todas las implementaciones de exclusión

Usa este extremo para obtener la lista de recursos de FindingsRefinement creados en tu instancia.

Método: GET

Endpoint:

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

Reemplaza lo siguiente:

REGION: Es la Google Cloud región de la instancia de Google SecOps.

PROJECT_ID: Es el ID del proyecto de Google Cloud .

LOCATION: Es la ubicación de la instancia de Google SecOps (a menudo, es la misma que la región).

INSTANCE_ID: Es el ID de la instancia de Google SecOps.

Ejemplo:

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

Parámetros de consulta opcionales:

  • Usa los parámetros pageSize y pageToken para enumerar más resultados similares a otros extremos de lista dentro de la API.

  • Usa el parámetro filter para filtrar las reglas o los conjuntos de reglas a los que se les aplicaron exclusiones.

Prueba una exclusión con la API

Este endpoint prueba la exclusión en relación con las detecciones de las reglas y los conjuntos de reglas especificados y, luego, valida la eficacia de la exclusión para suprimir las detecciones no deseadas. La IU usa las detecciones de los últimos 30 días para las pruebas.

Método: POST

Endpoint:

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

Reemplaza lo siguiente:

REGION: Es la Google Cloud región de la instancia de Google SecOps.

PROJECT_ID: Es el ID del proyecto de Google Cloud .

LOCATION: Es la ubicación de la instancia de Google SecOps (a menudo, es la misma que la región).

INSTANCE_ID: Es el ID de la instancia de Google SecOps.

Ejemplo:

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

Cuerpo de la solicitud:

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

Este endpoint prueba la exclusión en las detecciones que se generaron en las reglas y los conjuntos de reglas especificados en la solicitud. Ayuda a determinar la eficacia de la exclusión para suprimir las detecciones que no se deberían generar. El sistema usa las detecciones de los últimos 30 días como el período para probar las exclusiones.

Limitaciones

  • Todas las exclusiones (con o sin filtros de resultados) deben especificar un campo query. Para crear una exclusión solo con outcomeFilters, especifica una expresión regular match-all.

    
  ...other fields in FindingsRefinement

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

  outcomeFilters: [ your outcome filters ]

    La expresión regular coincide con cualquier nombre de host. Por lo tanto, esta búsqueda coincide con todas las detecciones. Por lo tanto, el filtrado efectivo se determina únicamente por los filtros de resultado.

  • Las exclusiones no admiten una configuración de tiempo de actividad (TTL). Sin embargo, puedes crear un TTL único si calculas la hora de vencimiento específica y agregas una condición de marca de tiempo en la definición de exclusión. Por ejemplo, para configurar una exclusión que venza a fin de año, especifica la consulta de la siguiente manera:

    
  ...other fields in FindingsRefinement

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

  outcomeFilters: [your outcome filters]

    En este ejemplo, se confirma que solo se suprimen las detecciones creadas por eventos con una marca de tiempo anterior al final del año.

    Nota: Es posible que esto no se muestre correctamente en la ventana Editar exclusiones de la interfaz de usuario, ya que solo admite campos string.

¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.