Sugerencias y solución de problemas cuando escribes analizadores

En este documento, se describen los problemas que puedes encontrar cuando escribes código del analizador.

Cuando escribes código de analizador, es posible que encuentres errores cuando las instrucciones de análisis no funcionen como se espera. Las situaciones que pueden generar errores incluyen las siguientes:

  • Un patrón Grok falla.
  • Una operación rename o replace falla.
  • Errores de sintaxis en el código del analizador

Prácticas comunes en el código del analizador

En las siguientes secciones, se describen las prácticas recomendadas, las sugerencias y las soluciones para solucionar problemas.

Evita usar puntos o guiones en los nombres de las variables

El uso de guiones y puntos en los nombres de las variables puede causar un comportamiento inesperado, a menudo cuando se realizan operaciones merge para almacenar valores en campos UDM. También puedes encontrar problemas intermitentes de análisis.

Por ejemplo, no uses los siguientes nombres de variables:

  • my.variable.result
  • my-variable-result

En su lugar, usa el siguiente nombre de variable: my_variable_result.

No uses términos con significado especial como nombre de variable

Algunas palabras, como event y timestamp, pueden tener un significado especial en el código del analizador.

A menudo, la cadena event se usa para representar un solo registro UDM y se utiliza en la declaración @output. Si un mensaje de registro incluye un campo llamado event o si defines una variable intermedia llamada event, y el código del analizador usa la palabra event en la sentencia @output, recibirás un mensaje de error sobre un conflicto de nombres.

Cambia el nombre de la variable intermedia por otra opción o usa el término event1 como prefijo en los nombres de campos de UDM y en la sentencia @output.

La palabra timestamp representa la marca de tiempo creada del registro sin procesar original. Un valor establecido en esta variable intermedia se guarda en el campo de UDM metadata.event_timestamp. El término @timestamp representa la fecha y hora en que se analizó el registro sin procesar para crear un registro UDM.

En el siguiente ejemplo, se establece el campo de UDM metadata.event_timestamp en la fecha y hora en que se analizó el registro sin procesar.

 # Save the log parse date and time to the timestamp variable
  mutate {
     rename => {
       "@timestamp" => "timestamp"
     }
   }

En el siguiente ejemplo, se establece el campo de UDM metadata.event_timestamp en la fecha y la hora extraídas del registro original sin procesar y almacenados en la variable intermedia when.

   # Save the event timestamp to timestamp variable
   mutate {
     rename => {
       "when" => "timestamp"
     }
   }

No uses los siguientes términos como variables:

  • marca de tiempo de la colección
  • createtimestamp
  • event
  • filename
  • mensaje
  • espacio de nombres
  • salida
  • recuentodeerrores
  • timestamp
  • Zona horaria

Almacenar cada valor de datos en un campo de UDM independiente

No almacenes varios campos en un solo campo UDM mediante la concatenación con un delimitador. A continuación, se muestra un ejemplo:

"principal.user.first_name" => "first:%{first_name},last:%{last_name}"

En su lugar, almacena cada valor en un campo de UDM independiente.

"principal.user.first_name" => "%{first_name}"
"principal.user.last_name" => "%{last_name}"

Usa espacios en lugar de tabulaciones en el código

No uses tabulaciones en el código del analizador. Usa solo espacios y aplica sangría de 2 espacios a la vez.

No realizar varias acciones de combinación en una sola operación

Si combinas varios campos en una sola operación, es posible que se generen resultados incoherentes. En su lugar, coloca las sentencias merge en operaciones separadas.

Por ejemplo, reemplaza el siguiente ejemplo:

mutate {
  merge => {
      "security_result.category_details" => "category_details"
      "security_result.category_details" => "super_category_details"
  }
}

Con este bloque:

mutate {
  merge => {
    "security_result.category_details" => "category_details"
  }
}

mutate {
  merge => {
    "security_result.category_details" => "super_category_details"
  }
}

Cómo elegir expresiones condicionales if frente a if else

Si el valor condicional que estás probando solo puede tener una sola coincidencia, usa la declaración condicional if else. Este enfoque es un poco más eficiente. Sin embargo, si tienes una situación en la que el valor probado podría coincidir más de una vez, usa varias declaraciones if distintas y ordena las declaraciones desde el caso más genérico hasta el más específico.

