security-alert-center/docs/agent-integration.md

Интеграция агентов с SAC

Контракт между ssh-monitor, RDP-login-monitor и Security Alert Center.
Изменения вносятся в репозитории агентов отдельными задачами.

---

1. Режим UseSAC

1.1. Параметры конфигурации

ssh-monitor (/etc/ssh-monitor.conf):

# 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):

$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 (RDP): до 1.2.8-SAC Invoke-WebRequest мог слать JSON не в UTF-8 — в UI «Отчёты» summary вида RDP 24?: ?????? вместо RDP 24ч: сессий …. Обновите Sac-Client.ps1 на всех хостах; старые события в БД не пересчитываются, исправятся только новые ingest после деплоя.

Только правки Sac-Client.ps1 / sac-client.sh: для RDP достаточно поднять patch в version.txt (и при необходимости $ScriptVersion); для Linux sac-client.sh обновится по checksum даже без смены SSH_MONITOR_VERSION, но рекомендуется поднимать обе метки для логов.

1.5. Правила Problems v1 (SAC backend)

rule_id	Условие	Пороги (env)
rule:brute_force_burst	ssh.login.failed / rdp.login.failed, один source_ip	SAC_BRUTE_FORCE_WINDOW_MINUTES=15, SAC_BRUTE_FORCE_THRESHOLD=30
rule:privilege_spike	privilege.sudo.command на хосте	SAC_PRIVILEGE_SPIKE_WINDOW_MINUTES=10, SAC_PRIVILEGE_SPIKE_THRESHOLD=10
rule:host_silence	был heartbeat, но устарел (agent.heartbeat)	SAC_HEARTBEAT_STALE_MINUTES (как для UI «Хосты»)

Свежий agent.heartbeat автоматически resolve open/ack проблему rule:host_silence. Одиночные high/critical (ban, mass bruteforce) — как раньше.

---

2. Протокол ingest

2.1. Запрос

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

{ ... событие по event-schema-v1.json ... }

2.2. Ответ

HTTP	Значение	status в теле	created
201	Событие записано впервые	created	true
409	Тот же event_id уже есть (идемпотентность)	duplicate	false
422	Ошибка JSON Schema	—	—

Пример 201:

{
  "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. Чеклист готовности агента

• Параметры конфига задокументированы в README агента (ssh-monitor, RDP-login-monitor)
• --check-sac / Test-SacConnection / -CheckSac
• Spool и повторная отправка
• Все типы из п. 3 покрыты (RDP: основные; 4648 — при появлении обработки)
• event_id UUID на каждое событие
• Секреты не в git

---

8. См. также

• event-schema-v1.json
• TZ.md §3.2, §4.8