Maltrail предназначен для сетевого мониторинга на основе индикаторов. Его эвристические обнаружения дополняют
сопоставление с трейлами, но не заменяют телеметрию конечных точек или систему предотвращения вторжений
общего назначения.

## Возможности

- Полная сборка трейлов, объединяющая более 3 000 встроенных статических файлов, 42 интеграции с публичными фидами
  и дополнительные трейлы, предоставляемые оператором.
- Многопоточный сенсор на Rust с использованием libpcap и опциональными воркерами захвата Linux `PACKET_FANOUT`.
- Сервер на Python, обеспечивающий интерфейс отчётности, приём событий и HTTP API.
- Пользовательские трейлы и белые списки в виде простого текста, которые можно проверять и контролировать версии.
- Эвристики для сканирования, исчерпания DNS, DGA-подобных запросов, подозрительных загрузок, прокси-зондирований,
  подозрительных значений User-Agent и связанной сетевой активности.
- Локальное журналирование событий, удалённое журналирование Maltrail, CEF через syslog и вывод Logstash JSON.
- Проверка развёртывания с помощью `maltrail-sensor -T` и опциональные метрики Prometheus.

## Содержание

- [Архитектура](#architecture)
- [Интерфейс отчётности](#reporting-interface)
- [Производительность](#performance)
- [Установка](#installation)
  - [Установщик](#installer)
  - [Сборка из исходного кода](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Конфигурация](#configuration)
- [Трейлы](#trails)
- [События и API](#events-and-api)
- [Эксплуатация](#operations)
  - [Мониторинг](#monitoring)
  - [Хранение событий](#event-retention)
- [Документация](#documentation)
- [Участие в разработке](#contributing)
- [Проект](#project)
  - [Лицензия](#license)
  - [Сопровождающие](#maintainers)
  - [Спонсоры](#sponsors)
  - [Презентации и публикации](#presentations-and-publications)
  - [Производный чёрный список](#derived-blacklist)
  - [Сторонние интеграции](#third-party-integrations)
  - [Благодарности](#acknowledgements)

## Архитектура

Maltrail состоит из двух независимых процессов, которые могут работать на одном хосте или на разных хостах:```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

Один capture worker используется по умолчанию. Дополнительные worker'ы могут увеличить пропускную способность захвата, но хеширование потоков Linux делит состояние для каждого источника между worker'ами и, следовательно, снижает чувствительность некоторых эвристик сканирования. В документированном тесте 91% эвристических оповещений при одном worker'е сохранялись при двух worker'ах, 86% — при четырёх и 65% — при восьми. Точное сопоставление trail осталось неизменным. Увеличивайте `CAPTURE_FANOUT` только тогда, когда метрики потерь захвата показывают, что это необходимо.

Методология бенчмарков, результаты на оборудовании, вывод профайлера, измерения памяти и проверки fanout в реальном времени задокументированы в [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md).

## Установка

### Установщик

Установщик проверяется на двенадцати дистрибутивах Linux — Debian, Ubuntu, Fedora, Rocky, AlmaLinux, Arch, openSUSE Leap и Tumbleweed, а также Alpine — плюс FreeBSD и macOS, при каждом релизе, с полным результатом, записанным в [`docs/compat`](https://github.com/stamparm/maltrail/blob/master/docs/compat). Raspberry Pi OS и другие 64-битные ARM-системы используют сборку `aarch64`; для 32-битного ARM нет готового сенсора, и его необходимо собирать из исходного кода.```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

Общие параметры установщика:```bash
sh install.sh --role sensor      # Install only the sensor
sh install.sh --ref 3.1.2        # Install a release tag instead of master
sh install.sh --no-service       # Install without changing systemd
sh install.sh --dry-run          # Print commands without applying them
sh install.sh --uninstall        # Remove the managed installation; keep logs and state

Затем соберите и проверьте сенсор:```bash
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail

cargo build --release --manifest-path sensor/Cargo.toml

sudo setcap cap_net_raw,cap_net_admin=eip \
  sensor/target/release/maltrail-sensor

sudo install -d -o "$USER" -g "$(id -gn)" -m 750 /var/log/maltrail

sensor/target/release/maltrail-sensor -T
sensor/target/release/maltrail-sensor

Готовые бинарные файлы сенсора прилагаются к текущим релизам с контрольными суммами SHA-256: Linux `x86_64`
и `aarch64` как для glibc, так и для musl, macOS на Apple silicon и Intel, FreeBSD `amd64` и
Windows `x86_64`.

Сборки для glibc статически линкуют libpcap и нацелены на glibc 2.28, поэтому единственное, что им
нужно — это библиотека C — ничего устанавливать не требуется, одинаково на RHEL 8+, Debian 10+, Ubuntu 18.04+ и Leap 15.x. Сборки
для musl полностью статические, поэтому Alpine не нужно вообще ничего. Сборка для Windows — 64-битная и требует Windows 10 или новее плюс
установленный [Npcap](https://npcap.com) до того, как она запустится — `wpcap.dll` является зависимостью времени загрузки,
поэтому без неё загрузчик отказывается запускать исполняемый файл, а не выдаёт ошибку при захвате. В архиве об этом
тоже сказано.

Бинарные файлы из версий **3.1.1 и более ранних** — нет: они линковали libpcap динамически и запрашивали её по
имени, которое использует их сборочный хост AlmaLinux. Debian и Ubuntu поставляют идентичную библиотеку под
более старым именем `libpcap.so.0.8`, поэтому эти бинарные файлы останавливаются ещё до запуска —```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file

### Systemd

Поставляемые модули в `packaging/systemd/` запускают оба процесса от имени
непривилегированного пользователя `maltrail`. Systemd создаёт `/var/log/maltrail` и `/var/lib/maltrail`, ограничивает
доступ к файловой системе и предоставляет сенсору `CAP_NET_RAW` и `CAP_NET_ADMIN`.

Установщик настраивает эти модули автоматически. Для существующей установки из исходного кода следуйте
процедуре ручной настройки службы в [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md).

Проверить состояние службы и логи можно с помощью:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

Конфигурация контейнера, хранилище, привилегии и проверки работоспособности описаны в
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/master/docker/README.md).

## Конфигурация

Maltrail читает `maltrail.conf`, который содержит отдельные настройки `[Sensor]` и `[Server]`. Установщик
размещает управляемую конфигурацию в `/etc/maltrail.conf`.

Часто используемые параметры сенсора включают:

| Параметр | Назначение |
| --- | --- |
| `MONITOR_INTERFACE` | Интерфейс или интерфейсы захвата; `any` выбирает все поддерживаемые интерфейсы |
| `CAPTURE_FILTER` | Фильтр захвата BPF |
| `CAPTURE_FANOUT` | Количество сокетов захвата Linux; по умолчанию один |
| `CAPTURE_WORKERS` | Воркеры захвата, по одному сокету на каждый; по умолчанию равно `CAPTURE_FANOUT`, то есть один, если не задан ни один из них |
| `LOG_DIR` | Каталог локального журнала событий |
| `TRAILS_FILE` | Сгенерированная база данных трейлов |
| `LOG_SERVER` | Удалённый сервер событий Maltrail |
| `SYSLOG_SERVER` | Назначение или назначения CEF syslog |
| `LOGSTASH_SERVER` | Назначение или назначения Logstash JSON |
| `STATS_ADDRESS` | Слушатель метрик Prometheus; отключён, если не настроен |
| `UPDATE_PERIOD` | Интервал обновления трейлов |
| `STATIC_TRAILS_URL` | Откуда загружается собранный набор статических трейлов; привяжите его к датированному релизу, чтобы контролировать появление нового контента |
| `USER_WHITELIST` | Управляемые оператором индикаторы, которые не должны вызывать оповещения |
| `CUSTOM_TRAILS_DIR` | Управляемый оператором каталог трейлов |
| `STATIC_TRAILS_DIR` | Необязательная копия репозитория трейлов; используется только для отображения ссылки на источник трейла в UI |

`PROCESS_COUNT` применяется к выведенному из эксплуатации Python-сенсору и к устаревшему механизму
ограничения журнала событий; он **не** задаёт количество воркеров Rust-сенсора. Настраивайте воркеры
захвата с помощью `CAPTURE_FANOUT` или `CAPTURE_WORKERS`.

Запустите проверку развёртывания после изменения конфигурации:```bash
sensor/target/release/maltrail-sensor -T

Направьте его на конкретный релиз `content-YYYYMMDD-HHMM`, чтобы зафиксировать версию, и тогда неудачная публикация не станет сразу глобальной. Набор кэшируется рядом с `TRAILS_FILE`, что и обеспечивает работу офлайн- или изолированной пересборки; опубликованный `sha256` проверяется перед загрузкой, поэтому развёртывание, которое обновляется чаще, чем меняется контент, передаёт 65 байт вместо 11 МБ, а полезная нагрузка, не совпадающая со своим дайджестом, отклоняется в пользу кэша.

`update_trails()` публикует новый `TRAILS_FILE` атомарно и только после успешной сборки. Фиды, возвращающие пустой результат, сообщаются по имени, чтобы развёртывание не зависело молча от источника, который тихо прекратил работу.

Добавляйте свои индикаторы в `CUSTOM_TRAILS_DIR`, а всё, что никогда не должно вызывать событие, — в `USER_WHITELIST`. Держите и то, и другое вне каталога установки, чтобы обновление не могло их перезаписать.

Вклад в статические трейлы направляйте в [stamparm/trails](https://github.com/stamparm/trails); новые фиды — сюда. В любом случае индикатору нужна классификация и источник, который кто-то может проверить — см. [Contributing](#contributing).

## События и API

Maltrail записывает одно событие, разделённое пробелами, на каждое обнаружение, используя CSV-экранирование там, где значение содержит пробелы:```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

| `--no-color` | Отключить цветной вывод |
| `--debug` | Включить режим отладки |
| `--verbose` | Включить подробный вывод |
| `--silent` | Подавить весь вывод |
| `--json` | Выводить результаты в формате JSON |
| `--csv` | Выводить результаты в формате CSV |
| `--html` | Выводить результаты в формате HTML |
| `--xml` | Выводить результаты в формате XML |
| `--markdown` | Выводить результаты в формате Markdown |
| `--output FILE` | Записать вывод в FILE |
| `--input FILE` | Читать входные данные из FILE |
| `--config FILE` | Использовать файл конфигурации FILE |
| `--threads N` | Использовать N потоков |
| `--timeout N` | Установить тайм-аут в N секунд |
| `--retry N` | Повторить N раз |
| `--proxy URL` | Использовать прокси-сервер по адресу URL |
| `--user-agent STRING` | Установить строку User-Agent |
| `--header STRING` | Добавить пользовательский заголовок |
| `--cookie STRING` | Добавить пользовательскую cookie |
| `--help` | Показать справку |
| `--version` | Показать версию |```json
{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)",
  "confidence": 100
}

Он воспроизводит подготовленный pcap эмулированного вредоносного трафика (срабатывания trail по DNS-запросу, IP, `IP:port`, пути URL и заголовку `Host`, а также эвристики SQL-инъекций, обхода каталогов, RCE, XSS, проверки прокси, sinkhole, отсутствующего `Host` и сканирования портов/веб-ресурсов/заражений) через установленный сенсор и проверяет, что каждое ожидаемое обнаружение срабатывает. Ему не требуются root, сетевой интерфейс или собственный набор trail. При исправной установке выводится `20/20 detection(s) fired`.

Когда настроен `STATS_ADDRESS`, отслеживайте как минимум следующие метрики Prometheus:

| Метрика | Операционное значение |
| --- | --- |
| `maltrail_up == 0` | Ни один рабочий процесс захвата не запущен |
| Рост `maltrail_capture_dropped_total` | Кольцевой буфер захвата теряет пакеты |
| Рост `maltrail_local_log_errors_total` | События были сгенерированы, но не могли быть записаны локально |
| Рост `maltrail_remote_log_errors_total` | События не могли быть доставлены в удалённый приёмник; при `DISABLE_LOCAL_LOG_STORAGE` они теряются |
| `maltrail_trail_generation` не увеличивается | Активный набор trail не обновляется |
| `maltrail_log_dir_free_bytes` | Оставшаяся ёмкость для локального хранения событий |
| Рост `maltrail_state_saturations_total` | Достигнут лимит состояния эвристики |
| Рост `maltrail_throttle_evictions_total` | Таблица ограничения событий достигла предела, поэтому события агрегируются раньше, чем настроено |

Насыщение состояния влияет на соответствующую эвристику; точное сопоставление trail остаётся активным.

Отправьте `SIGHUP` или используйте `systemctl reload maltrail-sensor`, чтобы запросить перезагрузку trail. Файлы trail, обновлённые другим процессом, обнаруживаются автоматически и публикуются рабочим процессам без перезапуска сенсора.

Сжатое хранилище наблюдаемых данных (`USE_CONDENSED_STORAGE`, `meta.sqlite`) поддерживает представления новизны и retro-hunt на сервере. Побочный индекс журнала событий по дням (`USE_EVENT_INDEX`, `LOG_DIR/index/*.sqlite`, примерно вдвое больше размера журнала на диске) обеспечивает точность `/counts` и скорость `/hunt`; он поддерживается инкрементально из самих журналов и может быть перестроен с помощью `server.py --rebuild-index`. Совместимость с выведенным из эксплуатации сенсором описана в [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md).

### Хранение событий

Maltrail не выполняет ротацию и не удаляет журналы событий. Операторы несут ответственность за определение сроков хранения, архивирования и удаления в соответствии с требованиями к хранилищу и политикой организации.

Рекомендуемые практики:

- Отправляйте долговременную копию событий на удалённый сервер Maltrail или в SIEM с помощью `LOG_SERVER`, `SYSLOG_SERVER` или `LOGSTASH_SERVER`.
- Настройте оповещения по `maltrail_log_dir_free_bytes` с достаточным запасом для ожидаемой интенсивности событий.
- Выполняйте ротацию, архивирование или удаление локальных ежедневных журналов с помощью внешних инструментов.
- Храните файлы, необходимые интерфейсу отчётности, несжатыми в `LOG_DIR`; архивируйте сжатые файлы в другом месте.

Когда файловая система журналов заполнена, сенсор не может добавлять события. Журналы событий также могут содержать IP-адреса и домены, которые в некоторых юрисдикциях регулируются как персональные данные; политика хранения должна учитывать применимые требования.

### Синтетический трафик

Чтобы проверить, что обнаружение и панель управления по-прежнему работают, не дожидаясь реального трафика:```bash
python3 server.py --detect-test                      # assert every detection fires, then exit
python3 server.py --detect-test --keep DIR --serve   # ...and keep the events, serving them on :8338

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

| Документ | Содержание |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md) | Установка, привилегии, конфигурация и устранение неполадок |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ARCHITECTURE.md) | Внутреннее устройство сенсора и поток данных |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) | Намеренные отличия от снятого с эксплуатации Python-сенсора |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md) | Измерения, профили и результаты тестирования |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ROADMAP.md) | Открытые задачи по сенсору |
| [`SekuriPy Labs`](https://www.sekuripy.hr/labs/maltrail/) | Инженерные заметки, бенчмарки и статьи |

## Участие в разработке

Дополнения трейлов, поддержка фидов, сообщения об ошибках, документация и улучшения сенсора приветствуются.
Предложения по трейлам должны включать надёжный источник и использовать наиболее узкую подходящую
классификацию.

Перед отправкой кода запустите соответствующие проверки. Полный набор проверок сенсора:```bash
bash sensor/tools/check.sh

Сборку для Windows можно запустить из Linux, именно там и были найдены её ошибки:```bash
sh sensor/tools/check_windows.sh