josevnz/suricatalogРазбирайте, фильтруйте и визуализируйте логи Suricata eve.json с помощью инструментов командной строки для предупреждений, потоков, DNS и полезных нагрузок. Включает учебное пособие по изучению Suricata и тестированию правил.
# SuricataLog [](https://pepy.tech/project/suricatalog) Когда я начал изучать, как использовать [Suricata](https://suricata.io/), я быстро обнаружил, что мне нужен инструмент для просмотра файла eve.json; большинство руководств и документации, которые я находил, предлагали установить стек для выполнения следующих задач: 1. Хранить логи в центральном месте 2. Нормализовать и обогащать события, особенно оповещения 3. Использовать фронтенд для погружения в данные Что очень полезно, но что если мне просто нужно было быстро просмотреть события? Рано или поздно вам [надоест до смерти](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-examplesjq.html) делать это: ```shell cat eve.json | jq -r -c 'select(.event_type=="alert")|.payload'| base64 --decode ``` SuricataLog — это набор инструментов/скриптов для разбора и отображения лог-файлов Suricata (таких как /var/log/suricata/eve.json) [Формат Eve JSON](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-format.html) не очень сложен, поэтому я написал несколько скриптов с функциями, которые, как я считал, будут наиболее полезны для анализа моей домашней сети. В качестве бонуса я описал свой опыт обучения в [руководстве](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md), которое вы можете использовать, чтобы изучить Suricata, а также узнать, как её тестировать. ## Установка из Pypi ### Установка из Pypi.org ```shell uv pip install SuricataLog ``` ### Установка из исходного кода ```shell git clone [email protected]:josevnz/SuricataLog.git cd SuricataLog uv build uv pip install dist/suricatalog-1.1.6-py3-none-any.whl ``` ### Установка для разработчиков Итак, вы хотите внести свой вклад? Или нашли ошибку и думаете, что можете отправить патч? Отлично! Вот что вы можете сделать, чтобы запустить режим разработки: ```shell git clone [email protected]:josevnz/SuricataLog.git cd SuricataLog uv build uv sync --dev uv pip install --editable . ``` Запустить модульные тесты после этого очень просто: ```shell (SuricataLog) [josevnz@dmaf5 SuricataLog]$ python -m unittest test/*.py ......... ---------------------------------------------------------------------- Ran 9 tests in 0.334s OK ``` Если модульные тесты не проходят, то это, скорее всего, первое место, где нужно исправить проблему. Я также рекомендую запустить консоль textualize и следить за сообщениями консоли: ```shell # textual console textual console --exclude SYSTEM --exclude EVENT ``` Затем в другом терминале: ```shell textual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json ``` Это выведет даже отладочные сообщения в консоль (вы можете исключить их, если перезапустите консоль с '--exclude DEBUG') ### Создание Docker-образа Пожалуйста, ознакомьтесь с [DOCKER.md](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/DOCKER.md) для получения более подробной информации. ## Запуск скриптов После того как всё установлено в вашей виртуальной среде, вы должны иметь возможность вызывать скрипты Вы можете узнать, какие приложения установились, используя автодополнение после активации виртуальной среды: ```shell eve_[tab][tab] ``` А если вы установите расширение автодополнения Bash, вы также получите некоторые подсказки для флагов. ### Простой парсер EVE-логов Лучше увидеть самому (помните, используйте --help, чтобы узнать, какие опции поддерживаются) #### Формат таблицы:  ````shell eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json ```` ### Готовые отчёты с 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 ``` Взгляните на несколько примеров ниже: #### 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 ``` ### Запуск приложений eve_* в браузере  Вы можете запускать приложения Suricata Log в браузере, используя обёртку `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 ``` Вам нужно передать '--', чтобы сообщить серверу, что эти опции принадлежат вызываемому eve_*, который вы хотите запустить. ## Запуск из Docker Также возможно запустить SuricataLog из Docker-контейнера. Пожалуйста, ознакомьтесь с [DOCKER.md](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/DOCKER.md) для получения более подробной информации ## Запуск с uv Если у вас есть uv, вы можете просто сделать это: ```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 ``` Вы поняли идею. ## Автодополнение Bash Я старался следовать [8.6 Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#Programmable-Completion) Я предоставил автодополнение для наиболее распространённых флагов. Вы можете узнать все флаги, передав '--help' любому из скриптов. ### Установка команд автодополнения Вы можете установить автодополнение Bash для всех скриптов SuricataLog. Просто запустите 'eve_autocomplete' и следуйте инструкциям: ```shell eve_autocomplete --help ``` ## Поддерживаемые версии Я работаю над этим проектом **в свободное время**, и я не могу поддерживать все возможные комбинации Linux/Python. Это моя текущая тестовая среда, и она может измениться без дополнительного уведомления | 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 | *Вы более чем приветствуетесь*: * Отправляйте патчи с новыми функциями и исправлениями ошибок. * Открывайте отчёты об ошибках. Будьте как можно более подробными, иначе у меня не останется выбора, кроме как закрыть его. ## Руководства * [Suricata, RaspberryPI4 и Python для защиты вашей домашней сети](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/TUTORIAL.md) * [Использование SuricataLog для анализа ваших событий](https://github.com/josevnz/suricatalog/blob/dependabot/uv/uv-1176edd47e/Using_SuricataLog_to_analyze_your_events.md)
