SuricataLog

Quando comecei a aprender como usar o Suricata, rapidamente descobri que precisava de uma ferramenta para inspecionar o arquivo eve.json; A maioria dos tutoriais e documentação por aí sugeria instalar uma pilha para realizar as seguintes tarefas:

1. Armazenar os logs em um local central
2. Normalizar e enriquecer os eventos, especialmente alertas
3. Usar um frontend para mergulhar nos dados

O que é muito útil, mas e se eu só precisasse fazer uma inspeção rápida dos eventos?

Mais cedo ou mais tarde você vai morrer de tédio fazendo isso:

cat eve.json | jq -r -c 'select(.event_type=="alert")|.payload'| base64 --decode

SuricataLog é um conjunto de ferramentas/scripts para analisar e exibir arquivos de log do Suricata (como /var/log/suricata/eve.json)

O formato Eve JSON não é muito complexo, então escrevi alguns scripts com os recursos que achei mais úteis para a análise da minha rede doméstica.

Como bônus, escrevi minha experiência de aprendizado como um tutorial que você pode usar para aprender sobre o Suricata e também como testá-lo.

Instalando a partir do PIP

Antes de fazer qualquer outra coisa, certifique-se de que seu ambiente está pronto:

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

Instalando a partir do Pypi.org

pip3 install --upgrade SuricataLog

Instalando a partir da fonte

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

Instalação para desenvolvedores

Então você quer contribuir? Ou encontrou um bug e acha que pode enviar um patch? Legal! Aqui está o que você pode fazer para executar em modo de desenvolvimento:

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 .

Executar 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 lugar para corrigir um problema.

Também recomendo executar o console textualize e observar as mensagens do console:

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

Em outro terminal:

textual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json

Isso imprimirá até mensagens de depuração no console (você pode excluí-las se reiniciar o console com '--exclude DEBUG')

Criando uma imagem Docker

Por favor, verifique DOCKER.md para mais detalhes.

Executando os scripts

Uma vez que tudo esteja instalado em seu ambiente virtual, você deve ser capaz de chamar os scripts

Você pode descobrir quais aplicativos foram instalados usando o autocompletar, após ativar seu ambiente virtual:

eve_[tab][tab]

E se você instalar a extensão de autocompletar Bash, também receberá algumas sugestões para as flags.

Analisador simples de log EVE

Melhor ver por si mesmo (lembre-se, use --help para aprender quais 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 ...]

Este script é inspirado nos exemplos fornecidos em [15.1.3. Eve JSON ‘jq’ Examples](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-
examplesjq.html) Algumas coisas: * A saída usa JSON colorido

argumentos posicionais:
  eve                Caminho para um ou mais arquivos /var/log/suricata/eve.json para analisar.

argumentos opcionais:
  -h, --help         Mostra esta mensagem de ajuda e sai
  --nxdomain         Mostra registros DNS com NXDOMAIN
  --payload          Mostra alertas com payload imprimível
  --flow             Relatório de fluxo agregado por protocolo e porta de destino
  --netflow NETFLOW  Obtém o netflow para um determinado endereço IP
  --useragent        Principais user agents no tráfego HTTP

Veja 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

Executando aplicações eve_* em um navegador

Você pode executar as aplicações Suricata Log em um navegador usando o wrapper eve_server:

# Mostrar relatório de fluxo em um arquivo eve.json
eve_server --application eve_json -- --flow ~/eve.json

# Mostrar relatório de NX domain
eve_server --application eve_json -- --nxdomain ~/eve.json

# Inspecionar os registros eve.json
eve_server --applications eve_log -- ~/eve.json

Você precisa passar o '--' para informar ao servidor que essas opções pertencem à eve_* subjacente que você deseja chamar.

Executando a partir do Docker

Também é possível executar SuricataLog a partir de um contêiner Docker. Consulte DOCKER.md para mais detalhes.

Executando com uv

Se você tiver uv, pode simplesmente fazer isso:

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

Você entendeu a ideia.

Autocompletar Bash

Tentei ao máximo seguir 8.6 Programmable Completion

Forneci autocompletar para as flags mais comuns. Você pode descobrir todas as flags passando '--help' para qualquer um dos scripts.

Instalação dos comandos de autocompletar

Você pode instalar o autocompletar Bash para todos os scripts SuricataLog. Basta executar 'eve_autocomplete' e seguir as instruções:

eve_autocomplete --help

Versões suportadas

Trabalho neste projeto no meu tempo livre e não posso suportar todas as combinações de Linux/Python existentes. Esta é minha bancada de testes atual e pode mudar sem aviso prévio.

Você é mais do que bem-vindo para:

• Enviar patches com novos recursos e correções de bugs.
• Abrir relatórios de bugs. Seja o mais detalhado possível, caso contrário não terei escolha a não ser fechá-lo.

Tutoriais

• Suricata, RaspberryPI4 e Python para proteger sua rede doméstica
• Usando SuricataLog para analisar seus eventos