AWatch-rus/docs/WINDOWS_RUST_AGENT_WORKTIME_RU.md

Windows Rust Agent Worktime/RDP

Назначение

awatch-agent-rs заменяет PowerShell-сборщик worktime-session-collector.ps1 для учета Windows/RDP-сессий.

Цель перехода:

• меньше зависимость от PowerShell и локали Windows;
• стабильный сбор RDP/local/disconnected сессий через WinAPI WTS;
• единый TelemetryRecord для портала, отчетов, KPI активности и UEBA;
• сохранение PowerShell-сценария только как legacy fallback.

Агент не собирает содержимое окон, документов, ввод с клавиатуры или снимки экрана. Для worktime/session path используются только:

• username;
• session_id;
• session_type;
• active;
• started_at, если платформа отдаст это поле;
• remote_addr, если платформа отдаст это поле.

Конфигурация агента

Файл Windows:

C:\ProgramData\AWatch-rus\agent\awatch-agent.toml

Минимальный пример:

server_url = "https://<GATEWAY_HOST>/api/telemetry"
api_key = "CHANGE_ME"
collect_interval_seconds = 30
role = "workstation"

enable_processes = true
enable_network = true
enable_security_events = true
enable_workforce_activity = true

spool_dir = "C:\\ProgramData\\AWatch-rus\\agent\\spool"
timeout_seconds = 10
retry_attempts = 3

aw_api_base = "http://<AW_SERVER_HOST>:5600/api/0"
aw_worktime_enabled = true

По умолчанию в example-конфиге aw_worktime_enabled=false. Включайте его только после настройки aw_api_base, spool-директории и rollback-процедуры.

Источники сессий

Агент пишет диагностическое поле session_source:

• wts_api - основной промышленный путь через WinAPI WTS;
• quser_utf16 - fallback через query user/quser в UTF-16;
• quser_lossy - fallback через обычный console output;
• env_sessionname_fallback - fallback по переменной SESSIONNAME;
• local_fallback - последняя локальная заглушка, когда системные источники не вернули сессии.

В TelemetryRecord.diagnostics дополнительно пишутся:

• sessions_collected_total;
• rdp_sessions_total;
• active_sessions_total;
• collector_source;
• collector_error.

Достоверность данных агента

Портал и отчеты поднимают diagnostics в два блока:

• agent_quality - обратная совместимость и технические счетчики;
• agent_quality_explain - управленческий вывод о доверии к KPI.

Статусы agent_quality:

• ok - основной источник wts_api, ошибки коллектора нет;
• fallback - данные получены через quser_utf16, quser_lossy или env_sessionname_fallback;
• degraded - используется local_fallback или есть некритичная ошибка коллектора;
• error - есть критичная ошибка коллектора, например отказ доступа, некорректный обязательный payload или ошибка парсинга;
• unknown - старый агент или payload без diagnostics.

Статусы agent_quality_explain:

• OK - данные приняты в KPI;
• WARNING - данные собраны резервным способом, допустимы как оперативный ориентир, но требуют проверки для доказательной базы;
• DEGRADED - данные не приняты в KPI;
• UNKNOWN - агент не передал диагностику качества данных.

local_fallback считается диагностическим сигналом, а не доказательством активности. События worktime, опубликованные из local_fallback, получают active=false, ignoredForKpi=true и не должны увеличивать KPI сотрудника или подтверждать RDP-активность. В портале для этого режима выводится текст: Диагностический режим, данные не засчитываются в KPI.

Портал также строит agent_quality_history за 7 дней из telemetry JSONL: последняя запись каждого дня превращается в статус доверия к KPI. Если за неделю меньше 5 дней OK, недельный KPI считается требующим валидации.

Портал строит agent_quality_nodes по последней записи каждого рабочего места за период. Ключ узла выбирается так: hostname, затем machine_id, затем unknown. Это позволяет не ломать старые telemetry payload и одновременно показывать руководителю, какие рабочие станции портят достоверность KPI. Источник local_fallback в этой сводке помечается как диагностический и не подтверждает KPI узла.

На основе agent_quality_nodes портал также считает agent_coverage_sla: покрытие ожидаемого парка рабочих мест по файлу expected nodes. Свежий local_fallback может подтверждать наличие телеметрии, но не подтверждает KPI узла и снижает coverage_pct.

PowerShell Legacy Fallback

В deployment-config.json используется блок:

{
  "collectors": {
    "worktimeSessionEnabled": true,
    "worktimeSessionMode": "rust_primary",
    "worktimeLegacyFallbackEnabled": true
  }
}

Режимы:

• powershell_primary - старое поведение, PowerShell collector основной;
• rust_primary - Rust agent основной, PowerShell запускается только как legacy fallback при недоступности Rust agent или stale worktime bucket.

Для полного отключения PowerShell worktime fallback:

{
  "collectors": {
    "worktimeSessionEnabled": false,
    "worktimeSessionMode": "rust_primary",
    "worktimeLegacyFallbackEnabled": false
  }
}

Проверка

Проверить локальный JSON агента:

C:\ProgramData\AWatch-rus\agent\awatch-agent-rs.exe `
  --config C:\ProgramData\AWatch-rus\agent\awatch-agent.toml `
  --once --print-json

Ожидаемые признаки:

• active_sessions содержит local/RDP/disconnected сессии;
• rdp_sessions содержит активные RDP-сессии;
• session_source равен wts_api в штатном режиме;
• diagnostics.rdp_sessions_total соответствует числу RDP-сессий.

Проверить, что legacy PowerShell не запущен:

Get-CimInstance Win32_Process |
  Where-Object {
    $_.Name -match 'powershell|pwsh' -and
    $_.CommandLine -match 'worktime-session-collector.ps1'
  }

Проверить ActivityWatch bucket:

curl "http://<AW_SERVER_HOST>:5600/api/0/buckets/aw-worktime-sessions_<HOST>/events?limit=5"

В свежих событиях должно быть:

{
  "source": "awatch-agent-rs",
  "sessionSource": "wts_api",
  "collectorSource": "wts_api",
  "ignoredForKpi": false
}

Spool и восстановление

Если aw_worktime_enabled=true, но aw_api_base временно недоступен, агент кладет worktime-записи в:

<spool_dir>\aw-worktime

При следующем успешном цикле агент пытается выгрузить накопленный spool с тем же retry_attempts.

Rollback на PowerShell

1. Остановить Rust Scheduled Task или сервис агента.
2. В deployment-config.json установить:

{
  "collectors": {
    "worktimeSessionEnabled": true,
    "worktimeSessionMode": "powershell_primary",
    "worktimeLegacyFallbackEnabled": true
  }
}

3. Перезапустить guard/recovery AWatch-rus.
4. Проверить, что worktime-session-collector.ps1 снова пишет события в aw-worktime-sessions_<HOST>.

PowerShell collector не удаляется из поставки именно для такого rollback.