feat: подпись сервера во всех уведомлениях и документация

Добавлены message_ensure_server_line и SERVER_DISPLAY_NAME; версия 1.1.3-server-label. Гайды по уведомлениям и автообновлению.
2026-05-25 09:23:32 +10:00
parent 21ef703866
commit 7ce9f1d526
7 changed files with 321 additions and 31 deletions
@@ -0,0 +1,98 @@
+# Уведомления ssh-monitor
+
+Документ описывает, **какие сообщения** отправляет монитор, **какие поля** в них есть и как настроить **подпись сервера** и **часовой пояс**.
+
+См. также: [README.md](../README.md), пример конфига [ssh-monitor.conf.example](../ssh-monitor.conf.example).
+
+## Подпись сервера (🖥️ Сервер)
+
+Начиная с версии **1.1.3-server-label**, каждое уведомление, проходящее через **`notify_send()`**, получает строку **«🖥️ Сервер: …»** сразу **после первой строки** (заголовка алерта).
+
+Формат значения:
+
+| Условие | Пример |
+|---------|--------|
+| `SERVER_DISPLAY_NAME` пусто, IPv4 найден | `web01 (10.1.20.5)` |
+| `SERVER_DISPLAY_NAME` пусто, IPv4 нет | `web01` |
+| Задан `SERVER_DISPLAY_NAME="prod-db-01"` | `prod-db-01 (10.1.20.5)` |
+
+IPv4 определяется через `ip -4 route get` (исходящий адрес) или `hostname -I`. Нужны утилиты **`hostname`** и **`ip`** — см. [install-prerequisites.ru.md](install-prerequisites.ru.md).
+
+Если в тексте сообщения уже есть подстрока **`🖥️ Сервер:`**, вторая строка **не добавляется** (защита от дубля при ручной вставке).
+
+### Пример: успешный SSH
+
+```
+✅ УСПЕШНОЕ SSH ПОДКЛЮЧЕНИЕ
+🖥️ Сервер: myhost (10.1.20.5)
+👤 Пользователь: alice
+🌐 IP адрес: 10.1.20.1
+🕐 Время: 25.05.2026 09:08:22
+```
+
+### Пример: sudo
+
+```
+⚠️ ИСПОЛЬЗОВАНИЕ SUDO
+🖥️ Сервер: myhost (10.1.20.5)
+👤 Пользователь: alice
+🔑 От имени USER: root
+💻 Команда: /bin/bash
+📁 Директория: /home/alice
+🕐 Время: 24.05.2026 16:54:49
+```
+
+## Настройка в `/etc/ssh-monitor.conf`
+
+```bash
+# Пусто = hostname (+ IPv4 при возможности)
+SERVER_DISPLAY_NAME=""
+
+# Или фиксированное имя для этого хоста в общем чате:
+# SERVER_DISPLAY_NAME="dc1-app-03"
+```
+
+Проверка эффективной подписи:
+
+```bash
+sudo ssh-monitor --check-config
+```
+
+В выводе будет строка `SERVER_DISPLAY_NAME=... (эффективно: ...)`.
+
+## Типы уведомлений
+
+| Событие | Заголовок (первая строка) | Доп. поля |
+|---------|----------------------------|-----------|
+| Успешный SSH | ✅ УСПЕШНОЕ SSH ПОДКЛЮЧЕНИЕ | пользователь, IP клиента, время |
+| SSH под root | 🔑 SSH ВХОД ПОД ROOT | IP, время |
+| Неудачная попытка SSH | ❌ НЕУДАЧНАЯ ПОПЫТКА SSH | пользователь, IP, счётчик попыток, время |
+| Sudo | ⚠️ ИСПОЛЬЗОВАНИЕ SUDO | пользователь, USER=, команда, PWD, время |
+| Бан IP | 🚫 IP ЗАБЛОКИРОВАН АВТОМАТИЧЕСКИ | IP, попытки, длительность, время |
+| Порог без бана | ⚠️ ЛИМИТ НЕУДАЧНЫХ SSH (автобан отключён…) | IP, попытки, время |
+| Брутфорс | 🧨 ВОЗМОЖНЫЙ МАССОВЫЙ БРУТФОРС SSH | IP, счётчик за окно, время |
+| Host key / MITM | 🔐 ВНИМАНИЕ: изменение SSH host key… | фрагмент журнала, время |
+| logind: новая сессия | 🖥️ НОВАЯ СЕССИЯ (systemd-logind) | пользователь, ID сессии, время |
+| logind: сбой | ❌ СБОЙ (systemd-logind) | строка журнала, время |
+| Ежедневный отчёт | 📊 ЕЖЕДНЕВНЫЙ ОТЧЕТ SSH МОНИТОРИНГА | статистика 24 ч, баны, топ IP, сессии |
+| Heartbeat | ❤️ Heartbeat - скрипт мониторинга работает | время |
+| Старт / стоп | ✅ СКРИПТ МОНИТОРИНГА ЗАПУЩЕН / ⚠️ ОСТАНОВЛЕН | версия, каналы, время |
+
+Во всех перечисленных случаях **🖥️ Сервер** добавляется автоматически (кроме сообщений, где вы сами вставили эту строку).
+
+## Время в сообщениях (🕐)
+
+Строки **«🕐 Время»** формируются функцией **`notification_date()`**:
+
+1. Если задан **`NOTIFY_TZ`** (IANA, например `Europe/Moscow`) — используется он.
+2. Иначе, если задан **`DAILY_REPORT_TZ`** — он.
+3. Иначе — зона процесса (`date` у systemd-сервиса; часто UTC, если в unit указано `Environment=TZ=UTC`).
+
+Ежедневный отчёт по календарю и часу **`DAILY_REPORT_HOUR`** использует **`DAILY_REPORT_TZ`** (или зону процесса) — см. README.
+
+## Каналы доставки
+
+- **`NOTIFY_CHAIN`**: `telegram`, `email` — при каждом событии попытка **во все** каналы списка.
+- **`BACKUP_WEBHOOK_URL`**: только если **все** каналы цепочки не доставили сообщение.
+
+Режим **`--dry-run`**: уведомления не отправляются; в stderr печатается текст **уже с подписью сервера**.