206 lines
8.6 KiB
Markdown
206 lines
8.6 KiB
Markdown
# Интеграция агентов с SAC
|
||
|
||
Контракт между **ssh-monitor**, **RDP-login-monitor** и **Security Alert Center**.
|
||
Изменения вносятся в репозитории агентов отдельными задачами.
|
||
|
||
---
|
||
|
||
## 1. Режим `UseSAC`
|
||
|
||
### 1.1. Параметры конфигурации
|
||
|
||
**ssh-monitor** (`/etc/ssh-monitor.conf`):
|
||
|
||
```ini
|
||
# off | exclusive | dual | fallback
|
||
UseSAC="exclusive"
|
||
SAC_URL="https://sac.kalinamall.ru/api/v1/events"
|
||
SAC_API_KEY="sac_xxxxxxxx"
|
||
SAC_SPOOL_DIR="/var/lib/ssh-monitor/sac-spool"
|
||
SAC_SEND_HEARTBEAT="1"
|
||
SAC_FALLBACK_FAILURES="5"
|
||
SAC_TIMEOUT_SEC="12"
|
||
```
|
||
|
||
**RDP-login-monitor** (`Login_Monitor.ps1` или отдельный `.conf`):
|
||
|
||
```powershell
|
||
$UseSAC = "exclusive" # off | exclusive | dual | fallback
|
||
$SacUrl = "https://sac.kalinamall.ru/api/v1/events"
|
||
$SacApiKey = "sac_xxxxxxxx"
|
||
$SacSpoolDir = "D:\Soft\Logs\sac-spool"
|
||
```
|
||
|
||
### 1.2. Матрица поведения
|
||
|
||
| Событие | `off` | `exclusive` | `dual` | `fallback` |
|
||
|---------|-------|-------------|--------|------------|
|
||
| Auth / sudo / ban / RDP login | Telegram/email с агента | Только SAC JSON | SAC + Telegram | SAC; при сбоях → Telegram |
|
||
| Daily report | С агента | SAC формирует и шлёт | Оба | SAC, fallback как выше |
|
||
| Heartbeat | С агента (если включён) | Только SAC (`agent.heartbeat`) | Оба | SAC |
|
||
| Локальный LOG_FILE | Да | Да | Да | Да |
|
||
|
||
### 1.3. Проверка при старте
|
||
|
||
- `UseSAC=off` — без изменений: хотя бы один канал `NOTIFY_CHAIN` (как сейчас).
|
||
- `UseSAC≠off` — обязательны `SAC_URL`, `SAC_API_KEY`; HTTP `GET {base}/health` OK.
|
||
- `--check-sac` / `Test-SacConnection` — отправка `agent.test`, ожидание **HTTP 201** (повтор с тем же `event_id` — **409**, тоже успех для spool).
|
||
|
||
### 1.4. Версии и доставка обновлений
|
||
|
||
При **любом** изменении агента, влияющем на SAC или поведение на хосте, поднимайте версию и пушьте в **git.kalinamall.ru**:
|
||
|
||
| Агент | Маркер версии | Как хост узнаёт о новой версии |
|
||
|-------|---------------|--------------------------------|
|
||
| **ssh-monitor** | `SSH_MONITOR_VERSION` в `ssh-monitor`; `# SAC client release:` в `sac-client.sh` | `update_ssh_monitor.sh`: `git pull` в клоне → сравнение sha256 `ssh-monitor` и `sac-client.sh` |
|
||
| **RDP-login-monitor** | `$ScriptVersion` в `Login_Monitor.ps1` и **та же** строка в `version.txt` на шаре NETLOGON | `Deploy-LoginMonitor.ps1`: `version.txt` на шаре > `deployed_version.txt` → копирует `Login_Monitor.ps1` и `Sac-Client.ps1` |
|
||
|
||
Только правки `Sac-Client.ps1` / `sac-client.sh`: для RDP достаточно поднять patch в `version.txt` (и при необходимости `$ScriptVersion`); для Linux `sac-client.sh` обновится по checksum даже без смены `SSH_MONITOR_VERSION`, но **рекомендуется** поднимать обе метки для логов.
|
||
|
||
---
|
||
|
||
## 2. Протокол ingest
|
||
|
||
### 2.1. Запрос
|
||
|
||
```http
|
||
POST /api/v1/events HTTP/1.1
|
||
Host: sac.kalinamall.ru
|
||
Content-Type: application/json
|
||
Authorization: Bearer sac_xxxxxxxx
|
||
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
|
||
|
||
```
|
||
|
||
### 2.2. Ответ
|
||
|
||
| HTTP | Значение | `status` в теле | `created` |
|
||
|------|----------|-----------------|-----------|
|
||
| **201** | Событие записано впервые | `created` | `true` |
|
||
| **409** | Тот же `event_id` уже есть (идемпотентность) | `duplicate` | `false` |
|
||
| **422** | Ошибка JSON Schema | — | — |
|
||
|
||
Пример **201**:
|
||
|
||
```json
|
||
{
|
||
"status": "created",
|
||
"event_id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"created": true,
|
||
"sac_event_url": "https://sac.kalinamall.ru/api/v1/events/12345",
|
||
"problem_id": null
|
||
}
|
||
```
|
||
|
||
`event_id` — обязательный **UUID** (RFC 4122), уникален глобально; в БД индекс `UNIQUE (event_id)`.
|
||
|
||
### 2.3. Spool при ошибке
|
||
|
||
1. Записать JSON в `SAC_SPOOL_DIR/{event_id}.json`.
|
||
2. **ssh-monitor:** каждую итерацию цикла вызывается `sac_flush_spool` (до 20 файлов).
|
||
3. После успеха (**HTTP 201** или **409**) — удалить файл из spool.
|
||
4. Лимит размера spool (например 500 MB) — логировать WARN, не удалять без алерта.
|
||
|
||
---
|
||
|
||
## 3. Маппинг уведомлений → типы событий
|
||
|
||
### 3.1. ssh-monitor
|
||
|
||
| Текущий текст (сокращённо) | `type` | `severity` |
|
||
|----------------------------|--------|------------|
|
||
| Успешное SSH | `ssh.login.success` | info |
|
||
| Неудачная SSH | `ssh.login.failed` | warning |
|
||
| IP заблокирован | `ssh.ip.banned` | high |
|
||
| Лимит без бана | `ssh.ip.bruteforce.threshold` | warning |
|
||
| Массовый брутфорс | `ssh.bruteforce.mass` | high |
|
||
| Sudo | `privilege.sudo.command` | warning–critical* |
|
||
| logind new/removed/failed | `session.logind.*` | info–warning |
|
||
| Ежедневный отчёт | `report.daily.ssh` | info |
|
||
| Heartbeat | `agent.heartbeat` | info |
|
||
|
||
\* critical — по эвристике команды (`useradd`, `passwd`, `rm -rf`, …) в `details.risk_level`.
|
||
|
||
**Дополнительные поля в `details` (exclusive):**
|
||
|
||
- `user`, `source_ip`, `port`, `attempt_number`, `max_attempts`
|
||
- `sudo`: `run_as`, `command`, `pwd`, `risk_level`
|
||
- `ban`: `ban_until`, `enable_ip_ban`
|
||
- `brute`: `window_sec`, `fails_in_window`
|
||
- `whitelist_matched`: boolean
|
||
|
||
### 3.2. RDP-login-monitor
|
||
|
||
| Событие | `type` | `severity` |
|
||
|---------|--------|------------|
|
||
| 4624 успех | `rdp.login.success` | info |
|
||
| 4625 неудача | `rdp.login.failed` | warning |
|
||
| 4648 | `auth.explicit.credentials` | warning |
|
||
| RD Gateway 302 | `rdg.connection.success` | info |
|
||
| RD Gateway 303 | `rdg.connection.failed` | warning |
|
||
| Старт/стоп | `agent.lifecycle` | info |
|
||
| Отчёт | `report.daily.rdp` | info |
|
||
|
||
**Дополнительные поля:**
|
||
|
||
- `event_id_windows`, `logon_type`, `ip_address`, `workstation_name`
|
||
- `gateway_target`, `gateway_error_code`
|
||
- `filtered_out`, `filter_reason`
|
||
|
||
---
|
||
|
||
## 4. Поля `dedup_key` (рекомендации)
|
||
|
||
| Тип | Формат dedup_key |
|
||
|-----|------------------|
|
||
| ssh.login.success | `{product}\|{host}\|ssh.login.success\|{user}\|{ip}` |
|
||
| ssh.login.failed | `{product}\|{host}\|ssh.login.failed\|{ip}` (окно в SAC) |
|
||
| privilege.sudo | `{product}\|{host}\|sudo\|{user}\|{hash(command)}` |
|
||
| rdp.login.failed | `{product}\|{host}\|rdp.failed\|{ip}\|{user}` |
|
||
|
||
SAC применяет cooldown по `dedup_key` + правилам.
|
||
|
||
---
|
||
|
||
## 5. Точки встраивания в код агентов
|
||
|
||
### ssh-monitor
|
||
|
||
- Новая функция `send_sac_event()` вызывается из мест, где сейчас `notify_send "$message"`.
|
||
- Обёртка `notify_or_sac()`:
|
||
- `UseSAC=off` → `notify_send`
|
||
- `exclusive` → только `send_sac_event` (в `summary` — тот же текст)
|
||
- `dual` → оба
|
||
- `fallback` → `send_sac_event`; при fail increment counter → при пороге `notify_send`
|
||
|
||
### RDP-login-monitor
|
||
|
||
- `Send-SacEvent` + замена вызовов `Send-TelegramMessage` для событий мониторинга.
|
||
- Heartbeat и daily report — отдельные типы в SAC.
|
||
|
||
---
|
||
|
||
## 6. Обратная совместимость
|
||
|
||
- По умолчанию `UseSAC=off` — поведение 100% как сейчас.
|
||
- `BACKUP_WEBHOOK_URL` в ssh-monitor при `exclusive` не используется для обычных алертов (только emergency в `fallback` — опционально).
|
||
|
||
---
|
||
|
||
## 7. Чеклист готовности агента
|
||
|
||
- [x] Параметры конфига задокументированы в README агента (ssh-monitor, RDP-login-monitor)
|
||
- [x] `--check-sac` / `Test-SacConnection` / `-CheckSac`
|
||
- [x] Spool и повторная отправка
|
||
- [ ] Все типы из п. 3 покрыты (RDP: основные; 4648 — при появлении обработки)
|
||
- [ ] `event_id` UUID на каждое событие
|
||
- [ ] Секреты не в git
|
||
|
||
---
|
||
|
||
## 8. См. также
|
||
|
||
- [event-schema-v1.json](event-schema-v1.json)
|
||
- [TZ.md](TZ.md) §3.2, §4.8
|