SuricataLog

Когда я начал изучать, как использовать Suricata, я быстро обнаружил, что мне нужен инструмент для просмотра файла eve.json; большинство руководств и документации, которые я находил, предлагали установить стек для выполнения следующих задач:

1. Хранить логи в центральном месте
2. Нормализовать и обогащать события, особенно оповещения
3. Использовать фронтенд для погружения в данные

Что очень полезно, но что если мне просто нужно было быстро просмотреть события?

Рано или поздно вам надоест до смерти делать это:

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

SuricataLog — это набор инструментов/скриптов для разбора и отображения лог-файлов Suricata (таких как /var/log/suricata/eve.json)

Формат Eve JSON не очень сложен, поэтому я написал несколько скриптов с функциями, которые, как я считал, будут наиболее полезны для анализа моей домашней сети.

В качестве бонуса я описал свой опыт обучения в руководстве, которое вы можете использовать, чтобы изучить Suricata, а также узнать, как её тестировать.

Установка из Pypi

Установка из Pypi.org

uv pip install SuricataLog

Установка из исходного кода

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
uv build
uv pip install dist/suricatalog-1.1.6-py3-none-any.whl

Установка для разработчиков

Итак, вы хотите внести свой вклад? Или нашли ошибку и думаете, что можете отправить патч? Отлично! Вот что вы можете сделать, чтобы запустить режим разработки:

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
uv build
uv sync --dev
uv pip install --editable .

Запустить модульные тесты после этого очень просто:

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

OK

Если модульные тесты не проходят, то это, скорее всего, первое место, где нужно исправить проблему.

Я также рекомендую запустить консоль textualize и следить за сообщениями консоли:

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

Затем в другом терминале:

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

Это выведет даже отладочные сообщения в консоль (вы можете исключить их, если перезапустите консоль с '--exclude DEBUG')

Создание Docker-образа

Пожалуйста, ознакомьтесь с DOCKER.md для получения более подробной информации.

Запуск скриптов

После того как всё установлено в вашей виртуальной среде, вы должны иметь возможность вызывать скрипты

Вы можете узнать, какие приложения установились, используя автодополнение после активации виртуальной среды:

eve_[tab][tab]

А если вы установите расширение автодополнения Bash, вы также получите некоторые подсказки для флагов.

Простой парсер EVE-логов

Лучше увидеть самому (помните, используйте --help, чтобы узнать, какие опции поддерживаются)

Формат таблицы:

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

Готовые отчёты с 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

Взгляните на несколько примеров ниже:

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

Запуск приложений eve_* в браузере

Вы можете запускать приложения Suricata Log в браузере, используя обёртку 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

Вам нужно передать '--', чтобы сообщить серверу, что эти опции принадлежат вызываемому eve_*, который вы хотите запустить.

Запуск из Docker

Также возможно запустить SuricataLog из Docker-контейнера. Пожалуйста, ознакомьтесь с DOCKER.md для получения более подробной информации

Запуск с uv

Если у вас есть uv, вы можете просто сделать это:

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

Вы поняли идею.

Автодополнение Bash

Я старался следовать 8.6 Programmable Completion

Я предоставил автодополнение для наиболее распространённых флагов. Вы можете узнать все флаги, передав '--help' любому из скриптов.

Установка команд автодополнения

Вы можете установить автодополнение Bash для всех скриптов SuricataLog. Просто запустите 'eve_autocomplete' и следуйте инструкциям:

eve_autocomplete --help

Поддерживаемые версии

Я работаю над этим проектом в свободное время, и я не могу поддерживать все возможные комбинации Linux/Python. Это моя текущая тестовая среда, и она может измениться без дополнительного уведомления