Compartir vía

Uso de Logstash para transmitir registros con transformaciones de canalización a través de la API basada en DCR

  • Artículo

Importante

La ingesta de datos mediante el complemento de salida de Logstash con reglas de colección de datos (DCR) se encuentra actualmente en versión preliminar pública. Esta característica se proporciona sin un Acuerdo de Nivel de Servicio. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

El nuevo complemento de salida Logstash de Microsoft Sentinel admite transformaciones de canalización y configuración avanzada a través de reglas de recopilación de datos (DCR). El complemento reenvía cualquier tipo de registro de orígenes de datos externos a tablas personalizadas o estándar en Log Analytics o Microsoft Sentinel.

En este artículo, aprenderá a configurar el nuevo complemento de Logstash para que transmita los datos aLog Analytics o Microsoft Sentinel mediante DCR, con control total sobre el esquema de salida. Obtenga información sobre cómo implementar el complemento.

Nota:

Una versión anterior del complemento de Logstash permite conectar orígenes de datos a través de Logstash a través de la API de recopilación de datos.

Con el nuevo complemento, puede hacer lo siguiente:

  • Controlar la configuración de los tipos y nombres de columna.
  • Realizar transformaciones en tiempo de ingesta, como el filtrado o el enriquecimiento.
  • Ingerir registros personalizados en una tabla personalizada o ingerir un flujo de entrada de Syslog en la tabla Syslog de Log Analytics.

La ingesta en tablas estándar solo se limita a las tablas estándar admitidas para la ingesta de registros personalizados.

Para obtener más información sobre cómo trabajar con el motor de recopilación de datos de Logstash, consulte la página de introducción a Logstash.

Información general

Arquitectura e información

Diagrama de la arquitectura de Logstash.

El motor de Logstash consta de tres componentes:

  • Complementos de entrada: colección personalizada de datos de diversos orígenes.
  • Complementos de filtro: manipulación y normalización de los datos según los criterios especificados.
  • Complementos de salida: envío personalizado de datos recopilados y procesados a varios destinos.

Nota

  • Microsoft solo admite el complemento de salida de Logstash proporcionado por Microsoft Sentinel que se trata aquí. El complemento actual se denomina microsoft-sentinel-log-analytics-logstash-output-plugin, v1.1.0. Puede abrir una incidencia de soporte técnico en caso de que surja cualquier problema relacionado con el complemento de salida.

  • Microsoft no admite complementos de salida de terceros de Logstash para Microsoft Sentinel ni ningún otro complemento de Logstash o componente de ningún tipo.

  • Consulte los requisitos previos para la compatibilidad con la versión de Logstash del complemento.

El complemento de salida de Microsoft Sentinel para Logstash envía datos con formato JSON al área de trabajo de Log Analytics mediante la API de ingesta de registros de Log Analytics. Los datos se ingieren en registros personalizados o en una tabla estándar.

Implementación del complemento de salida de Microsoft Sentinel en Logstash

Para configurar el complemento, siga estos pasos:

  1. Revise los requisitos previos
  2. Instale el complemento
  3. Cree un archivo de ejemplo
  4. Cree los recursos necesarios relacionados con DCR
  5. Configure el archivo de configuración de Logstash
  6. Reinicio de Logstash
  7. Visualización de los registros entrantes en Microsoft Sentinel
  8. Supervisión de registros de auditoría de complementos de salida

Requisitos previos

  • Instale una versión compatible de Logstash. El complemento admite las siguientes versiones de Logstash:

    • 7.0 - 7.17.13
    • 8.0 - 8.9
    • 8.11

    Nota:

    Si usa Logstash 8, se recomienda deshabilitar ECS en la canalización.

  • Verifique que dispone de un área de trabajo de Log Analytics en la que tenga al menos derechos de colaborador.

  • Verifique que dispone de permisos para crear objetos DCR en el área de trabajo.

Instalación del complemento

El complemento de salida de Microsoft Sentinel está disponible en la colección de Logstash.

Creación de un archivo de ejemplo

En esta sección, creará un archivo de ejemplo en uno de estos escenarios:

Creación de un archivo de ejemplo para registros personalizados

