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 alert
3. Utilizzare un frontend per esplorare i dati

Il che è molto utile, ma se avessi solo bisogno di fare una veloce ispezione degli eventi?

Prima o poi ti annoi a morte a fare così:

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 ritenevo più utili per l'analisi della mia rete domestica.

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

Installazione da PIP

Prima di fare qualsiasi altra cosa, assicurati che il tuo ambiente sia pronto:

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

Installazione da Pypi.org

pip3 install --upgrade SuricataLog

Installazione da sorgente

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

Installazione per sviluppatori

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

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 .

Eseguire i test unitari è molto semplice dopo:

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

OK

Se i test unitari falliscono, 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

Per maggiori dettagli, consulta DOCKER.md.

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 il completamento automatico, dopo aver attivato il tuo ambiente virtuale:

eve_[tab][tab]

E se installi l'estensione di completamento automatico Bash, riceverai anche alcuni suggerimenti per i flag.

Semplice parser di log EVE

Meglio vedere da soli (ricorda, usa --help per conoscere le opzioni 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:

# Mostra il report del flusso su un file eve.json
eve_server --application eve_json -- --flow ~/eve.json

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

# Ispeziona i record di eve.json
eve_server --applications eve_log -- ~/eve.json

Devi passare '--' per dire 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:

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 l'idea.

Completamento automatico Bash

Ho cercato di seguire 8.6 Programmable Completion

Ho fornito il completamento automatico per i flag più comuni. Puoi scoprire tutti i flag passando '--help' a qualsiasi script.

Installazione dei comandi di completamento automatico

Puoi installare il completamento automatico Bash per tutti gli script SuricataLog. Basta eseguire 'eve_autocomplete' e seguire le istruzioni:

eve_autocomplete --help

Versioni supportate

Lavoro a questo progetto nel mio tempo libero e non posso supportare ogni combinazione di Linux/Python in circolazione. Questa è la mia configurazione di test attuale, e potrebbe cambiare senza preavviso.

Sei più che benvenuto a:

• Inviare patch con nuove funzionalità e correzioni di bug.
• Aprire segnalazioni di bug. Sii il più dettagliato possibile, altrimenti non avrò altra scelta che chiuderle.

Tutorial

• Suricata, RaspberryPI4 e Python per proteggere la tua rete domestica
• Usare SuricataLog per analizzare i tuoi eventi