docs(wiki): document collector and grafana hardening

2026-05-28 11:05:59 +03:00
parent cc9e4a0669
commit 79eff54774
8 changed files with 453 additions and 0 deletions
@@ -0,0 +1,68 @@
+# Windows Collector Suite
+
+## 3. Windows collectors
+
+Коммит `cc9e4a0` существенно усилил Windows/RDP контур, особенно `windows/worktime-session-collector.ps1` и общую recovery библиотеку `windows/ActivityWatch.Windows.Common.psm1`.
+
+## Worktime Session Collector
+
+`worktime-session-collector.ps1` получил крупное расширение: новые helper-функции для session/process state, отдельную публикацию session events и более строгую нормализацию buckets.
+
+Ключевые изменения:
+
+- `Ensure-Bucket` теперь принимает `ClientName` и `BucketType`, а не жестко прошитые значения;
+- добавлена поддержка bucket `aw-session-events_<host>`;
+- collector публикует logon/session state и process transitions, если это включено конфигурацией;
+- session records лучше отделяют active/disconnected/unknown состояния;
+- downstream server-side bridge получает более качественные `sessionId`, `username`, `sessionName` и activity markers.
+
+## Process events
+
+Новый флаг:
+
+```yaml
+aw_windows_process_events_enabled: true
+```
+
+Он попадает в deployment config как:
+
+```json
+sessionEvents.processEventsEnabled
+```
+
+Когда флаг включен, Windows collector публикует process-level изменения в session events bucket. Это дает server-side слою больше контекста для active session detection и forensic review.
+
+## Localized Administrator
+
+Новый параметр:
+
+```yaml
+aw_windows_builtin_administrator_name: "Администратор"
+```
+
+Назначение: явно фиксировать локализованное имя встроенной учетной записи Administrator с SID `*-500`.
+
+Для текущего Windows host `SHARKON2025` task name должен строиться как:
+
+```text
+ActivityWatch Launch [SHARKON2025_Администратор]
+```
+
+Если task по `SHARKON2025_Administrator` не найден, recovery/deploy path обязан пробовать кириллическое имя `Администратор`. Это зафиксировано через:
+
+- default vars в `ansible/deploy_aw_windows.yml`;
+- `ansible/group_vars/aw_windows.yml`;
+- example vars в `ansible/group_vars/windows.example.yml`;
+- env override `AWATCH_RUS_BUILTIN_ADMINISTRATOR_NAME`;
+- fallback в `Get-ActivityWatchBuiltInAdministratorName`.
+
+## Recovery hardening
+
+`ActivityWatch.Windows.Common.psm1` усилил recovery path:
+
+- `Get-ActivityWatchBuiltInAdministratorName` сначала смотрит env override, затем SID-500 lookup, затем host-specific fallback `SHARKON2025 -> Администратор`;
+- `Normalize-ActivityWatchUsers` стабилизирован для pipeline/list cases;
+- удаление scheduled tasks стало устойчивее к частично удаленным task definitions;
+- recovery task может ориентироваться на live interactive session и запускаться в interactive logon context, когда это безопаснее для watcher'ов.
+
+Операционный вывод: для RDP/console telemetry нельзя полагаться на task name с английским `Administrator` на русифицированной Windows. Локализованное имя должно быть частью deploy vars.