En este escenario, configurará el complemento de entrada de Logstash para enviar eventos a Microsoft Sentinel. En este ejemplo, usamos el complemento de entrada del generador para simular eventos. Puede usar cualquier otro complemento de entrada.

En este ejemplo, el archivo de configuración de Logstash tiene el siguiente aspecto:

input {
      generator {
            lines => [
                 "This is a test log message"
            ]
           count => 10
      }
}

  1. Copie la configuración del complemento de salida siguiente en el archivo de configuración de Logstash.

    output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      create_sample_file => true
      sample_file_path => "<enter the path to the file in which the sample data will be written>" #for example: "c:\\temp" (for windows) or "/tmp" for Linux. 
    }
}

  2. Para asegurarse de que la ruta de acceso del archivo a la que se hace referencia existe antes de crear el archivo de ejemplo, inicie Logstash.

    El complemento escribe diez registros en un archivo de ejemplo denominado sampleFile<epoch seconds>.json en la ruta de acceso configurada. Por ejemplo: c:\temp\sampleFile1648453501.json. A continuación, parte de un archivo de ejemplo que crea el complemento:

    [
        {
            "host": "logstashMachine",
            "sequence": 0,
            "message": "This is a test log message",
            "ls_timestamp": "2022-03-28T17:45:01.690Z",
            "ls_version": "1"
        },
        {
            "host": "logstashMachine",
            "sequence": 1
    ...

    ]

    El complemento agrega automáticamente estas propiedades a cada registro:

    • ls_timestamp: la hora a la que se recibe el registro del complemento de entrada
    • ls_version: la versión de canalización de Logstash.

    Puede quitar estos campos al crear el DCR.

Creación de un archivo de ejemplo para ingerir registros en la tabla Syslog

En este escenario, configurará el complemento de entrada de Logstash para enviar eventos syslog a Microsoft Sentinel.

  1. Si los mensajes de syslog aún no se reenvían a la máquina de Logstash, puede usar el comando logger para generar mensajes. Por ejemplo (para Linux):

    logger -p local4.warn --rfc3164 --tcp -t CEF: "0|Microsoft|Device|cef-test|example|data|1|here is some more data for the example" -P 514 -d -n 127.0.0.1
Here is an example for the Logstash input plugin:
input {
     syslog {
         port => 514
    }
}

  2. Copie la configuración del complemento de salida siguiente en el archivo de configuración de Logstash.

    output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      create_sample_file => true
      sample_file_path => "<enter the path to the file in which the sample data will be written>" #for example: "c:\\temp" (for windows) or "/tmp" for Linux. 
    }
}

  3. Para asegurarse de que la ruta de acceso del archivo existe antes de crear el archivo de ejemplo, inicie Logstash.

    El complemento escribe diez registros en un archivo de ejemplo denominado sampleFile<epoch seconds>.json en la ruta de acceso configurada. Por ejemplo: c:\temp\sampleFile1648453501.json. A continuación, parte de un archivo de ejemplo que crea el complemento:

    [
    	{
    		"logsource": "logstashMachine",
    		"facility": 20,
    		"severity_label": "Warning",
    		"severity": 4,
    		"timestamp": "Apr  7 08:26:04",
    		"program": "CEF:",
    		"host": "127.0.0.1",
    		"facility_label": "local4",
    		"priority": 164,
    		"message": 0|Microsoft|Device|cef-test|example|data|1|here is some more data for the example",
    		"ls_timestamp": "2022-04-07T08:26:04.000Z",
    		"ls_version": "1"
    	}
]

    El complemento agrega automáticamente estas propiedades a cada registro:

    • ls_timestamp: la hora a la que se recibe el registro del complemento de entrada
    • ls_version: la versión de canalización de Logstash.

    Puede quitar estos campos al crear el DCR.

Creación de los recursos de DCR necesarios

Para configurar el complemento de Logstash basado en DCR de Microsoft Sentinel, primero debe crear los recursos relacionados con DCR.

En esta sección, creará recursos para su DCR, en uno de estos escenarios:

Creación de recursos de DCR para la ingesta en una tabla personalizada

