SuricataLog

Quando ho iniziato a imparare come usare Suricata ho subito scoperto che avevo bisogno di uno strumento per ispezionare il file eve.json; la maggior parte dei tutorial e della documentazione in circolazione suggeriva di installare uno stack per svolgere le seguenti attività:

1. Archiviare i log in una posizione centrale
2. Normalizzare e arricchire gli eventi, in particolare gli avvisi
3. Usare un frontend per analizzare i dati

Il che è molto utile, ma cosa succede se avevo solo bisogno di fare una rapida ispezione degli eventi?

Prima o poi ti annoierai a morte facendo questo:

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

SuricataLog è un insieme di strumenti/script per analizzare e visualizzare i file di log di Suricata (come /var/log/suricata/eve.json)

Il formato Eve JSON non è molto complesso, quindi ho scritto alcuni script con le funzionalità che pensavo potessero essere più utili per l'analisi della mia rete domestica.

Come bonus, ho scritto la mia esperienza di apprendimento come tutorial che puoi usare per imparare su Suricata e anche come testarlo.

Installazione da Pypi

Installazione da Pypi.org

uv pip install SuricataLog

Installazione dal sorgente

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

Installazione per sviluppatori

Quindi vuoi contribuire? O hai trovato un bug e pensi di poter inviare una patch? Ottimo! Ecco cosa puoi fare per eseguire in modalità sviluppo:

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
uv build
uv sync --dev
uv pip install --editable .

Eseguire gli unit test è molto semplice dopo questo:

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

OK

Se gli unit test falliscono, allora questo è molto probabilmente il primo posto dove risolvere un problema.

Consiglio anche di eseguire la console textualize e osservare i messaggi della console:

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

Poi su un altro terminale:

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

Questo stamperà anche i messaggi di debug sulla console (puoi escluderli se riavvii la console con '--exclude DEBUG')

Creazione di un'immagine Docker

Consulta DOCKER.md per maggiori dettagli.

Esecuzione degli script

Una volta che tutto è installato nel tuo ambiente virtuale dovresti essere in grado di chiamare gli script

Puoi scoprire quali applicazioni sono state installate usando l'autocompletamento, dopo aver attivato il tuo ambiente virtuale:

eve_[tab][tab]

E se installi l'estensione di autocompletamento Bash otterrai anche alcuni suggerimenti per i flag.

Semplice parser di log EVE

Meglio vederlo da soli (ricorda, usa --help per scoprire quali opzioni sono supportate)

Formato tabella:

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

Report predefiniti 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

Dai un'occhiata ad alcuni esempi qui sotto:

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

Esecuzione delle applicazioni eve_* su un browser

Puoi eseguire le applicazioni Suricata Log su un browser usando il 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

Devi passare il '--' per indicare al server che queste opzioni appartengono all'eve_* sottostante che vuoi chiamare.

Esecuzione da Docker

È anche possibile eseguire SuricataLog da un container Docker. Consulta DOCKER.md per maggiori dettagli

Esecuzione con uv

Se hai uv, puoi semplicemente fare questo:

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

Hai capito il concetto.

Autocompletamento Bash

Ho fatto del mio meglio per seguire 8.6 Programmable Completion

Ho fornito l'autocompletamento per i flag più comuni. Puoi scoprire tutti i flag passando '--help' a uno qualsiasi degli script.

Installazione dei comandi di autocompletamento

Puoi installare l'autocompletamento Bash per tutti gli script di SuricataLog. Basta eseguire 'eve_autocomplete' e seguire le istruzioni:

eve_autocomplete --help

Versioni supportate