Elige un conjunto representativo de archivos de registro para probar los cambios del analizador

Una práctica recomendada consiste en probar el código del analizador mediante muestras de registro sin procesar con una amplia variedad de formatos. Esto te permite encontrar registros únicos o casos extremos que el analizador podría necesitar.

Agrega comentarios descriptivos al código del analizador

Agrega comentarios al código del analizador que expliquen por qué la instrucción es importante, en lugar de qué hace la instrucción. El comentario ayuda a cualquier persona que mantenga el analizador a seguir el flujo. A continuación, se muestra un ejemplo:

# only assign a Namespace if the source address is RFC 1918 or Loopback IP address
if [jsonPayload][id][orig_h] =~ /^(127(?:\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))\{3\}$)|(10(?:\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))\{3\}$)|(192\.168(?:\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))\{2\}$)|(172\.(?:1[6-9]|2\d|3[0-1])(?:\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))\{2\}$)/ {
  mutate {
    replace => {
      "event1.idm.read_only_udm.principal.namespace" => "%{resource.labels.project_id}"
    }
  }
}

Inicializa variables intermedias con anticipación

Antes de extraer valores del registro original sin procesar, inicializa las variables intermedias que se usarán para almacenar valores de prueba.

Esto evita que se muestre un error que indica que la variable intermedia no existe.

La siguiente declaración asigna el valor de la variable product al campo de UDM metadata.product_name.

mutate{
  replace => {
    "event1.idm.read_only_udm.metadata.product_name" => "%{product}"
  }
}

Si la variable product no existe, verás el siguiente error:

"generic::invalid_argument: pipeline failed: filter mutate (4) failed: replace failure: field \"event1.idm.read_only_udm.metadata.product_name\": source field \"product\": field not set"

Puedes agregar una sentencia on_error para detectar el error. A continuación, se muestra un ejemplo:

mutate{
  replace => {
    "event1.idm.read_only_udm.metadata.product_name" => "%{product}"
    }
  on_error => "_error_does_not_exist"
  }

La declaración del ejemplo anterior captura correctamente el error de análisis en una variable booleana intermedia, llamada _error_does_not_exist. No te permite usar la variable product en una sentencia condicional, por ejemplo, if. A continuación, se muestra un ejemplo:

if [product] != "" {
  mutate{
    replace => {
      "event1.idm.read_only_udm.metadata.product_name" => "%{product}"
    }
  }
  on_error => "_error_does_not_exist"
}

En el ejemplo anterior, se muestra el siguiente error porque la cláusula condicional if no admite declaraciones on_error:

"generic::invalid_argument: pipeline failed: filter conditional (4) failed: failed to evaluate expression: generic::invalid_argument: "product" not found in state data"

Para resolverlo, agrega un bloque de instrucciones separado que inicialice las variables intermedias antes de ejecutar las declaraciones del filtro de extracción (json, csv, xml, kv o grok). A continuación, se muestra un ejemplo.

filter {
  # Initialize intermediate variables for any field you will use for a conditional check
  mutate {
    replace => {
      "timestamp" => ""
      "does_not_exist" => ""
    }
  }

  # load the logs fields from the message field
  json {
    source         => "message"
    array_function => "split_columns"
    on_error       => "_not_json"
  }
}

El fragmento actualizado del código del analizador controla las múltiples situaciones con una instrucción condicional para verificar si el campo existe. Además, la declaración on_error controla los errores que pueden ocurrir.

Convertir SHA-256 a base64

En el siguiente ejemplo, se extrae el valor SHA-256, lo codifica en base64, convierte los datos codificados en una string hexadecimal y, luego, se reemplazan los campos específicos con los valores extraídos y procesados.

if [Sha256] != "" 
{
  base64
  {
  encoding => "RawStandard"
  source => "Sha256"
  target => "base64_sha256"
  on_error => "base64_message_error"
  }
  mutate
  {
    convert =>
    {
      "base64_sha256" => "bytestohex"
    }
    on_error => "already_a_string"
  }
  mutate
  {
    replace => 
  {
     "event.idm.read_only_udm.network.tls.client.certificate.sha256" => "%{base64_sha256}"
     "event.idm.read_only_udm.target.resource.name" => "%{Sha256}"
  }
  }
}

