josevnz/suricatalogAnalizza, filtra e visualizza i log Suricata eve.json con strumenti CLI per alert, flussi, DNS e payload. Include un tutorial per imparare Suricata e testare le regole.
# SuricataLog [](https://pepy.tech/project/suricatalog) Quando ho iniziato a imparare come usare [Suricata](https://suricata.io/) 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](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-examplesjq.html) facendo questo: ```shell 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](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-format.html) 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](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) che puoi usare per imparare su Suricata e anche come testarlo. ## Installazione da Pypi ### Installazione da Pypi.org ```shell uv pip install SuricataLog ``` ### Installazione dal sorgente ```shell 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: ```shell 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: ```shell (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: ```shell # textual console textual console --exclude SYSTEM --exclude EVENT ``` Poi su un altro terminale: ```shell 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](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/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: ```shell 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:  ````shell eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json ```` ### Report predefiniti 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 ``` Dai un'occhiata ad alcuni esempi qui sotto: #### 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 ``` ### Esecuzione delle applicazioni eve_* su un browser  Puoi eseguire le applicazioni Suricata Log su un browser usando il 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 ``` 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](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/DOCKER.md) per maggiori dettagli ## Esecuzione con uv Se hai uv, puoi semplicemente fare questo: ```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 ``` Hai capito il concetto. ## Autocompletamento Bash Ho fatto del mio meglio per seguire [8.6 Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#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: ```shell eve_autocomplete --help ``` ## Versioni supportate Lavoro a questo progetto nel **mio tempo libero** e non posso supportare ogni combinazione di Linux/Python esistente. Questo è il mio attuale banco di prova, e potrebbe cambiare senza ulteriore preavviso | 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 | *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 chiuderla. ## Tutorial * [Suricata, RaspberryPI4 e Python per proteggere la tua rete domestica](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) * [Usare SuricataLog per analizzare i tuoi eventi](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/Using_SuricataLog_to_analyze_your_events.md)
