SuricataLog

Quand j'ai commencé à apprendre à utiliser Suricata, j'ai vite découvert que j'avais besoin d'un outil pour inspecter le fichier eve.json ; la plupart des tutoriels et de la documentation suggéraient d'installer une pile pour effectuer les tâches suivantes :

1. Stocker les logs dans un emplacement centralisé
2. Normaliser et enrichir les événements, en particulier les alertes
3. Utiliser un frontal pour explorer les données

Ce qui est très utile, mais que faire si je voulais simplement inspecter rapidement les événements ?

Tôt ou tard, vous en aurez marre à mourir de faire ceci :

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 log Suricata (comme /var/log/suricata/eve.json)

Le format Eve JSON 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 prime, j'ai rédigé mon expérience d'apprentissage sous forme de tutoriel que vous pouvez utiliser pour apprendre Suricata et aussi comment le tester.

Installation via PIP

Avant toute chose, assurez-vous que votre environnement est prêt :

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

Installation depuis Pypi.org

pip3 install --upgrade SuricataLog

Installation depuis les sources

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

Installation pour le développement

Vous voulez contribuer ? Ou vous avez trouvé un bug et pensez pouvoir soumettre un correctif ? Super ! Voici comment faire pour exécuter en mode développement :

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 .

Exécuter les tests unitaires est très facile ensuite :

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

OK

Si les tests unitaires échouent, c'est 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 :

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

Ensuite, dans un autre terminal :

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 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'auto-complétion, après avoir activé votre environnement virtuel :

eve_[tab][tab]

Et si vous installez l'extension d'auto-complétion Bash, vous obtiendrez également des suggestions pour les options.

Analyseur simple de logs EVE

Voyez par vous-même (rappelez-vous, utilisez --help pour connaître les options prises en charge)

Format tableau :

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

Rapports prêts à l'emploi avec 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

Jetez un œil à quelques exemples ci-dessous :

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

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 :

# Afficher le rapport de flux sur un fichier eve.json
eve_server --application eve_json -- --flow ~/eve.json

# Afficher le rapport NX domain
eve_server --application eve_json -- --nxdomain ~/eve.json

# Inspecter les enregistrements eve.json
eve_server --applications eve_log -- ~/eve.json

Vous devez passer le '--' pour indiquer au serveur que ces options appartiennent à l'eve_* que vous souhaitez appeler.

Exécution depuis Docker

Il est également possible d'exécuter SuricataLog depuis un conteneur Docker. Veuillez consulter le DOCKER.md pour plus de détails

Exécution avec uv

Si vous avez uv, vous pouvez simplement faire ceci :

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 avez compris l'idée.

Auto-complétion Bash

J'ai fait de mon mieux pour suivre 8.6 Programmable Completion

J'ai fourni l'auto-complétion pour les options les plus courantes. Vous pouvez découvrir toutes les options en passant '--help' à n'importe quel script.

Installation des commandes d'auto-complétion

Vous pouvez installer l'auto-complétion Bash pour tous les scripts SuricataLog. Exécutez simplement 'eve_autocomplete' et suivez les instructions :

eve_autocomplete --help

Versions prises en charge

Je travaille sur ce projet sur mon temps libre et je ne peux pas prendre en charge toutes les combinaisons de versions Linux/Python existantes. Voici mon banc d'essai actuel, et il peut changer sans préavis

Vous êtes les bienvenus 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
• Utiliser SuricataLog pour analyser vos événements