josevnz/suricatalogAnalyser, filtrer et visualiser les logs eve.json de Suricata avec des outils CLI pour les alertes, les flux, le DNS et les payloads. Inclut un tutoriel pour apprendre Suricata et tester des règles.
# SuricataLog [](https://pepy.tech/project/suricatalog) Lorsque j'ai commencé à apprendre à utiliser [Suricata](https://suricata.io/), j'ai rapidement constaté que j'avais besoin d'un outil pour inspecter le fichier eve.json ; la plupart des tutoriels et de la documentation disponibles suggéraient d'installer une pile pour effectuer les tâches suivantes : 1. Stocker les journaux dans un emplacement central 2. Normaliser et enrichir les événements, en particulier les alertes 3. Utiliser une interface frontend pour explorer les données Ce qui est très utile, mais que faire si j'avais simplement besoin d'inspecter rapidement les événements ? Tôt ou tard, vous finirez par vous [ennuyer à mourir](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-examplesjq.html) à faire ceci : ```shell cat eve.json | jq -r -c 'select(.event_type=="alert")|.payload'| base64 --decode ``` SuricataLog est un ensemble d'outils/scripts pour analyser et afficher les fichiers de journaux Suricata (comme /var/log/suricata/eve.json) Le [format Eve JSON](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-format.html) n'est pas très complexe, j'ai donc écrit quelques scripts avec les fonctionnalités que je pensais être les plus utiles pour l'analyse de mon réseau domestique. En bonus, j'ai rédigé mon expérience d'apprentissage sous forme de [tutoriel](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) que vous pouvez utiliser pour en savoir plus sur Suricata et aussi comment le tester. ## Installation depuis Pypi ### Installation depuis Pypi.org ```shell uv pip install SuricataLog ``` ### Installation depuis les sources ```shell git clone [email protected]:josevnz/SuricataLog.git cd SuricataLog uv build uv pip install dist/suricatalog-1.1.6-py3-none-any.whl ``` ### Installation pour le développement Vous souhaitez contribuer ? Ou vous avez trouvé un bug et pensez pouvoir soumettre un correctif ? Parfait ! Voici ce que vous pouvez faire pour exécuter en mode développement : ```shell git clone [email protected]:josevnz/SuricataLog.git cd SuricataLog uv build uv sync --dev uv pip install --editable . ``` Exécuter les tests unitaires est très simple ensuite : ```shell (SuricataLog) [josevnz@dmaf5 SuricataLog]$ python -m unittest test/*.py ......... ---------------------------------------------------------------------- Ran 9 tests in 0.334s OK ``` Si les tests unitaires échouent, c'est très probablement le premier endroit où corriger un problème. Je recommande également d'exécuter la console textualize et de surveiller les messages de la console : ```shell # textual console textual console --exclude SYSTEM --exclude EVENT ``` Puis dans un autre terminal : ```shell textual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json ``` Cela affichera même les messages de débogage sur la console (vous pouvez les exclure si vous redémarrez la console avec '--exclude DEBUG') ### Création d'une image Docker Veuillez consulter [DOCKER.md](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/DOCKER.md) pour plus de détails. ## Exécution des scripts Une fois que tout est installé dans votre environnement virtuel, vous devriez pouvoir appeler les scripts Vous pouvez découvrir quelles applications ont été installées en utilisant l'autocomplétion, après avoir activé votre environnement virtuel : ```shell eve_[tab][tab] ``` Et si vous installez l'extension d'autocomplétion Bash, vous obtiendrez également des suggestions pour les options. ### Analyseur simple de journal EVE Mieux vaut le voir par vous-même (rappelez-vous, utilisez --help pour découvrir les options prises en charge) #### Format tableau :  ````shell eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json ```` ### Rapports prédéfinis avec 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 ``` Jetez un œil à quelques exemples ci-dessous : #### 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 ``` ### Exécution des applications eve_* dans un navigateur  Vous pouvez exécuter les applications Suricata Log dans un navigateur en utilisant le 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 ``` Vous devez passer le '--' pour indiquer au serveur que ces options appartiennent à l'application eve_* sous-jacente que vous souhaitez appeler. ## Exécution depuis Docker Il est également possible d'exécuter SuricataLog depuis un conteneur Docker. Veuillez consulter [DOCKER.md](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/DOCKER.md) pour plus de détails ## Exécution avec uv Si vous avez uv, vous pouvez simplement faire ceci : ```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 ``` Vous voyez l'idée. ## Autocomplétion Bash J'ai fait de mon mieux pour suivre [8.6 Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#Programmable-Completion) J'ai fourni l'autocomplétion pour les options les plus courantes. Vous pouvez découvrir toutes les options en passant '--help' à n'importe lequel des scripts. ### Installation des commandes d'autocomplétion Vous pouvez installer l'autocomplétion Bash pour tous les scripts SuricataLog. Exécutez simplement 'eve_autocomplete' et suivez les instructions : ```shell eve_autocomplete --help ``` ## Versions prises en charge Je travaille sur ce projet **pendant mon temps libre** et je ne peux pas prendre en charge toutes les combinaisons Linux/Python existantes. Voici ma configuration de test actuelle, qui peut changer sans préavis | SuricataLog | Prise en charge | OS | Python | Suricata | |-------------|-----------|----------------------------------|-----------|----------| | <= 0.8 | NON | NA | < 3.8 | 6.04 | | 0.9+ | NON | fedora 37 | => 3.11.4 | 6.04 | | 0.9+ | NON | Armbian 23.02.2 Jammy | => 3.10.6 | 6.04 | | 0.9+ | NON | Ubuntu 20.04.4 LTS (Focal Fossa) | => 3.8.10 | 6.04 | | 1.0.3+ | OUI | fedora 40 | => 3.11.4 | 7.0.6 | *Vous êtes plus que bienvenu pour* : * Soumettre des correctifs avec de nouvelles fonctionnalités et des corrections de bugs. * Ouvrir des rapports de bugs. Soyez aussi détaillé que possible, sinon je n'aurai d'autre choix que de le fermer. ## Tutoriels * [Suricata, RaspberryPI4 et Python pour sécuriser votre réseau domestique](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) * [Utiliser SuricataLog pour analyser vos événements](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/Using_SuricataLog_to_analyze_your_events.md)