Para ingerir los datos en una tabla personalizada, siga estos pasos, según el tutorial Envío de datos a registros de Azure Monitor mediante la API de REST (Azure Portal):

  1. Revise los requisitos previos.

  2. Configurar la aplicación.

  3. Adición de una tabla de registro personalizado.

  4. Analice y filtre los datos de ejemplo mediante el archivo de ejemplo que creó en la sección anterior.

  5. Recopilación de información de la DCR.

  6. Asignación de permisos a la DCR.

    Omita el paso Enviar datos de ejemplo.

Si tiene algún problema, consulte los pasos de solución de problemas.

Creación de recursos de DCR para la ingesta en una tabla estándar

Para ingerir los datos en una tabla estándar como Syslog o CommonSecurityLog, use un proceso basado en el tutorial Envío de datos a registros de Azure Monitor mediante la API de REST (plantillas de Resource Manager). Aunque en el tutorial se explica cómo ingerir datos en una tabla personalizada, puede ajustar fácilmente el proceso para ingerir datos en una tabla estándar. Los pasos siguientes indican los cambios pertinentes en los pasos.

  1. Revise los requisitos previos.

  2. Recopilación de los detalles del área de trabajo.

  3. Configuración de una aplicación.

    Omisión del paso de creación de una tabla en el área de trabajo de Log Analytics. Este paso no es relevante al ingerir datos en una tabla estándar, ya que la tabla ya está definida en Log Analytics.

  4. Cree el DCR. En este paso,

    • proporcione el archivo de ejemplo que creó en la sección anterior.
    • Use el archivo de ejemplo que creó para definir la propiedad streamDeclarations. Cada uno de los campos del archivo de ejemplo debe tener una columna correspondiente con el mismo nombre y el tipo adecuado (vea el ejemplo siguiente).
    • Configure el valor de la propiedad outputStream con el nombre de la tabla estándar en lugar de la tabla personalizada. A diferencia de las tablas personalizadas, los nombres de tabla estándar no tienen el sufijo _CL.
    • El prefijo del nombre de la tabla debe ser Microsoft- en lugar de Custom-. En nuestro ejemplo, el valor de la propiedad outputStream es Microsoft-Syslog.

  5. Asignación de permisos a una DCR.

    Omita el paso Enviar datos de ejemplo.

Si tiene algún problema, consulte los pasos de solución de problemas.

Ejemplo: DCR que ingiere datos en la tabla Syslog

Observe lo siguiente:

  • Los nombres y tipos de columna streamDeclarations deben ser los mismos que los campos de archivo de ejemplo, pero no es necesario especificar todos ellos. Por ejemplo, en la DCR siguiente, los campos PRI, type y ls_version se omiten de la columna streamDeclarations.
  • La propiedad dataflows transforma la entrada en el formato de tabla Syslog y establece outputStream en Microsoft-Syslog.
{
	"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
	"contentVersion": "1.0.0.0",
	"parameters": {
		"dataCollectionRuleName": {
			"type": "String",
			"metadata": {
				"description": "Specifies the name of the Data Collection Rule to create."
			}
		},
		"location": {
			"defaultValue": "westus2",
			"allowedValues": [
				"westus2",
				"eastus2",
				"eastus2euap"
			],
			"type": "String",
			"metadata": {
				"description": "Specifies the location in which to create the Data Collection Rule."
			}
		},
        "location": {
            "defaultValue": "[resourceGroup().location]", 
            "type": "String", 
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule." 
            } 
        },
		"workspaceResourceId": {
			"type": "String",
			"metadata": {
				"description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
			}
		}
	},
	"resources": [
		{
			"type": "Microsoft.Insights/dataCollectionRules",
			"apiVersion": "2021-09-01-preview",
			"name": "[parameters('dataCollectionRuleName')]",
			"location": "[parameters('location')]",
			"properties": {
				"streamDeclarations": {
					"Custom-SyslogStream": {
						"columns": [
							{
                        "name": "ls_timestamp",
                        "type": "datetime"
                    },	{
                        "name": "timestamp",
                        "type": "datetime"
                    },
                    {
                        "name": "message",
                        "type": "string"
                    }, 
					{
                        "name": "facility_label",
                        "type": "string"
                    },
					{
                        "name": "severity_label",
                        "type": "string"
                    },
                    {
                        "name": "host",
                        "type": "string"
                    },
                    {
                        "name": "logsource",
                        "type": "string"
                    }
	]
				      }
				},
				"destinations": {
					"logAnalytics": [
						{
							"workspaceResourceId": "[parameters('workspaceResourceId')]",
							"name": "clv2ws1"
						}
					]
				},
				"dataFlows": [
					{
					"streams": [
						"Custom-SyslogStream"
					],
					"destinations": [
						"clv2ws1"
					],
					"transformKql": "source | project TimeGenerated = ls_timestamp, EventTime = todatetime(timestamp), Computer = logsource, HostName = logsource, HostIP = host, SyslogMessage = message, Facility = facility_label, SeverityLevel = severity_label",
						"outputStream": "Microsoft-Syslog"
					}
				]
			}
		}
	],
	"outputs": {
		"dataCollectionRuleId": {
			"type": "String",
			"value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
		}
	}
}

