Справочник API — обзор¶
Umbryx предоставляет JSON/HTTP API (~640 эндпоинтов в ~90 роутерах) плюс один WebSocket. Эта страница описывает общую механику; далее — списки эндпоинтов по областям. Всё ниже сверено с текущей реализацией.
Базовый URL и версии¶
- Базовый путь:
/api./api/v1/*прозрачно переписывается в/api/*middleware — работают обе формы - Интерактивная документация: выключена по умолчанию; включается
ENABLE_API_DOCS=true(/docs,/redoc,/openapi.json)
Аутентификация¶
Все пути /api/* требуют аутентификации, кроме небольшого
публичного набора (health, auth login/setup/status/refresh/mfa, флоу
OIDC, вебхуки, workstation/service-инжест — каждый защищён своим
механизмом).
Принимаемые учётные данные:
Authorization: Bearer <access-token>(JWT, HS256)- Session cookie
rt_auth(httpOnly — то, что использует SPA) ?token=<stream-token>— принимается только на двух стриминговых эндпоинтах (вывод задач, AI-чат); короткоживущий (≤120 с), blacklist при logout, ограничен по методу
Невалидный/истёкший → 401. Глобальная роль viewer → 403 на
не-GET.
Авторизация¶
require_admin— платформенный администратор- Проектные эндпоинты проверяют членство + строку права через
check_pid_access: не-участник получает404(существование не раскрывается), участник без права —403 - Строки прав и 11 ролей: Контроль доступа
Соглашения¶
- Пагинация: query-параметры
limit+offset(потолки различаются, максимум 2000); общее количество — в заголовке ответаX-Total-Count - Ошибки: единая форма —
json {"code": "...", "message": "...", "detail": "...", "details": [...]}; ошибки валидации —422сcode: "validation_failed" - ROE-гейт: цель вне scope →
403 roe_violation; активность, требующая подтверждения →202 roe_approval_required - Лицензионный гейт (EE): мутации в wind-down →
402
Стриминг¶
- Вывод задач:
GET /api/projects/{pid}/jobs/{job_id}/output-stream(SSE) - AI-чат:
POST /api/projects/{pid}/ai/chats/{cid}/stream(SSE) - Файлы (отчёты, экспорты): стриминговые ответы с
Content-Disposition
WebSocket: ws://<host>/ws/{pid} — аутентификация по session cookie,
лимиты соединений на пользователя, фильтрация по правам получателя с
маскированием секретных полей.
Примеры (из тестового набора)¶
# логин — устанавливает cookie rt_auth
curl -c jar -X POST http://localhost:3000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"<password>"}'
# → {"user":{"id":"u...","username":"admin","role":"platform_admin",...}}
# создать проект (создатель становится владельцем)
curl -b jar -X POST http://localhost:3000/api/projects \
-H 'Content-Type: application/json' \
-d '{"name":"Engagement","added":"2026-10-09T00:00:00Z","status":"active"}'
# → 201 {"id":"p...","name":"Engagement",...}
# список хостов (с пагинацией)
curl -b jar 'http://localhost:3000/api/hosts?pid=p...&limit=500&offset=0'
# → 200, X-Total-Count: <n>, [ {...host...} ]
# раскрыть секрет учётной записи (требует credentials.read_secret; аудируется)
curl -b jar http://localhost:3000/api/creds/crd.../secret
# → {"secret":"...","ttl":30}
Группы эндпоинтов¶
| Группа | Префикс | Основное | Издание |
|---|---|---|---|
| Auth и MFA | /api/auth |
login, setup, ротация refresh, MFA, stream-токены | оба |
| OIDC | /api/auth/oidc, /api/orgs/{id}/oidc-providers, /api/system/oidc-providers |
SSO-флоу + CRUD провайдеров | оба (по плану) |
| Пользователи/админ | /api/admin |
CRUD пользователей, исходящий прокси | оба |
| Проекты и участники | /api/projects |
CRUD, участники, приглашения, команды, передача владения, purge | оба |
| Организации | /api/orgs |
org, участники, команды | оба |
| Хосты и активы | /api/hosts, /api/networks, /api/host-activities |
CRUD, bulk, risk scores, burn | оба |
| Креды | /api/creds, /api/projects/{pid}/secrets |
CRUD, reveal, vault | оба |
| Findings и задачи | /api/findings, /api/tasks… |
CRUD, кандидаты, коллекции | оба |
| Заметки/loot/scope/домены | /api/notes, /api/loots, /api/scopes, /api/domains |
CRUD + вложения/загрузки | оба |
| ROE | /api/projects/{pid}/roe |
чтение/сохранение | оба |
| Сканы и watch | /api/projects/{pid}/scans, .../watch |
nmap/nuclei/cme/httpx/ffuf/donpapi; surface watches | оба |
| Jobs | /api/projects/{pid}/jobs |
список/cancel/retry/approve, SSE-стрим, артефакты; command/output редактируются без credentials.read_secret; stream-токены — только на стриминговых эндпоинтах |
оба |
| Bulk и пивоты | /api/projects/{pid}/bulk-exec, .../pivots |
массовое исполнение, валидация учётных данных/матрица, туннели | оба |
| C2 | /api/c2 |
интеграции, сессии, исполнение, sync, BOF | оба |
| C2 Ops | /api/infra-v2/c2 |
listener, генерация полезной нагрузки | оба (core-роутер) |
| Плейбуки и автоматизации | /api/playbooks, /api/projects/{pid}/automations, /api/scheduled-playbooks |
CRUD, прогоны, packs, бандлы | оба |
| KB/шаблоны/MITRE | /api/kb, /api/finding-templates, /api/snippets, /api/projects/{pid}/mitre|purple |
знания + покрытие | оба |
| Timeline и аудит | /api/timeline, /api/audit, /api/admin/audit |
события, undo, verify | оба |
| Отчёты и экспорт | /api/projects/{pid}/report/*, /api/export/*, CSV, импорты |
PDF/HTML/MD, ZIP, Nessus/Burp/BloodHound | оба |
| Карта сети и топология | /api/projects/{pid}/network, .../topology |
nodes/links/regions, preview/apply, smart build | оба |
| Attack paths | /api/attack-paths, эндпоинты редактора |
пути, шаги, nodes/edges/branches, версии | оба |
| Поиск | /api/search, /api/saved-searches |
поиск по сущностям | оба |
| Модули и плагины | /api/modules, /api/plugins, /api/admin/modules |
тумблеры, объекты, upload/sign | оба |
| Workstations | /api/workstations |
CRUD, пул, Provisioning (EE), executor, actions | оба (provisioning — EE) |
| Sync и вебхуки | /api/sync, /api/webhooks/{token} |
sync между экземплярами, инжест C2 | оба |
| AI | /api/ai, /api/projects/{pid}/ai |
провайдеры, чаты, SSE, аудит | оба |
| Файрволы, деконфликтация, уведомления | по областям | импорт конфигов, claims, конфигурация уведомлений | оба |
| Закрытие | /api/projects/{pid}/close|archive|decommission-report |
бэкенд Closure Wizard | оба |
| Система | /api/system |
health, логи, метрики, HA, edition, лицензия | оба |
| Platform Ops | /api/infra-v2 |
провайдеры, стеки, сервисы, links, учётные данные, VPN | EE |
| DNS / SSL | /api/infra-v2/dns, /api/infra-v2/ssl |
зоны, записи, ANetExec-сертификаты | EE |
| Управляемые экземпляры (managed instances) | /api/instance-templates, /api/managed-instances, /api/instance-credentials |
k8s-пул, claim/release | EE |