Merge PR #14: feat(dlp) enforcement + email outbound collector

2026-05-03 23:41:00 +03:00
parent 3e565b7a2e f916764d53
commit ff548a5840
7 changed files with 1768 additions and 277 deletions
@@ -0,0 +1,126 @@
+# DLP Enforcement (action: "block")
+
+## Обзор
+
+Phase 2.5 расширяет DLP endpoint collector функциями **активного предотвращения** (enforcement).
+При `action: "block"` в правиле DLP-политики коллектор не только регистрирует инцидент, но и выполняет блокирующее действие:
+
+| Канал     | Действие при `block`                                      |
+|-----------|-----------------------------------------------------------|
+| clipboard | Очистка буфера обмена (`Set-Clipboard -Value $null`)      |
+| usb       | Перевод USB-диска в read-only (`Set-Disk -IsReadOnly`)    |
+| print     | Отмена задания печати (`Remove-CimInstance Win32_PrintJob`)|
+
+Во всех случаях пользователь получает Windows-уведомление (balloon notification) с описанием причины блокировки.
+
+## Конфигурация политики
+
+Формат `dlp-policy.json` не изменился — поле `action` в правиле теперь поддерживает значение `"block"` наряду с `"alert"` (по умолчанию).
+
+### Пример: блокировка USB записи
+
+```json
+{
+  "defaults": {
+    "enabled": true,
+    "action": "alert",
+    "severity": "medium",
+    "cooldownSeconds": 300
+  },
+  "endpoint": {
+    "usb": [
+      {
+        "id": "block-all-usb-write",
+        "action": "block",
+        "severity": "high",
+        "message": "Запись на USB-носитель заблокирована политикой DLP"
+      }
+    ],
+    "clipboard": [
+      {
+        "id": "block-pdn-clipboard",
+        "action": "block",
+        "severity": "high",
+        "regexPatterns": [
+          "\\b\\d{3}-\\d{3}-\\d{3}\\s?\\d{2}\\b",
+          "\\b\\d{4}\\s?\\d{6}\\b"
+        ],
+        "minLength": 8,
+        "message": "Буфер обмена очищен: обнаружены персональные данные (СНИЛС/паспорт)"
+      }
+    ],
+    "print": [
+      {
+        "id": "block-confidential-print",
+        "action": "block",
+        "severity": "high",
+        "documentRegex": "(?i)(конфиденциально|секретно|confidential|restricted)",
+        "message": "Печать заблокирована: документ содержит метку конфиденциальности"
+      }
+    ]
+  }
+}
+```
+
+### Пример: только мониторинг (без блокировки)
+
+```json
+{
+  "endpoint": {
+    "usb": [
+      {
+        "id": "monitor-usb",
+        "action": "alert",
+        "severity": "medium",
+        "message": "Обнаружено подключение USB-носителя"
+      }
+    ]
+  }
+}
+```
+
+## Телеметрия
+
+Каждый инцидент с enforcement записывается в bucket `aw-dlp-incidents_<host>` с дополнительным полем:
+
+```json
+{
+  "ruleId": "block-all-usb-write",
+  "action": "block",
+  "severity": "high",
+  "signalType": "usb_insert",
+  "enforced": true,
+  "driveLetter": "E:",
+  "volumeName": "FLASH_DRIVE"
+}
+```
+
+- `enforced: true` — блокировка выполнена успешно
+- `enforced: false` — блокировка не удалась (недостаточно прав, устройство недоступно и т.д.)
+
+## Требования
+
+- **Clipboard block**: Не требует повышенных прав.
+- **USB write-block**: Требует запуск от имени администратора (для `Set-Disk -IsReadOnly`). При запуске без прав блокировка не сработает, но инцидент будет зарегистрирован с `enforced: false`.
+- **Print block**: Требует права на отмену заданий печати (обычно — SYSTEM или администратор принт-сервера).
+
+## Уведомления
+
+При каждой блокировке пользователю показывается Windows balloon notification:
+
+| Канал     | Заголовок                            |
+|-----------|--------------------------------------|
+| clipboard | `DLP: буфер обмена очищен`           |
+| usb       | `DLP: USB заблокирован для записи`   |
+| print     | `DLP: печать заблокирована`          |
+
+Текст уведомления берётся из поля `message` правила политики.
+
+## Rollback
+
+Для отключения enforcement без изменения кода — смените `action` с `"block"` на `"alert"` в `dlp-policy.json`. Все правила продолжат мониторинг без блокировки.
+
+Для USB, переведённого в read-only, восстановление:
+```powershell
+Get-Disk | Where-Object { $_.BusType -eq 'USB' -and $_.IsReadOnly } | Set-Disk -IsReadOnly $false
+```
@@ -32,6 +32,24 @@
 - File-operation telemetry (create/delete/rename/archive hints) — прототип внедрён (`windows/file-operations-collector.ps1`).
 - Central incident aggregation/export — прототип внедрён (`scripts/aggregate_dlp_events.py`, `docs/dlp-aggregator.md`).