Configuración del archivo de configuración de Logstash

Para configurar el archivo de configuración de Logstash para ingerir los registros en una tabla personalizada, recupere estos valores:

Campo Recuperación
client_app_Id El valor Application (client) ID que se crea en el paso 3 al crear los recursos de DCR, según el tutorial que usó en esta sección.
client_app_secret El valor Application (client) ID que crea en el paso 5 al crear los recursos de DCR, según el tutorial que usó en esta sección.
tenant_id Identificador de inquilino de la suscripción. Puede encontrar el identificador de inquilino en Inicio > Microsoft Entra ID > Información general > Información básica.
data_collection_endpoint El valor del URI logsIngestion en el paso 3 al crear los recursos de DCR, según el tutorial que usó en esta sección.
dcr_immutable_id El valor del DCR immutableId en el paso 6 al crear los recursos de DCR, según el tutorial que usó en esta sección.
dcr_stream_name En el caso de las tablas personalizadas, como se explica en el paso 6 al crear los recursos de DCR, vaya a la vista JSON de la DCR y copie la propiedad dataFlows>streams. Observe dcr_stream_name en el ejemplo siguiente.

En el caso de las tablas estándar, el valor es Custom-SyslogStream.

Después de recuperar los valores necesarios:

  1. Reemplace la sección de salida del archivo de configuración de Logstash que creó en el paso anterior por el ejemplo siguiente.
  2. Reemplace las cadenas de marcador de posición en el ejemplo siguiente por los valores recuperados.
  3. Asegúrese de cambiar el atributo create_sample_file a false.

Configuración opcional

Campo Descripción Default value
azure_cloud Se usa para especificar el nombre de la nube de Azure que se usa, Los valores disponibles son: AzureCloud, AzureChinaCloud y AzureUSGovernment. AzureCloud
key_names Una matriz de cadenas. Proporcione este campo si desea enviar un subconjunto de las columnas a Log Analytics. Ninguno (este campo está vacío)
plugin_flush_interval Define la diferencia máxima de tiempo (en segundos) entre enviar dos mensajes a Log Analytics. 5
retransmission_time Establece la cantidad de tiempo en segundos para retransmitir mensajes una vez que se ha producido un error en el envío. 10
compress_data Cuando este campo es True, los datos del evento se comprimen antes de usar la API. Se recomienda para canalizaciones de alto rendimiento. False
proxy Especifique la dirección URL de proxy que se va a usar para todas las llamadas de API. Ninguno (este campo está vacío)
proxy_aad Especificar la dirección URL de proxy que se usará para las llamadas API a Microsoft Entra ID. El mismo valor que 'proxy' (el campo está vacío)
proxy_endpoint Especifique la dirección URL de proxy que se va a usar para las llamadas API al punto de conexión de recopilación de datos. El mismo valor que 'proxy' (el campo está vacío)

Ejemplo: Sección de configuración del complemento de salida

output {
    microsoft-sentinel-log-analytics-logstash-output-plugin {
      client_app_Id => "<enter your client_app_id value here>"
      client_app_secret => "<enter your client_app_secret value here>"
      tenant_id => "<enter your tenant id here> "
      data_collection_endpoint => "<enter your logsIngestion URI here> "
      dcr_immutable_id => "<enter your DCR immutableId here> "
      dcr_stream_name => "<enter your stream name here> "
      create_sample_file=> false
      sample_file_path => "c:\\temp"
      proxy => "http://proxy.example.com"
    }
}

