197 lines
4.4 KiB
Markdown
197 lines
4.4 KiB
Markdown
# AWatch-rus Rust Agent Baseline
|
||
|
||
Документ описывает промышленный каркас будущего Rust Agent. Это baseline
|
||
агента, а не реализация мониторинга пользователя.
|
||
|
||
## Архитектура
|
||
|
||
Crate:
|
||
|
||
```text
|
||
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
|
||
|
||
Единый контракт:
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"type": "heartbeat",
|
||
"payload": {
|
||
"agent_version": "0.1.0",
|
||
"platform": "windows",
|
||
"status": "online"
|
||
}
|
||
}
|
||
```
|
||
|
||
Heartbeat не содержит hostname, список процессов, окна, clipboard, screenshots,
|
||
пакеты сети или содержимое документов.
|
||
|
||
## Local Spool
|
||
|
||
Очередь:
|
||
|
||
```text
|
||
spool/
|
||
├── pending/
|
||
└── dead-letter/
|
||
```
|
||
|
||
Поведение:
|
||
|
||
- `enqueue` пишет envelope атомарно через временный файл и rename;
|
||
- успешная отправка удаляет запись из `pending`;
|
||
- временная ошибка увеличивает `retry_count` и сохраняет запись;
|
||
- превышение `retry_max_attempts` переносит запись в `dead-letter`;
|
||
- поврежденный JSON переносится в `dead-letter` с reason-файлом.
|
||
|
||
## Retry
|
||
|
||
Retry использует bounded exponential backoff:
|
||
|
||
```text
|
||
base_backoff_ms * 2^attempt
|
||
```
|
||
|
||
Число попыток ограничено `retry_max_attempts`. Запись не удаляется из spool без
|
||
успешной отправки.
|
||
|
||
## Health
|
||
|
||
Локальный endpoint:
|
||
|
||
```text
|
||
GET /healthz
|
||
```
|
||
|
||
Ответ:
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```text
|
||
GET /metrics
|
||
```
|
||
|
||
CLI-проверка:
|
||
|
||
```bash
|
||
awatch-agent --metrics
|
||
```
|
||
|
||
## Structured Logging
|
||
|
||
JSON log line содержит:
|
||
|
||
- `timestamp`;
|
||
- `level`;
|
||
- `agent_id`;
|
||
- `component`;
|
||
- `message`.
|
||
|
||
Пример:
|
||
|
||
```json
|
||
{
|
||
"timestamp": "2026-06-07T00:00:00Z",
|
||
"level": "INFO",
|
||
"agent_id": "00000000-0000-5000-8000-000000000001",
|
||
"component": "heartbeat",
|
||
"message": "heartbeat envelope queued"
|
||
}
|
||
```
|
||
|
||
## CLI
|
||
|
||
Сформировать heartbeat envelope без отправки:
|
||
|
||
```bash
|
||
awatch-agent --print-envelope
|
||
```
|
||
|
||
Поставить heartbeat в локальную очередь:
|
||
|
||
```bash
|
||
awatch-agent --enqueue-heartbeat
|
||
```
|
||
|
||
Выгрузить spool:
|
||
|
||
```bash
|
||
awatch-agent --flush-spool
|
||
```
|
||
|
||
Запустить локальный health endpoint:
|
||
|
||
```bash
|
||
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-поддержка конкретной ОС требует отдельной валидации.
|