+### Phase 2.5 — Enforcement (внедрено)
+
+- USB write-block (`Set-Disk -IsReadOnly`) при `action: "block"` — внедрено.
+- Print job cancel (`Remove-CimInstance Win32_PrintJob`) при `action: "block"` — внедрено.
+- Clipboard clear (`Set-Clipboard -Value $null`) при `action: "block"` — внедрено.
+- Windows balloon notification пользователю при блокировке — внедрено.
+- Телеметрия enforcement (`enforced: true/false` в incident heartbeat) — внедрено.
+- Документация: `docs/dlp-enforcement.md`.
+
+### Phase 2.5 — Email Outbound Collector (внедрено)
+
+- Мониторинг исходящей почты через Outlook COM (Sent Items polling) — внедрено.
+- SMTP network connection detection (порты 25/587/465/2525) — внедрено.
+- DLP-правила `endpoint.email[]` (regex по теме, получателям, вложениям, externalOnly) — внедрено.
+- Enforcement: перемещение в Drafts при `action: "block"` (Outlook mode) — внедрено.
+- Приватность: тема/получатели как SHA256, тело не читается — внедрено.
+- Документация: `docs/email-outbound-collector.md`.
+
 ### Phase 3

 - Policy engine service (server-side), versioned policies, approval workflow.