Soluciona errores en las instrucciones del analizador

No es inusual que los registros entrantes tengan un formato de registro inesperado o tengan datos con un formato incorrecto.

Puedes compilar el analizador para que maneje estos errores. Una práctica recomendada es agregar controladores on_error al filtro de extracción y, luego, probar la variable intermedia antes de continuar con el siguiente segmento de la lógica del analizador.

En el siguiente ejemplo, se usa el filtro de extracción json con una declaración on_error para configurar la variable booleana _not_json. Si _not_json se configura como true, significa que la entrada de registro entrante no estaba en un formato JSON válido y que no se analizó de forma correcta. Si la variable _not_json es false, la entrada de registro entrante estaba en un formato JSON válido.

 # load the incoming log from the default message field
  json {
    source         => "message"
    array_function => "split_columns"
    on_error       => "_not_json"
  }

También puedes probar si un campo tiene el formato correcto. En el siguiente ejemplo, se verifica si _not_json se configuró como true, lo que indica que el registro no estaba en el formato esperado.

 # Test that the received log matches the expected format
  if [_not_json] {
    drop { tag => "TAG_MALFORMED_MESSAGE" }
  } else {
    # timestamp is always expected
    if [timestamp] != "" {

      # ...additional parser logic goes here …

    } else {

      # if the timestamp field does not exist, it's not a log source
      drop { tag => "TAG_UNSUPPORTED" }
    }
  }

Esto garantiza que el análisis no falle si los registros se transfieren con un formato incorrecto para el tipo de registro especificado.

Usa el filtro drop con la variable tag para que la condición se capture en la tabla de métricas de transferencia en BigQuery.

  • TAG_UNSUPPORTED
  • TAG_MALFORMED_ENCODING
  • TAG_MALFORMED_MESSAGE
  • TAG_NO_SECURITY_VALUE

El filtro drop evita que el analizador procese el registro sin procesar, normalice los campos y cree un registro UDM. El registro sin procesar original aún se transfiere a Google Security Operations y se puede buscar mediante la búsqueda de registros sin procesar en Google Security Operations.

El valor que se pasa a la variable tag se almacena en el campo drop_reason_code de la tabla de métricas de transferencia. Puedes ejecutar una consulta ad hoc en la tabla, similar a la siguiente:

SELECT
  log_type,
  drop_reason_code,
  COUNT(drop_reason_code) AS count
FROM `datalake.ingestion_metrics`
GROUP BY 1,2
ORDER BY 1 ASC

Solucionar errores de validación

Cuando compilas un analizador, es posible que encuentres errores relacionados con la validación, por ejemplo, si no se establece un campo obligatorio en el registro de UDM. El error puede ser similar al siguiente:

Error: generic::unknown: invalid event 0: LOG_PARSING_GENERATED_INVALID_EVENT: "generic::invalid_argument: udm validation failed: target field is not set"

El código del analizador se ejecuta correctamente, pero el registro UDM generado no incluye todos los campos UDM obligatorios según el valor establecido en metadata.event_type. Los siguientes son ejemplos adicionales que pueden causar este error:

  • Si metadata.event_type es USER_LOGIN y no se configura el campo UDM target.user value.
  • Si el metadata.event_type es NETWORK_CONNECTION y el campo UDM target.hostname no está configurado.

Para obtener más información sobre el campo de UDM metadata.event_type y los campos obligatorios, consulta la Guía de uso de UDM.

Una opción para solucionar este tipo de error es comenzar con la configuración de los valores estáticos en los campos de UDM. Después de definir todos los campos de UDM necesarios, examina el registro original sin procesar para ver qué valores analizar y guardar en el registro de UDM. Si el registro original sin procesar no contiene ciertos campos, es posible que debas establecer valores predeterminados.

La siguiente es una plantilla de ejemplo, específica para un tipo de evento USER_LOGIN, que ilustra este enfoque.

Ten en cuenta lo siguiente:

  • La plantilla inicializa variables intermedias y configura cada una en una cadena estática.
  • El código en la sección Asignación de campos establece los valores de las variables intermedias en los campos de UDM.