Para establecer otros parámetros para el complemento de salida de Logstash de Microsoft Sentinel, consulte el archivo readme del complemento de salida.

Nota:

Por motivos de seguridad, se recomienda no indicar implícitamente los atributos client_app_Id, client_app_secret, tenant_id, data_collection_endpoint y dcr_immutable_id en el archivo de configuración de Logstash. Se recomienda almacenar esta información confidencial en un almacén de claves de Logstash.

Reinicio de Logstash

Reinicie Logstash con la configuración actualizada del complemento de salida y vea que los datos se ingieren en la tabla correcta según la configuración de DCR.

Visualización de los registros entrantes en Microsoft Sentinel

  1. Compruebe que los mensajes se envían al complemento de salida.

  2. En el menú de navegación de Microsoft Sentinel, haga clic en Registros. En el encabezado Tablas, expanda la categoría Registros personalizados. Busque y haga clic en el nombre de la tabla que especificó (con un sufijo _CL) en la configuración.

    Captura de pantalla de registros personalizados de Logstash.

  3. Para ver los registros de la tabla, consulte la tabla usando su nombre como esquema.

    Captura de pantalla de una consulta de registros personalizados de Logstash.

Supervisión de registros de auditoría de complementos de salida

Para supervisar la conectividad y la actividad del complemento de salida de Microsoft Sentinel, habilite el archivo de registro de Logstash adecuado. Consulte el documento Diseño del directorio de Logstash para conocer la ubicación del archivo de registro.

Si no ve ningún dato en este archivo de registro, genere y envíe algunos eventos localmente (a través de los complementos de entrada y filtro) para asegurarse de que el complemento de salida está recibiendo datos. Microsoft Sentinel solo ofrece soporte técnico para los problemas relacionados con el complemento de salida.

Seguridad de red

Defina la configuración de red y habilite el aislamiento de red para el complemento de salida Logstash de Microsoft Sentinel.

Etiquetas de servicio de red virtual

El complemento de salida de Microsoft Sentinel es compatible con las etiquetas de servicio de red virtual Azure. Se requieren etiquetas AzureMonitor y AzureActiveDirectory.

Las etiqueta de servicio de red de Azure Virtual se pueden usar para definir controles de acceso a la red en grupos de seguridad de red, Azure Firewall y rutas definidas por el usuario. Use etiquetas de servicio en lugar de direcciones IP específicas cuando cree reglas de seguridad y rutas. Para los escenarios en los que no se pueden usar etiquetas de servicio de red virtual de Azure, se indican a continuación los requisitos de Firewall.

Requisitos de firewall

En la tabla siguiente se enumeran los requisitos de firewall para escenarios en los que no se pueden usar etiquetas de servicio de red virtual de Azure.

Nube Punto de conexión Propósito Port Dirección Omitir inspección de HTTPS
Azure Commercial https://login.microsoftonline.com Servidor de autorización (la plataforma de identidad de Microsoft) Puerto 443 Salida Sí
Azure Commercial https://<data collection endpoint name>.<Azure cloud region>.ingest.monitor.azure.com Puntos de conexión de recopilación de datos Puerto 443 Salida Sí
Azure Government https://login.microsoftonline.us Servidor de autorización (la plataforma de identidad de Microsoft) Puerto 443 Salida Sí
Azure Government Reemplace el ".com" anterior por ".us". Puntos de conexión de recopilación de datos Puerto 443 Salida Sí
Microsoft Azure operado por 21Vianet https://login.chinacloudapi.cn Servidor de autorización (la plataforma de identidad de Microsoft) Puerto 443 Salida Sí
Microsoft Azure operado por 21Vianet Reemplace el ".com" anterior por ".cn". Puntos de conexión de recopilación de datos Puerto 443 Salida Sí

Limitaciones

Pasos siguientes

En este artículo, aprendió a usar Logstash para conectar orígenes de datos externos a Microsoft Sentinel. Para obtener más información sobre Microsoft Sentinel, consulte los siguientes artículos: