Композиционный анализ (КА) и SBOM

CodeGraph включает встроенный модуль композиционного анализа для проверки зависимостей, поиска уязвимостей и формирования SBOM. Модуль покрывает требования процесса 5.16 ГОСТ Р 56939-2024.

Обзор¶

Конвейер композиционного анализа:

Парсеры зависимостей → Генератор SBOM → Проверка уязвимостей → Отчёт
         ↓                    ↓                    ↓                ↓
   7 модулей парсеров   CycloneDX 1.5       4 источника       SARIF/ГОСТ/JSON
   7 экосистем          SPDX 2.3            SQLite-кэш        Коды возврата CI

Поддерживаемые языки¶

Текущая реализация содержит 7 модулей парсеров и покрывает Python, JavaScript/TypeScript, Go, Java/Kotlin, C#, PHP и C/C++. TypeScript использует парсер JavaScript. Kotlin использует парсер Java (build.gradle.kts). 1С:Предприятие не имеет стандартного менеджера пакетов.

Источники уязвимостей¶

Результаты кэшируются локально в SQLite (data/vuln_cache.sqlite) с настраиваемым сроком действия.

Команды CLI¶

Формирование SBOM¶

python -m src.cli sbom generate --format cyclonedx --output sbom.json
python -m src.cli sbom generate --format spdx --project myproject

Форматы: cyclonedx (CycloneDX 1.5, по умолчанию), spdx (SPDX 2.3).

Аудит зависимостей¶

# Базовый аудит (только OSV)
python -m src.cli sbom audit

# Полный аудит с несколькими источниками
python -m src.cli sbom audit --sources osv,nvd,bdu --format sarif --output sca.sarif

# Режим CI: код возврата 1 при критических уязвимостях
python -m src.cli sbom audit --fail-on critical --format json

Коды возврата: - 0 — уязвимостей выше порога нет - 1 — есть уязвимости выше порога --fail-on - 2 — ошибка выполнения

Форматы вывода: json, sarif, markdown, gost.

Синхронизация кэша уязвимостей¶

python -m src.cli sbom sync --sources osv,nvd,bdu
python -m src.cli sbom sync --force  # очистка и пересинхронизация

Формирование отчёта ГОСТ¶

python -m src.cli sbom gost-report --language ru --output gost_sca.md
python -m src.cli sbom gost-report --language en

Формирует отчёт в формате Markdown с четырьмя разделами по ГОСТ Р 56939-2024 5.16.3: - 5.16.3.2 — Перечень зависимостей - 5.16.3.3 — Контроль актуальности версий - 5.16.3.4 — Результаты проверки на уязвимости - 5.16.3.5 — Рекомендации по обновлению

REST API¶

Все маршруты SCA смонтированы под /api/v1/deps.

Project-scoped конечные точки (основной контракт)¶

Web-экраны SCA / SBOM используют именно project-scoped endpoints выше. Портфельный агрегат /api/v2/dashboard/sca/overview остаётся доступным, но не является основным источником данных для проектного SCA-экрана.

Legacy scan-scoped endpoints (compatibility)¶

Эти маршруты сохранены для CLI/manual workflow, где временный граф сначала загружается через /scan, но они не являются каноническим multi-project контрактом:

POST /api/v1/deps/projects/{project_name}/audit¶

Аудит зависимостей с настраиваемыми источниками и порогом серьёзности.

{
  "sources": ["osv", "nvd", "bdu_fstec"],
  "fail_on": "critical",
  "format": "json"
}

Ответ содержит threshold_breached: true при превышении порога.

GET /api/v1/deps/projects/{project_name}/gost-report¶

Формирование отчёта ГОСТ 5.16.3.

GET /api/v1/deps/projects/codegraph/gost-report?language=ru

Возвращает {"format": "markdown", "language": "ru", "content": "..."}.

POST /api/v1/deps/sync-cache¶

Синхронизация локального кэша уязвимостей.

{
  "sources": ["osv", "nvd", "bdu_fstec"],
  "force": false
}

Инструменты MCP¶

Три инструмента MCP для интеграции с IDE:

