PapaTramp/ssh-monitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(home): mirror from kalinamall (b0abf99) with papatramp URLs

Browse Source
This commit is contained in:
PTah
2026-07-14 20:43:55 +10:00
commit 10704e0f88
40 changed files with 7253 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auto-update.ru.md
+173
View File
@@ -0,0 +1,173 @@
# Автообновление ssh-monitor
Скрипт **`update_ssh_monitor.sh`** обновляет **`/usr/local/bin/ssh-monitor`** из git и перезапускает systemd-сервис.
## Основной путь: Security Alert Center
На продакшен-хостах обновление идёт **через SAC**, без cron:
1. Админ нажимает **«Обновить ssh-monitor (SSH)»** в карточке хоста.
2. SAC по SSH запускает `/opt/scripts/update_ssh_monitor.sh` с `REPO_URL` / `GIT_BRANCH` из **Настройки → Обновления агентов**.
3. Updater сам выполняет `git pull`, синхронизирует `sac-client.sh` и watchdog, дописывает отсутствующие ключи в **`/etc/ssh-monitor.conf`**, **выставляет `chmod`/`chown`** на конфиг, SAC-spool, счётчики и state-файлы, перезапускает **`ssh-monitor.service`**.
Участие админа на сервере **не требуется** (кроме первичной настройки `SAC_URL` / `SAC_API_KEY` в конфиге).
При **первой установке** (нет updater на хосте) SAC выполняет bootstrap с **`--deploy`**: clone, ipset при необходимости, systemd unit, полный hardening.
**Cron / systemd timer** — опциональная альтернатива с тем же скриптом и обязательным `REPO_URL` в окружении.
Watchdog и таймеры watchdog **не изменяются** при обычном update (кроме синхронизации скрипта watchdog из git).
**Конфиг `/etc/ssh-monitor.conf`:** при первой установке копируется из `ssh-monitor.conf.example`. При каждом update в **существующий** конфиг **дописываются** отсутствующие SAC-переменные и ключи безопасности; **`UseSAC=fallback`**. Telegram/SMTP и прочие ключи **не перезаписываются**.
Установка монитора и unit-файлов: [README.md](../README.md), зависимости: [install-prerequisites.ru.md](install-prerequisites.ru.md).
## Что делает скрипт
1. Создаёт рабочий каталог **`UPDATE_DIR`** (по умолчанию `/opt/scripts/update`).
2. При **`--deploy`** / bootstrap SAC проверяет **`ipset`** и при отсутствии пытается установить через пакетный менеджер. Обычное обновление **не** вызывает `apt-get`.
3. В **`UPDATE_DIR`** выполняет **`git clone`** или **`git fetch` + checkout / `git pull --ff-only`** (без слепого `reset --hard`).
4. Проверяет **`release/manifest-VERSION.json`** (SHA256 файлов + commit) **до** копирования в `/usr/local/bin`.
5. Ищет **`ssh-monitor`** в клоне (GitLab layout или плоский репозиторий).
6. Сравнивает **SHA256** с **`LOCAL_SCRIPT_PATH`** (`/usr/local/bin/ssh-monitor`).
7. **Всегда** синхронизирует **`sac-client.sh`**, **`ssh-monitor-perms.sh`**, watchdog.
8. Дописывает ключи конфига; **`apply_runtime_security_hardening`**: `chmod 600` конфиг, `700` spool, `600` state/SAC-файлы, whitelist.
9. При изменении **`ssh-monitor`**, **`sac-client.sh`** или конфига — **`systemctl restart ssh-monitor.service`**.
10. Лог: **`/var/log/update_script.log`** (блок «Итог обновления», строки `manifest` и `security hardening`).
```mermaid
flowchart LR
A[SAC или cron] --> B[update_ssh_monitor.sh]
B --> C[git fetch/checkout]
C --> M{manifest OK?}
M -->|нет| X[exit 1]
M -->|да/skip| D[sync sac-client + perms lib]
C --> E{SHA256 ssh-monitor?}
D --> F[harden config/spool/state]
E -->|да| G[backup + cp ssh-monitor]
E -->|нет| F
G --> F
F --> H{что-то изменилось?}
H -->|да| I[restart ssh-monitor.service]
H -->|нет| J[без перезапуска]
```
## Настройка перед первым запуском
| Переменная | По умолчанию | Назначение |
|------------|--------------|------------|
| `UPDATE_DIR` | `/opt/scripts/update` | Каталог для git-клона |
| `REPO_URL` | *(обязательно)* | URL git — задаётся SAC, export или `Environment=` в cron |
| `GIT_BRANCH` | `main` | Ветка для clone/pull, если **`GIT_REF`** не задан |
| `GIT_REF` | *(пусто)* | Тег (`2.2.0-SAC`), ветка или commit SHA для checkout |
| `GIT_VERIFY_MODE` | `off` | `off` \| `tag` \| `commit` — см. раздел ниже |
| `GIT_ALLOW_RESET` | `0` | `1` = разрешить `git reset --hard` при расхождении истории (риск) |
| `RELEASE_MANIFEST_STRICT` | `0` | `1` = exit 1, если manifest для версии не найден |
| `LOCAL_SCRIPT_PATH` | `/usr/local/bin/ssh-monitor` | Куда копировать монитор |
| `LOG_FILE` | `/var/log/update_script.log` | Лог обновлений |
| `UPDATE_VIA_SAC` | *(опционально)* | SAC выставляет `1`; при отсутствии бинарника включается `--deploy` |
Требования: **root**, **git**, **python3** (manifest verify), доступ к репозиторию.
## Pinned ref и manifest (2.2.0+)
Updater читает **`GIT_REF`**, **`GIT_VERIFY_MODE`**, **`GIT_ALLOW_RESET`** из env или `/etc/ssh-monitor.conf`.
### Режимы `GIT_VERIFY_MODE`
| Режим | Поведение | Когда |
|-------|-----------|-------|
| **`off`** | После fetch принять ref как есть | Тест, legacy; дефолт в скрипте |
| **`tag`** | `GIT_REF` должен существовать как тег | **Рекомендуется для прода** |
| **`commit`** | `GIT_REF` = полный SHA commit | Жёсткий pin без тегов |
Если **`GIT_REF`** пуст, используется **`GIT_BRANCH`** (`git pull --ff-only`). При невозможности fast-forward updater **не** делает `reset --hard` (только с **`GIT_ALLOW_RESET=1`**).
### Release manifest
В репозитории: **`release/manifest-VERSION.json`** — SHA256 ключевых файлов и `git_commit`. Updater сверяет manifest **после** git sync и **до** копирования бинарников.
- Файл найден и hash не совпал → **exit 1**, ничего не перезаписывается.
- Файл не найден → WARN, update продолжается (или exit 1 при **`RELEASE_MANIFEST_STRICT=1`**).
- Копирование **`update_ssh_monitor.sh`** в `/opt/scripts/` и re-exec — только если manifest для версии был и прошёл verify.
Генерация manifest — см. [release-manifest.ru.md](release-manifest.ru.md). После `./contrib/install-git-hooks.sh` manifest обновляется **автоматически** при bump версии в pre-commit. Ручной wrapper: `.local/build-release-manifest.sh` (не в git).
```bash
./contrib/install-git-hooks.sh # один раз после clone
# bump version.txt + ssh-monitor → git commit (hook добавит manifest)
git tag 2.2.3-SAC
```
### Примеры для прода
**SAC / env на хосте** (через настройки SAC или unit):
```bash
REPO_URL=https://git.papatramp.ru/PapaTramp/ssh-monitor.git
GIT_REF=2.2.0-SAC
GIT_VERIFY_MODE=tag
```
**systemd timer** (`/etc/systemd/system/ssh-monitor-update.service`):
```ini
[Service]
Type=oneshot
Environment=REPO_URL=https://git.papatramp.ru/PapaTramp/ssh-monitor.git
Environment=GIT_REF=2.2.0-SAC
Environment=GIT_VERIFY_MODE=tag
ExecStart=/opt/scripts/update_ssh_monitor.sh
```
При доверенном закрытом зеркале **manifest + `GIT_REF=tag`** — достаточный минимум; GPG-подписи тегов — backlog (см. [security-roadmap.ru.md](security-roadmap.ru.md)).
## Первичная установка (--deploy)
```bash
sudo REPO_URL=https://git.papatramp.ru/PapaTramp/ssh-monitor.git ./update_ssh_monitor.sh --deploy
# или first_deploy.sh с REPO_URL в окружении
```
Через SAC bootstrap выполняется автоматически с **`--deploy`**.
## Установка updater (если не через SAC bootstrap)
```bash
sudo mkdir -p /opt/scripts
sudo cp update_ssh_monitor.sh /opt/scripts/update_ssh_monitor.sh
sudo chmod 750 /opt/scripts/update_ssh_monitor.sh
```
Проверка:
```bash
sudo REPO_URL=https://git.papatramp.ru/PapaTramp/ssh-monitor.git /opt/scripts/update_ssh_monitor.sh
sudo tail -30 /var/log/update_script.log
```
## Запуск по расписанию (опционально)
### Cron
```
0 4 * * * REPO_URL=https://git.papatramp.ru/PapaTramp/ssh-monitor.git /opt/scripts/update_ssh_monitor.sh
```
### systemd timer
См. предыдущие примеры `ssh-monitor-update.service` / `.timer` с `Environment=REPO_URL=...`.
## Откат
```bash
ls -la /usr/local/bin/ssh-monitor.backup.*
sudo cp /usr/local/bin/ssh-monitor.backup.YYYYMMDD_HHMMSS /usr/local/bin/ssh-monitor
sudo systemctl restart ssh-monitor.service
```
## Ограничения
- Секреты (`SAC_API_KEY`, Telegram) SAC **не** прописывает — только в `/etc/ssh-monitor.conf` на хосте.
- При недоступном git **`git pull`** пишет предупреждение и продолжает с локальной копией.
- **`REPO_URL`** без дефолта в скрипте — только доверенное зеркало (kalinamall / своё Gitea).
docs/install-prerequisites.ru.md
+152
View File
@@ -0,0 +1,152 @@
# Системные зависимости и установка окружения
Этот документ описывает, **какой софт** на сервере нужен для работы **ssh-monitor**, и **как его поставить** типовыми пакетами. Саму установку скрипта, конфигов и **systemd** смотрите в корневом [README.md](../README.md).
## 1. Что должно быть на хосте
### Обязательно
| Назначение | Что используется | Примечание |
|------------|------------------|------------|
| Интерпретатор | **Bash** (версия с `declare -A`) | Обычно уже есть (`/bin/bash`). |
| Запуск брандмауэра | **iptables**; для IPv6 — **ip6tables** (если баните IPv6) | Скрипт добавляет правила `DROP` для заблокированных IP. Нужен **root** (скрипт не стартует без root, кроме `--dry-run` / проверок). |
| Telegram | **curl** | Запросы к `api.telegram.org`. |
| Почта (канал `email`) | **Python 3** | SMTP через стандартную библиотеку. |
| Резервный webhook | **Python 3** + **curl** | Сборка JSON и `POST`. |
Без **хотя бы одного** настроенного канала (`telegram` или `email`) скрипт завершится с ошибкой — это не зависимости ОС, а настройка в `/etc/ssh-monitor.conf`.
### Настоятельно рекомендуется (полный функционал)
| Назначение | Что используется |
|------------|------------------|
| Журнал SSH/sudo/брутфорс, logind | **systemd** + **`journalctl`** |
| Дедупликация уведомлений logind для SSH | **`loginctl`** (часть **systemd**) |
| Удобный просмотр логов сервиса | **`journalctl`** |
На минималистичных системах без **journald** часть функций не работает или упрощается; отчёт за сутки по SSH может опираться на **`/var/log/auth.log`** (см. ниже).
### Утилиты из «базовой» системы
Обычно уже установлены: `grep`, `sed`, `awk`, `sort`, `date`, `who`, `mktemp`, `sudo` (если запускаете не напрямую от root), `wc`, `hostname`, `ip` (для подписи сервера в уведомлениях). Для дедупликации sudo в журнале желательны **`sha256sum`** или **`cksum`**.
---
## 2. Пошаговая установка пакетов (Debian / Ubuntu)
Выполняйте от пользователя с `sudo`.
**Шаг 1.** Обновить индексы пакетов:
```bash
sudo apt update
```
**Шаг 2.** Минимум для Telegram и бана по firewall:
```bash
sudo apt install -y iptables curl
```
При необходимости IPv6 (если на сервере используется `ip6tables`):
```bash
sudo apt install -y ip6tables
```
(На многих образах **ip6tables** уже входит в метапакет с iptables.)
**Шаг 3.** Если включите доставку почты (`MAIL_*` в конфиге):
```bash
sudo apt install -y python3
```
**Шаг 4.** Типовой сервер с **systemd** уже содержит `journalctl` и `loginctl`. Если ставите минимальный контейнер без них — для полного мониторинга нужен стек с **systemd** и **journald** (или см. раздел про ограничения без journald).
**Шаг 5.** (Опционально) Сохранение правил **iptables** после перезагрузки — отдельно от ssh-monitor, например:
```bash
sudo apt install -y iptables-persistent netfilter-persistent
```
Скрипт при наличии каталога **`/etc/iptables`** может записывать туда `rules.v4` / `rules.v6` (см. код `save_iptables_rules`). Имеет смысл создать каталог и настроить автозагрузку правил по документации вашего дистрибутива.
---
## 3. Другие дистрибутивы
Принцип тот же: пакеты **bash**, **iptables** (+ **ip6tables**), **curl**, **python3**; для полного функционала — **systemd** с **journald**.
Примеры:
- **RHEL / Alma / Rocky:** `dnf install iptables curl python3 systemd` (имена метапакетов могут отличаться).
- **Alpine:** `apk add bash iptables ip6tables curl python3` — отдельно проверьте наличие **systemd** / **journalctl** (на Alpine часто нет; мониторинг по journal будет недоступен).
---
## 4. Системы без `journalctl` (классический syslog)
- События **SSH** могут читаться из **`/var/log/auth.log`** (если скрипт не находит `journalctl`).
- **Ежедневная статистика** по этим файлам для отчёта **точнее с Python 3** (разбор логов в скрипте). Без Python отчёт может использовать упрощённый fallback.
- Блоки, завязанные на **`journalctl`** (**sudo** по журналу, **systemd-logind**, часть **security/brute**), на таком хосте **не дадут полного результата**.
---
## 5. Конфликты с UFW / другими обёртками firewall
Скрипт вставляет правила **iptables** самостоятельно. Если используете **UFW**, **firewalld** или только **nftables** без совместимости с iptables-nft, возможны конфликты или неожиданный порядок правил. После внедрения проверьте:
```bash
sudo iptables -L INPUT -n -v --line-numbers
```
При необходимости согласуйте порядок с вашей схемой управления firewall.
---
## 6. Опционально: watchdog
Скрипт **`ssh-monitor-watchdog`** проверяет сервис `ssh-monitor.service` и актуальность heartbeat; при сбое выполняет `systemctl restart`.
**Установка:**
1. Скопируйте скрипт:
`sudo install -m 750 ./ssh-monitor-watchdog /usr/local/bin/ssh-monitor-watchdog`
2. Установите unit и timer:
`sudo cp ./ssh-monitor-watchdog.service.example /etc/systemd/system/ssh-monitor-watchdog.service`
`sudo cp ./ssh-monitor-watchdog.timer.example /etc/systemd/system/ssh-monitor-watchdog.timer`
3. Включите timer:
```bash
sudo systemctl daemon-reload
sudo systemctl enable ssh-monitor-watchdog.timer
sudo systemctl start ssh-monitor-watchdog.timer
```
4. Проверка:
```bash
sudo systemctl status ssh-monitor-watchdog.timer
sudo systemctl list-timers | grep ssh-monitor-watchdog
sudo journalctl -u ssh-monitor-watchdog.service -f
```
Параметры watchdog задаются в **`/etc/ssh-monitor.conf`** (переменные `WATCHDOG_*` в примере конфига).
---
## 7. Краткий чек-лист перед первым запуском
- [ ] Установлены **iptables** (и при необходимости **ip6tables**).
- [ ] Для Telegram установлен **curl**; для почты / webhook — **python3**.
- [ ] Настроен **`/etc/ssh-monitor.conf`** (минимум один канал уведомлений).
- [ ] Понятен порядок правил firewall на хосте (UFW и т.д.).
- [ ] (По желанию) настроено сохранение правил после перезагрузки.
Далее: установка самого **`ssh-monitor`**, unit **systemd** и проверка — в [README.md](../README.md).
Дополнительно:
- [notifications.ru.md](notifications.ru.md) — подпись **«🖥️ Сервер»** в уведомлениях, типы алертов, часовые пояса.
- [auto-update.ru.md](auto-update.ru.md) — автообновление скрипта через **`update_ssh_monitor.sh`**.
docs/notifications.ru.md
+97
View File
@@ -0,0 +1,97 @@
# Уведомления 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` — при каждом событии попытка **во все** каналы списка.
Режим **`--dry-run`**: уведомления не отправляются; в stderr печатается текст **уже с подписью сервера**.
docs/release-manifest.ru.md
+46
View File
@@ -0,0 +1,46 @@
# Release manifest
Файлы `release/manifest-VERSION.json` — SHA256 агентских скриптов **как в git** (после `checkout` на Linux). Updater сверяет их до копирования на хост.
## Автоматически (рекомендуется)
Один раз после clone:
**Linux / Git Bash:**
```bash
./contrib/install-git-hooks.sh
```
**Windows (PowerShell):**
```powershell
.\contrib\install-git-hooks.ps1
```
При коммите, если изменились **`version.txt`**, **`SSH_MONITOR_VERSION`** в `ssh-monitor` или любой из агентских файлов (`ssh-monitor`, `*.sh` из списка manifest), **pre-commit** вызовет `contrib/manifest/generate.py` и добавит `release/manifest-{версия}.json` в коммит.
## Ручная генерация (локально)
Скрипты **`.local/build-release-manifest.ps1`** (Windows) и **`.local/build-release-manifest.sh`** (Git Bash) создаются установщиком и **не коммитятся** (см. `.gitignore`).
```powershell
.\.local\build-release-manifest.ps1
.\.local\build-release-manifest.ps1 2.2.3-SAC
```
```bash
./.local/build-release-manifest.sh
```
Ядро генерации в репозитории: `contrib/manifest/generate.py` (используется hook и локальным wrapper).
## Релиз (чек-лист)
1. Bump `SSH_MONITOR_VERSION` + `version.txt`
2. `git add` изменённые файлы
3. `git commit` — hook обновит manifest (или вручную `.local/build-release-manifest.sh`)
4. `git tag X.Y.Z-SAC`
5. Push в kalinamall (+ GitHub при необходимости)
Поле `git_commit` в manifest по умолчанию **пустое** (проверяются только SHA256 файлов). Опционально после коммита: `python3 contrib/manifest/generate.py --pin-commit`.
См. также [auto-update.ru.md](auto-update.ru.md).
docs/sac-ingest.ru.md
+40
View File
@@ -0,0 +1,40 @@
# SAC ingest: таймауты и fallback
Документ для эксплуатации **ssh-monitor** с `UseSAC=fallback` или `exclusive` при нагрузке на SAC (массовый update агентов, deploy backend).
См. также: [ingest-mass-update-backlog.ru.md](https://git.papatramp.ru/PapaTramp/security-alert-center/src/branch/main/docs/ingest-mass-update-backlog.ru.md) (SAC + ops).
## `SAC_TIMEOUT_SEC`
Таймаут **connect** и **max-time** для `curl` к SAC (`/health`, `POST /api/v1/events`).
| Сценарий | Рекомендация |
|----------|--------------|
| Обычная нагрузка | **45** (дефолт в `ssh-monitor.conf.example` и при миграции с 12) |
| Массовый restart агентов, тяжёлый ingest на SAC | **60–90** на время окна обслуживания |
| SAC на том же хосте перезапускается (`sac-deploy`) | Кратковременные отказы POST — норма; не поднимать таймаут «навсегда» без причины |
На стороне SAC (nginx) для ingest задан `proxy_read_timeout 120s` на `POST /api/v1/events`. Агентский таймаут **не обязан** равняться 120: достаточно, чтобы POST не обрывался раньше типичного ответа API. При `SAC_TIMEOUT_SEC` меньше nginx-лимита агент уйдёт в spool и `sac-fail.count`, а не «висит» минутами.
Проверка после смены:
```bash
sudo ssh-monitor --check-config
sudo ssh-monitor --check-sac
```
## `sac-fail.count` и режим `fallback`
При ошибке POST ingest счётчик в `SAC_FAIL_COUNT_FILE` увеличивается. После **`SAC_FALLBACK_FAILURES`** подряд (по умолчанию 5) агент перестаёт слать в SAC и шлёт только в локальный Telegram, пока `/health` снова не станет OK.
**Сброс счётчика:** любой успешный POST (в т.ч. heartbeat) обнуляет `sac-fail.count`.
**Shutdown / SIGTERM (с 2.3.2-SAC):** при остановке монитора (`systemctl stop`, restart во время SAC-update) неудачный lifecycle POST **не увеличивает** счётчик — иначе после штатного restart пачки хостов агент ложно уходит в Telegram-fallback.
Lifecycle при SAC-update по-прежнему **пропускается**, если существует state-file `agent-update-in-progress` (см. `update_ssh_monitor.sh`).
## Операционные правила
1. Не совмещать `sudo /opt/sac-deploy.sh` и массовое «Обновить ssh-monitor» по многим хостам в одно окно.
2. Обновлять Linux-хосты **пачками по 2–3**.
3. На зрелых хостах — **`UseSAC=exclusive`**, если локальный Telegram при fallback не нужен.
docs/security-roadmap.ru.md
+261
View File
@@ -0,0 +1,261 @@
# Security roadmap — ssh-monitor
Чек-лист правок по аудиту безопасности. **Код пока не трогаем** — документ для совместного просмотра и утверждения фаз.
Связанные файлы: `ssh-monitor`, `update_ssh_monitor.sh`, `sac-client.sh`, `ssh-monitor-watchdog`, `ssh-monitor.conf.example`.
---
## Модель доверия (согласовано)
| Объект | Кто отвечает |
|--------|----------------|
| **`REPO_URL`** | Оператор. Указывает **своё** зеркало (kalinamall, GitHub после санитайза, форк). Жёсткий allowlist в коде **не нужен**. |
| **Закрытое зеркало** | Доверенный git в LAN/VPN — основной путь обновления. |
| **Публичный GitHub** | Санитизированная копия без секретов; обновление оттуда допустимо, если оператор сам прописал URL. |
| **`/etc/ssh-monitor.conf`** | Доверенный root-only файл; агент работает от root. |
| **Аудиты** | Нерегулярно; roadmap закрывает разумный baseline, не «вечный SOC». |
---
## Порядок релизов
| Версия | Фазы | Суть |
|--------|------|------|
| **2.1.7-SAC** | Фаза 1 + выбранное из Фазы 4 | Права, `REPO_URL` обязателен, webhook, docs | ✅ реализовано |
| **2.1.8-SAC** | Дополнение к 1.1 | SAC-first update: hardening прав на каждом прогоне updater | ✅ реализовано |
| **2.1.9-SAC** | Дополнение к 1.x | Watchdog: `🖥️ Сервер:` в Telegram (как у агента) | ✅ реализовано |
| **2.3.2-SAC** | **Фаза 4.2** | Shutdown: не крутить `sac-fail.count`; docs `SAC_TIMEOUT_SEC` | ✅ реализовано |
| **2.3.1-SAC** | Hotfix | `--check-config` + whitelist IPv4 | ✅ реализовано |
| **2.2.3-SAC** | Дополнение к 2.2.x | Подавление sudo TG при SAC bootstrap/update | ✅ реализовано |
| **2.2.1-SAC** | Дополнение к 2.2.0 | Подавление lifecycle/watchdog TG при SAC-update | ✅ реализовано |
| **2.2.0-SAC** | **Фаза 2** | Manifest, pinned ref, без слепого `reset --hard` | ✅ реализовано |
| **2.3.0-SAC** | Фаза 3 | Парсер конфига без `source` (minor breaking) |
Bump: `ssh-monitor` (`SSH_MONITOR_VERSION`) + `version.txt` в каждом релизе.
**Текущий статус (2026-07-08):** фаза **4.2** закрыта (2.3.2-SAC). Дальше — ops (`UseSAC=exclusive`, пачки update) и опционально GPG / `GIT_REF=tag` на проде.
Backlog по ingest при массовом update (SAC + ops): [ingest-mass-update-backlog.ru.md](https://git.papatramp.ru/PapaTramp/security-alert-center/src/branch/main/docs/ingest-mass-update-backlog.ru.md) (отдельный ToDo).
---
## Фаза 1 — 2.1.7-SAC
### 1.1 Права на state / spool (M4)
- [x] При создании каталогов и файлов состояния: `chown root:root`, каталоги `chmod 700`, файлы `chmod 600`
- [x] Затронуть: `SAC_SPOOL_DIR`, `SAC_FAIL_COUNT_FILE`, heartbeat / last_* (где создаёт `ssh-monitor` / `sac-client.sh` / deploy)
- [x] **2.1.8:** `update_ssh_monitor.sh` → `apply_runtime_security_hardening` на **каждом** update (SAC, cron, вручную): retrofit `chmod`/`chown` существующих путей из конфига
- [x] В `--check-config`: предупреждение, если существующие пути с ослабленными правами
**Файлы:** `ssh-monitor`, `sac-client.sh`, при необходимости `update_ssh_monitor.sh`
---
### 1.2 Проверка прав конфига при старте (C1, частично)
- [x] Перед загрузкой конфига: если `/etc/ssh-monitor.conf` существует — проверить `root:root`, mode `600` или `400`
- [x] **Поведение по умолчанию:** `WARN` в лог + stderr, работа продолжается (не ломать старые установки с `644`)
- [x] Опционально в конфиге: `CONFIG_STRICT_PERMS=1` → **exit 1** при нарушении
**Решение агента:** strict выключен по умолчанию; в README рекомендовать `chmod 600` и позже `400`.
---
### 1.3 `BACKUP_WEBHOOK_URL` (H3) — **вариант A (soft-deprecate)**
- [x] В `ssh-monitor.conf.example`: закомментировать / убрать из «активного» блока, комментарий `DEPRECATED: не используется в типовом деплое; будет удалён в 2.3.x`
- [x] В README / `docs/notifications.ru.md`: пометить **legacy / необязательно**
- [x] В `--check-config`: если задан — WARN (удалён в 2.3.0)
- [x] **Удаление кода** — **2.3.0-SAC**
---
### 1.4 `REPO_URL` — только из env, без дефолта в коде (C3) — **утверждено**
- [x] Убрать захардкоженный default `https://git.kalinamall.ru/...` из `update_ssh_monitor.sh`
- [x] При старте updater: если `REPO_URL` пуст — **exit 1**, сообщение в **stderr** и **`$LOG_FILE`**
- [x] Текст ошибки: что задать (`export REPO_URL=...` или в systemd unit `Environment=REPO_URL=...`)
- [x] SAC: основной путь обновления (кнопка в UI); cron/timer — опционально. Bootstrap SAC → `--deploy`
- [x] **Не** делать allowlist доменов — оператор сам выбирает зеркало
**Файлы:** `update_ssh_monitor.sh`, `docs/auto-update.ru.md`, пример unit/timer если есть
**Заметка:** после 2.1.7 на всех хостах нужно явно прописать `REPO_URL` до следующего обновления.
---
### 1.5 Документация threat model
- [x] `README.md` + этот файл: root-агент, доверие к `REPO_URL` и конфигу, санитайз GitHub
- [x] Рекомендация: критичные хосты — только закрытое зеркало; автообновление осознанно
---
## Фаза 2 — 2.2.0-SAC
### 2.1 Pinned ref и режим верификации (C2) — **утверждено, детали на агенте**
Новые переменные (env или ключи в `/etc/ssh-monitor.conf`, читаемые updater’ом):
| Переменная | Назначение | Рекомендация |
|------------|------------|--------------|
| **`GIT_REF`** | Что checkout: тег (`2.2.0-SAC`), ветка (`main`) или commit SHA | **Тег релиза** — оптимально для прода |
| **`GIT_VERIFY_MODE`** | `off` \| `tag` \| `commit` | См. ниже |
**`GIT_VERIFY_MODE`:**
| Значение | Поведение | Когда использовать |
|----------|-----------|-------------------|
| **`off`** | После fetch принять ref как есть (как сейчас, но без `reset --hard` по умолчанию) | Тест, если manifest ниже достаточен |
| **`tag`** | `GIT_REF` должен быть **аннотированным тегом**; опционально `git tag -v` (см. 2.4) | **Рекомендуется для прода** |
| **`commit`** | `GIT_REF` = полный SHA; сверка с manifest | Жёсткий pin без тегов |
- [x] Реализовать чтение `GIT_REF` / `GIT_VERIFY_MODE` в `update_ssh_monitor.sh`
- [x] Дефолты для 2.2.0: `GIT_REF` пуст → `GIT_BRANCH`; `GIT_VERIFY_MODE=off` в скрипте, **`tag`** в prod-документации
- [x] **`docs/auto-update.ru.md`**: отдельный раздел с примерами systemd и таблицей режимов
---
### 2.2 Без слепого `reset --hard` (C2) — **утверждено**
- [x] При failed `git pull --ff-only`: **не** делать `reset --hard` автоматически
- [x] Лог + stderr: «история разошлась, требуется ручное вмешательство или новый clone»
- [x] Опционально: `GIT_ALLOW_RESET=1` только для ручного/CI (документировать риск)
---
### 2.3 Release manifest (C2, C4) — **утверждено**
- [x] Файл в репо, например `release/manifest-2.2.0-SAC.json`:
```json
{
"version": "2.2.0-SAC",
"git_commit": "abc123...",
"files": {
"ssh-monitor": "sha256:...",
"sac-client.sh": "sha256:...",
"update_ssh_monitor.sh": "sha256:...",
"ssh-monitor-watchdog": "sha256:..."
}
}
```
- [x] Публиковать manifest при каждом релизе (в git, рядом с тегом)
- [x] Updater: после checkout сверять SHA256 файлов из клона с manifest **до** копирования в `/usr/local/bin`
- [x] Несовпадение → exit 1, ничего не перезаписывать
- [x] Скрипт/цель в `Makefile` + `contrib/manifest/generate.py`; pre-commit hook; ручной `.local/` (не в remote)
**Связь с 2.4:** manifest из **того же** `REPO_URL` защищает от подмены файлов в clone и от «не того» коммита; не защищает от полной компрометации git-сервера (для этого GPG).
---
### 2.4 GPG-подписи тегов — **опционально, скорее отложить**
**Вопрос:** если обновляем только из своего `REPO_URL` (kalinamall), нужен ли GPG?
| Угроза | Manifest + pinned tag | + GPG tag |
|--------|----------------------|-----------|
| Подмена файлов в clone / wrong commit | Да | Да |
| Компрометация аккаунта git (вредоносный force-push) | **Нет** | Да (если ключ не украден) |
| Доверенный LAN git у оператора | Обычно достаточно manifest | Nice-to-have |
**Решение для roadmap:**
- [x] **2.2.0:** не блокировать релиз на GPG; `GIT_VERIFY_MODE=tag` без `-v`
- [ ] **Backlog:** `GIT_GPG_VERIFY=1` + ключ в `/etc/ssh-monitor/trusted-release-key.asc`, если позже понадобится
- [x] Документировать: при доверенном закрытом зеркале manifest + `GIT_REF=tag` — **достаточный минимум**
---
### 2.5 Re-exec updater только после verify (C4) — **утверждено**
- [x] `UPDATER_REEXEC` / копирование `update_ssh_monitor.sh` в `/opt/scripts/` — только если manifest SHA256 совпал
- [x] Иначе: лог, старая версия updater остаётся, exit 1
---
## Фаза 3 — 2.3.0-SAC (парсер конфига)
### 3.1 Парсер без `source` (C1) — **утверждено**
- [x] Whitelist ключей: `TELEGRAM_*`, `SAC_*`, `MAIL_*`, `NOTIFY_*`, числовые лимиты, пути и т.д.
- [x] Формат строк: `KEY="value"` / `KEY='value'` / `KEY=value`
- [x] Игнор `#` комментариев; неизвестные ключи — WARN
**Файлы:** `ssh-monitor-perms.sh` (`ssh_monitor_config_load_file`), `ssh-monitor`, `ssh-monitor-watchdog`
---
### 3.2 Миграция — **решение агента**
- [x] **2.3.0:** парсер по умолчанию; `source` **удалён**
- [x] Синтаксис файла **не меняется** для пользователя — те же `KEY="value"`
- [x] В release notes: «поведение то же, выполнение bash из конфига невозможно»
- [x] `ssh-monitor --check-config` проверяет неизвестные/битые строки (WARN) и значения (ERROR)
- [x] Отдельная команда миграции **не нужна** (формат тот же)
---
### 3.3 Валидация значений — **решение агента**
- [x] URL: `SAC_URL` — http(s)://host
- [x] Enum: `UseSAC` ∈ `off|exclusive|dual|fallback`; `GIT_VERIFY_MODE` ∈ `off|tag|commit`
- [x] Числа: существующие `validate_numeric_or_default`
- [x] IP/CIDR в `WHITELIST_*` — базовая проверка формата
- [x] Ошибки валидации → exit 1 на старте и в `--check-config`
---
### 3.x Удаление `BACKUP_WEBHOOK` (если утвердили soft-deprecate в 1.3)
- [x] Удалить код и документацию в **2.3.0**
---
## Фаза 4 — что делаем, что нет
| Пункт | Версия | Решение |
|-------|--------|---------|
| **4.4** `ensure_ipset_installed` не на каждый update | 2.1.7 | **Делаем:** только `--deploy` / `first_deploy.sh`; обычный update не вызывает `apt-get` | ✅ |
| **4.3** Права whitelist-файла | 2.1.7 | **Делаем:** при загрузке `/etc/ssh_monitor_whitelist.txt` — WARN если не root:root | ✅ |
| **4.5** JSON healthcheck через `json.dumps` | 2.2.0 | **Делаем:** мелкий fix L3 | ✅ |
| **4.1** Секреты не через environ в Python | — | **Не делаем** (мало выигрыша при root) |
| **4.2** Telegram token в URL | — | **Не делаем** (ограничение Bot API) |
| **4.6** systemd hardening (non-root) | — | **Не делаем** (ipset/iptables требуют root) |
| **M6** Ротация логов | — | Уже есть `contrib/logrotate.d/` — только упоминание в README |
| **M7** `set_config_kv` sed | 2.2.0 | **Делаем:** экранирование `/` и `"` в `val` при merge конфига | ✅ |
---
## Вне scope (согласовано не раздувать)
- Жёсткий allowlist `REPO_URL` / зеркал — оператор задаёт свой URL
- Cert pinning TLS
- HashiCorp Vault / systemd-creds для секретов (backlog на годы)
- Регулярные внешние аудиты
---
## Чек-лист «перед стартом работы завтра»
- [x] **Релиз 2.1.7–2.1.9** — фаза 1 + SAC-first + watchdog server label
- [x] **Релиз 2.2.0** — scope: 2.1–2.3, 2.5, 4.5, 4.7(M7); **2.4 GPG отложить**
- [x] **Релиз 2.3.0** — scope: 3.1–3.3, удаление webhook
- [ ] **Дефолт `GIT_REF`** в 2.2.0: тег из `version.txt` vs `main`
- [x] **Миграция хостов:** SAC-first update, `known_hosts`, `REPO_URL` через SAC
- [ ] **Ingest mass-update backlog** — см. security-alert-center `docs/ingest-mass-update-backlog.ru.md`
---
## Открытые вопросы на завтра
1. **1.3** — `BACKUP_WEBHOOK_URL`: soft-deprecate (A), удалить сразу (B), оставить (C)?
2. **1.2** — достаточно WARN по умолчанию или сразу strict на новых установках?
3. **2.1** — дефолт `GIT_REF`: тег `version.txt` или ветка `main`?
4. Подтверждение: **ни на одном хосте** не используется Slack/Discord webhook через `BACKUP_WEBHOOK_URL`?
---
*Документ создан для ревью. После утверждения — работа по фазам в отдельных коммитах с bump версии.*