Administra las exclusiones de reglas

Compatible con:

En este documento, se explica cómo administrar de manera 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 detecciones específicas generen alertas. 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 manera 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

Extremo:

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

Reemplaza lo siguiente:

REGION: Es la región de Google Cloud para 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, 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.0.1",
      "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 están vinculados por una cláusula AND implícita.

Campos obligatorios: displayName, type, query

Campos generados por el sistema: No especifiques name, createTime ni updateTime. El sistema administra estos campos, que 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 como 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 los filtros de consulta o resultado exactos que contiene.

Método: GET

Extremo: 

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

Reemplaza lo siguiente:

REGION: Es la región de Google Cloud para 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, 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

Aplica una exclusión a una regla o un conjunto de reglas

Debes aplicar la exclusión a reglas específicas o conjuntos de reglas seleccionados. Cuando aplicas la exclusión a una regla o 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 de FindingsRefinementDeployment se deben actualizar.

Método: PATCH

Extremo:

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

Reemplaza lo siguiente:

REGION: Es la región de Google Cloud para 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, la misma que la región).

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

REFINEMENT_ID: Es el 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": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/<var>CATEGORY_ID</var>/curatedRuleSets/<var>RULE_SET_ID</var>"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/<var>CURATED_RULE_ID</var>"
    ],
    "rules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/rules/<var>RULE_ID</var>"
    ]
  }
}

En el cuerpo de la solicitud, especifica las listas de nombres de recursos de conjuntos de reglas seleccionadas, reglas seleccionadas y reglas en curatedRuleSets, curatedRules y rules reemplazando CATEGORY_ID, RULE_SET_ID, CURATED_RULE_ID y RULE_ID.

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

Accede a la implementación de la exclusión

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

Método: GET

Extremo:

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

Reemplaza lo siguiente:

REGION: Es la región de Google Cloud para 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, la misma que la región).

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

REFINEMENT_ID: Es el 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 extremo para recuperar la lista de recursos findingsRefinements.

Método: GET

Extremo:

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

Reemplaza lo siguiente:

REGION: Es la región de Google Cloud para 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, 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 el siguiente extremo para obtener la lista de recursos de FindingsRefinement creados en tu instancia.

Método: GET

Extremo:

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

Reemplaza lo siguiente:

REGION: Es la región de Google Cloud para 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, 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 que tienen exclusiones aplicadas.

Prueba una exclusión con la API

El siguiente extremo prueba la exclusió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 los últimos 30 días de detecciones para las pruebas.

Método: POST

Extremo:

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

Reemplaza lo siguiente:

REGION: Es la región de Google Cloud para 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, 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.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/<var>CATEGORY_ID</var>/curatedRuleSets/<var>RULE_SET_ID</var>"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/<var>CURATED_RULE_ID</var>"
    ],
    "rules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/rules/<var>RULE_ID</var>"
    ]
  }
}

Este extremo 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 qué tan eficaz es la exclusión para suprimir las detecciones que no deberían generarse. El sistema usa las detecciones de los últimos 30 días como el período para probar las exclusiones. En el ejemplo anterior, el campo interval prueba las detecciones desde el 1 de septiembre de 2025 a las 00:00 UTC (1756684800) hasta el 1 de octubre de 2025 a las 00:00 UTC (1759276800), y detectionExclusionApplication especifica los nombres de los recursos con los que se realizarán las pruebas reemplazando CATEGORY_ID, RULE_SET_ID, CURATED_RULE_ID y RULE_ID.

Sintaxis de consulta y reglas de campo

El campo findingsRefinements.query admite un subconjunto restringido de la sintaxis de YARA-L 2.0 en lugar de la sintaxis completa de la búsqueda de UDM (udmSearch). Debido a que estas dos sintaxis de consulta difieren, una consulta que se ejecuta correctamente en udmSearch puede fallar con un error 400 INVALID_ARGUMENT en una exclusión.

En las siguientes secciones, se describen las reglas de sintaxis para el campo findingsRefinements.query:

Para validar una consulta de exclusión antes de la implementación, llama al extremo testFindingsRefinement en lugar de udmSearch.

Gramática booleana

El campo findingsRefinements.query requiere una sintaxis booleana de forma normal conjuntiva (CNF) plana. En la CNF plana, unes una o más cláusulas con AND, y cada cláusula entre paréntesis contiene solo comparaciones OR planas sin paréntesis anidados.

El campo findingsRefinements.query admite las siguientes estructuras booleanas:

  • Una sola comparación o una secuencia plana de comparaciones OR, como field_a = "val_1" OR field_b = "val_2".
  • Varias cláusulas unidas por AND (o espacio en blanco implícito AND), en las que cada cláusula entre paréntesis contiene solo comparaciones OR planas. Por ejemplo, field_a = "val_1" AND (field_b = "val_2" OR field_c = "val_3")
  • Agrega el prefijo NOT antes de una sola comparación, como NOT principal.hostname = "scanner.example.com".

El campo findingsRefinements.query rechaza las siguientes estructuras booleanas con un error 400 INVALID_ARGUMENT:

  • Paréntesis anidados, como A AND (B OR (C AND D))
  • Operadores lógicos OR entre cláusulas entre paréntesis, como (A AND B) OR (C AND D).

