MP Events Monitor

Инструмент мониторинга и анализа источников событий в MaxPatrol

Скрипт предназначен для комплексного анализа состояния источников событий в MP. Позволяет проверить соответствие активов политикам сбора событий, выявить проблемы с аудитом и мониторингом, а также сгенерировать детальные отчеты в формате Excel.

🚀 Основные возможности

• Гибкая фильтрация активов с поддержкой PDQL-запросов для точного отбора активов по любым критериям
• Проверка политик событий с автоматической валидациией соответствия активов настроенным политикам сбора событий
• Excel-отчеты для детальной аналитики с визуализацией проблем и статистикой по каждому активу
• Множественные режимы работы охватывают спектр задач от полного аудита инфраструктуры до точечной проверки конкретных активов
• Поддержка всех типов аутентификации - пользователь, Client Secret, Personal Token

📁 Структура проекта

mp-events-monitor/
├── 📄 event_checker.py          # Основной скрипт
├── 📄 requirements.txt          # Зависимости Python
├── 📄 README.md                 # Документация проекта
├── 📄 LICENSE                   # Лицензия MIT
├── 📄 CONTRIBUTING.md           # Руководство по участию
├── 📁 lib/                      # Библиотеки
│   ├── asset.py                 # Работа с активами
│   ├── events.py                # Обработка событий
│   ├── events_no_ai.py          # Версия без asyncio для Python 3.7.3
│   ├── get_token.py             # Аутентификация
│   ├── policies_checker.py      # Проверка политик
│   ├── settings_checker.py      # Валидация настроек
│   └── xlsx_out.py              # Генерация Excel-отчетов
├── 📁 configs/                  # Конфигурационные файлы
│   ├── assets_filters.json      # Фильтры активов
│   ├── event_policies.json      # Политики проверки событий
│   ├── example.config.env       # Пример файла конфигурации окружения
│   ├── asset_ids.txt            # UUID активов для режима Asset_IDs
│   └── dynamic_groups.txt       # UUID динамических групп
├── 📁 docs/                     # Дополнительная документация
│   ├── excel-reports-guide.md   # Руководство по отчетам
│   └── images/                  # Изображения для документации
└── 📁 dependencies/             # Офлайн-зависимости
    ├── python-dependencies-offline.zip
    └── offline-install.md       # Инструкции по офлайн установке

🛠️ Установка и настройка

Системные требования

• Python 3.7+
• MaxPatrol 27.3+
• Доступ к API MP

Быстрый старт

1. Клонируйте репозиторий:

   git clone https://github.com/Security-Experts-Community/mp-events-monitor.git
   cd mp-events-monitor

2. Установите зависимости:

   pip install -r requirements.txt

   💡 Если отстутствует интернет: используйте архив с предустановленными зависимостями dependencies/python-dependencies-offline.zip. Подробные инструкции по установке см. в dependencies/offline-install.md

3. Настройте конфигурацию и аутентификацию (.env):

   Заполните файл конфигурации окружения на основе configs/example.config.env и сохраните копию как configs/.config.env:

   HOST=your-mp-host.domain.com
   # Вариант 1 (рекомендуется): Personal Token
   PERSONAL_TOKEN=pat_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
   
   # Вариант 2: Логин/пароль
   #LOGIN=your_username
   #PASSWORD=your_password
   
   # Вариант 3: Client Secret + логин/пароль
   #LOGIN=your_username
   #PASSWORD=your_password
   #CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   

   ⚠️ Поддерживаются 3 способа аутентификации. При одновременном указании всех полей приоритет у PERSONAL_TOKEN.