Puedes expandir este código agregando variables intermedias y campos UDM adicionales. Después de que identifiques todos los campos de UDM que se deben propagar, haz lo siguiente:

  • En la sección Configuración de entrada, agrega código que extraiga campos del registro original sin procesar y establezca los valores en las variables intermedias.

  • En la sección Date Extract, agrega código que extraiga la marca de tiempo del evento del registro original sin procesar, la transforme y la establezca en la variable intermedia.

  • Según sea necesario, reemplaza el valor inicializado establecido en cada variable intermedia por una cadena vacía.

filter {
 mutate {
   replace => {
     # UDM > Metadata
     "metadata_event_timestamp"    => ""
     "metadata_vendor_name"        => "Example"
     "metadata_product_name"       => "Example SSO"
     "metadata_product_version"    => "1.0"
     "metadata_product_event_type" => "login"
     "metadata_product_log_id"     => "12345678"
     "metadata_description"        => "A user logged in."
     "metadata_event_type"         => "USER_LOGIN"

     # UDM > Principal
     "principal_ip"       => "192.168.2.10"

     # UDM > Target
     "target_application"            => "Example Connect"
     "target_user_user_display_name" => "Mary Smith"
     "target_user_userid"            => "mary@example.com"

     # UDM > Extensions
     "auth_type"          => "SSO"
     "auth_mechanism"     => "USERNAME_PASSWORD"

     # UDM > Security Results
     "securityResult_action"         => "ALLOW"
     "security_result.severity"       => "LOW"

   }
 }

 # ------------ Input Configuration  --------------
  # Extract values from the message using one of the extraction filters: json, kv, grok

 # ------------ Date Extract  --------------
 # If the  date {} function is not used, the default is the normalization process time

  # ------------ Field Assignment  --------------
  # UDM Metadata
  mutate {
    replace => {
      "event1.idm.read_only_udm.metadata.vendor_name"        =>  "%{metadata_vendor_name}"
      "event1.idm.read_only_udm.metadata.product_name"       =>  "%{metadata_product_name}"
      "event1.idm.read_only_udm.metadata.product_version"    =>  "%{metadata_product_version}"
      "event1.idm.read_only_udm.metadata.product_event_type" =>  "%{metadata_product_event_type}"
      "event1.idm.read_only_udm.metadata.product_log_id"     =>  "%{metadata_product_log_id}"
      "event1.idm.read_only_udm.metadata.description"        =>  "%{metadata_description}"
      "event1.idm.read_only_udm.metadata.event_type"         =>  "%{metadata_event_type}"
    }
  }

  # Set the UDM > auth fields
  mutate {
    replace => {
      "event1.idm.read_only_udm.extensions.auth.type"        => "%{auth_type}"
    }
    merge => {
      "event1.idm.read_only_udm.extensions.auth.mechanism"   => "auth_mechanism"
    }
  }

  # Set the UDM > principal fields
  mutate {
    merge => {
      "event1.idm.read_only_udm.principal.ip"                => "principal_ip"
    }
  }

  # Set the UDM > target fields
  mutate {
    replace => {
      "event1.idm.read_only_udm.target.user.userid"             =>  "%{target_user_userid}"
      "event1.idm.read_only_udm.target.user.user_display_name"  =>  "%{target_user_user_display_name}"
      "event1.idm.read_only_udm.target.application"             =>  "%{target_application}"
    }
  }

  # Set the UDM > security_results fields
  mutate {
    merge => {
      "security_result.action" => "securityResult_action"
    }
  }

  # Set the security result
  mutate {
    merge => {
      "event1.idm.read_only_udm.security_result" => "security_result"
    }
  }

 # ------------ Output the event  --------------
  mutate {
    merge => {
      "@output" => "event1"
    }
  }

}

Analiza texto no estructurado con una función Grok

Cuando usas una función Grok para extraer valores de texto no estructurado, puedes usar patrones de Grok predefinidos y declaraciones de expresiones regulares. Los patrones grok facilitan la lectura del código. Si la expresión regular no incluye caracteres abreviados (como \w o \s), puedes copiar y pegar la instrucción directamente en el código del analizador.

Debido a que los patrones Grok son una capa de abstracción adicional en la declaración, es posible que compliquen la solución de problemas cuando encuentres un error. El siguiente es un ejemplo de una función Grok que contiene patrones de Grok predefinidos y expresiones regulares.