@@ -0,0 +1,164 @@
+# Email Outbound Collector
+
+## Обзор
+
+Мониторинг исходящей почты на Windows-эндпоинтах. Два режима работы:
+
+| Режим    | Источник                       | Данные                                                |
+|----------|--------------------------------|-------------------------------------------------------|
+| outlook  | Outlook COM (Sent Items)       | Subject, From, To/CC, вложения, размер тела           |
+| smtp     | `Get-NetTCPConnection`         | SMTP-соединения (порты 25/587/465/2525), процесс      |
+
+По умолчанию `Mode = 'both'` — оба режима активны одновременно.
+
+## Запуск
+
+```powershell
+# С deployment-config.json (штатный вариант)
+.\email-outbound-collector.ps1
+
+# С явными параметрами
+.\email-outbound-collector.ps1 -ServerHost 10.10.10.13 -ServerPort 5600 -Mode outlook
+
+# Только SMTP мониторинг (без Outlook)
+.\email-outbound-collector.ps1 -ServerHost 10.10.10.13 -Mode smtp
+```
+
+### Параметры
+
+| Параметр       | По умолчанию                            | Описание                        |
+|----------------|-----------------------------------------|---------------------------------|
+| `-ConfigPath`  | `C:\ProgramData\ActivityWatch\deployment-config.json` | Путь к конфигу            |
+| `-ServerHost`  | из конфига                              | Адрес AW-сервера                |
+| `-ServerPort`  | из конфига / 5600                       | Порт AW-сервера                 |
+| `-PolicyPath`  | из конфига / `dlp-policy.json`          | Путь к DLP-политике             |
+| `-Mode`        | `both`                                  | `outlook`, `smtp`, или `both`   |
+| `-PollSeconds` | из конфига / 10                         | Интервал опроса                 |
+
+## AW Buckets
+
+- `aw-email-monitor_<host>` — все email-события (signal heartbeats)
+- `aw-dlp-incidents_<host>` — инциденты при срабатывании DLP-правил
+
+## DLP-политика: секция `endpoint.email`
+
+Добавляется в существующий `dlp-policy.json`:
+
+```json
+{
+  "endpoint": {
+    "email": [
+      {
+        "id": "block-external-attachments",
+        "action": "block",
+        "severity": "high",
+        "minAttachments": 1,
+        "externalOnly": true,
+        "internalDomain": "@company.ru",
+        "message": "Запрещена отправка вложений на внешние адреса"
+      },
+      {
+        "id": "alert-confidential-subject",
+        "action": "alert",
+        "severity": "medium",
+        "subjectRegex": "(?i)(конфиденциально|секретно|для служебного пользования)",
+        "message": "Обнаружена отправка письма с пометкой конфиденциальности"
+      },
+      {
+        "id": "alert-personal-data",
+        "action": "alert",
+        "severity": "high",
+        "recipientRegex": "(?i)(gmail\\.com|mail\\.ru|yandex\\.ru|yahoo\\.com)",
+        "minAttachments": 1,
+        "message": "Отправка вложений на личную почту"
+      }
+    ]
+  }
+}
+```
+
+### Параметры правил
+
+| Поле              | Тип    | Описание                                                  |
+|-------------------|--------|-----------------------------------------------------------|
+| `id`              | string | Уникальный ID правила (обязательно)                       |
+| `action`          | string | `alert` (по умолчанию) или `block`                        |
+| `severity`        | string | `low`, `medium`, `high`, `critical`                       |
+| `subjectRegex`    | string | Regex по теме письма                                      |
+| `recipientRegex`  | string | Regex по списку получателей                               |
+| `senderRegex`     | string | Regex по адресу отправителя                               |
+| `attachmentRegex` | string | Regex по именам вложений                                  |
+| `minAttachments`  | int    | Минимальное количество вложений для срабатывания           |
+| `minBodyLength`   | int    | Минимальная длина тела письма                             |
+| `externalOnly`    | bool   | Срабатывать только на внешних получателей                  |
+| `internalDomain`  | string | Домен организации (используется с `externalOnly`)         |
+| `cooldownSeconds` | int    | Cooldown между повторными инцидентами                     |
+| `message`         | string | Текст уведомления пользователю и в инцидент               |
+
+## Enforcement (action: "block")
+
+**Outlook mode**: письмо перемещается из Sent Items в Drafts. Пользователь получает balloon notification.
+
+**SMTP mode**: только уведомление (перехват SMTP-соединения на сетевом уровне не реализуем из PowerShell). Инцидент записывается с `enforced: false`.
+
+## Телеметрия
+
+### Heartbeat `email_sent` (Outlook mode)
+```json
+{
+  "signalType": "email_sent",
+  "subject": "<sha256 hash>",
+  "sender": "user@company.ru",
+  "recipientCount": 3,
+  "recipients": "<sha256 hash>",
+  "attachmentCount": 2,
+  "attachmentNames": "report.xlsx; data.csv",
+  "bodyLength": 1520,
+  "collectionMode": "outlook"
+}
+```
+
+### Heartbeat `smtp_connection` (SMTP mode)
+```json
+{
+  "signalType": "smtp_connection",
+  "remoteAddress": "74.125.205.108",
+  "remotePort": 587,
+  "processId": 12340,
+  "processName": "OUTLOOK",
+  "collectionMode": "smtp"
+}
+```
+
+### Incident
+```json
+{
+  "ruleId": "block-external-attachments",
+  "action": "block",
+  "severity": "high",
+  "signalType": "email_outbound",
+  "subject": "<sha256>",
+  "attachmentCount": 2,
+  "enforced": true
+}
+```
+
+## Приватность
+
+- Тема и получатели записываются как SHA256-хеш (не открытый текст).
+- Тело письма не читается и не хранится — записывается только длина.
+- Имена вложений записываются открытым текстом (для DLP-анализа).
+
+## Интеграция в ensemble
+
+Добавьте в `launch-watchers.ps1` или Task Scheduler:
+
+```powershell
+Start-Process powershell.exe -ArgumentList '-ExecutionPolicy Bypass -File "C:\ProgramData\ActivityWatch\email-outbound-collector.ps1"' -WindowStyle Hidden
+```
+
+## Требования
+
+- **Outlook mode**: Microsoft Outlook установлен и настроен для текущего пользователя.
+- **SMTP mode**: Не требует дополнительного ПО. Работает на уровне TCP-соединений.
+- **Enforcement (block)**: Outlook mode — требует доступ к COM объекту Outlook.