Перейти к основному содержимому

Формирование SBOM и аудит зависимостей

Сформируйте SBOM проекта и проверьте зависимости по выбранным источникам уязвимостей. Прочитайте результаты аудита и экспортируйте отчёт в SARIF.

Руководства

SBOM — перечень программных компонентов, который можно приложить к выпуску или передать команде безопасности. Он помогает увидеть состав сторонних пакетов и сопоставить зависимости с отчётом об уязвимостях. CodeGraph формирует перечень в CycloneDX или SPDX и выпускает отчёт аудита в JSON, SARIF, Markdown или формате ГОСТ.

Начните с инвентаризации: получите файл, проверьте имена и версии компонентов и сохраните его вместе с ревизией исходников. Затем выполните аудит и разберите находки перед обновлением зависимостей. Команда читает файлы зависимостей проекта и сопоставляет версии пакетов со сведениями выбранных источников. Специалист по безопасности разбирает находки для выпускаемой конфигурации продукта.

Подготовка и полный пример

Установите Python 3.11 или новее и зависимости CodeGraph по разделу подготовки руководства CLI. Следующий пример предназначен для локальной разработки из исходников и оболочки PowerShell. Перейдите в корень установленного репозитория CodeGraph. Каталог sbom-demo должен быть новым: команды создают в нём файлы примера.

$env:PYTHONPATH = (Get-Location).Path
New-Item -ItemType Directory -Path sbom-demo
@'
{
  "name": "sbom-demo",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "packages": {
    "": {"name": "sbom-demo", "version": "1.0.0"},
    "node_modules/lodash": {"version": "4.17.20"}
  }
}
'@ | Set-Content sbom-demo/package-lock.json -Encoding utf8
Set-Content sbom-demo/config.yaml "security:`n  local_cli_enabled: true" -Encoding utf8
Push-Location sbom-demo
try {
  python -m src.cli sbom generate --format cyclonedx --output sbom.json
  $sbom = Get-Content sbom.json -Raw | ConvertFrom-Json
  $sbom.components | Select-Object name, version
  Get-FileHash sbom.json -Algorithm SHA256
} finally {
  Pop-Location
}

Ожидаемый результат: SBOM written to sbom.json (cyclonedx, 1 components). Файл sbom-demo/sbom.json содержит bomFormat: CycloneDX, specVersion: 1.5 и компонент lodash с версией 4.17.20 и bom-ref: pkg:lodash@4.17.20. Это учебный lockfile с фиксированной версией; для своего проекта используйте lockfile из проверяемой ревизии. Пакет устанавливать не нужно: команда читает файл зависимостей. Настройка security.local_cli_enabled включает CLI только для локальной разработки. Без неё CLI выводит сообщение об отключении и завершает работу до генерации. После команды проверьте созданный файл и его содержимое.

Сформируйте перечень для проекта

python -m src.cli sbom generate --project "<project>" --format cyclonedx --output "<sbom.json>"

Замените <project> зарегистрированным именем проекта, а <sbom.json> — путём выходного файла. Сохраните кавычки для значений с пробелами. Без --project команда проверяет текущий каталог. Если имя проекта не удалось разрешить, реализация также использует текущий каталог: заранее проверьте, какие исходники находятся в нём, чтобы не проверить другой проект.

Форматы: --format {cyclonedx,spdx}, по умолчанию cyclonedx. Сохраните ревизию исходников, команду, выходной файл и его SHA-256. При сообщении No dependencies found. команда возвращает 0 и не создаёт SBOM. Проверьте выбранный каталог и формат файлов зависимостей: команда включает в SBOM компоненты из распознанных файлов.

Проверьте уязвимости

sbom audit заново сканирует манифесты выбранного проекта и проверяет полученный граф зависимостей через указанные источники. Выполняйте генерацию SBOM и аудит для одной ревизии, чтобы сопоставлять компоненты и находки.

python -m src.cli sbom audit `
  --project "<project>" `
  --format sarif `
  --fail-on high `
  --output "<sca.sarif>"

Для каталога из полного примера выполните аудит и просмотрите находки:

Push-Location sbom-demo
try {
  python -m src.cli sbom audit --sources osv --format sarif --fail-on high --output sca.sarif
  $report = Get-Content sca.sarif -Raw | ConvertFrom-Json
  $report.runs[0].results | Select-Object ruleId, level
  $report.runs[0].tool.driver.rules | Select-Object id, properties
} finally {
  Pop-Location
}

Форматы отчёта: --format {sarif,json,markdown,gost}, по умолчанию json. Источники задаются через --sources osv,nvd,bdu_fstec; по умолчанию используется osv. Параметр --fail-on {critical,high,medium,low} возвращает код 1 при обнаружении уязвимости указанной серьёзности или выше. Без параметра этот порог не применяется. Находки с серьёзностью unknown остаются в отчёте, но не входят в сравнение с порогом --fail-on. Для SARIF проверьте tool.driver.rules[].properties.severity и сопоставьте правило с results[].ruleId. Разберите такие находки по сведениям источника, чтобы назначить серьёзность и выбрать исправление. Код 2 обозначает обработанную командой ошибку. Проверьте наличие отчёта, его содержимое и сообщения об ошибках источников, прежде чем использовать результат в CI.

Команда python -m src.cli sbom sync --sources osv,nvd,bdu_fstec записывает отметку синхронизации для перечисленных источников и выводит статистику локального кэша. При проверке уязвимостей данные запрашивает sbom audit. Сохраните отчёт, сообщения источников и время проверки вместе с ревизией проекта; при ошибке источника восстановите доступ и повторите аудит.

Результаты через REST API

Операции SCA для проекта находятся под /api/v1/security/sca. Точные операции и схемы запросов проверьте в справочнике REST развёрнутого экземпляра CodeGraph. Порядок работы с зарегистрированным проектом и основные маршруты описаны в сценарии анализа зависимостей.

Разберите находки

  1. Подтвердите имя пакета, точную версию, экосистему и путь зависимости.
  2. Проверьте источник сведений об уязвимости и свежесть кэша.
  3. Оцените, выполняется ли уязвимый код в конфигурации развёрнутого продукта.
  4. Обновите или удалите зависимость. Если исправление откладывается, укажите компенсирующие меры и срок пересмотра решения.
  5. После изменения заново сформируйте SBOM и отчёт об уязвимостях.
Сообщить об ошибке в документации