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

Установка, настройка и эксплуатация open-source инструмента для мониторинга и аудита безопасности Linux-серверов.

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

Разверните Open Defender на Linux-сервере за пару минут: скачайте бинарник из релизов, установите его как systemd-сервис и проверьте конфигурацию.

ARCH=$(uname -m)
case "$ARCH" in
  x86_64)        ARCH=amd64 ;;
  i386|i686)     ARCH=386 ;;
  aarch64|arm64) ARCH=arm64 ;;
  armv7l|armv6l) ARCH=arm32 ;;
  *) echo "Неизвестная архитектура: $ARCH"; exit 1 ;;
esac
sudo curl -L -o /usr/bin/open-defender \
  https://github.com/fridalif/open-defender/releases/latest/download/open-defender_$ARCH
sudo chmod +x /usr/bin/open-defender

sudo open-defender -i

open-defender -t

open-defender -s

Установка

Open Defender поставляется единым бинарником и интегрируется с systemd. Установка и запуск выполняются одной командой.

sudo curl -L -o /usr/bin/open-defender \
  https://github.com/fridalif/open-defender/releases/latest/download/open-defender_amd64
sudo chmod +x /usr/bin/open-defender

sudo open-defender -i

systemctl status open-defender
sudo systemctl restart open-defender
journalctl -u open-defender -f

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

Все настройки хранятся в YAML-файле /etc/open-defender/config.yaml. Каждый монитор задаёт движок получения событий, источник и пороги срабатывания.

Режимы монитора

• blocker — обнаруживает и блокирует источник атаки (бан по времени).
• logger — только фиксирует события, без блокировки.
• disabled — монитор выключен и не запускается.

Ключевые параметры

• engine — источник событий: syslog, journal или docker.
• log_path / unit_name — файл лога для syslog или юнит для journal/docker.
• pattern — регулярное выражение с обязательной группой (?P<ip>...).
• tries / window_seconds / ban_seconds — порог попыток, окно и длительность бана.
• ip_whitelist — адреса, которые никогда не блокируются.
• Для resource_monitor — пороги warning/alert по CPU и RAM (нулевые значения выключают лимит).

sudo nano /etc/open-defender/config.yaml

После правок всегда запускайте open-defender -t — конфиг только читается и никогда не перезаписывается, так что проверка безопасна на живой установке.

Мониторы

Команда open-defender -s выводит включённые мониторы с их режимом, движком, источником и порогами. Выключенные (disabled) перечисляются внизу и не запускаются.

/etc/open-defender/config.yaml

MONITOR           MODE     ENGINE   SOURCE                   TRIES
ssh_monitor       blocker  syslog   /var/log/auth.log        5 in 300s, ban 900s
database_monitor  logger   journal  postgresql               5 in 300s
resource_monitor  enabled  -        /var/log/open-defender/  cpu 60/90, ram 60/90

disabled: web_recon_monitor, web_brute_monitor

В планах: eBPF-мониторинг (сеть, запуск команд, модули ядра, cron, сервисы) и режим аудита безопасности. Следите за репозиторием.

Экспорт событий

Open Defender умеет отправлять события в Light Defender Dashboard по собственному протоколу поверх WebSocket. Это полностью опционально: без секции exporter агент работает автономно и никуда не ходит.

При enabled: false коннектор не запускается вовсе: события не ставятся в очередь и наружу не уходят. Все мониторы при этом продолжают работать как обычно.

Настройка

Секция exporter в /etc/open-defender/config.yaml. Значения user_id, config_id и публичный ключ выдаёт дашборд вместе с готовым конфигом.

exporter:
  enabled: true
  endpoint_address: connector.light-defender.ru
  user_id: <ваш user_id из дашборда>
  config_id: <ваш config_id из дашборда>
  endpoint_rsa_public_key: <публичный ключ дашборда, base64>

• enabled — включает коннектор.
• endpoint_address — адрес WebSocket-эндпоинта дашборда.
• user_id / config_id — идентификаторы агента, уходят в каждом сообщении.
• endpoint_rsa_public_key — ключ, которым шифруется всё, что агент отправляет наверх.

Шифрование