grok {
  match => {
    "message" => [
      "%{NUMBER:when}\\s+\\d+\\s%{SYSLOGHOST:srcip} %{WORD:action}\\/%{NUMBER:returnCode} %{NUMBER:size} %{WORD:method} (?P<url>\\S+) (?P<username>.*?) %{WORD}\\/(?P<tgtip>\\S+).*"
    ]
  }
}

Una instrucción de extracción sin patrones de Grok puede tener un mejor rendimiento. Por ejemplo, en el siguiente ejemplo se requiere menos de la mitad de los pasos de procesamiento para que coincidan. Esta es una consideración importante para una fuente de registro de volumen potencialmente alto.

Comprender las diferencias entre las expresiones regulares RE2 y PCRE

Los analizadores de Google Security Operations usan RE2 como motor de expresiones regulares. Si conoces la sintaxis de PCRE, es posible que notes diferencias. A continuación, se muestra un ejemplo:

La siguiente es una declaración de PCRE: (?<_custom_field>\w+)\s

La siguiente es una sentencia RE2 para el código del analizador: (?P<_custom_field>\\w+)\\s

Asegúrate de escapar los caracteres de escape

Google Security Operations almacena los datos de registro entrantes sin procesar en formato codificado en JSON. Esto es para garantizar que las cadenas de caracteres que parecen ser la abreviatura de expresiones regulares se interpreten como la cadena literal. Por ejemplo, \t se interpreta como la cadena literal, en lugar de un carácter de tabulación.

El siguiente ejemplo es un registro original sin procesar y el registro con formato codificado en JSON. Observa el carácter de escape que se agregó delante de cada carácter de barra inversa que rodea al término entry.

A continuación, se muestra el registro sin procesar original:

field=\entry\

A continuación, se muestra el registro convertido al formato con codificación JSON:

field=\\entry\\

Cuando usas una expresión regular en el código del analizador, debes agregar caracteres de escape adicionales si deseas extraer solo el valor. Para hacer coincidir una barra inversa en el registro sin procesar original, usa cuatro barras inversas en la instrucción de extracción.

La siguiente es una expresión regular para el código del analizador:

^field=\\\\(?P<_value>.*)\\\\$

El siguiente es el resultado que se generó. El grupo con nombre _value almacena el término entry:

"_value": "entry"

Cuando mueves una declaración de expresión regular estándar al código del analizador, escapa los caracteres abreviados de expresiones regulares en la instrucción de extracción. Por ejemplo, cambia \s a \\s.

Deja los caracteres especiales de la expresión regular sin cambios cuando se tengan dos escapes en la instrucción de extracción. Por ejemplo, \\ no se modifica como \\.

La siguiente es una expresión regular estándar:

^.*?\\\"(?P<_user>[^\\]+)\\\"\s(?:(logged\son|logged\soff))\s.*?\\\"(?P<_device>[^\\]+)\\\"\.$

La siguiente expresión regular se modifica para que funcione dentro del código del analizador.

^.*?\\\"(?P<_user>[^\\\\]+)\\\"\\s(?:(logged\\son|logged\\soff))\\s.*?\\\"(?P<_device>[^\\\\]+)\\\"\\.$

En la siguiente tabla, se resume cuándo una expresión regular estándar debe incluir caracteres de escape adicionales antes de incluirla en el código del analizador.

Expresión regular Expresión regular modificada para el código del analizador Descripción del cambio
\s
\\s
Los caracteres de atajo deben escaparse.
\.
\\.
Los caracteres reservados deben tener escape.
\\"
\\\"
Los caracteres reservados deben tener escape.
\]
\\]
Los caracteres reservados deben tener escape.
\|
\\|
Los caracteres reservados deben tener escape.
[^\\]+
[^\\\\]+
Los caracteres especiales dentro de un grupo de clases de caracteres deben tener escape.
\\\\
\\\\
Los caracteres especiales fuera de un grupo de clases de caracteres o los caracteres abreviados no requieren un escape adicional.

Las expresiones regulares deben incluir un grupo de captura con nombre

Una expresión regular, como "^.*$", es una sintaxis RE2 válida. Sin embargo, en el código del analizador, falla con el siguiente error:

