Skip to content

api.md

Latest commit

 

History

History
228 lines (183 loc) · 8.21 KB

api.md

File metadata and controls

228 lines (183 loc) · 8.21 KB

API, контракты сервисов и Swagger

Публичный UI API

Браузер обращается к Express UI API по http://localhost:3000/api. Это основной frontend-facing contract.

Health

Method Path Назначение
GET /api/healthz Health check UI API

Templates

Method Path Назначение
GET /api/templates?perimeter=ALL Список policy templates по perimeter
GET /api/templates/:templateId Чтение полного policy template
GET /api/templates/cwe Чтение локального CWE catalog
POST /api/templates/cwe/update Обновление локального CWE catalog
POST /api/templates/summary Сохранение selected template summary для request
POST /api/templates/users Создание user template
DELETE /api/templates/users/:templateId Удаление user template

Поддерживаемые значения perimeter query: INTERNAL, EXTERNAL, BOTH, ALL.

Analyses

Method Path Назначение
POST /api/analyses/run Запустить analysis job
GET /api/analyses/:analysisId/run-status Получить live job status
POST /api/analyses/:analysisId/cancel Запросить отмену
GET /api/analyses/:analysisId/context Получить user input context из final report service
GET /api/analyses/:analysisId/overview Получить analysis overview
GET /api/analyses/:analysisId/findings Получить final findings
GET /api/analyses/:analysisId/attention Получить policy-relevant findings
GET /api/analyses/:analysisId/incomplete Получить findings с отсутствующими обязательными полями
GET /api/analyses/:analysisId/without-cwe Получить findings без CWE mapping

Пример запуска:

{
  "analysisId": "scan-001",
  "templateId": "owasp-web",
  "images": [
    {
      "digest": "nginx@sha256:...",
      "secret": false
    },
    {
      "digest": "api@sha256:...",
      "secret": true
    }
  ]
}

Cache

Method Path Назначение
GET /api/cache/raw Proxy raw Service E cache document
GET /api/cache/vulnerabilities Нормализованная таблица vulnerability cache для UI

Orchestrator API

Orchestrator является внутренним сервисом Docker-сети и не публикуется на host в root compose.

Method Path Назначение
GET /healthz Health check
GET /api/healthz API health check
POST /api/analyses/run Принять job и запустить pipeline
GET /api/analyses/:analysisId/run-status Вернуть in-memory job snapshot
POST /api/analyses/:analysisId/cancel Abort active job, если он ещё выполняется

Job statuses:

  • queued;
  • running;
  • canceling;
  • complete;
  • failed;
  • canceled.

Pipeline stages:

  • queued;
  • preparing;
  • saving_template;
  • readiness;
  • scanning;
  • enriching;
  • finalizing;
  • complete;
  • failed;
  • canceled.

Внутренние service APIs и Swagger

Каждый .NET-сервис отдаёт Swagger UI на опубликованном локальном порту.

Service Swagger URL Комментарий
Service A http://localhost:8081/swagger Templates and CWE catalog
Service C http://localhost:8082/swagger Readiness and Trivy DB metadata
Service D http://localhost:8083/swagger Raw scan and stored raw scan files
Service E http://localhost:8084/swagger CWE mapping, stored mapping files, cache
Service F http://localhost:8085/swagger Read-only final report views

Service A — Templates

Method Path Назначение
GET /api/v1/templates Список template headers с фильтрацией по perimeter
GET /api/v1/templates/{templateId} Чтение full template snapshot
POST /api/v1/templates/users Создание user template
DELETE /api/v1/templates/users/{templateId} Удаление user template
POST /api/v1/templates/summary Сохранение selected template summary в artifacts
GET /api/v1/cwe Список локальных CWE catalog entries
POST /api/v1/cwe/update Принудительное обновление local CWE catalog
GET /health Health check

Запрос template summary:

{
  "request_id": "scan-001",
  "template_id": "owasp-web"
}

Service C — Readiness

Method Path Назначение
POST /api/v1/readiness Запуск readiness checks для request_id
POST /api/v1/trivy-db/update Принудительное обновление Trivy DB
GET /api/v1/trivy-db/metadata Чтение local Trivy DB metadata
GET /health Health check

Запрос readiness:

{
  "request_id": "scan-001"
}

Service D — Raw scan

Method Path Назначение
POST /api/v1/scan Сканировать Docker images и записать raw artifacts
GET /api/v1/scan/{request_id} Прочитать stored scan summary
GET /api/v1/scan/{request_id}/{file} Прочитать stored per-image raw report по SHA-256 file name
DELETE /api/v1/scan/{request_id} Удалить все raw scan artifacts для request
DELETE /api/v1/scan/{request_id}/{file} Удалить один raw per-image file
GET /health Health check

Запрос scan:

{
  "request_id": "scan-001",
  "image-digest": [
    {
      "nginx@sha256:...": {
        "secret": false
      }
    },
    {
      "api@sha256:...": {
        "secret": true
      }
    }
  ]
}

Service E — CWE resolver

Method Path Назначение
POST /api/v1/cwe_mapping Смапить Service D vulnerability IDs на CWE и записать enriched artifacts
GET /api/v1/check/summary/{request_id} Прочитать stored mapping summary
GET /api/v1/check/result/{request_id}/{scan_id}.json Прочитать per-image mapping result
GET /api/v1/check/cache Прочитать aggregated vulnerability cache
GET /api/v1/check/cache/{vuln_id} Прочитать один raw cache entry
DELETE /api/v1/delete/result/{request_id} Удалить все mapping artifacts для request
DELETE /api/v1/delete/result/{request_id}/{scan_id}.json Удалить один mapping result file
POST /api/v1/proxies/check Проверить proxy configuration для resolver providers
GET /health Health check

Запрос CWE mapping:

{
  "request_id": "scan-001"
}

Service F — Final report

Method Path Назначение
GET /api/v1/user-input/{requestId} Вернуть selected template и submitted image context
GET /api/v1/analysis_overview/{requestId} Вернуть per-image totals и policy match counters
GET /api/v1/result/{requestId} Вернуть final findings выше selected severity threshold
GET /api/v1/need_fix/{requestId} Вернуть findings, которые совпали с policy template CWE
GET /api/v1/could_not/{requestId} Вернуть findings с missing required fields
GET /api/v1/without_cwe/{requestId} Вернуть findings без CWE identifiers
GET /health Health check

Поведение ошибок

UI API оборачивает upstream network failures в JSON errors с полями:

  • error;
  • code;
  • message;
  • status;
  • details;
  • logRef.

Frontend нормализует эти ошибки в короткие сообщения вида Code 502: UPSTREAM_FETCH_FAILED и сохраняет detailed fields для debug.