Сценарий 20: Анализ зависимостей

Комплексный анализ зависимостей: проверка уязвимостей, обнаружение устаревших пакетов, соответствие лицензиям, оценка состояния и генерация SBOM.

Содержание

Быстрый старт

/select 20

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

Архитектура

Модуль анализа зависимостей (src/dependencies/) состоит из 4 компонентов, связанных в конвейер:

Исходный код проекта
    |
    v
DependencyGraphBuilder (scan_project, NetworkX-граф)
    |
    v
DependencyGraph (файлы + зависимости + уязвимости)
    |
    +---> VulnerabilityChecker (OSV API + GitHub Advisory + NVD)
    |
    +---> DependencyAnalyzer (find_outdated, find_unused, find_duplicates,
    |                         suggest_updates, get_health_score)
    |
    +---> LicenseChecker (SPDX-нормализация, определение copyleft, экспорт SBOM)
    |
    v
Отчёт / REST API / CLI
Компонент Модуль Назначение
DependencyGraphBuilder graph_builder.py Сканирование проектов, разбор файлов зависимостей, построение NetworkX-графа
VulnerabilityChecker vulnerability.py Проверка зависимостей по базам OSV, GitHub Advisory, NVD
DependencyAnalyzer analyzer.py Поиск устаревших/неиспользуемых/дублирующихся пакетов, предложения обновлений, оценка состояния
LicenseChecker license_checker.py SPDX-нормализация, определение copyleft, совместимость, экспорт SBOM

7 модулей парсеров (src/dependencies/parsers/):

Парсер Файлы
Python pyproject.toml, requirements.txt, Pipfile, setup.py
JavaScript package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
Go go.mod, go.sum
Java pom.xml, build.gradle, build.gradle.kts
C# *.csproj, packages.config, Directory.Packages.props
PHP composer.json, composer.lock
C/C++ conanfile.txt, conanfile.py, vcpkg.json, CMakeLists.txt

Определение намерения

Workflow (src/workflow/scenarios/dependencies_analysis.py) определяет запросы об анализе зависимостей через is_dependency_query() с 36 двуязычными ключевыми словами:

Язык Ключевые слова
Английский (24) dependency, dependencies, package, npm, pip, cargo, maven, gradle, go mod, vulnerability, CVE, security audit, outdated, update, license, SBOM, supply chain, dependency graph, package manager, lock file, version conflict, transitive
Русский (12) зависимость, зависимости, пакет, уязвимость, устаревший, обновить, лицензия, граф зависимостей, менеджер пакетов, цепочка поставок

Функция dependencies_workflow() зарегистрирована в LangGraph через graph_builder.py и маршрутизируется через intent_classifier.py → router.py. Необязательное обогащение через EnrichmentAdapter добавляет векторный контекст.

Поддерживаемые менеджеры пакетов

Перечисление PackageManager (12 значений):

Значение Менеджер Язык
PIP pip Python
POETRY Poetry Python
CONDA Conda Python
NPM npm JavaScript
YARN Yarn JavaScript
PNPM pnpm JavaScript
GO Go Modules Go
CARGO Cargo Rust
BUNDLER Bundler Ruby
MAVEN Maven Java
GRADLE Gradle Java
NUGET NuGet .NET

Модели данных

Dependency (14 полей)

Поле Тип Описание
id str Уникальный идентификатор
name str Имя пакета
version_spec str? Требование версии (например, >=1.0.0)
resolved_version str? Фактически установленная версия
is_dev bool Зависимость разработки
is_optional bool Необязательная зависимость
is_direct bool Прямая или транзитивная (по умолчанию: True)
license str? Идентификатор лицензии
repository_url str? URL репозитория
homepage_url str? Домашняя страница проекта
description str? Описание пакета
file_id str? Ссылка на DependencyFile
parent_ids list[str] ID родительских зависимостей
child_ids list[str] ID дочерних зависимостей

DependencyGraph (3 коллекции + 5 методов)

Поле/Метод Тип Описание
files list[DependencyFile] Разобранные файлы манифестов
dependencies dict[str, Dependency] Все зависимости по ID
vulnerabilities list[Vulnerability] Найденные уязвимости
get_dependency(name) метод Найти зависимость по имени
get_direct_dependencies() метод Фильтр прямых зависимостей
get_transitive_dependencies() метод Фильтр транзитивных зависимостей
get_dev_dependencies() метод Фильтр зависимостей разработки
to_dict() метод Сериализация в словарь

Vulnerability (15 полей)

Поле Тип Описание
id str Внутренний ID
dependency_name str Затронутый пакет
dependency_version str? Затронутая версия
vuln_id str Идентификатор CVE или GHSA
source VulnerabilitySource OSV, GITHUB_ADVISORY, NVD или SNYK
severity VulnerabilitySeverity CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN
cvss_score float? Оценка CVSS (0.0–10.0)
title str Название уязвимости
description str Подробное описание
affected_versions str? Диапазон затронутых версий
fixed_version str? Версия с исправлением
references list[str] Ссылки
published_at datetime? Дата публикации
checked_at datetime? Когда была выполнена проверка
metadata dict Дополнительные метаданные

LicenseInfo (7 полей)

Поле Тип Описание
dependency_name str Имя пакета
license_id str Идентификатор SPDX
license_name str Человекочитаемое название
is_osi_approved bool Лицензия одобрена OSI
is_copyleft bool Copyleft-лицензия
is_allowed bool? Разрешена политикой проекта
notes str? Дополнительные примечания

DependencyConfig (13 полей)

Поле Тип По умолчанию Описание
auto_scan_on_import bool True Автосканирование при импорте проекта
include_dev bool True Включать зависимости разработки
max_depth int 10 Максимальная глубина зависимостей
vulnerability_enabled bool True Включить проверку уязвимостей
vulnerability_sources list[str] ["osv", "github_advisory", "nvd"] Активные источники уязвимостей
check_interval_hours int 24 Интервал повторной проверки
severity_threshold str "medium" Минимальная серьёзность для отчёта
license_check_enabled bool True Включить проверку лицензий
allowed_licenses list[str] ["MIT", "Apache-2.0", ...] Разрешённые лицензии
flagged_licenses list[str] ["GPL-3.0", "AGPL-3.0", ...] Помеченные лицензии
python_files list[str] ["pyproject.toml", ...] Шаблоны манифестов Python
javascript_files list[str] ["package.json", ...] Шаблоны манифестов JavaScript
go_files list[str] ["go.mod", "go.sum"] Шаблоны манифестов Go

Проверка уязвимостей

VulnerabilityChecker опрашивает 3 базы данных уязвимостей:

Источник API Экосистемы
OSV api.osv.dev/v1 (REST) PyPI, npm, Go, crates.io, Maven
GitHub Advisory GitHub GraphQL API Все через GHSA
NVD National Vulnerability Database Все через CPE

Перечисление VulnerabilitySource также включает SNYK, но без активной реализации.

Уровни серьёзности (перечисление VulnerabilitySeverity):

Серьёзность Оценка CVSS
CRITICAL 9.0–10.0
HIGH 7.0–8.9
MEDIUM 4.0–6.9
LOW 0.1–3.9
UNKNOWN Недоступна

Анализ зависимостей

DependencyAnalyzer предоставляет 6 методов анализа:

Метод Описание
find_outdated(graph, check_latest) Поиск пакетов с доступными обновлениями
find_unused(graph) Обнаружение потенциально неиспользуемых зависимостей
find_duplicates(graph) Поиск дублирующихся пакетов в файлах
suggest_updates(graph, conservative) Предложение безопасных обновлений (conservative: только minor/patch)
get_health_score(graph) Расчёт оценки состояния 0–100 с рейтингом A–F
_score_to_rating(score) Преобразование числовой оценки в буквенный рейтинг

Проверка лицензий

LicenseChecker обеспечивает соответствие лицензиям:

  • SPDX-нормализация — 17 псевдонимов лицензий, приведённых к стандартным идентификаторам SPDX
  • Классификация лицензий — 10 разрешительных, 16 copyleft, 4 слабых copyleft
  • Отслеживание одобрения OSI

Ключевые методы:

Метод Описание
check_license(dep) Проверка лицензии одной зависимости
check_graph(graph) Проверка всех зависимостей в графе
find_issues(graph) Поиск проблем совместимости лицензий
find_missing_licenses(graph) Поиск зависимостей без информации о лицензии
check_compatibility(licenses) Проверка совместимости между лицензиями
export_sbom(graph, format) Экспорт SBOM в формате SPDX 2.3 или CycloneDX 1.4

Оценка состояния

get_health_score() возвращает оценку 0–100 с детализацией:

Категория Макс. штраф Описание
Уязвимости 50 баллов На основе количества и серьёзности
Устаревшие пакеты 30 баллов На основе числа устаревших зависимостей
Дубликаты 10 баллов На основе количества дубликатов

Шкала рейтинга:

Оценка Рейтинг
90–100 A
80–89 B
70–79 C
60–69 D
0–59 F

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

Датакласс DependencyConfig (13 параметров):

