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, а также для тестирования.

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

Прежде чем что-либо делать, убедитесь, что ваше окружение готово:

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

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

pip3 install --upgrade SuricataLog

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

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

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

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

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 .

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

(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 Программируемое завершение

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

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

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

eve_autocomplete --help

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

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

Это мой текущий тестовый стенд, и он может измениться без предварительного уведомления

Вы можете:

• Отправлять патчи с новыми функциями и исправлениями ошибок.
• Открывать отчёты об ошибках. Будьте максимально подробны, иначе у меня не будет другого выбора, кроме как закрыть его.

Учебные пособия

• Suricata, RaspberryPI4 и Python для защиты вашей домашней сети
• Использование SuricataLog для анализа ваших событий