josevnz/suricatalogAnaliza, filtra y visualiza registros eve.json de Suricata con herramientas CLI para alertas, flujos, DNS y cargas útiles. Incluye un tutorial para aprender Suricata y probar reglas.
# SuricataLog [](https://pepy.tech/project/suricatalog) Cuando empecé a aprender a usar [Suricata](https://suricata.io/) 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](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-examplesjq.html) haciendo esto: ```shell 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](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-format.html) 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](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) que puedes usar para aprender sobre Suricata y también cómo probarlo. ## Instalación desde Pypi ### Instalación desde Pypi.org ```shell uv pip install SuricataLog ``` ### Instalación desde el código fuente ```shell 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: ```shell 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: ```shell (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: ```shell # textual console textual console --exclude SYSTEM --exclude EVENT ``` Luego en otra terminal: ```shell 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](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/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: ```shell 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:  ````shell eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json ```` ### Reportes predefinidos con eve_json.py ```shell (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  ```shell eve_json --nxdomain test/eve.json ``` #### PAYLOAD  ```shell eve_json --payload ~/Downloads/eve.json ``` #### FLOW  ```shell eve_json --flow test/eve_udp_flow.json ``` #### NETFLOW  ```shell eve_json --netflow 224.0.0.251 test/eve_udp_flow.json ``` #### USERAGENT  ```shell 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`: ```shell # 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](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/DOCKER.md) para más detalles ## Ejecutando con uv Si tienes uv, puedes simplemente hacer esto: ```shell 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](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#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: ```shell eve_autocomplete --help ``` ## Versiones soportadas Trabajo en este proyecto en **mi tiempo libre** y no puedo soportar todas las combinaciones de Linux/Python que existen. Este es mi banco de pruebas actual, y puede cambiar sin previo aviso | SuricataLog | Supported | OS | Python | Suricata | |-------------|-----------|----------------------------------|-----------|----------| | <= 0.8 | NO | NA | < 3.8 | 6.04 | | 0.9+ | NO | fedora 37 | => 3.11.4 | 6.04 | | 0.9+ | NO | Armbian 23.02.2 Jammy | => 3.10.6 | 6.04 | | 0.9+ | NO | Ubuntu 20.04.4 LTS (Focal Fossa) | => 3.8.10 | 6.04 | | 1.0.3+ | YES | fedora 40 | => 3.11.4 | 7.0.6 | *Eres más que bienvenido a*: * Enviar parches con nuevas características y correcciones de bugs. * Abrir reportes de bugs. Sé lo más detallado posible, de lo contrario no tendré otra opción que cerrarlo. ## Tutoriales * [Suricata, RaspberryPI4 y Python para asegurar tu red doméstica](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) * [Usando SuricataLog para analizar tus eventos](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/Using_SuricataLog_to_analyze_your_events.md)