Одно WebSocket-соединение, каждый кадр в нём — зашифрованный JSON-конверт. Симметричный ключ шифруется RSA-OAEP/SHA-256, тело — AES-256-GCM.

[ RSA(aes_key) ][ nonce, 12 байт ][ ciphertext ]

• Пара ключей агента — RSA-2048, генерируется на каждую сессию и никогда не пишется на диск.
• Агент шифрует сообщения ключом дашборда, дашборд — сессионным ключом агента, который тот передаёт в system/hello.
• После переподключения сессионный ключ другой, поэтому кадры прошлой сессии расшифровать уже нельзя.

Обмен сообщениями

агент                                  дашборд
    |                                        |
    |  WebSocket, endpoint_address           |
    |--------------------------------------->|
    |  system/hello                          |
    |  сессионный публичный ключ агента      |
    |--------------------------------------->|
    |          config/set_config             |  не позже
    |<---------------------------------------|  30 секунд
    |  system/ack   ok | error               |
    |--------------------------------------->|
  ==+============ сессия открыта ============+==
    |  alert/raised   одно событие           |  без
    |--------------------------------------->|  подтверждений
    |          config/get_config             |
    |<---------------------------------------|
    |  config/config   текущий конфиг        |
    |--------------------------------------->|
    |          ping, каждые 30 секунд        |
    |<---------------------------------------|
    |  pong                                  |
    |--------------------------------------->|

Порядок рукопожатия фиксирован: hello, затем set_config, затем ack. Дальше порядок свободный: агент шлёт события по мере их появления и отвечает на запросы дашборда.

Типы сообщений

• system/hello (агент → дашборд) — открывает сессию и передаёт сессионный публичный ключ.
• alert/raised (агент → дашборд) — событие безопасности, одно на конверт. Подтверждения и повторной отправки нет.
• config/config (агент → дашборд) — текущий конфиг в ответ на get_config.
• system/ack (агент → дашборд) — результат задачи: ok или error с описанием.
• config/set_config (дашборд → агент) — новый конфиг. Секция exporter и белый список адресов машины сохраняются локальными.
• config/get_config (дашборд → агент) — запрос текущего конфига.

Структура события

{
  "version": 2,
  "task_id": 0,
  "service": "alert",
  "operation": "raised",
  "configuration_id": "...",
  "user_id": "...",
  "payload": {
    "events": [
      {
        "source": "ssh_monitor",
        "ip": "203.0.113.7",
        "message": "ssh_monitor -> found offenders ip ...",
        "happened_at": "2026-07-24T10:15:00Z",
        "details": { "engine": "syslog", "source": "/var/log/auth.log" }
      }
    ]
  }
}

Поле source называет монитор: ssh_monitor, web_brute_monitor, web_recon_monitor, database_monitor, network_antirecon, resource_monitor или ip_ban. У resource_monitor дополнительно приходит severity и метрика с порогом.

Тайминги и лимиты

• Подключение — 15 секунд, рукопожатие — 30 секунд на сообщение.
• Чтение — 90 секунд, таймер обновляется каждым ping от сервера.
• Максимальный размер кадра — 1 МБ.
• Переподключение — 5 секунд, плюс 10 секунд за каждую неудачу, не больше 100 секунд. После успешного подключения счётчик сбрасывается.
• Очередь на отправку — 1024 конверта. Если она переполнена, события отбрасываются: мониторы не ждут сеть никогда.
• Недоступный эндпоинт не ломает защиту: агент просто повторяет попытки в фоне.

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

Полное описание протокола, всех полей и поведения при сбоях — в CLIENT.md на GitHub.

CLI-команды

Полный набор флагов. Команды -t, -s и -h не требуют root, остальным нужны права суперпользователя.

Usage: open-defender [options]

Options:
  -i, --install    установить open-defender как systemd-сервис и запустить
  -u, --update     обновить бинарник до последнего релиза с GitHub
  -t, --test       проверить текущий конфиг и выйти
  -s, --status     показать включённые мониторы и выйти
  -r, --restart    перезапустить сервис open-defender
  -h, --help       показать это сообщение

Обновление

Флаг -u обновляет установленный бинарник до последнего релиза с GitHub. Версия берётся из version.txt репозитория, архитектура — из текущего бинарника.

sudo open-defender -u

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