SuricataLog

Cuando empecé a aprender a 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 disponible sugerían instalar un stack para realizar las siguientes tareas:

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

Lo cual es muy útil, pero ¿y si solo necesitaba hacer una inspección rápida de los eventos?

Tarde o temprano te morirás de aburrimiento haciendo esto:

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

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

El formato Eve JSON no es muy complejo, así que escribí algunos scripts con las características 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 Pypi

Instalación desde Pypi.org

uv pip install SuricataLog

Instalación desde el código fuente

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
uv build
uv pip install dist/suricatalog-1.1.6-py3-none-any.whl

Instalación para desarrolladores

¿Así que quieres contribuir? ¿O encontraste un bug y crees que puedes enviar un parche? ¡Genial! Esto es lo que puedes hacer para ejecutar en modo desarrollo:

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
uv build
uv sync --dev
uv 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 donde arreglar 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 los mensajes de depuración en la consola (puedes excluirlos si reinicias la consola con '--exclude DEBUG')

Creando una imagen Docker

Por favor revisa DOCKER.md para más detalles.

Ejecutando los scripts

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

Puedes descubrir 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 los flags.

Parser simple de logs EVE

Mejor velo por ti mismo (recuerda, usa --help para aprender qué opciones están soportadas)

Formato de tabla:

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

Reportes predefinidos con eve_json.py

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

This script is inspired by the examples provided on [15.1.3. Eve JSON ‘jq’ Examples](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-
examplesjq.html) A few things: * The output uses colorized JSON

positional arguments:
  eve                Path to one or more /var/log/suricata/eve.json file to parse.

optional arguments:
  -h, --help         show this help message and exit
  --nxdomain         Show DNS records with NXDOMAIN
  --payload          Show alerts with a printable payload
  --flow             Aggregated flow report per protocol and destination port
  --netflow NETFLOW  Get the netflow for a given IP address
  --useragent        Top user agent in HTTP traffic

Echa un vistazo a 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

Ejecutando aplicaciones eve_* en un navegador

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

# Show the flow report on a eve.json file
eve_server --application eve_json -- --flow ~/eve.json

# Show NX domain report
eve_server --application eve_json -- --nxdomain ~/eve.json

# Inspect the eve.json records
eve_server --applications eve_log -- ~/eve.json

Necesitas pasar el '--' para indicarle al servidor que esas opciones pertenecen al eve_* subyacente que quieres llamar.

Ejecutando desde Docker

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

Ejecutando con uv

Si tienes uv, puedes simplemente hacer 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

Ya te haces una idea.

Autocompletado de Bash

Hice mi mejor esfuerzo por seguir 8.6 Programmable Completion

Proporcioné autocompletado para los flags más comunes. Puedes descubrir todos los flags 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. Solo ejecuta 'eve_autocomplete' y sigue las instrucciones:

eve_autocomplete --help

Versiones soportadas