# OWASP Dependency Track

### Назначение

Dependency Track используется для анализа рисков зависимостей на основе SBOM. В TRAIO этот шаг обычно идёт после генерации SBOM (например, Syft) и позволяет получить унифицированный отчёт по findings в JSON

### Requirements

* В Sequences до этого шага должен быть выполнен job генерации SBOM (например, **Syft**), чтобы SBOM-файл был доступен в pipeline volume
* Установленный Dependency Track отдельно
  * Сетевая доступность до Depedency Track HTTP/HTTPS
  * Адрес Dependency Track
  * API Token с правами: BOM\_UPLOAD, PORTFOLIO\_MANAGEMENT, PROJECT\_CREATION\_UPLOAD, VIEW\_PORTFOLIO, VIEW\_VULNERABILITY

### Как работает

1. Job формирует уникальные `projectName` и `projectVersion` на каждый запуск (ephemeral-режим)
2. Загружает SBOM в Dependency Track через endpoint загрузки BOM с `autoCreate=true`
3. Ждёт завершения обработки BOM по `token`
4. Находит UUID созданного проекта по `name` и `version`
5. Экспортирует findings в JSON и сохраняет файл в `/data`
6. Удаляет проект в Dependency-Track (cleanup)

### Docker image

Для запуска job используется образ:

* `registry.gitlab.com/traio-group/tools/dependency-track:latest`

### Переменные окружения

| Переменная             | Обязательная                 | Пример                                | Описание                                                                             |
| ---------------------- | ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| **DT\_URL**            | Да                           | `https://dependency-track.company.kz` | URL инстанса Dependency-Track (без завершающего `/` или с ним — скрипт нормализует). |
| **DT\_API\_KEY**       | Да                           | `***`                                 | API key для доступа к Dependency-Track API.                                          |
| **SBOM\_PATH**         | (указывается автоматический) | `sbom.json` или `/data/sbom.json`     | Путь к SBOM-файлу, который будет загружен в Dependency-Track.                        |
| **REPORT\_FILE\_NAME** | (указывается автоматический) | `dependency-track-findings.json`      | Имя выходного отчёта (будет сохранён в `/data`).                                     |
| **SCAN\_TYPE**         | (указывается автоматический) | `OWASP Dependency Track`              | Тип сканирования для парсинга                                                        |

### Команда запуска

Скрипта для job:

```sh
echo "[stage 0] init"
DT="${DT_URL%/}"
HDR="X-Api-Key: ${DT_API_KEY}"
OUT="/data/${REPORT_FILE_NAME}"
RUN_ID="$(date +%Y%m%d-%H%M%S)"
PN="traio-scan-${RUN_ID}"
PV="run-${RUN_ID}"
echo "[info] projectName=${PN}"
echo "[info] projectVersion=${PV}"

# Stage 1 — Upload BOM (SBOM -> Dependency-Track)
echo "[stage 1] upload bom"
UPLOAD="$(curl -sS -X POST "${DT}/api/v1/bom" \
  -H "${HDR}" \
  -F "projectName=${PN}" \
  -F "projectVersion=${PV}" \
  -F "autoCreate=true" \
  -F "bom=@${SBOM_PATH}")"
TOKEN="$(echo "$UPLOAD" | jq -r '.token')"
echo "[info] upload token=${TOKEN}"

# Stage 2 — Wait for BOM processing
echo "[stage 2] wait bom processing"
i=0
while [ $i -lt 18 ]; do
  PROC="$(curl -sS "${DT}/api/v1/bom/token/${TOKEN}" -H "${HDR}")"
  echo "[wait] attempt=$((i+1))/18 status=${PROC}"
  echo "$PROC" | jq -e '(.processing == false) or (.status == "PROCESSED") or (.status == "COMPLETE")' >/dev/null 2>&1 && break
  i=$((i+1))
  sleep 10
done

# Stage 3 — Resolve project UUID
echo "[stage 3] lookup project uuid"
LOOKUP="$(curl -sS -G "${DT}/api/v1/project/lookup" \
  --data-urlencode "name=${PN}" \
  --data-urlencode "version=${PV}" \
  -H "${HDR}")"
UUID="$(echo "$LOOKUP" | jq -r '.uuid')"
echo "[info] project uuid=${UUID}"

# Stage 4 — Export findings JSON
echo "[stage 4] export findings (FPF)"
curl -sS "${DT}/api/v1/finding/project/${UUID}/export" -H "${HDR}" | jq '.' > "${OUT}"

echo "[info] report saved: ${OUT}"
ls -lah "${OUT}"

# Stage 5 — Cleanup (delete ephemeral project)
echo "[stage 5] cleanup (delete project)"
curl -sS -X DELETE "${DT}/api/v1/project/${UUID}" -H "${HDR}" >/dev/null 2>&1 || true
echo "[done] dependency-track job finished"
```

### Типовые ошибки и диагностика

* **401/403 при запросах к API**
  * Проверьте `DT_API_KEY` и права ключа.
* **TOKEN = null / пустой ответ на upload**
  * Проверьте `DT_URL`, доступность инстанса и корректность `SBOM_PATH`.
* **Долгая обработка BOM**
  * Увеличьте число попыток/таймаут ожидания (сейчас 18×10с = 180с).

###  Ссылки

* [Docs Dependency Track](https://docs.dependencytrack.org/)
* [Dependency Track API](https://docs.dependencytrack.org/integrations/rest-api/)