Sugerencias y solución de problemas cuando se escriben analizadores
En este documento, se describen los problemas que puedes encontrar cuando escribes código de analizador.
Cuando escribas código del analizador, es posible que encuentres errores cuando las instrucciones de análisis no funcionen como se espera. Entre las situaciones que podrían generar errores, se incluyen las siguientes:
- Falla un patrón
Grok
- Falla una operación de
rename
oreplace
- 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 ayudarte a 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 de UDM. También es posible que tengas problemas de análisis intermitentes.
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 una variable.
Algunas palabras, como event
y timestamp
, pueden tener un significado especial en el código del analizador.
La cadena event
suele usarse para representar un solo registro de UDM y se usa en la sentencia @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 a otro o usa el término event1
como
prefijo en los nombres de los campos de la 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 UDM metadata.event_timestamp
. El término @timestamp
representa la fecha y la hora en que se analizó el registro sin procesar para crear un registro de UDM.
En el siguiente ejemplo, se establece el campo UDM metadata.event_timestamp
en la fecha y la 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 UDM metadata.event_timestamp
en la fecha y la hora extraídas del registro sin procesar original y almacenadas en la variable intermedia when
.
# Save the event timestamp to timestamp variable
mutate {
rename => {
"when" => "timestamp"
}
}
No uses los siguientes términos como variables:
- collectiontimestamp
- createtimestamp
- evento
- filename
- mensaje
- espacio de nombres
- output
- onerrorcount
- timestamp
- Zona horaria
Almacena cada valor de datos en un campo de UDM independiente
No almacenes varios campos en un solo campo de la UDM concatenando los campos 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 sangría de 2 espacios a la vez.
No realices varias acciones de combinación en una sola operación.
Si combinas varios campos en una sola operación, es posible que obtengas 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"
}
}
Elige entre las expresiones condicionales if
y if else
Si el valor condicional que estás probando solo puede tener una coincidencia, usa la sentencia 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 sentencias if
distintas y ordena las sentencias
del caso más genérico al caso más específico.
Elige un conjunto representativo de archivos de registro para probar los cambios del analizador
Una práctica recomendada es probar el código del analizador con muestras de registros sin procesar con una amplia variedad de formatos. Esto te permite encontrar registros únicos o casos extremos que el analizador podría necesitar controlar.
Agrega comentarios descriptivos al código del analizador
Agrega comentarios al código del analizador que expliquen por qué la sentencia es importante, en lugar de lo que hace. 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 sin procesar original, inicializa las variables intermedias que se usarán para almacenar los valores de prueba.
Esto evita que se muestre un error que indique que la variable intermedia no existe.
La siguiente sentencia asigna el valor de la variable product
al campo UDM metadata.product_name
.
mutate{
replace => {
"event1.idm.read_only_udm.metadata.product_name" => "%{product}"
}
}
Si la variable product
no existe, recibirá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 sentencia del ejemplo anterior detecta correctamente el error de análisis en una variable intermedia booleana, 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"
}
El ejemplo anterior muestra el siguiente error porque la cláusula condicional if
no admite instrucciones 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 resolver este problema, agrega un bloque de instrucciones independiente que inicialice las variables intermedias antes de ejecutar las instrucciones 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 sentencia condicional para verificar si el campo existe. Además, la instrucción on_error
controla los errores que se puedan encontrar.
Convierte SHA-256 a Base64
En el siguiente ejemplo, se extrae el valor SHA-256, se codifica en base64, se convierten los datos codificados en una cadena hexadecimal y, luego, se reemplazan campos específicos por 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}"
}
}
}
Controla errores en las instrucciones del analizador
No es raro que los registros entrantes tengan un formato de registro inesperado o datos con formato incorrecto.
Puedes compilar el analizador para controlar 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 sentencia on_error
para establecer la variable booleana _not_json
. Si _not_json
está configurado como true
, significa que la entrada de registro entrante no tenía un formato JSON válido y no se analizó correctamente. Si la variable _not_json
es false
, la entrada de registro entrante estaba en 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
está configurado 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
impide que el analizador procese el registro sin procesar, normalice los campos y cree un registro de UDM. El registro sin procesar original aún se transfiere a Google Security Operations y se puede buscar con 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
Cómo solucionar errores de validación
Cuando compilas un analizador, es posible que encuentres errores relacionados con la validación, por ejemplo, un campo obligatorio no se establece en el registro de la 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 de UDM generado no incluye todos los campos de UDM obligatorios, como se define por el valor establecido en metadata.event_type
. Los siguientes son ejemplos adicionales que pueden causar este error:
- Si
metadata.event_type
esUSER_LOGIN
y no se configuró el campo UDMtarget.user value
. - Si
metadata.event_type
esNETWORK_CONNECTION
y no se configuró el campo UDMtarget.hostname
.
Para obtener más información sobre el campo de la UDM metadata.event_type
y los campos obligatorios, consulta la guía de uso de la UDM.
Una opción para solucionar este tipo de error es comenzar por establecer valores estáticos en los campos de la UDM. Después de definir todos los campos de la AUA necesarios, examina el registro sin procesar original para ver qué valores analizar y guardar en el registro de la AUA. Si el registro sin procesar original no contiene ciertos campos, es posible que debas establecer valores predeterminados.
La siguiente es una plantilla de ejemplo, específica de un tipo de evento USER_LOGIN
, que ilustra este enfoque.
Ten en cuenta lo siguiente:
- La plantilla inicializa las variables intermedias y establece cada una en una cadena estática.
- El código de la sección Field Assignment establece los valores en las variables intermedias en los campos de la AUA.
Para expandir este código, agrega variables intermedias y campos de UDM adicionales. Después de identificar todos los campos de la AUA que se deben propagar, haz lo siguiente:
En la sección Input Configuration, agrega código que extraiga campos del registro sin procesar original y establezca los valores en las variables intermedias.
En la sección Extracción de fecha, agrega código que extraiga la marca de tiempo del evento del registro sin procesar original, 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 sentencias de expresiones regulares. Los patrones de Grok hacen que el código sea más fácil de leer. Si la expresión regular no incluye caracteres de abreviatura (como \w
, \s
), puedes copiar y pegar la sentencia directamente en el código del analizador.
Debido a que los patrones de Grok son una capa de abstracción adicional en la sentencia, pueden hacer que la solución de problemas sea más compleja cuando encuentres un error. El siguiente es un ejemplo de una función de 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 sentencia de extracción sin patrones de Grok puede tener un mejor rendimiento. Por ejemplo, en el siguiente ejemplo, se tarda menos de la mitad de los pasos de procesamiento en hacer coincidir. Esta es una consideración importante para una fuente de registro de volumen potencialmente alto.
Comprende 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 sentencia PCRE: (?<_custom_field>\w+)\s
El siguiente es un enunciado 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 sin procesar entrantes en formato codificado JSON. Esto se hace para garantizar que las cadenas de caracteres que parecen ser abreviaturas 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.
En el siguiente ejemplo, se muestra un registro sin procesar original y el registro en formato codificado JSON.
Observa el carácter de escape que se agrega delante de cada carácter de barra inversa que rodea el término entry
.
El siguiente es el registro sin procesar original:
field=\entry\
El siguiente es el registro convertido al formato codificado 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 diagonal inversa en el registro sin procesar original, usa cuatro barras diagonales inversas en la sentencia de extracción.
La siguiente es una expresión regular para el código del analizador:
^field=\\\\(?P<_value>.*)\\\\$
El siguiente es el resultado generado. El grupo llamado _value
almacena el término entry
:
"_value": "entry"
Cuando muevas una sentencia de expresión regular estándar al código del analizador, escapa los caracteres de abreviatura de la expresión regular en la sentencia de extracción.
Por ejemplo, cambia \s
a \\s
.
No cambies los caracteres especiales de la expresión regular cuando se escapen dos veces en la sentencia de extracción. Por ejemplo, \\
permanece sin cambios 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 funcionar 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 |
Se deben escapar los caracteres de abreviatura. |
\. |
\\. |
Se deben escapar los caracteres reservados. |
\\" |
\\\" |
Se deben escapar los caracteres reservados. |
\] |
\\] |
Se deben escapar los caracteres reservados. |
\| |
\\| |
Se deben escapar los caracteres reservados. |
[^\\]+ |
[^\\\\]+ |
Los caracteres especiales dentro de un grupo de clase de caracteres deben incluir el escape correcto. |
\\\\ |
\\\\ |
Los caracteres especiales fuera de un grupo de clase de caracteres o los caracteres abreviados no requieren un escape adicional. |
Las expresiones regulares deben incluir un grupo de captura nombrado.
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 de Grok, estos incluyen un grupo de captura con nombre de forma predeterminada. Cuando uses anulaciones de expresión regular, asegúrate de incluir un grupo con nombre.
La siguiente es una expresión regular de ejemplo en el código del analizador:
"^(?P<_catchall>.*$)"
El siguiente es el resultado, que muestra el texto asignado al grupo llamado _catchall
.
"_catchall": "User \"BOB\" logged on to workstation \"DESKTOP-01\"."
Usa un grupo con nombre comprehensivo para comenzar a crear la expresión
Cuando crees una sentencia de extracción, comienza con una expresión que capture más de lo que deseas. Luego, expande la expresión un campo a la vez.
En el siguiente ejemplo, se comienza con un grupo nombrado (_catchall
) que coincide con todo el mensaje. Luego, compila la expresión en pasos haciendo coincidir
partes adicionales del texto. Con cada paso, el grupo con nombre _catchall
contiene menos del texto original. Continúa y itera un paso a la vez para que coincida con el mensaje hasta que ya no necesites el grupo con nombre _catchall
.
Paso | Expresión regular en el código del analizador | Resultado del grupo de captura llamado _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. |
Escapa caracteres de abreviatura en la expresión regular
Recuerda escapar los caracteres de abreviatura de la expresión regular cuando uses la expresión en el código del analizador. A continuación, se muestra un ejemplo de cadena de texto 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, al resultado le falta la letra s
.
Expresión regular estándar | Resultado del grupo de captura llamado _firstWord |
---|---|
"^(?P<_firstWord>[^\s]+)\s.*$" |
"_firstWord": "Thi", |
Esto se debe a que las expresiones regulares en el código del analizador requieren un carácter de escape adicional que se agrega a los caracteres de abreviatura. En el ejemplo anterior, \s
debe cambiarse a \\s
.
Expresión regular revisada para el código del analizador | Resultado del grupo de captura llamado _firstWord |
---|---|
"^(?P<_firstWord>[^\\s]+)\\s.*$" |
"_firstWord": "This", |
Esto se aplica solo a los caracteres de abreviatura, como \s
, \r
y \t
.
No es necesario escapar otros caracteres, como ``.
Ejemplo completo
En esta sección, se describen las reglas anteriores como un ejemplo de extremo a extremo. Esta es una cadena de texto no estructurado y la expresión regular estándar escrita para analizar la cadena. 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>[^\\]+)\\\"\.$
Esta expresión extrae 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 estándar de RE2 para que funcione en el código del analizador.
^.*?\\\"(?P<_user>[^\\\\]+)\\\"\\s(?:(logged\\son|logged\\soff))\\s.*?\\\"(?P<_device>[^\\\\]+)\\\"\\.$
¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.