Конфигурация¶

В config.yaml в разделе dependencies:

dependencies:
  enabled: true
  vulnerability:
    sources: [osv, github_advisory, nvd, bdu_fstec]

  vuln_cache:
    enabled: true
    db_path: "data/vuln_cache.sqlite"
    ttl_hours: 24
    sync_interval_hours: 12

  sources:
    osv:
      enabled: true
    nvd:
      enabled: true
      api_key_env: "NVD_API_KEY"
      rate_limit_per_second: 5
    bdu_fstec:
      enabled: true
      base_url: "https://bdu.fstec.ru/api"
    github_advisory:
      enabled: true
      token_env: "GITHUB_TOKEN"

  ci:
    fail_on: "critical"
    sarif_output: "sca-results.sarif"

  sbom:
    default_format: "cyclonedx"
    cyclonedx_version: "1.5"
    include_dev_deps: false

Доступ через get_unified_config().sca:

from src.config import get_unified_config
cfg = get_unified_config().sca
cfg.ci_fail_on          # "critical"
cfg.sbom_default_format # "cyclonedx"
cfg.vuln_cache_ttl_hours # 24

Интеграция с CI¶

Рабочий процесс GitHub Actions: .github/workflows/sca-audit.yml:

- name: Аудит зависимостей
  run: python -m src.cli sbom audit --sources osv --format sarif --output sca-results.sarif --fail-on critical

- name: Загрузка SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: sca-results.sarif

Рабочий процесс запускается при изменении файлов манифестов зависимостей: 1. Формирует CycloneDX SBOM 2. Выполняет аудит с --fail-on critical (блокирует конвейер при критических уязвимостях) 3. Загружает SARIF в GitHub Code Scanning 4. Сохраняет SBOM как артефакт сборки

Соответствие ГОСТ Р 56939-2024¶

Модуль КА покрывает процесс 5.16 через SCAEvaluator в подсистеме соответствия. Запуск:

python -m src.cli compliance gost-56939 --format markdown --language ru

Оценщик проверяет 5 артефактов: 1. SBOM (5.16.3.2) 2. Контроль актуальности (5.16.3.3) 3. Проверка уязвимостей (5.16.3.4) 4. Рекомендации по обновлению (5.16.3.5) 5. Множественные источники уязвимостей

Статус: 0 = ПРОБЕЛ, 1–3 = ЧАСТИЧНО, 4–5 = ПОЛНОСТЬЮ.

Экспорт SARIF¶

Результаты КА экспортируются в формате SARIF 2.1.0, совместимом с: - GitHub Code Scanning - VS Code SARIF Viewer - Azure DevOps

Соответствие серьёзности: CRITICAL/HIGH → error, MEDIUM → warning, LOW → note.

Каждая находка содержит: - Расположение файла манифеста и номер строки - Версию исправления (при наличии) - Поддержку подавления (suppressed, suppression_reason)

Архитектура¶

src/dependencies/
    parsers/
        python.py, javascript.py, go.py     # существующие
        java.py, c_cpp.py, csharp.py, php.py # новые
        __init__.py                          # реестр ALL_PARSERS
    models.py           # Dependency, Vulnerability, SCAFinding и др.
    vulnerability.py    # VulnerabilityChecker (OSV, GitHub, NVD, БДУ ФСТЭК)
    vuln_cache.py       # SQLite-кэш с TTL
    license_checker.py  # CycloneDX 1.5, SPDX 2.3
    sarif_export.py     # SARIF 2.1.0 для находок КА
    gost_report.py      # Генератор отчёта ГОСТ 5.16.3
    graph.py            # DependencyGraphBuilder (NetworkX)
    analyzer.py         # Устаревшие, неиспользуемые, показатель здоровья
src/cli/sbom_commands.py    # CLI: sbom generate/audit/sync/gost-report
src/api/routers/dependencies.py  # REST API (project-scoped + legacy compatibility)
src/mcp/tools/sca.py       # Инструменты MCP (3)
src/compliance/gost_56939/evaluators/automated.py  # SCAEvaluator