SuricataLog

Cuando empecé a aprender cómo usar Suricata, rápidamente descubrí que necesitaba una herramienta para inspeccionar el archivo eve.json; la mayoría de los tutoriales y la documentación disponibles sugerían instalar un stack para realizar las siguientes tareas:

1. Almacenar los registros en una ubicación centralizada
2. Normalizar y enriquecer los eventos, especialmente las alertas
3. Usar un frontend para explorar los datos

Lo cual es muy útil, pero ¿qué pasa si solo necesito hacer una inspección rápida de los eventos?

Tarde o temprano te aburrirás hasta la muerte haciendo esto:

cat eve.json | jq -r -c 'select(.event_type=="alert")|.payload'| base64 --decode

SuricataLog es un conjunto de herramientas/scripts para analizar y mostrar archivos de registro de Suricata (como /var/log/suricata/eve.json)

El formato Eve JSON no es muy complejo, así que escribí algunos scripts con las funciones que pensé que serían más útiles para el análisis de mi red doméstica.

Como bonus, escribí mi experiencia de aprendizaje como un tutorial que puedes usar para aprender sobre Suricata y también cómo probarlo.

Instalación desde PIP

Antes de hacer cualquier otra cosa, asegúrate de que tu entorno esté listo:

python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
python3 -m pip install --upgrade pip setuptools wheel

Instalación desde Pypi.org

pip3 install --upgrade SuricataLog

Instalación desde el código fuente

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
python3 -m pip install --upgrade build
python3 -m build
pip3 install dist/SuricataLog-X.Y.Z-py3-none-any.whl

Instalación para desarrolladores

¿Quieres contribuir? ¿O encontraste un error y crees que puedes enviar un parche? ¡Genial! Esto es lo que puedes hacer para ejecutar en modo de desarrollo:

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
pip install --upgrade pip
python -m pip install --upgrade build
pip install textual-dev
pip install --editable .

Ejecutar las pruebas unitarias es muy fácil después de eso:

(SuricataLog) [josevnz@dmaf5 SuricataLog]$ python -m unittest test/*.py
.........
----------------------------------------------------------------------
Ran 9 tests in 0.334s

OK

Si las pruebas unitarias fallan, entonces este es probablemente el primer lugar para solucionar un problema.

También recomiendo ejecutar la consola de textualize y observar los mensajes de la consola:

# textual console
textual console --exclude SYSTEM --exclude EVENT

Luego, en otra terminal:

textual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json

Eso imprimirá incluso mensajes de depuración en la consola (puedes excluirlos si reinicias la consola con '--exclude DEBUG')

Creación de una imagen Docker

Por favor, consulta DOCKER.md para más detalles.

Ejecución de los scripts

Una vez que todo esté instalado en tu entorno virtual, deberías poder llamar a los scripts.

Puedes averiguar qué aplicaciones se instalaron usando el autocompletado, después de activar tu entorno virtual:

eve_[tab][tab]

Y si instalas la extensión de autocompletado de Bash, también obtendrás algunas sugerencias para las banderas.

Analizador simple de registros EVE

Mejor véelo por ti mismo (recuerda, usa --help para aprender qué opciones están disponibles)

Formato de tabla:

eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json

Informes predefinidos con eve_json.py

(suricatalog) [josevnz@dmaf5 SuricataLog]$ eve_json --help
usage: eve_json [-h] [--nxdomain | --payload | --flow | --netflow NETFLOW | --useragent] eve [eve ...]

Este script está inspirado en los ejemplos proporcionados en [15.1.3. Eve JSON 'jq' Examples](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-
examplesjq.html) Algunas cosas: * La salida usa JSON coloreado

positional arguments:
  eve                Ruta a uno o más archivos /var/log/suricata/eve.json para analizar.

optional arguments:
  -h, --help         Muestra este mensaje de ayuda y salida
  --nxdomain         Muestra registros DNS con NXDOMAIN
  --payload          Muestra alertas con un payload imprimible
  --flow             Informe de flujo agregado por protocolo y puerto de destino
  --netflow NETFLOW  Obtiene el netflow para una dirección IP dada
  --useragent        Agente de usuario principal en el tráfico HTTP

Mira algunos ejemplos a continuación:

NXDOMAIN

eve_json --nxdomain test/eve.json

PAYLOAD

eve_json --payload ~/Downloads/eve.json

FLOW

eve_json --flow test/eve_udp_flow.json

NETFLOW

eve_json --netflow 224.0.0.251 test/eve_udp_flow.json

USERAGENT

eve_json --useragent test/eve.json

Ejecutar aplicaciones eve_* en un navegador

Puedes ejecutar las aplicaciones de Suricata Log en un navegador usando el envoltorio eve_server:

# Muestra el informe de flujo en un archivo eve.json
eve_server --application eve_json -- --flow ~/eve.json

# Muestra el informe de NX domain
eve_server --application eve_json -- --nxdomain ~/eve.json

# Inspecciona los registros de eve.json
eve_server --applications eve_log -- ~/eve.json

Debes pasar '--' para indicar al servidor que estas opciones pertenecen a la eve_* subyacente que deseas llamar.

Ejecutar desde Docker

También es posible ejecutar SuricataLog desde un contenedor Docker. Consulta DOCKER.md para más detalles.

Ejecutar con uv

Si tienes uv, puedes hacer simplemente esto:

uvx --from SuricataLog eve_log /var/log/suricata/eve.json
uvx --from SuricataLog eve_json --useragent /var/log/suricata/eve.json
uvx --from SuricataLog eve_server --application eve_json -- --flow /var/log/suricata/eve.json

Te haces una idea.

Autocompletado de Bash

Hice lo mejor que pude para seguir 8.6 Programmable Completion

Proporcioné autocompletado para las banderas más comunes. Puedes descubrir todas las banderas pasando '--help' a cualquiera de los scripts.

Instalación de los comandos de autocompletado

Puedes instalar el autocompletado de Bash para todos los scripts de SuricataLog. Simplemente ejecuta 'eve_autocomplete' y sigue las instrucciones:

eve_autocomplete --help

Versiones compatibles

Trabajo en este proyecto en mi tiempo libre y no puedo soportar todas las combinaciones de versiones de Linux/Python que existen. Esta es mi plataforma de pruebas actual, y puede cambiar sin previo aviso

Eres más que bienvenido a:

• Enviar parches con nuevas funcionalidades y correcciones de errores.
• Abrir informes de errores. Sé lo más detallado posible, de lo contrario no tendré más remedio que cerrarlo.

Tutoriales

• Suricata, RaspberryPI4 y Python para asegurar tu red doméstica
• Usar SuricataLog para analizar tus eventos