Puedes reescribir la lógica anidada, como A OR (B AND C), en una CNF plana como (A OR B) AND (A OR C). Para condiciones complejas de OR de AND en las que la expansión de CNF crece demasiado, crea recursos FindingsRefinement independientes para cada rama AND.

Operadores y literales admitidos

En la siguiente tabla, se enumeran cada función de consulta, su compatibilidad con findingsRefinements.query y un ejemplo o una alternativa válidos:

Función Asistencia en findingsRefinements.query Ejemplo o alternativa
Operadores de comparación Admite =, !=, <, <=, > y >=. Las comparaciones de cadenas, expresiones regulares y mapas admiten = y !=. metadata.log_type = "WINDOWS_SYSMON"
Expresiones regulares Admite expresiones regulares delimitadas por barras (/.../) en campos de cadena y mapa. principal.hostname = /^scanner-[0-9]+\.example\.com$/
Modificador que no distingue mayúsculas de minúsculas Admite nocase en comparaciones de cadenas y expresiones regulares. Los campos de enumeración no admiten nocase. principal.user.userid = "admin" nocase
Literales Admite cadenas entre comillas dobles, números enteros, números de punto flotante, valores booleanos (true o false) y literales de bytes en base64 (b"..."). security_result.about.file.sha256 = "e3b0c4..."
Coincidencia de rango CIDR Admite la palabra clave CIDR_RANGE en los campos de dirección IP. principal.ip = CIDR_RANGE "192.0.2.0/24"
Funciones de YARA-L No admite funciones de YARA-L, como net.ip_in_range_cidr o re.regex. Usa CIDR_RANGE para las subredes de IP o /.../ para las expresiones regulares.
Listas de referencia y tablas de datos No admite la lista de referencias (%list_name) ni las búsquedas en tablas de datos en las consultas de exclusión. Enumera los valores con comparaciones OR planas o outcomeFilters.

Campos de UDM admitidos y límites de profundidad de ruta

El campo findingsRefinements.query aplica las siguientes reglas de campo de UDM:

  • Las rutas de acceso de campo admiten un máximo de 6 segmentos separados por puntos, como target.process.file.sha256 (4 segmentos) o target.resource.attribute.labels["env"] (4 segmentos).
  • Las rutas de acceso de campo con 7 o más segmentos separados por puntos no se validan y muestran un error 400 INVALID_ARGUMENT (Not a valid field path). Por ejemplo, target.process.file.signature_info.sigcheck.signers.name tiene 7 segmentos y se rechaza.
  • Los campos de hoja admiten tipos de datos escalares (string, entero, flotante y bool), enum y bytes.
  • Los campos de mapa y Label admiten búsquedas con claves entre corchetes, como additional.fields["key"] = "value" y target.resource.attribute.labels["project"] = "prod".
  • Los alias de búsqueda de UDM agrupados, como ip, hostname, user y hash, se admiten junto con las rutas de acceso completas de los campos de eventos de UDM.
  • Las rutas de acceso del grafo de entidades (graph.*) y los campos message sin clave no se admiten en las consultas de exclusión.

Limitaciones

  • Todas las exclusiones (con o sin filtros de resultados) deben especificar un campo query. Para crear una exclusión con solo el campo outcomeFilters, incluye los campos FindingsRefinement obligatorios y establece el campo query en una expresión 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"
    }
  ]
}

    La expresión regular coincide con cualquier nombre de host. Por lo tanto, esta consulta coincide con todas las detecciones. Por lo tanto, el filtrado efectivo se determina solo por los filtros de resultados.

  • Las exclusiones no admiten una configuración de tiempo de actividad (TTL). Sin embargo, puedes crear un TTL único calculando el tiempo de vencimiento específico y agregando una condición de marca de tiempo en la definición de exclusión. Por ejemplo, para establecer que una exclusión venza el 1 de enero de 2026 a las 00:00 UTC (1767225600), especifica la consulta de la siguiente manera:

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

    Incluye los otros campos obligatorios de FindingsRefinement y tus filtros de resultados según sea necesario. En el ejemplo anterior, se confirma que solo se suprimen las detecciones creadas por eventos con una marca de tiempo anterior al 1 de enero de 2026 a las 00:00 UTC (1767225600).

    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.

  • Reglas compuestas: No apliques una exclusión de regla directamente a una regla compuesta. Debes aplicar la exclusión a las reglas subyacentes fundamentales que se incorporan a la regla compuesta. Esto se debe a que las exclusiones de reglas se evalúan en función de los campos de UDM (como principal.user.userid), pero las reglas compuestas se activan en función de otras detecciones, no de los campos de UDM. Si aplicas una exclusión de regla directamente a una regla compuesta, la exclusión no coincidirá y el evento no se excluirá.

    Para encontrar la regla fundamental, puedes inspeccionar la definición de la regla compuesta en la consola de Google SecOps (en Centro de contenido > Detecciones seleccionadas) y revisar la sección events: de la lógica de YARA-L para identificar los nombres de las reglas fundamentales.

  • Sintaxis de consulta y profundidad de campo: Las consultas de exclusión deben usar la sintaxis booleana de forma normal conjuntiva (CNF) plana y las rutas de campo de UDM con un máximo de 6 segmentos separados por puntos. Para obtener más información, consulta Sintaxis de consultas y reglas de campos.

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