4. Основные параметры запуска задаются через .env или CLI:

   Ключевые параметры описаны и валидируются в lib/settings_checker.py (pydantic settings). По умолчанию читается configs/.config.env. Полезные поля:

   Параметр	Описание	Значение по умолчанию
   logging_level	Уровень логирования	INFO
   time_delta_hours	Глубина анализа событий (часы)	168
   reconnect_times	Повторы при запросах/ошибках	5
   max_threads_for_siem_api	Количество потоков при опросе SIEM (для псевдопоследовательного исполнения запросов выставите 1)	11
   mode	Режим работы	Assets_filters
   out_folder	Папка вывода	out
   pdql_assets	PDQL для режимов про активы	`select(@Host, Host.@id as asset_id, Host.@audittime)
   event_policies_file	Путь к файлу с политиками событий	configs/event_policies.json
   asset_filters_file	Путь к файлу с фильтрами активов	configs/assets_filters.json

   💡 Полный список параметров и их дефолтных значений: Запустите скрипт с флагом python event_checker.py -h

5. Запустите первую проверку:

   python event_checker.py

🎛️ Режимы работы

Assets_filters (Рекомендуемый)

Основной режим работы скрипта. Использует конфигурационный файл configs/assets_filters.json для настройки различных групп активов. Для каждой группы можно настроить собственные PDQL-запросы, указать динамические группы, добавить специфические политики проверки, настроить черные и белые списки политик. Скрипт создает детальную статистику для тех активов, которые попадают под настроенные в файле критерии отбора.

💡 Если необходимо использовать другой (личный) файл вместо configs/assets_filters.json, его можно передать через параметр asset_filters_file.

ALL_assets

Проверка всех активов в группе "Все активы". Использует политики согласно параметру event_policies.

ALL_events

Работа по всем событиям без активов. Использует политики согласно параметру event_policies. НО! Если в системе источников событий более 1000, данный режим запрещено применять.

Dynamic_Groups_assets / Dynamic_Groups_events

Работа с динамическими группами из файла configs/dynamic_groups.txt. Используют политики согласно параметру event_policies.

Asset_IDs

Проверка конкретных активов по их UUID из файла configs/asset_ids.txt. Использует политики согласно параметру event_policies.

📊 Интерпретация результатов

После выполнения скрипт создает Excel-файлы с результатами анализа:

Страница "simple"

• OK — актив настроен корректно
• No asset — активы не найдены для указанных адресов
• Audit — проблемы с аудитом (сканированием)
• OS events — проблемы со сбором событий ОС

Страница "FULL"

Детальная информация по всем активам с результатами проверки политик.

Страницы политик

Подробный анализ по каждой политике событий для ручной диагностики.

📖 Подробное руководство: docs/excel-reports-guide.md

⚙️ Дополнительная конфигурация

Политики событий (configs/event_policies.json)

⚠️ Не рекомендуется изменять этот файл, в нем заложена основная логика работы.

Структура файла:

• Каждая политика имеет уникальное имя (очень важно для регулярных выражений в assets_filters.json)
• Внутри политики - список условий
• Каждое условие - словарь, где ключи соответствуют таксономии MP
• При редактировании файла следите за корректностью JSON-синтаксиса

💡 Если необходимо использовать другой файл политик, его можно передать через параметр event_policies_file.

Фильтры активов (configs/assets_filters.json)

Основные параметры:

Параметр	Обязательный	Тип данных	Описание
"название_группы"	✅	string	Имя модуля - используется как имя папки для результатов
comment	❌	array	Массив комментариев с описанием группы активов
comment_filter	❌	string	Дополнительные комментарии по фильтрации
PDQL	✅	string	PDQL-запрос для поиска активов (обязательно должен содержать поле asset_id)
default_politics_blacklist	❌	string или array	Регулярка (или список регулярок) политик для включения (приоритетнее, чем whitelist)
default_politics_whitelist	❌	string или array	Регулярка (или список регулярок) политик для исключения
mandatory_policies	❌	string или array	Регулярки политик для обязательной перепроверки в итоговом отчете. Автоматически добавляется в default_politics_blacklist (дубли исключаются). При отсутствии одной из обязательных политик это будет отображено в отчете
group	❌	string	UUID группы для выполнения запроса (includeNestedGroups: true)
specific_politics	❌	array	Дополнительные политики только для этой группы активов

Регулярные выражения для политик:

• ^w os — события ОС Windows
• ^u os — события ОС Unix/Linux
• ^n os — события сетевых устройств
• ^sw — софт на Windows серверах
• ^sa — антивирусы и агенты
• ^s — все софтовые логи

Комбинирование регулярок:

"default_politics_blacklist": "^w os |^s[wa] "
// или списком:
"default_politics_blacklist": ["^w os ", "^sa", "^sw"]

Другие конфигурационные файлы

configs/asset_ids.txt (режим Asset_IDs):

# Один UUID актива на строку
12345678-1234-5678-9012-123456789012
87654321-4321-8765-2109-876543210987

configs/dynamic_groups.txt (режимы Dynamic_Groups_*):

# Один UUID динамической группы на строку
00000000-0000-0000-0000-000000000000
11111111-1111-1111-1111-111111111111

🤝 Участие в проекте

Мы приветствуем вклад от сообщества! Если вы хотите внести свой вклад в развитие проекта, ознакомьтесь с руководством по участию в разработке.

Мы приветствуем:

• Сообщения об ошибках и предложения улучшений
• Улучшение документации
• Добавление новых функций
• Улучшение обработки ошибок и логирования

📚 Полезная документация

Документация проекта

• 📊 Руководство по Excel отчетам — подробное описание интерпретации результатов анализа
• 🤝 Руководство по участию в разработке — как внести вклад в проект
• 💾 Инструкции по офлайн установке — установка зависимостей без интернета

Техническая документация

• 🔐 Client Secret аутентификация — настройка Client Secret
• 🔍 PDQL Reference — справочник по языку запросов PDQL

📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.