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

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

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

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

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

## Установка

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

Установщик поддерживает Debian, Ubuntu, Raspberry Pi OS, RHEL, Fedora и openSUSE:```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

Предварительно собранные бинарники сенсора для `x86_64` и `aarch64` прикреплены к текущим релизам с контрольными суммами SHA-256.
Они статически линкуются с libpcap и рассчитаны на glibc 2.28, так что единственное, что им нужно, — это библиотека C: ничего устанавливать не требуется, будь то RHEL 8+, Debian 10+, Ubuntu 18.04+ или Leap 15.x. На системах на основе musl, таких как Alpine Linux, собирайте из исходников.

Бинарники из **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` | Назначение или назначения JSON Logstash |
| `STATS_ADDRESS` | Слушатель метрик Prometheus; отключён, если не настроен |
| `UPDATE_PERIOD` | Интервал обновления следов |
| `STATIC_TRAILS_URL` | Откуда загружается собранный набор статических следов; закрепите его за датированным релизом, чтобы контролировать появление нового контента |
| `USER_WHITELIST` | Управляемые оператором индикаторы, которые не должны вызывать оповещения |
| `CUSTOM_TRAILS_DIR` | Управляемый оператором каталог следов |
| `STATIC_TRAILS_DIR` | Необязательная копия репозитория следов; используется только для отображения источника цитирования следа в интерфейсе |

`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>

### Использование

#### Анализ

#### Сравнение

### Примеры

#### Анализ контракта

#### Сравнение двух контрактов

#### Сохранение результатов в файл

### Выходные данные

Ariana выводит результаты в формате JSON. Каждый результат содержит следующую информацию:

- **severity**: Уровень серьёзности проблемы (например, `high`, `medium`, `low`)
- **title**: Краткое описание проблемы
- **description**: Подробное описание проблемы
- **location**: Расположение проблемы в исходном коде (файл, строка, столбец)
- **recommendation**: Предлагаемое исправление или рекомендация

Пример выходных данных:

```json
{
  "results": [
    {
      "severity": "high",
      "title": "Уязвимость повторного входа",
      "description": "Функция `withdraw` вызывает внешний контракт перед обновлением состояния, что позволяет атакующему повторно войти в функцию.",
      "location": {
        "file": "examples/ERC20.sol",
        "line": 42,
        "column": 5
      },
      "recommendation": "Используйте паттерн checks-effects-interactions или добавьте модификатор для предотвращения повторного входа."
    }
  ]
}

[analysis]
severity_threshold = "medium"
include_deprecated = false

[output]
format = "json"
pretty = true

{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)",
  "confidence": 100
}
```
Поле `confidence` (0–100 или `null`, если недоступно) показывает, насколько сильно источники подтверждают
запись: 40 для одного фида, +15 за каждый дополнительный независимо согласующийся фид вплоть до 100, и полные
баллы для собственных пользовательских и статических записей оператора. Оно вычисляется при обновлении трейлов на основе
согласованности фидов в побочный файл `trails.confidence` рядом с `trails.csv`; сервер, получающий трейлы
с `UPDATE_SERVER`, не имеет данных о происхождении для оценки и сообщает `null`. Используйте его для приоритизации
триажа — запись из одного фида с оценкой 40 заслуживает повторного просмотра, прежде чем для неё будет создано правило файрвола.

Поиск поддомена может совпасть с его указанным родительским доменом. Поиск по URL проверяет `host/path` перед проверкой
только хоста. Сервер читает базу трейлов с отображением в память и наблюдает за обновлениями трейлов без
перезапуска.

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

## Операции

### Мониторинг

Используйте `maltrail-sensor -T` как шлюз развёртывания и конфигурации. Поставляемый systemd-юнит запускает его
как `ExecStartPre`.

Чтобы подтвердить, что само обнаружение работает — а не только то, что процессы запускаются, — выполните:```bash
python3 server.py --detect-test
```
Он воспроизводит подготовленный pcap-файл эмулируемого вредоносного трафика (срабатывания по DNS-запросу, IP-адресу, `IP:port`, пути URL и заголовку `Host`, а также эвристики SQL-инъекций, обхода каталогов, RCE, XSS, прокси-зондирования, sinkhole, отсутствующего `Host` и сканирования портов/веб/инфекций) через установленный сенсор и проверяет, что каждое ожидаемое обнаружение срабатывает. Ему не нужны root-права, сетевой интерфейс или собственный набор следов. Исправная установка выводит `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` не увеличивается | Активный набор следов не обновляется |
| `maltrail_log_dir_free_bytes` | Оставшаяся ёмкость для локального хранения событий |
| Увеличение `maltrail_state_saturations_total` | Достигнут предел состояния эвристики |
| Увеличение `maltrail_throttle_evictions_total` | Таблица ограничения событий достигла своего предела, поэтому события агрегируются раньше, чем настроено |

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

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

Сжатое хранилище наблюдаемых данных (`USE_CONDENSED_STORAGE`, `meta.sqlite`) поддерживает представления новизны и ретро-охоты на сервере. Побочный индекс журнала событий за день (`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-адреса и домены, которые в некоторых юрисдикциях регулируются как персональные данные; политика хранения должна учитывать применимые требования.

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