"ParseLogEntry failed: pipeline failed: filter grok (0) failed: failed to parse data with all match
patterns"

Debes agregar un grupo de captura válido a la expresión. Si usas patrones Grok, estos incluyen un grupo de captura con nombre de forma predeterminada. Cuando uses anulaciones de expresiones regulares, asegúrate de incluir un grupo con nombre.

El siguiente es un ejemplo de una expresión regular en un código del analizador:

"^(?P<_catchall>.*$)"

El siguiente es el resultado, que muestra el texto asignado al grupo con nombre _catchall.

"_catchall": "User \"BOB\" logged on to workstation \"DESKTOP-01\"."

Usa un grupo llamado genérico para comenzar a medida que compilas la expresión.

Cuando compiles una declaración de extracción, comienza con una expresión que capte más de lo que deseas. Luego, expande la expresión un campo a la vez.

En el siguiente ejemplo, se usa un grupo con nombre (_catchall) que coincide con todo el mensaje. Luego, hace coincidir partes adicionales del texto para compilar la expresión en pasos. Con cada paso, el grupo llamado _catchall contiene menos texto original. Continúa y, luego, itera un paso a la vez para que coincida con el mensaje hasta que ya no necesites el grupo con nombre _catchall.

Step Expresión regular en el código del analizador Resultado del grupo de captura con nombre _catchall
1
"^(?P<_catchall>.*$)"
User \"BOB\" logged on to workstation \"DESKTOP-01\".
2
^User\s\\\"(?P<_catchall>.*$)
BOB\" logged on to workstation \"DESKTOP-01\".
3
^User\s\\\"(?P<_user>.*?)\\\"\s(?P<_catchall>.*$)
logged on to workstation \"DESKTOP-01\".
Continúa hasta que la expresión coincida con toda la cadena de texto.

Caracteres abreviados de escape en la expresión regular

Recuerda escapar los caracteres abreviados de expresiones regulares cuando uses la expresión en el código del analizador. La siguiente es una cadena de texto de ejemplo y la expresión regular estándar que extrae la primera palabra, This.

  This is a sample log.

La siguiente expresión regular estándar extrae la primera palabra, This. Sin embargo, cuando ejecutas esta expresión en el código del analizador, falta la letra s en el resultado.

Expresión regular estándar Resultado del grupo de captura con nombre _firstWord
"^(?P<_firstWord>[^\s]+)\s.*$" "_firstWord": "Thi",

Esto se debe a que las expresiones regulares en el código del analizador requieren que se agregue un carácter de escape adicional a los caracteres abreviados. En el ejemplo anterior, \s debe cambiarse a \\s.

Expresión regular revisada para el código del analizador Resultado del grupo de captura con nombre _firstWord
"^(?P<_firstWord>[^\\s]+)\\s.*$" "_firstWord": "This",

Esto se aplica solo a los caracteres abreviados, como \s, \r y \t. Otros caracteres, como ``, no necesitan agregar más escape.

Ejemplo completo

En esta sección, se describen las reglas anteriores como ejemplo de extremo a extremo. Esta es una cadena de texto no estructurada y la expresión regular estándar escrita para analizarla. Por último, incluye la expresión regular modificada que funciona en el código del analizador.

La siguiente es la cadena de texto original.

User "BOB" logged on to workstation "DESKTOP-01".

La siguiente es una expresión regular RE2 estándar que analiza la cadena de texto.

^.*?\\\"(?P<_user>[^\\]+)\\\"\s(?:(logged\son|logged\soff))\s.*?\\\"(?P<_device>[^\\]+)\\\"\.$

Con esta expresión, se extraen los siguientes campos.

Grupo de coincidencias Posición del carácter String de texto
Coincidencia completa 0-53
User \"BOB\" logged on to workstation \"DESKTOP-01\".
Grupo `_user` 7-10
BOB
Grupo 2. 13-22
logged on
Grupo "_device" 40-50
DESKTOP-01

Esta es la expresión modificada. Se modificó la expresión regular RE2 estándar para que funcione en el código del analizador.

^.*?\\\"(?P<_user>[^\\\\]+)\\\"\\s(?:(logged\\son|logged\\soff))\\s.*?\\\"(?P<_device>[^\\\\]+)\\\"\\.$