Cómo usar extensiones del analizador

Google Security Operations proporciona varios métodos para definir cómo se analizan y normalizan los datos de los registros sin procesar originales en un registro del modelo de datos unificado (UDM).

• Sin embargo, los analizadores predeterminados son instrucciones de asignación de datos precompiladas que administra Google Security Operations y que asignan los datos de registro sin procesar originales a los campos de la UDM.
• Analizadores personalizados: Instrucciones de asignación de datos personalizadas que crea y administra un cliente que satisface las necesidades específicas de análisis de datos del cliente.
• Extensiones del analizador: Instrucciones adicionales de asignación de datos que extienden un analizador predeterminado o personalizado para asignar campos adicionales en el registro sin procesar original. Esto no reemplaza por completo un analizador predeterminado o personalizado, sino que extiende las instrucciones de asignación existentes en un analizador predeterminado o personalizado.

En este documento, se describe cómo usar las extensiones del analizador.

Antes de comenzar

En los siguientes documentos, se explican los conceptos previos que es importante conocer cuando se trabaja con extensiones de analizador:

• Descripción general del modelo de datos unificado
• Descripción general del análisis de registros
• Referencia de sintaxis del analizador

Acerca de las extensiones del analizador

Una extensión del analizador te permite crear instrucciones de asignación adicionales además de las definidas en un analizador predeterminado o personalizado para satisfacer un caso de uso único. El objetivo de esta función es extender un analizador predeterminado o personalizado existente. Una extensión de analizador no reemplaza un analizador predeterminado o personalizado. No puedes crear un analizador nuevo con una extensión de analizador.

La extensión del analizador lee el registro sin procesar original y, luego, inserta los valores extraídos en campos específicos del registro de la AUA. El registro de la UDM contiene datos que establecen el analizador predeterminado o personalizado y la extensión del analizador.

Las instrucciones de asignación de datos en una extensión de analizador tienen prioridad sobre las de un analizador predeterminado o personalizado. Si hay un conflicto en las instrucciones de asignación, la extensión del analizador reemplazará un valor establecido por el analizador predeterminado o personalizado. Por ejemplo, si el analizador predeterminado asigna un campo de registro sin procesar al campo de UDM event.metadata.description y la extensión del analizador asigna un campo de registro sin procesar diferente al mismo campo de UDM, la extensión del analizador reemplazará el valor establecido por el analizador predeterminado. Una excepción es con los campos repetidos. Puedes configurar la extensión del analizador para que agregue valores cuando escribas datos en un campo repetido.

Creas una extensión de analizador por tipo de registro. Cada tipo de registro se identifica con una etiqueta de transferencia única. Consulta Analizador predeterminado admitido para obtener una lista de los tipos de registros.

Para crear una extensión de analizador, Google Security Operations debe poder transferir y normalizar los registros sin procesar originales con un analizador predeterminado o personalizado. La extensión del analizador extrae datos adicionales del registro sin procesar original y, luego, los combina en el registro de la AUA.

Las extensiones del analizador admiten los siguientes tipos de instrucciones de asignación:

• Tipo de fragmento de código: Escribes código de analizador similar a los analizadores predeterminados y personalizados. Los registros sin procesar originales pueden estar en cualquiera de los formatos de datos compatibles para el tipo de registro.
• Tipo de campo de datos: Especifica los campos de origen y destino en la interfaz de la aplicación. Los registros sin procesar originales deben tener uno de los siguientes formatos:
  • JSON, XML o CSV nativos
  • Encabezado de Syslog más JSON, XML o CSV nativos Puedes crear una instrucción de asignación de tipo de campo de datos para un subconjunto de tipos de registro en Análisis de sintaxis predeterminados compatibles. Busca los que tengan el formato JSON, XML, CSV, SYSLOG + JSON, SYSLOG + XML y SYSLOG + CSV.

Ten en cuenta lo siguiente cuando crees una extensión de analizador:

• Los datos se pueden asignar a cualquier campo de la AUA que admita los tipos de datos estándar y los valores repetidos.
• No puedes asignar datos a los siguientes campos del UDM:
  • event.idm.read_only_udm.additional
  • event.idm.graph.entity.additional
