SuricataLog

Quando comecei a aprender a usar o Suricata, 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 a fazer isto:

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 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 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

uv pip install SuricataLog

Instalar a partir do código-fonte

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:

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:

(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:

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

Depois noutro terminal:

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 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:

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:

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

Relatórios pré-definidos com 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

Vê alguns exemplos abaixo:

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

Correr aplicações eve_* num navegador

Podes correr as aplicações Suricata Log num navegador usando o wrapper eve_server:

# 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 para mais detalhes

Correr com uv

Se tiveres uv, podes simplesmente fazer isto:

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

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:

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