Роль: backend-архитектор и автор API-спецификаций
Задача:
Подготовь полный Markdown-документ для API эскалации рисков безопасности. Документ должен быть одновременно машиночитаемым и удобным для инженерных и security-команд.
Формат результата:
- Верни один завершённый Markdown-документ и ничего вне него.
- В начале включи полную спецификацию OpenAPI 3.0 или 3.1 в виде YAML-блока, пригодного для импорта в Swagger, Redoc и аналогичные инструменты.
- После YAML добавь человекочитаемую документацию на русском языке с примерами `curl`, примерами JSON-запросов и ответов, а также процессами управления уязвимостями.
Что обязательно раскрыть:
1. `Общее`
- Название API, версия, цель, базовый URL, схема версионирования.
- Bearer Token как обязательный механизм авторизации; опционально mutual TLS и RBAC.
- Header, claims, rate limits, idempotency, retry и backoff.
2. `Endpoints`
- `POST /v1/escalations`
- `GET /v1/escalations`
- `GET /v1/escalations/{escalationId}`
- `PATCH /v1/escalations/{escalationId}`
- `POST /v1/escalations/{escalationId}/acknowledge`
- `POST /v1/escalations/{escalationId}/close`
- `POST /v1/escalations/{escalationId}/comments`
- `POST /v1/escalations/calculate-score`
- `POST /v1/webhooks`
- `DELETE /v1/webhooks/{id}`
Для каждого endpoint укажи путь, метод, headers, query и path параметры, JSON Schema тел, успешные и ошибочные ответы, HTTP-коды, error codes, `ETag` или `If-Match` и `Idempotency-Key`.
3. `Payloads`
- Полные JSON Schema для `Escalation`, `Comment`, `Evidence`, `WebhookSubscription`, `ErrorResponse`.
- Примеры валидных и невалидных запросов.
4. `Обработка ошибок`
- Унифицированная схема ошибок и поведение клиента.
5. `Итоговые оценки риска`
- Алгоритм risk scoring с факторами CVSS, criticality, exploitability, business impact, age и prior incidents.
- Формула или псевдокод, пороги `Low`, `Medium`, `High`, `Critical`, три примера расчёта и поля ответа `finalScore`, `severityLabel`, `scoreBreakdown`, `recommendedAction`, `escalationLevel`, `nextReviewDate`.
6. `Логика эскалации и процедуры`
- Полный процесс от triage до закрытия, правила SLA, уведомления, ручные подтверждения, пересмотр и webhook payloads.
7. `Безопасность и соответствие`
- Хранение доказательств, шифрование, audit logs, сопоставление с NIST, CIS и ISO27001.
8. `Дополнительно`
- Примеры `curl`, минимум 5 тестовых кейсов, правила миграции версий API и набор эксплуатационных метрик.
Ограничения:
- YAML OpenAPI должен быть структурно валидным и полным по ключевым элементам.
- JSON Schema делай точной и достаточной для валидации.
- Не задавай уточняющих вопросов и не выдавай альтернативные версии.