• Antes de crear una instrucción de asignación de datos, asegúrate de que tu instancia de Google Security Operations haya transferido registros sin procesar originales en los últimos 30 días para el tipo de registro y de que estos registros sin procesar contengan el campo que planeas definir en los criterios de condición previa. Estos registros sin procesar originales se usan para validar las instrucciones de asignación de datos.
• Una vez que se publique una extensión de analizador, comenzará a analizar los datos entrantes. No puedes analizar datos de registro sin procesar de forma retroactiva.

Ciclo de vida de una extensión del analizador

Las extensiones del analizador tienen un ciclo de vida con los siguientes estados:

• DRAFT: Extensión de analizador recién creada que aún no se envió.
• VALIDATING: Google Security Operations valida las instrucciones de asignación en función de los registros sin formato existentes para garantizar que los campos se analicen sin errores.
• LIVE: La extensión del analizador pasó la validación y ahora está en producción. Extrae y transforma datos de registros sin procesar entrantes en registros de la AUA.
• FAILED: La extensión del analizador no pudo validar.

Abre la página Extensiones del analizador.

Sigue los pasos de una de las siguientes secciones para acceder a la página Extensiones de analizador.

Cómo comenzar desde la barra de navegación

1. En la barra de navegación, selecciona Configuración, Configuración de SIEM y, luego, Análisis.
2. Identifica el tipo de registro que deseas extender en la tabla Parsers.
3. Navega a esa fila y, luego, haz clic en el menú more_vert.
4. Haz clic en Create Extension.

Cómo comenzar desde la búsqueda de registros sin procesar

1. Usa la Búsqueda de registros sin procesar para buscar registros similares a los que se analizarán.
2. Selecciona un evento en el panel Eventos > Cronograma.
3. Expande el panel Datos del evento.
4. Haz clic en el botón Administrar analizador.
5. En el diálogo Manage Parser, selecciona Create Extension y, luego, haz clic en Next. Se abrirá la página Parser Extensions en modo de edición. Puedes comenzar a definir la extensión del analizador.

Crea una nueva extensión de analizador

En esta sección, se describe cómo crear una extensión de analizador después de abrir la página Extensiones de analizador. Los campos disponibles en la página Parser Extensions diferirán según la estructura del registro sin procesar.

1. Revisa el ejemplo de signo sin procesar en el panel Raw Log para confirmar que sea representativo de los registros que procesará la extensión del analizador. Usa el ejemplo de registro sin procesar como referencia cuando crees la extensión del analizador.

   • Si navegaste a la página Parser Extensions desde la Búsqueda de registros sin procesar, el panel mostrará el registro sin procesar original que seleccionaste en los resultados de la búsqueda.

   • Si navegaste a la página Parser Extensions en la barra de navegación, se mostrará un registro sin procesar de muestra para ese tipo de registro.

2. Elige el Método de extensión. Selecciona una de las siguientes opciones:

   • Asigna campos de datos: Crea una asignación de campos de datos. Usa los campos de la aplicación para definir el campo de registro sin procesar original y el campo de la UDM de destino.

   • Escribe un fragmento de código: Crea un fragmento de código para todos los formatos de registro compatibles. El fragmento de código usa la misma sintaxis de analizador que los analizadores predeterminados y personalizados. Para obtener más información sobre la sintaxis del analizador, consulta Sintaxis del analizador.

Continúa con una de las siguientes sub secciones específicas del Método de extensión seleccionado.

• Cómo crear una instrucción de asignación de campos de datos
• Cómo crear una instrucción de asignación de fragmentos de código

Crea una instrucción de asignación de campos de datos

Crea una instrucción de asignación de campos de datos cuando los registros sin procesar entrantes están en formato JSON, XML, CSV, encabezado de Syslog más JSON, encabezado de Syslog más XML o encabezado de Syslog más CSV. Define la ruta de acceso al nombre del campo original y el campo de UDM de destino en la instrucción de asignación de datos.

1. En el selector Campos repetidos, especifica cómo la extensión del analizador guarda un valor en campos que admiten un array de valores.

   • Agregar valores: El valor se agrega al conjunto existente de valores almacenados en el campo.
   • Reemplaza valores: El valor reemplaza todos los valores almacenados anteriormente por el nuevo.

   Algunos campos de la UDM, como principal.ip y entity.asset.hostname, almacenan un array de valores. Estos campos repetidos se identifican con la etiqueta repeated en la lista de campos del modelo de datos unificado. Para obtener información más detallada, consulta Selector de campos repetidos.