| Документ | Содержание |
| --- | --- |
| [`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
```
Он запускает форматирование, Clippy с запретом предупреждений, а также наборы тестов в режимах debug и release. Запустите набор тестов Python-сервера с помощью:```bash
bash tests/run.sh python3
```
## Проект

### Лицензия

Maltrail распространяется под лицензией MIT. См. [`LICENSE`](https://github.com/stamparm/maltrail/blob/master/LICENSE).

### Сопровождающие

- Miroslav Stampar ([@stamparm](https://github.com/stamparm))
- Mikhail Kasimov ([@MikhailKasimov](https://github.com/MikhailKasimov))

### Спонсоры

- [Sansec](https://sansec.io/) (2024–2025)
- [Sansec](https://sansec.io/) (2020–2021)

### Презентации и публикации

- 47-я встреча TF-CSIRT, Прага, 2016
  ([слайды](https://web.archive.org/web/20161109135211/https://www.terena.org/activities/tf-csirt/meeting47/M.Stampar-Maltrail.pdf))
- _Detect attacks on your network with Maltrail_, Linux Magazine, 2022
  ([статья](https://www.linux-magazine.com/Issues/2022/258/Maltrail))
- _Best Cyber Threat Intelligence Feeds_, Silent Push, 2022
  ([обзор](https://www.silentpush.com/blog/best-cyber-threat-intelligence-feeds))
- _Research on Network Malicious Traffic Detection System Based on Maltrail_, Nanotechnology
  Perceptions, 2024
  ([статья](https://nano-ntp.com/index.php/nano/article/view/1915/1497))

### Производный список блокировки

Список, содержащий только домены, полученный из статических списков `malware/`, публикуется по адресу
[`maltrail-malware-domains.txt`](https://raw.githubusercontent.com/stamparm/aux/master/maltrail-malware-domains.txt).
Его можно использовать как входные данные для систем фильтрации DNS, но операторам следует проверить и протестировать его перед
включением блокировки. Списки угроз могут содержать ложные срабатывания или индикаторы, которые не
подходят для каждого окружения.

### Сторонние интеграции

- [FreeBSD Port](https://www.freshports.org/security/maltrail)
- [OPNsense Gateway Plugin](https://github.com/opnsense/plugins/pull/1257)
- [D4 Project](https://www.d4-project.org/2019/09/25/maltrail-integration.html)
- [BlackArch Linux](https://github.com/BlackArch/blackarch/blob/master/packages/maltrail/PKGBUILD)
- [Validin](https://x.com/ValidinLLC/status/1719666086390517762)
- [Maltrail Add-on for Splunk](https://splunkbase.splunk.com/app/7211)
- [Maltrail decoder and rules for Wazuh](https://github.com/MikhailKasimov/maltrail-wazuh-decoder-and-rules)
- [GScan](https://github.com/grayddq/GScan) (только списки)
- [MalwareWorld](https://www.malwareworld.com/) (только списки)
- [oisd domain blocklist](https://oisd.nl/?p=inc) (только списки)
- [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json) (только списки)
- [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md) (только списки)
- [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables) (только списки)
- [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876) (только списки)
- [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json) (только списки)
- [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license) (только списки)
- [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed) (коннектор списков)

### Благодарности

- Thomas Kristner
- Eduardo Arcusa Les
- James Lay
- Ladislav Baco (@laciKE)
- John Kristoff (@jtkdpu)
- Michael Münz (@mimugmail)
- David Brush
- @Godwottery
- Chris Wild (@briskets)
- Keith Irwin (@ki9us)
- Simon Szustkowski (@simonszu)