API v1 и протокол ROY

Назначение документа

Документ описывает прикладной HTTP API СОПКА.Рой версии 1: публичные проверки состояния, API агента, workspace API и служебные JSON-интерфейсы веб-консоли. Owner API в этот документ намеренно не включён, потому что он относится к отдельному административному контуру владельца инсталляции и не должен использоваться как интеграционный контракт агента или рабочей области.

Канонический внешний базовый путь сервера - /roy. Если reverse proxy публикует приложение без префикса, из приведённых URL удаляется первая часть /roy. Все временные метки передаются в UTC в формате ISO 8601.

Версии текущего контракта

Версия программы агента не обязана совпадать с версией protocol/API. При несовместимой версии protocol_version или api_version сервер отвечает кодом 426 и возвращает поддерживаемые версии. Совместимые добавления полей выполняются в рамках v1.

Аутентификация и подпись

Подпись строится по строкам: версия подписи ROY1 или DLP1, HTTP-метод, полный путь с query string, timestamp, nonce, sequence и SHA-256 тела. Сервер принимает timestamp только в небольшом временном окне, хранит nonce и требует монотонный sequence для каждого устройства.

ROY1
POST
/roy/api/v1/agent/heartbeat
2026-08-27T08:10:15Z
base64-or-uuid-nonce
42
0f343b0931126a20f133d67c2b018a3b...

Жизненный цикл агента

1. Установщик проверяет доступность сервера через GET /roy/api/v1/agent/health.
2. До регистрации установщик может получить пакет агента по регистрационному ключу.
3. Агент формирует локальный UUID, пару ключей подписи и вызывает POST /roy/api/v1/agent/register.
4. После регистрации сервер связывает client ID, workspace, public key и device token.
5. Агент отправляет heartbeat, получает команды, update offer и policy bundle при изменении версии.
6. События, снимки экрана, результаты поиска файлов и статусы команд отправляются отдельными endpoint.
7. Realtime-доставка команд выполняется через Socket.IO, а HTTP heartbeat остаётся резервным каналом.

Публичные проверки состояния

curl -s https://dlp.example.local/roy/api/v1/agent/health

{
  "status": "ok",
  "server_time": "2026-08-27T08:10:15Z",
  "base_path": "/roy",
  "agent_version": "1.0.0"
}

Agent API v1

Регистрация агента

Регистрация выполняется до появления Bearer-токена. Клиент передаёт workspace, локальный идентификатор, сведения об ОС, версии протокола/API, список возможностей и публичный ключ для дальнейшей подписи запросов.

POST /roy/api/v1/agent/register
X-COPKA-ROY-Registration-Key: rgk_...
Content-Type: application/json

{
  "workspace_id": "01a04400-0000-7000-8000-000000000001",
  "client_uuid": "01a04411-2f4a-7b9e-9a31-2fb6b17e7810",
  "hostname": "WIN-OPS-042",
  "platform": "Windows 11 Pro",
  "os_family": "windows",
  "agent_version": "1.0.0",
  "protocol_version": 1,
  "api_version": 1,
  "capabilities": {
    "file_events": true,
    "clipboard": true,
    "screenshots": true,
    "file_search": true
  },
  "key_id": "copka_key_2b6f...",
  "public_key": "base64-ed25519-public-key"
}

{
  "status": "ok",
  "client_id": "01a04411-2f4a-7b9e-9a31-2fb6b17e7810",
  "device_token": "returned-on-registration",
  "protocol_accepted": true,
  "api_accepted": true,
  "protocol_version": 1,
  "api_version": 1,
  "policy_schema_version": 1
}

Heartbeat и команды

Heartbeat сообщает серверу, что агент online, обновляет метаданные клиента и сравнивает локальную версию политики с серверной. Если realtime-канал недоступен, сервер возвращает до нескольких ожидающих команд в поле commands.

POST /roy/api/v1/agent/heartbeat
Authorization: Bearer device-token
X-COPKA-ROY-Client-ID: 01a04411-2f4a-7b9e-9a31-2fb6b17e7810

{
  "hostname": "WIN-OPS-042",
  "platform": "Windows 11 Pro",
  "ip_address": "10.10.12.42",
  "agent_version": "1.0.0",
  "protocol_version": 1,
  "api_version": 1,
  "policy_uuid": "01a04422-9d3a-78f4-9e2c-990000000001",
  "policy_version": 17,
  "want_policy": false,
  "supports_interactive_monitoring": true
}

{
  "status": "ok",
  "client_id": "01a04411-2f4a-7b9e-9a31-2fb6b17e7810",
  "server_policy_version": 18,
  "policy_changed": true,
  "commands": [
    {
      "id": "01a04433-6f8d-7c62-9b13-2ed4bda60001",
      "command": "request_screenshot",
      "payload": {"reason": "manual"},
      "transport": "heartbeat"
    }
  ]
}

После обработки команды агент вызывает ACK endpoint. Статус может быть delivered, running, completed, failed, unsupported, expired или cancelled.

POST /roy/api/v1/agent/commands/01a04433-6f8d-7c62-9b13-2ed4bda60001/ack

{
  "status": "completed",
  "transport": "heartbeat",
  "result": {
    "message": "screenshot uploaded",
    "artifact_id": "01a04444-62d6-7560-9c2e-120000000001"
  }
}

Политики

Policy bundle возвращается по запросу /policies/<client_id> или внутри heartbeat, если клиент явно указал want_policy либо сервер обнаружил изменение версии. Сервер дополнительно проверяет, что client ID в пути совпадает с устройством из Bearer-токена.

GET /roy/api/v1/agent/policies/01a04411-2f4a-7b9e-9a31-2fb6b17e7810

