AWatch-rus/docs/RUST_AGENT_BASELINE_RU.md

AWatch-rus Rust Agent Baseline

Документ описывает промышленный каркас будущего Rust Agent. Это baseline агента, а не реализация мониторинга пользователя.

Архитектура

Crate:

adk-rust/crates/awatch-agent

Слои:

• config - загрузка конфигурации из файла и безопасные значения по умолчанию;
• envelope - единый telemetry envelope и heartbeat contract;
• spool - локальная очередь spool/pending и spool/dead-letter;
• transport - отправка envelope и retry/backoff;
• health - локальные GET /healthz и GET /metrics;
• logging - structured JSON logging;
• metrics - Prometheus text format.

Каркас не собирает активность пользователя и не реализует DLP/EDR-функции.

Telemetry Envelope

Единый контракт:

{
  "agent_id": "00000000-0000-5000-8000-000000000001",
  "host_id": "00000000-0000-5000-8000-000000000002",
  "platform": "windows",
  "timestamp": "2026-06-07T00:00:00Z",
  "records": []
}

records остается пустым или содержит только служебные записи baseline, пока отдельные collectors не прошли acceptance gates.

Heartbeat

Heartbeat записывается как служебный record:

{
  "type": "heartbeat",
  "payload": {
    "agent_version": "0.1.0",
    "platform": "windows",
    "status": "online"
  }
}

Heartbeat не содержит hostname, список процессов, окна, clipboard, screenshots, пакеты сети или содержимое документов.

Local Spool

Очередь:

spool/
├── pending/
└── dead-letter/

Поведение:

• enqueue пишет envelope атомарно через временный файл и rename;
• успешная отправка удаляет запись из pending;
• временная ошибка увеличивает retry_count и сохраняет запись;
• превышение retry_max_attempts переносит запись в dead-letter;
• поврежденный JSON переносится в dead-letter с reason-файлом.

Retry

Retry использует bounded exponential backoff:

base_backoff_ms * 2^attempt

Число попыток ограничено retry_max_attempts. Запись не удаляется из spool без успешной отправки.

Health

Локальный endpoint:

GET /healthz

Ответ:

{
  "ok": true,
  "status": "online",
  "agent_version": "0.1.0"
}

Endpoint предназначен для локального service/task health-check и не должен публиковаться наружу без отдельного решения.

Metrics

Prometheus metrics:

• awatch_agent_queued_records;
• awatch_agent_retry_count;
• awatch_agent_heartbeat_sent;
• awatch_agent_spool_size.

Локальный endpoint:

GET /metrics

CLI-проверка:

awatch-agent --metrics

Structured Logging

JSON log line содержит:

• timestamp;
• level;
• agent_id;
• component;
• message.

Пример:

{
  "timestamp": "2026-06-07T00:00:00Z",
  "level": "INFO",
  "agent_id": "00000000-0000-5000-8000-000000000001",
  "component": "heartbeat",
  "message": "heartbeat envelope queued"
}

CLI

Сформировать heartbeat envelope без отправки:

awatch-agent --print-envelope

Поставить heartbeat в локальную очередь:

awatch-agent --enqueue-heartbeat

Выгрузить spool:

awatch-agent --flush-spool

Запустить локальный health endpoint:

awatch-agent --healthz

Ограничения

Запрещено и не реализовано:

• keylogger;
• screenshot capture;
• clipboard capture;
• packet interception;
• process injection;
• kernel drivers;
• EDR functionality;
• DLP functionality;
• ML;
• LLM.

Platform claims остаются ограниченными: baseline-каркас компилируется как Rust crate, но production-поддержка конкретной ОС требует отдельной валидации.