Никакого языка правил, никаких ритуалов настройки, никакого ML. **След** — это домен, URL, IP-адрес, `IP:port` или
User-Agent, которые, как известно, принадлежат чему-то вредоносному, и Maltrail сообщает вам, когда такой появляется в
трафике.

---

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

- [Зачем Maltrail](#why-maltrail)
- [Архитектура](#architecture)
- [Производительность](#performance)
- [Быстрый старт](#quick-start)
  - [В качестве службы](#as-a-service)
  - [Docker](#docker)
- [Конфигурация](#configuration)
- [Следы](#trails)
- [События](#events)
- [Эксплуатация](#operating-it)
  - [Хранение событий](#event-retention)
- [Документация](#documentation)
- [Участие в разработке](#contributing)
- [Лицензия](#licence)
- [Спонсоры](#sponsors)
- [Разработчики](#developers)
- [Презентации](#presentations)
- [Публикации](#publications)
- [Чёрный список](#blacklist)
- [Благодарности](#thank-you)
- [Сторонние интеграции](#third-party-integrations)

---

## Зачем Maltrail

Большинство инструментов обнаружения сетевых угроз просят описать *поведение*. Maltrail задаёт более простой вопрос,
который отвечает на большинство реальных инцидентов: **разговаривает ли этот хост с тем, о ком мы уже знаем, что он плохой?**

* **Более 1,5 миллиона следов** — из более чем 3 000 курируемых статических списков и 46 публичных фидов,
  обновляемых ежедневно и растущих. Сильный перекос в сторону **вредоносного ПО** — C2-домены, дропперы,
  стилеры, инфраструктура APT — потому что именно это всплывает при реальной компрометации.
* **Следы — это обычный текст.** Один индикатор в строке, в файле, который можно читать, грепать и к которому можно отправлять
  pull request. Именно поэтому покрытие остаётся актуальным и поэтому всегда можно ответить на вопрос «почему это
  сработало?».
* **Достаточно быстро, чтобы не думать об этом.** Одно ядро обрабатывает канал 10 GbE при реалистичном
  смешанном трафике; см. [Производительность](#performance).
* **Эвристики поверх**, а не вместо — каждая из них названа в событии, а не просто балл: сканирование портов, UDP
  и веб-сканирование, истощение DNS, DGA-подобные запросы (пороги энтропии и согласных, чрезмерное количество
  NXDOMAIN), домены, переведённые в sinkhole, изъятые и припаркованные домены, длинные домены, загрузки по прямому IP
  и загрузки вредоносного ПО для IoT, подозрительные user agents и прокси-пробы.

---

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

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

**Читайте вторую таблицу, которую он выводит, а не первую.** Он сообщает о двух вещах, и они отвечают на разные вопросы:

* **весь процесс** — включает запуск, который на коротком повторном воспроизведении *и есть* измерение: загрузка набора следов из 1,5 млн строк обходится Rust-сенсору примерно в 1,1–1,5 с, а 300 000 пакетов обрабатываются менее чем за секунду. Это соотношение составляет около **3×**, и оно не относится к пути обработки пакетов.
* **установившийся режим** — запуск измеряется отдельно на повторе из одного пакета и вычитается. Это стоимость в расчёте на пакет, и именно она даёт указанные выше **14–37×**.

Загрузка следов — единственное место, где старый сенсор по-прежнему выигрывает: он отображает через mmap готовый сопутствующий файл `trails.csv.bin`, поэтому его *тёплый* старт быстрее, чем построение хранилища из CSV, — 1,25 с против 2,24 с на RPi 5. Эти затраты оплачиваются один раз за процесс; путь обработки пакетов — 300 000 раз.

Оба числа зависят от железа, так что измеряйте на своём — и учтите, что стенд сообщает `events=0` для обоих сенсоров на этой смеси трафика, поскольку она намеренно безвредна. Срабатывания детекций добавляют сверху стоимость журналирования событий.

Память не растёт с числом ядер: хранилище на 1,5 млн следов занимает **68,5 МБ** и неизменяемо разделяется всеми воркерами. Его построение — это указанные выше затраты на запуск: 1,2 с на Ryzen 7 PRO 4750U, 2,2 с на RPi 5 — и оно оплачивается один раз за процесс, а не за каждого воркера.

**Один воркер захвата по умолчанию.** Его путь обработки пакетов справляется с 4,2 Гбит/с этой смеси на ВМ с 2 vCPU, 8,7 Гбит/с на RPi 5 и 25,5 Гбит/с на Ryzen 9 5900X — в каждом случае больше, чем способен отдать сетевой интерфейс хоста, поэтому один воркер — это значение по умолчанию, а не компромисс. Дополнительные воркеры — это явное согласие (`CAPTURE_FANOUT`), потому что ядро распределяет захват по хэшу потоков, а эвристики сканирования считают по источнику: из эвристических предупреждений, которые поднимает один воркер, 91% выживает при 2 сокетах, 86% при 4, 65% при 8. Точное обнаружение следов идентично при любом числе воркеров. Масштабируйтесь, когда `maltrail_capture_dropped_total` скажет об этом, а не раньше.

<sub>Все цифры: эвристики включены, реальный набор следов на 1,5 млн строк, один воркер захвата, самый быстрый из трёх прогонов. Коэффициент установившегося режима варьировался в диапазоне 14–37× на указанных выше процессорах; стоимость на пакет — вот что ограничивает объём трафика, который способен поглотить один воркер. Методика, разбивка по протоколам, счётчики инструкций и вывод профилировщика — в [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/REPORT.md).</sub>

---

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

Сначала установите все зависимости — **все до одной**, иначе сборка завершится ошибкой на этапе компоновки с `cannot find -lpcap`:```bash
# Debian / Ubuntu / Raspberry Pi OS
sudo apt-get install cargo libpcap-dev libcap2-bin python3
# RHEL / Fedora
sudo dnf install cargo libpcap-devel libcap python3
# openSUSE / SLES     (do NOT add rustup; the packaged rust 1.74 already qualifies)
sudo zypper install cargo rust libpcap-devel libcap-progs python311

Предварительно собранные бинарные файлы сенсора для `x86_64` и `aarch64` прикреплены к каждому
[релизу](https://github.com/stamparm/maltrail/releases) с контрольной суммой SHA-256 — им нужен только
libpcap во время выполнения и вообще не нужен набор инструментов. Они собраны с **glibc 2.28**, поэтому работают на
RHEL 8+, Debian 10+, Ubuntu 18.04+ и openSUSE Leap 15.x; релиз отказывается публиковать бинарный файл,
который требует что-то новее. На musl (Alpine) вместо этого собирайте из исходников. Чтобы собрать из исходников:```bash
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail

# 1. build the sensor
cd sensor && cargo build --release && cd ..

# 2. let it capture without running as root
sudo setcap cap_net_raw,cap_net_admin=eip sensor/target/release/maltrail-sensor

# 3. give it somewhere to write events (LOG_DIR, /var/log/maltrail by default)
#    ('id -gn', not "$USER": not every distribution gives each user their own group)
sudo install -d -o "$USER" -g "$(id -gn)" -m 750 /var/log/maltrail

# 4. check the deployment before trusting it — exits non-zero if anything is wrong
sensor/target/release/maltrail-sensor -T

# 5. run it (first start builds the trail set; takes a minute)
sensor/target/release/maltrail-sensor

Затем откройте <http://127.0.0.1:8338> и войдите, используя учётные данные из `maltrail.conf` (`USERS`).

`-T` — это сокращение для «будет ли это работать?» — он проверяет конфигурацию, трейлы, белый список, каталог
журналов, фильтр захвата и привилегии и точно сообщает, чего не хватает:```
[o] log directory: '/var/log/maltrail' is writable
[o] log storage: 199.0 GB free on '/var/log/maltrail'
[o] capture filter: udp or icmp or (tcp and (tcp[tcpflags] == tcp-syn or port 80 or port...
[o] capture privileges: CAP_NET_RAW present
[o] interface: any
[o] workers: 1 - undiluted per-source heuristics; raise 'CAPTURE_FANOUT' only if
    'maltrail_capture_dropped_total' climbs
[o] whitelist: 3440 entries, 18 CIDR range(s)
[o] trails: 1505265 loaded (0 malformed row(s)), ipv4=144758 ipv4:port=253517 ipv6=2014 wildcard=29
[o] trail updates: updater present, python3 is Python 3.12.3
[o] heuristics: on (disabled: none)
[o] USE_CONDENSED_STORAGE: on, writing '/var/log/maltrail/meta.sqlite'
[i] configuration test PASSED

Это и есть вся установка — никаких каталогов создавать не нужно, `setcap` не нужен. Юниты создают и владеют `/var/log/maltrail` (события) и `/var/lib/maltrail` (набор trail) через `LogsDirectory=`/`StateDirectory=` от systemd, запускают оба процесса от непривилегированного пользователя `maltrail` с файловой системой только для чтения и дают сенсору ровно `CAP_NET_RAW` и `CAP_NET_ADMIN` — и ничего больше, и никакого root. Сенсор запускает `-T` как `ExecStartPre`, так что сломанное развёртывание падает на `systemctl start`, а не работает вслепую.

Проверьте: `systemctl status maltrail-sensor` и `journalctl -u maltrail-sensor -f`.

### Docker```bash
docker compose -f docker/docker-compose.yml up -d

Добавление индикатора — это добавление строки в текстовый файл. Добавление фида — это небольшой Python-модуль. Оба
представляют собой обычные pull request, и именно эта низкая планка входа сохраняет набор полезным.

Ваши собственные индикаторы размещаются в `CUSTOM_TRAILS_DIR`; всё, о чём вы никогда не хотите слышать, — в
`USER_WHITELIST`.

---

## События

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

Отвечает, находится ли домен, IP или URL в наборе трейлов, и какой ключ совпал — поддомен указанного домена сообщает о родительском, а URL пробуется как `host/path`, затем как голый хост. Чтение идёт через отображаемое в память хранилище трейлов, поэтому оно не стоит серверу памяти и подхватывает обновления трейлов без перезапуска.

Он не требует аутентификации для **публичного** набора трейлов, как и `/trails` рядом с ним: эта конечная точка уже отдаёт статические и фид-трейлы любому (именно так сенсор получает данные от `UPDATE_SERVER`), поэтому поиск по одному ключу раскрывает строго меньше того, что уже доступно на том же порту.

**Пользовательские трейлы требуют сессии.** Это ваши собственные индикаторы, а не публичные данные, и `ENABLE_MASK_CUSTOM` уже скрывает их имена от не-администраторов — поэтому `/check` сообщает совпадение только по пользовательским трейлам как промах любому, кому не разрешено его видеть. Данные о событиях остаются полностью закрытыми.

---

## Эксплуатация

* **`-T`** проверяет конфигурацию и завершает работу. Можно использовать как гейт развёртывания; systemd-юнит запускает его как `ExecStartPre`.
* **`STATS_ADDRESS`** открывает метрики Prometheus. Четыре метрики, на которые стоит настроить оповещения, — все они означают *что этот сенсор не обнаруживает то, что вы думаете*:

  | метрика | что означает |
  | --- | --- |
  | `maltrail_up == 0` | ни один воркер захвата не жив — этот хост **не мониторится** |
  | `rate(maltrail_capture_dropped_total)` | кольцо теряет пакеты — **пропущенные обнаружения** |
  | `rate(maltrail_local_log_errors_total)` | обнаружения были созданы, а затем **потеряны** |
  | `maltrail_trail_generation` не увеличивается | трейлы перестали обновляться |

  Также полезны: `maltrail_log_dir_free_bytes` (см. ниже) и `maltrail_state_saturations_total`, которая не равна нулю, когда шторм исчерпания состояний сузил эвристики. Точное сопоставление трейлов от этого не зависит — так задумано.

* **`systemctl reload`** (`SIGHUP`) перезагружает трейлы без перезапуска. Трейлы, обновлённые чем-либо ещё, подхватываются в течение секунды, с атомарной заменой — без перезапуска и без потери пакетов.
* **Сжатое хранилище наблюдаемых объектов** (`USE_CONDENSED_STORAGE`, `meta.sqlite`), которое питает представления `/meta` сервера для новизны и ретро-поиска, записывается в том же формате, который создаёт старый сенсор, и они построчно сравниваются стендом паритета. Каждое намеренное различие между сенсорами перечислено в [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/COMPATIBILITY.md).

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

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

Поэтому свободное место — это то, чем вы управляете, а не то, что игнорируете:

* **Выгружайте долговечную копию за пределы машины.** `LOG_SERVER` (или `SYSLOG_SERVER` / `LOGSTASH_SERVER`) делает сервер или вашу SIEM системой записи, а локальный файл сенсора — буфером. Это и есть стратегия хранения; локальный диск ей не является.
* **Настройте оповещение на `maltrail_log_dir_free_bytes`** с реальным запасом. `-T` тоже выводит его и предупреждает, когда значение ниже 10 ГБ. Когда он достигает нуля, сенсор не может дописывать, и обнаружения теряются.
* **Архивирование решаете вы.** Сжимайте или перемещайте старые ежедневные логи по своему расписанию, если нужно место. Обратите внимание: интерфейс отчётов отдаёт исторические логи как обычные файлы с произвольным доступом, поэтому сжатие их на месте удаляет эти дни из интерфейса — архивируйте их в другом месте.

Если ваша политика *требует* удаления (журналы событий содержат IP-адреса и домены, которые в некоторых юрисдикциях являются персональными данными), это явное решение оператора — принимайте его с помощью собственных инструментов, осознанно, а не позволяйте сенсору по умолчанию делать это молча.

---

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

| | |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md) | установка, права доступа, конфигурация, устранение неполадок |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/ARCHITECTURE.md) | как сенсор работает внутри |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/COMPATIBILITY.md) | каждое намеренное отличие от старого сенсора |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/REPORT.md) | измерения, профили и результаты тестов |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/ROADMAP.md) | что ещё осталось открытым |
| [`old/README.md`](https://github.com/stamparm/maltrail/blob/HEAD/old/README.md) | предыдущий Python-сенсор, оставлен как справочник и эталон для тестов |

---

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

Трейлы — самый ценный вклад: строка в правильном файле, с указанием источника. Фиды, отчёты об ошибках и работа над сенсором приветствуются в равной степени.

Полный цикл проверки сенсора — одна команда:```bash
bash sensor/tools/check.sh