2. Si aparecen los campos Syslog y Target, Google Security Operations detectó que el registro sin procesar incluye un encabezado de Syslog.

   Si Google Security Operations identifica que el ejemplo de registro sin procesar no es JSON, XML ni CSV nativo, y tiene un encabezado de Syslog, muestra los campos Syslog y Destino. Usa los siguientes campos para definir un Grok y patrones de expresiones regulares que procesen previamente el encabezado de Syslog y extraigan la parte estructurada del registro. La parte estructurada del registro se puede asignar con campos de datos.

   • Campo Syslog: Especifica el patrón de extracción, con Grok y expresiones regulares, que identifica el encabezado de Syslog y el mensaje de registro sin procesar.
   • Campo Target: Especifica el nombre de la variable en el patrón de extracción que almacena la parte estructurada del registro.

   Para obtener información sobre cómo definir un patrón de extracción con Grok y expresiones regulares, consulta Define los campos del extractor de Syslog.

   En la siguiente imagen, se proporciona un ejemplo de cómo agregar un patrón de extracción y un nombre de variable a los campos Syslog y Target, respectivamente.

   

   Los campos Syslog y Target son obligatorios y funcionan juntos para separar el encabezado de Syslog de la parte estructurada del registro.

3. Después de ingresar valores en los campos Syslog y Target, haz clic en el botón Validate. El proceso de validación verifica los errores de sintaxis y análisis y, luego, muestra una de las siguientes opciones:

   • Éxito: Aparecerán los campos de asignación de datos. Define el resto de la extensión del analizador.
   • Error: Aparece un mensaje de error. Corrige la condición de error antes de continuar.

4. De manera opcional, define una instrucción de precondición.

   La instrucción de precondición identifica solo un subconjunto de registros sin procesar originales que la extensión del analizador procesa haciendo coincidir un valor estático con un campo en el registro sin procesar. Si un registro sin procesar entrante cumple con los criterios de la condición previa, es decir, si los valores coinciden, la extensión del analizador aplica la instrucción de asignación. Si los valores no coinciden, la extensión del analizador no aplica la instrucción de asignación.

   Completa los siguientes campos:

   • Campo de condición previa: Ingresa la ruta de acceso completa al campo si el formato de datos de registro es JSON o XML, o la posición de la columna si el formato de datos es CSV.
   • Operador de condición previa: Selecciona EQUALS o NOT EQUALS.
   • Valor de la precondición: Ingresa el valor que debe coincidir con los datos del campo de precondición.

5. Define la instrucción de asignación de datos:

   • Campo de datos sin procesar: Ingresa la ruta de acceso completa al campo si el formato de datos de registro es JSON o XML, o la posición de la columna si el formato de datos es CSV.
   • Campo de destino: Ingresa el nombre de campo de la AUA completamente calificado en el que se almacenará el valor, por ejemplo, udm.metadata.collected_timestamp.seconds.

6. Haz clic en Enviar para guardar la instrucción de asignación.

7. Google Security Operations valida la instrucción de asignación.

   • Si el proceso de validación se realiza correctamente, el estado cambia a En vivo y la instrucción de asignación comienza a procesar los datos de registro entrantes.
   • Si el proceso de validación falla, el estado cambia a Falló y se muestra un error en el campo Registro sin procesar.

   El siguiente es un ejemplo de error de validación.

   ERROR: generic::unknown: pipeline.ParseLogEntry failed: LOG_PARSING_CBN_ERROR:
   "generic::invalid_argument: pipeline failed: filter mutate (7) failed: copy failure:
   copy source field \"jsonPayload.dest_instance.region\" must not be empty
   (try using replace to provide the value before calling copy)
   
   "LOG: {"insertId":"14suym9fw9f63r","jsonPayload":{"bytes_sent":"492",
   "connection":{"dest_ip":"10.12.12.33","dest_port":32768,"protocol":6,
   "src_ip":"10.142.0.238","src_port":22},"end_time":"2023-02-13T22:38:30.490546349Z",
   "packets_sent":"15","reporter":"SRC","src_instance":{"project_id":"example-labs",
   "region":"us-east1","vm_name":"example-us-east1","zone":"us-east1-b"},
   "src_vpc":{"project_id":"example-labs","subnetwork_name":"default",
   "vpc_name":"default"},"start_time":"2023-02-13T22:38:29.024032655Z"},
   "logName":"projects/example-labs/logs/compute.googleapis.com%2Fvpc_flows",
   "receiveTimestamp":"2023-02-13T22:38:37.443315735Z","resource":{"labels":
   {"location":"us-east1-b","project_id":"example-labs",
     "subnetwork_id":"00000000000000000000","subnetwork_name":"default"},
     "type":"gce_subnetwork"},"timestamp":"2023-02-13T22:38:37.443315735Z"}
   

