josevnz/suricatalogAnalise, filtre e visualize logs eve.json do Suricata com ferramentas CLI para alertas, fluxos, DNS e payloads. Inclui um tutorial para aprender Suricata e testar regras.
# SuricataLog [](https://pepy.tech/project/suricatalog) Quando comecei a aprender a usar o [Suricata](https://suricata.io/), rapidamente percebi que precisava de uma ferramenta para inspecionar o arquivo eve.json; A maioria dos tutoriais e da documentação disponível sugeria instalar uma stack para realizar as seguintes tarefas: 1. Armazenar os logs num local central 2. Normalizar e enriquecer os eventos, especialmente os alertas 3. Usar um frontend para explorar os dados O que é muito útil, mas e se eu só precisasse de fazer uma inspeção rápida dos eventos? Mais cedo ou mais tarde vais [morrer de tédio](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-examplesjq.html) a fazer isto: ```shell cat eve.json | jq -r -c 'select(.event_type=="alert")|.payload'| base64 --decode ``` SuricataLog é um conjunto de ferramentas/scripts para analisar e apresentar ficheiros de log do Suricata (como /var/log/suricata/eve.json) O [formato Eve JSON](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-format.html) não é muito complexo, por isso escrevi alguns scripts com as funcionalidades que achei que seriam mais úteis para a análise da minha rede doméstica. Como bónus, escrevi a minha experiência de aprendizagem como um [tutorial](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) que podes usar para aprender sobre o Suricata e também como testá-lo. ## Instalar a partir do Pypi ### Instalar a partir do Pypi.org ```shell uv pip install SuricataLog ``` ### Instalar a partir do código-fonte ```shell git clone [email protected]:josevnz/SuricataLog.git cd SuricataLog uv build uv pip install dist/suricatalog-1.1.6-py3-none-any.whl ``` ### Instalação para programadores Então queres contribuir? Ou encontraste um bug e achas que podes submeter um patch? Boa! Aqui está o que podes fazer para correr em modo de desenvolvimento: ```shell git clone [email protected]:josevnz/SuricataLog.git cd SuricataLog uv build uv sync --dev uv pip install --editable . ``` Correr os testes unitários é muito fácil depois disso: ```shell (SuricataLog) [josevnz@dmaf5 SuricataLog]$ python -m unittest test/*.py ......... ---------------------------------------------------------------------- Ran 9 tests in 0.334s OK ``` Se os testes unitários falharem, então este é provavelmente o primeiro sítio onde deves corrigir um problema. Recomendo também correr a consola textualize e ficar atento às mensagens da consola: ```shell # textual console textual console --exclude SYSTEM --exclude EVENT ``` Depois noutro terminal: ```shell textual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json ``` Isso vai imprimir até mensagens de debug na consola (podes excluí-las se reiniciares a consola com '--exclude DEBUG') ### Criar uma imagem Docker Consulta o [DOCKER.md](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/DOCKER.md) para mais detalhes. ## Correr os scripts Depois de tudo instalado no teu ambiente virtual, deves conseguir chamar os scripts Podes descobrir que aplicações foram instaladas usando o auto completar, depois de ativares o teu ambiente virtual: ```shell eve_[tab][tab] ``` E se instalares a extensão de auto completar do Bash também terás algumas sugestões para as flags. ### Parser simples de log EVE Melhor veres por ti próprio (lembra-te, usa --help para saber que opções são suportadas) #### Formato de tabela:  ````shell eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json ```` ### Relatórios pré-definidos com 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 ``` Vê alguns exemplos abaixo: #### 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 ``` ### Correr aplicações eve_* num navegador  Podes correr as aplicações Suricata Log num navegador usando o 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 ``` Precisas de passar o '--' para dizer ao servidor que estas opções pertencem ao eve_* subjacente que queres chamar. ## Correr a partir do Docker Também é possível correr o SuricataLog a partir de um contentor Docker. Consulta o [DOCKER.md](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/DOCKER.md) para mais detalhes ## Correr com uv Se tiveres uv, podes simplesmente fazer isto: ```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 ``` Percebeste a ideia. ## Auto completar do Bash Tentei fazer o meu melhor para seguir [8.6 Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#Programmable-Completion) Forneci auto completar para as flags mais comuns. Podes descobrir todas as flags passando '--help' a qualquer um dos scripts. ### Instalação dos comandos de auto completar Podes instalar o autocompletar do Bash para todos os scripts do SuricataLog. Basta correr o 'eve_autocomplete' e seguir as instruções: ```shell eve_autocomplete --help ``` ## Versões suportadas Trabalho neste projeto **no meu tempo livre** e não consigo suportar todas as combinações de Linux/Python que existem. Este é o meu ambiente de testes atual, e pode mudar sem aviso prévio | 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 | *És mais que bem-vindo a*: * Submeter patches com novas funcionalidades e correções de bugs. * Abrir relatórios de bugs. Sê o mais detalhado possível, caso contrário não terei outra opção senão fechá-lo. ## Tutoriais * [Suricata, RaspberryPI4 and Python to secure your home network](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) * [Using SuricataLog to analyze your events](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/Using_SuricataLog_to_analyze_your_events.md)