dependencies:
  auto_scan_on_import: true
  include_dev: true
  max_depth: 10

  # Проверка уязвимостей
  vulnerability_enabled: true
  vulnerability_sources:
    - osv
    - github_advisory
    - nvd
  check_interval_hours: 24
  severity_threshold: medium    # critical, high, medium, low

  # Проверка лицензий
  license_check_enabled: true
  allowed_licenses:
    - MIT
    - Apache-2.0
    - BSD-3-Clause
    - BSD-2-Clause
    - ISC
  flagged_licenses:
    - GPL-3.0
    - AGPL-3.0
    - GPL-2.0

Использование CLI

# Сканирование зависимостей
python -m src.cli.import_commands deps scan [путь] --include-dev --max-depth 10

# Список зависимостей (с фильтрами)
python -m src.cli.import_commands deps list --outdated --dev --direct --format table|json|tree

# Проверка уязвимостей
python -m src.cli.import_commands deps check-vulns --severity medium --fail-on high -o report.json

# Граф зависимостей
python -m src.cli.import_commands deps graph --format text|dot|json|mermaid --depth 3 -o graph.dot

# Проверка лицензий
python -m src.cli.import_commands deps licenses --check-compliance --allow MIT Apache-2.0 --deny GPL-3.0

# Оценка состояния
python -m src.cli.import_commands deps health

# Предложения по обновлению
python -m src.cli.import_commands deps update --conservative
python -m src.cli.import_commands deps update --all

REST API

Основные project-scoped endpoints в src/api/routers/dependencies.py:

Метод Эндпоинт Описание
GET /api/v1/deps/projects/{project_name}/summary SCA summary зарегистрированного проекта
GET /api/v1/deps/projects/{project_name}/dependencies Список зависимостей проекта
GET /api/v1/deps/projects/{project_name}/vulnerabilities Результаты проверки уязвимостей проекта
GET /api/v1/deps/projects/{project_name}/sbom Экспорт SBOM проекта
POST /api/v1/deps/projects/{project_name}/audit Аудит зависимостей проекта
GET /api/v1/deps/projects/{project_name}/gost-report Формирование project-scoped ГОСТ-отчёта 5.16.3

Legacy compatibility endpoints под /api/v1/deps/scan, /list, /graph, /check-vulnerabilities, /licenses, /health-score, /sbom, /audit и /sync-cache сохранены для scan-first workflow, но Web-продукт использует project-scoped endpoints выше.

Пример:

# Сканирование зависимостей
curl http://localhost:8000/api/v1/deps/projects/codegraph/summary

# Список зависимостей
curl http://localhost:8000/api/v1/deps/projects/codegraph/dependencies

# Экспорт SBOM
curl "http://localhost:8000/api/v1/deps/projects/codegraph/sbom?format=spdx"

Сценарии использования

Сканирование зависимостей

> Сканировать зависимости проекта

## Результаты сканирования зависимостей

**Проанализировано файлов:** 3
**Всего зависимостей:** 127 (23 прямых, 45 разработки, 59 транзитивных)

| Пакет | Версия | Тип | Лицензия |
|-------|--------|-----|----------|
| fastapi | 0.104.1 | прямая | MIT |
| pydantic | 2.5.2 | прямая | MIT |
| sqlalchemy | 2.0.23 | прямая | MIT |
| uvicorn | 0.24.0 | прямая | BSD-3-Clause |
| ... | | | |

Проверка уязвимостей

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

## Отчёт об уязвимостях

Найдено 3 уязвимости:

| ID | Пакет | Серьёзность | Исправлено в |
|----|-------|-------------|--------------|
| CVE-2024-12345 | requests | CRITICAL | 2.32.0 |
| CVE-2024-23456 | pillow | HIGH | 10.2.0 |
| CVE-2024-34567 | cryptography | MEDIUM | 41.0.7 |

Источники: OSV, GitHub Advisory, NVD

Оценка состояния

> Показать состояние зависимостей

## Состояние зависимостей: 72/100 (C)

Детализация:
- Уязвимости: 3 найдено (-25 баллов)
- Устаревшие: 5 пакетов (-3 балла)
- Дубликаты: 0 (-0 баллов)

Примеры вопросов

Сканирование: - «Сканировать проект на зависимости» - «Какие пакеты использует этот проект?» - «Показать граф зависимостей»

Безопасность: - «Проверить на уязвимые пакеты» - «Найти пакеты с критическими уязвимостями» - «Есть ли CVE в наших зависимостях?»

Обновления: - «Есть ли устаревшие зависимости?» - «Предложить безопасные обновления устаревших пакетов» - «Показать оценку состояния зависимостей»

Лицензии: - «Проверить совместимость всех лицензий с MIT» - «Сгенерировать SBOM для проекта» - «Найти зависимости без информации о лицензии»