Пиков / КАПО
Библиотека
Как читать авторский курс и нормативные материалы

Это учебные материалы, а не заключение о соответствии конкретного продукта. Организационные модели курса отделяйте от терминов стандарта: ППК в опубликованном проекте — машиночитаемый перечень, а живой реестр его версий является практикой сопровождения. Термин OSA в разных материалах имеет разный охват. Статус и обязательность нормативного документа проверяются отдельно; проект КАПО опубликован как проект первой редакции.

П29. Readiness dashboard

После приёмки поставок (П28) у вас в портфеле Dependency-Track лежат проекты по подсистемам соисполнителей. Эта практика — про следующий шаг: свести лицензионные и уязвимостные метрики проекта в один бинарный вердикт готовности к релизу и обосновать его машинными числами, а не «на глаз».

Цель

По проекту в Dependency-Track получить через REST API текущие метрики (critical/high/medium/low, policy violations) и вычислить бинарный verdict: ready тогда и только тогда, когда нет блокирующих уязвимостей (critical = 0, high = 0) и нет нарушений лицензионной политики. Результат — JSON метрик плюс однозначный ready / not ready с перечислением, что именно блокирует.

Команда или действие

UUID проекта берём из его карточки в UI или из GET /api/v1/project?name=.... Метрики возвращает endpoint current; аутентификация — заголовком X-Api-Key.

DT=https://dtrack.internal           # адрес инстанса Dependency-Track
KEY=odt_xxxxxxxxxxxxxxxxxxxx         # API-ключ команды (X-Api-Key)
UUID=8b9e...                         # UUID проекта подсистемы

# 1. Текущие метрики проекта
curl -s -H "X-Api-Key: $KEY" \
  "$DT/api/v1/metrics/project/$UUID/current" | tee metrics.json | jq .

# 2. Бинарный вердикт готовности из метрик
jq -r '
  if (.critical == 0 and .high == 0 and (.policyViolationsFail // 0) == 0)
  then "READY"
  else "NOT READY: critical=\(.critical) high=\(.high) policyFail=\(.policyViolationsFail // 0)"
  end' metrics.json

Если метрики пустые или нулевые сразу после загрузки SBOM Dependency-Track считает метрики асинхронно после BOM-анализа. Перед чтением запросите пересчёт — curl -s -H "X-Api-Key: $KEY" "$DT/api/v1/metrics/project/$UUID/refresh" — и опросите current через несколько секунд. «Нули по всем осям» сразу после импорта обычно означают «ещё не посчитано», а не «чисто».

Что вы должны увидеть

Шаг 1 — объект метрик проекта (приведён скелет ключевых полей; реальный ответ шире):

{
  "critical": 0,
  "high": 0,
  "medium": 4,
  "low": 11,
  "unassigned": 2,
  "vulnerabilities": 15,
  "vulnerableComponents": 9,
  "components": 142,
  "policyViolationsFail": 0,
  "policyViolationsWarn": 3,
  "policyViolationsLicenseTotal": 1,
  "firstOccurrence": 1718000000000,
  "lastOccurrence": 1718600000000
}

Шаг 2 — итоговый вердикт. Для приведённого объекта (critical = 0, high = 0, нет fail-нарушений политики):

READY

Если бы был один high и одно блокирующее нарушение лицензии:

NOT READY: critical=0 high=1 policyFail=1

Сводная управленческая таблица готовности по продукту (строка на подсистему/соисполнителя) собирается из тех же чисел:

Подсистема critical high policy fail Вердикт
A 0 0 0 ready
B 1 2 1 not ready
N 0 0 0 ready

Продукт готов к релизу только если готовы все строки; одна not ready опускает вердикт по всему изделию.

Если не получилось

Типичные ошибки - HTTP 401 / {"...":"unauthorized"} — нет или неверный заголовок X-Api-Key, либо у ключа нет permission VIEW_PORTFOLIO. Проверьте права команды-владельца ключа. - HTTP 404 на /metrics/project/$UUID/current — неверный UUID (взяли ID компонента вместо проекта) или метрики ещё ни разу не считались. Сначала вызовите .../refresh, затем current. - jq: null (null) and number ... cannot be ... — поле policyViolationsFail отсутствует в этой версии DT; именно для этого в выражении стоит // 0. Если падает на .critical — вы скормили jq не объект метрик, а сообщение об ошибке; проверьте metrics.json. - Вердикт READY, но релиз явно «грязный» — пороги считаете только по severity и игнорируете policy violations (лицензии, устаревшие компоненты). Лицензионный блокер не отражается в critical/high — он в policyViolationsFail.

Критерий зачёта

Показать преподавателю: сырой JSON метрик из current по проекту, команду вычисления вердикта и её вывод (READY либо NOT READY с перечнем блокеров), а также заполненную строку сводной таблицы готовности по подсистеме. Бонус — продемонстрировать, как policyViolationsFail > 0 переводит подсистему в not ready при нулевых critical/high.

Нормативная связка