Consulta Campos en una instrucción de asignación de datos para obtener una lista de todos los campos posibles en una extensión del analizador.

Campos en una instrucción de asignación de datos

En esta sección, se describen todos los campos que se pueden configurar en una extensión del analizador.

Crea una instrucción de asignación de fragmentos de código

Un fragmento de código usa una sintaxis similar a Logstash para definir cómo extraer y transformar los valores en el registro sin procesar original y asignarlos al registro de la UDM. Un fragmento de código usa la misma sintaxis y secciones de la instrucción que un analizador predeterminado o personalizado. Las secciones de un fragmento de código son las siguientes:

• Sección 1: Extrae los datos del registro original.
• Sección 2: Transforma los datos extraídos.
• Sección 3: Asigna uno o más valores a un campo de la AUA.
• Sección 4: Vincula los campos de eventos de la AUA a la clave @output.

En el siguiente ejemplo, se ilustra un fragmento de código.

Este es un ejemplo de registro sin procesar:

{
    "insertId": "00000000",
    "jsonPayload": {
        ...section omitted for brevity...
        "packets_sent": "4",
        ...section omitted for brevity...
    },
    "timestamp": "2022-05-03T01:45:00.150614953Z"
}

Este es un fragmento de código de muestra que asigna el valor en jsonPayload.packets_sent al campo de UDM network.sent_bytes.

mutate {
 replace => {
    "jsonPayload.packets_sent" => ""
 }
}

filter {
    # Section 1. extract the data from the original JSON log
    json {
        source => "message"
        array_function => "split_columns"
        on_error => "_not_json"
    }

    if [_not_json] {
        drop {
            tag => "TAG_UNSUPPORTED"
        }

    } else {
        # Section 2. transform the extracted data
        if [jsonPayload][packets_sent] not in ["",0] {
            mutate {
                convert => {
                    "jsonPayload.packets_sent" => "uinteger"
                }
            }

            # Section 3. assign the value to a UDM field
            mutate {
                copy => {
                    "udm.network.sent_bytes" => "jsonPayload.packets_sent"
                }
                on_error => "_exception"
            }

            if ![_exception] {
                # Section 4. Bind the UDM fields to the @output key
                mutate {
                    merge => {
                        "@output" => "event"
                    }
                }
            }
        }
    }
}

1. Haz clic en Enviar para guardar la instrucción de asignación.

2. Google Security Operations valida la instrucción de asignación.

   • Si el proceso de validación se realiza correctamente, el estado cambia a En vivo y la instrucción de asignación comienza a procesar los datos de registro entrantes.
   • Si el proceso de validación falla, el estado cambia a Falló y se muestra un error en el campo Registro sin procesar.

Cómo ver una extensión del analizador existente

1. En la barra de navegación, selecciona Configuración, Configuración de SIEM y, luego, Análisis.
2. En la lista de analizadores, identifica el tipo de registro con una extensión de analizador. Esto se identifica con el texto EXTENSION junto al nombre.
3. Navega a esa fila y, luego, haz clic en el menú more_vert.
4. Haz clic en Ver extensión.
5. Aparecerá el analizador View Custom/Prebuilt > pestaña Extension con detalles sobre la extensión del analizador. El panel de resumen muestra la extensión del analizador LIVE de forma predeterminada.

Cómo editar una extensión del analizador

1. Abre Ver analizador personalizado o precompilado > pestaña Extension. Consulta Cómo ver una extensión de analizador existente para obtener instrucciones sobre cómo abrir la página.
2. Haz clic en el botón Edit Extension. Aparecerá la página Parser Extensions.
3. Edita la extensión del paser.
   • Para cancelar la edición y descartar los cambios, haz clic en Descartar borrador.
4. Cuando termines de editar la extensión del analizador, haz clic en Enviar.

5. Si envías el cambio, se ejecutará el proceso de validación para validar la configuración nueva.

Cómo borrar una extensión del analizador

1. Abre Ver analizador personalizado o precompilado > pestaña Extension. Consulta Cómo ver una extensión de analizador existente para obtener instrucciones sobre cómo abrir esa página.