{
  "schema_version": 1,
  "policy_version": 18,
  "policy_uuid": "01a04455-1405-730f-8a24-750000000001",
  "target_os_family": "windows",
  "policies": [
    {
      "id": "usb-control",
      "name": "USB контроль",
      "enabled": true,
      "priority": 100,
      "rules": []
    }
  ],
  "signature": "base64-ed25519-signature"
}

События агента

Пакетная загрузка событий используется для основной телеметрии. Сервер нормализует типы событий, назначает UUIDv7 при отсутствии event_uuid, применяет лимиты, создаёт инциденты по результату политики и игнорирует дубли при повторной отправке того же события.

POST /roy/api/v1/agent/logs

{
  "hostname": "WIN-OPS-042",
  "platform": "Windows 11 Pro",
  "agent_version": "1.0.0",
  "protocol_version": 1,
  "api_version": 1,
  "logs": [
    {
      "event_uuid": "01a04466-9871-706a-8a9d-8d0000000001",
      "source_table": "agent",
      "source_id": "clipboard:42",
      "event_type": "clipboard_event",
      "timestamp": "2026-08-27T08:12:00Z",
      "severity": "medium",
      "details": "clipboard text matched policy",
      "payload": {
        "channel": "clipboard",
        "policy_result": "deny",
        "matched_policy_name": "Персональные данные"
      }
    }
  ]
}

{
  "status": "ok",
  "received": 1,
  "inserted": 1,
  "duplicates": 0,
  "grouped": 0
}

Снимки экрана

Endpoint принимает multipart/form-data. Файл должен быть PNG или JPEG, сервер проверяет изображение, перекодирует его в PNG, сохраняет в объектное хранилище и применяет срок хранения рабочей области.

POST /roy/api/v1/agent/screenshot
Content-Type: multipart/form-data

file=@screen.png
timestamp=2026-08-27T08:13:00Z

Поиск файлов

Агент передаёт события поиска файлов в том же event model. Для простых результатов допускается массив results, который сервер преобразует в события file_search_result. Предпросмотр и загрузка файла выполняются через отдельные session endpoint, созданные веб-консолью.

POST /roy/api/v1/agent/file_search/results

{
  "events": [
    {
      "source_table": "file_search",
      "source_id": "run-42:path-hash",
      "event_type": "file_search_result",
      "timestamp": "2026-08-27T08:14:00Z",
      "severity": "low",
      "details": "matched *.xlsx",
      "payload": {
        "run_id": 42,
        "file_path": "C:/Users/user/Documents/report.xlsx",
        "size_bytes": 48120,
        "sha256": "..."
      }
    }
  ]
}

Обновление агента

Информация о legacy ZIP-релизе доступна через /version. Основное автообновление выполняется через heartbeat: если для клиента создано задание обновления или включён режим auto, сервер возвращает update offer с installer_type, grant ID, download key, целевой версией и сроком действия. Для Windows основным типом является exe: агент скачивает CopkaRoySetup.exe, проверяет SHA-256 и запускает его с /quiet /auto-update. ZIP-путь с CopkaRoyUpdater.exe остаётся legacy fallback.

{
  "agent_update": {
    "available": true,
    "installer_type": "exe",
    "grant_id": "01a04477-412e-74da-93b5-4c0000000001",
    "download_method": "POST",
    "download_url": "https://dlp.example.local/roy/api/v1/agent/update/download/01a04477-412e-74da-93b5-4c0000000001",
    "download_key": "dlp_upd_...",
    "download_after_seconds": 42,
    "expires_at": "2026-08-27T08:25:15Z",
    "latest_version": "1.0.1",
    "sha256": "..."
  }
}

POST /roy/api/v1/agent/update/status

{
  "grant_id": "01a04477-412e-74da-93b5-4c0000000001",
  "status": "updated"
}

Remote shell events

Remote shell использует зашифрованный обмен. В API агента передаются только технические события с ciphertext и sequence; расшифровка выполняется на стороне браузера оператора и агента. Поддерживаемые события: remote_shell_answer, remote_shell_output, remote_shell_status.

POST /roy/api/v1/agent/remote_shell/events

{
  "event_name": "remote_shell_output",
  "payload": {
    "session_id": "01a04488-0189-71c8-8e77-260000000001",
    "algorithm": "ecdh-p256-hkdf-sha256-aes-256-gcm",
    "sequence": 7,
    "nonce": "base64-nonce",
    "ciphertext": "base64-ciphertext"
  }
}

Socket.IO

Socket.IO публикуется по ресурсу /roy/socket.io. Канал используется для быстрой доставки команд, live screen и интерактивных событий. Команды не считаются выполненными до ACK: если websocket недоступен или подтверждение не пришло, сервер оставляет команду в очереди и отдаёт её через heartbeat fallback.

Workspace API

Эти endpoint предназначены для пользователей веб-консоли и требуют обычной аутентифицированной сессии с доступом к рабочей области. Они не заменяют Agent API и не должны вызываться установленным агентом.

Служебный API веб-консоли

Маршруты /roy/internal/api/... используются страницами веб-интерфейса. Это не внешний стабильный контракт для сторонних систем: формат может меняться вместе с UI, а доступ проверяется через пользовательскую сессию, роль и текущую рабочую область.

Коды ответов и ошибки

Рекомендации по применению

• Агент должен считать registration key и device token секретами и не выводить их в обычные логи.
• Все рабочие запросы выполняются по HTTPS; прямой HTTP допустим только внутри доверенного reverse proxy контура.
• При сетевых сбоях агент повторяет отправку событий с тем же event_uuid, чтобы сервер мог убрать дубли.
• Heartbeat должен оставаться лёгким: крупные данные передаются через специализированные endpoint.