2. Haz clic en el botón Edit Extension. Aparecerá la página Parser Extensions.

3. Haz clic en el botón Borrar extensión.

Mientras editas una extensión del analizador, puedes borrarla en cualquier momento. Haz clic en una de las siguientes opciones:

• Descartar borrador
• Cómo borrar una extensión que no se pudo instalar

Más información sobre el selector de campos repetidos

Algunos campos de la AUA almacenan un array de valores, como principal.ip y Entity.asset.hostname. Si creas una extensión de analizador para almacenar datos en un campo repetido, esta opción te permite controlar si el valor se agrega al array o si reemplaza todos los valores existentes establecidos por el analizador predeterminado. Los campos repetidos se identifican con la etiqueta que se repite en la lista de campos del modelo de datos unificado.

Si se selecciona Agrega valores, la extensión del analizador agrega el valor extraído al array de valores existentes en el campo UDM. Si se selecciona Replace Values, la extensión del analizador reemplaza el array de valores existentes en el campo UDM por el valor extraído. El selector Campos repetidos no afecta la forma en que se almacenan los datos en los campos que no se repiten.

Una extensión del analizador puede asignar datos a un campo repetido solo cuando el campo repetido está en el nivel más bajo de la jerarquía. Por ejemplo, se admiten las asignaciones de valores a udm.principal.ip porque el campo ip repetido está en el nivel más bajo de la jerarquía y principal no es un campo repetido. No se admiten valores de asignación a udm.intermediary.hostname porque intermediary es un campo repetido y no está en el nivel más bajo de la jerarquía.

En la siguiente tabla, se proporcionan ejemplos de cómo la configuración de campos repetidos afecta el registro de la UDM generado.

Más información sobre los campos del extractor de Syslog

Los campos del extractor de Syslog te permiten separar el encabezado de Syslog de un registro estructurado mediante la definición de Grok, la expresión regular y un token nombrado en el patrón de expresión regular para almacenar el resultado.

Define los campos del extractor de Syslog

Los valores de los campos Syslog y Target funcionan juntos para definir cómo la extensión del analizador separa el encabezado de Syslog de la parte estructurada de un registro sin procesar. En el campo Syslog, defines una expresión con una combinación de Grok y la sintaxis de expresiones regulares. La expresión incluye un nombre de variable que identifica la parte estructurada del registro sin procesar. En el campo Target, especificas ese nombre de variable.

En el siguiente ejemplo, se muestra cómo funcionan estos campos en conjunto.

El siguiente es un ejemplo de registro sin procesar:

<13>1 2022-09-14T15:03:04+00:00 fieldname fieldname - - - {"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

El registro sin procesar contiene las siguientes secciones:

• Encabezado de Syslog: <13> 2022-09-14T15:03:04+00:00 fieldname fieldname - - -

• Evento con formato JSON: {"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

Para separar el encabezado de Syslog de la parte JSON del registro sin procesar, usa la siguiente expresión de ejemplo en el campo Syslog: %{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg}

• Esta parte de la expresión identifica el encabezado de Syslog: %{TIMESTAMP\_ISO8601} %{WORD} %{WORD} ([- ]+)?
• Esta parte de la expresión captura el segmento JSON del registro sin procesar: %{GREEDYDATA:msg}

Este ejemplo incluye el nombre de la variable msg. Tú eliges el nombre de la variable. La extensión del analizador extrae el segmento JSON del registro sin procesar y lo asigna a la variable msg.

En el campo Target, ingresa el nombre de la variable msg. El valor almacenado en la variable msg se ingresa a las instrucciones de asignación de campos de datos que creas en la extensión del analizador.

Con el ejemplo de registro sin procesar, el siguiente segmento se ingresa a la instrucción de asignación de datos:

{"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

En la siguiente imagen, se muestran los campos Syslog y Target completados:

En la siguiente tabla, se proporcionan ejemplos adicionales con registros de muestra, el patrón de extracción de Syslog, el nombre de la variable Target y el resultado.

Controla el acceso a las extensiones del analizador

Hay disponibles nuevos permisos que controlan quién puede ver y administrar las extensiones del analizador. De forma predeterminada, los usuarios con el rol de Administrador pueden acceder a las extensiones del analizador. Para obtener más información sobre cómo administrar usuarios y grupos, o asignar roles, consulta Control de acceso basado en roles.

En la siguiente tabla, se resumen los nuevos roles de Google Security Operations.