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

Сценарий 20 помогает инженеру и специалисту AppSec разобраться в сторонних пакетах проекта: какие зависимости используются, где обнаружены известные уязвимости и какие лицензии указаны для пакетов. Результаты можно собрать в SBOM — перечень компонентов программного обеспечения — и использовать при выборе обновлений.

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

Выберите способ анализа

Полный пример инвентаризации

Подготовьте Python-окружение проекта по руководству CLI. В корне репозитория CodeGraph создайте каталог dependency_example и сохраните следующий манифест в dependency_example/package.json:

{
  "name": "dependency-example",
  "version": "1.0.0",
  "dependencies": {
    "express": "4.18.2"
  },
  "devDependencies": {
    "typescript": "5.4.5"
  }
}

В корне репозитория сохраните программу dependency_inventory.py:

import json
from src.dependencies import DependencyGraphBuilder

builder = DependencyGraphBuilder()
for include_dev in (True, False):
    graph = builder.scan_project("dependency_example", include_dev=include_dev, max_depth=10)
    packages = sorted(
        ({"name": dep.name, "version_spec": dep.version_spec,
          "is_dev": dep.is_dev, "is_direct": dep.is_direct}
         for dep in graph.dependencies.values()),
        key=lambda dep: dep["name"],
    )
    print(json.dumps({"include_dev": include_dev, "files": len(graph.files),
                      "packages": packages}))

Запустите её в PowerShell:

python dependency_inventory.py

Программа выводит два JSON-объекта. В обоих поле files содержит 1: найден один манифест. При include_dev=true список packages содержит express со спецификацией версии 4.18.2 и typescript с 5.4.5. При include_dev=false остаётся только express. Обе зависимости прямые; у typescript поле is_dev=true.

scan_project находит поддерживаемые манифесты, выбирает парсеры и добавляет разобранные зависимости в список. При добавлении пакетов он применяет фильтр development-зависимостей. Вызов читает манифест и возвращает граф в памяти. Запросы к источникам уязвимостей и оценка лицензий выполняются отдельно. Версии выше служат фиксированными входными данными для примера разбора.

Проверьте уязвимости и лицензии через CLI

Для отчёта об уязвимостях и экспорта состава пакетов используйте руководство SCA и SBOM: оно показывает подготовку lock-файла, создание SBOM и проверку по OSV. Сохраните отчёт вместе с ревизией проекта, параметрами анализа и кодом завершения, чтобы сравнить результаты после обновления пакета.

В текущей версии deps check-vulns прерывается с ValueError, когда OSV возвращает находку с уровнем unknown; JSON-отчёт не создаётся. Эта команда исключена из исполняемых инструкций страницы.

Для проверки лицензий перейдите в корень анализируемого проекта. Подготовьте доступ Python к CodeGraph через установленный пакет или PYTHONPATH и локальный config.yaml, как описано в руководстве CLI. Команда читает манифесты текущего каталога:

python -m src.cli deps licenses --check-compliance --allow MIT Apache-2.0 --deny GPL-3.0

Задайте разрешённые и запрещённые лицензии по правилам вашего проекта. Команда сопоставляет идентификаторы из манифестов и lock-файлов с этими списками. Например, пакет с лицензией ISC при показанном списке MIT Apache-2.0 попадёт в таблицу с причиной not in allowed list; команда вернёт код 1. Для разрешённого пакета MIT такого нарушения не будет.

Проверка обрабатывает пакеты с заполненным полем лицензии. Значение UNKNOWN пропускается при сопоставлении списков. Если лицензия не указана, получите её идентификатор из источника пакета и дополните инвентаризацию перед оценкой.

Команды deps scan, deps list, deps graph, deps health и deps update в текущей версии завершаются с AttributeError. Для получения состава пакетов используйте Python-пример выше; эти пять CLI-команд исключены из исполняемых инструкций этой страницы.

Учитывайте сеть, кеш и актуальность

По умолчанию проверка использует OSV — базу известных уязвимостей. Для запроса нужен исходящий доступ к сети, если подходящей записи нет в локальном кеше. Для аудита зарегистрированного проекта дополнительные источники включаются в конфигурации: GitHub Advisory использует GITHUB_TOKEN, а NVD — NVD_API_KEY.

Сохраняйте вместе с отчётом активные источники, время запроса, время ожидания ответа, путь и TTL кеша — срок хранения записи. Для результата из кеша укажите возраст записи. При ошибке источника сохраните его сообщение и повторите проверку после восстановления доступа; так отчёт сохраняет связь с фактически полученными данными.

Получите результаты через REST API

REST API доступен по адресу /api/v1/security/sca. Подготовьте зарегистрированный проект с указанным source_path и войдите под пользователем с доступом к проекту. Используйте токен доступа из ответа POST /api/v1/auth/token. Для интеграции с выданным API-ключом передавайте X-API-Key вместо заголовка Bearer. Маршруты аутентификации перечислены в справочнике REST API.

Маршруты чтения используют локальные результаты SCA. Если сохранённой сводки нет, CodeGraph читает манифесты из source_path и собирает инвентаризацию. Эти GET-запросы используют сохранённые сведения об уязвимостях и не запускают запросы к внешним источникам.

• GET /api/v1/security/sca/projects/{project_name}/summary — сводка и состояние её данных.
• GET /api/v1/security/sca/projects/{project_name}/dependencies — список пакетов с пагинацией.
• GET /api/v1/security/sca/projects/{project_name}/vulnerabilities — находки из локальных результатов SCA.
• GET /api/v1/security/sca/projects/{project_name}/sbom — экспорт SBOM; параметр format выбирает spdx (по умолчанию) или cyclonedx.

В PowerShell задайте адрес сервера без завершающего слеша, имя зарегистрированного проекта и его UUID. Передайте токен доступа в переменную CODEGRAPH_ACCESS_TOKEN через одобренный канал конфигурации. Пример получает сводку и первую страницу пакетов:

$api = '<api-base-url>'
$project = [uri]::EscapeDataString('<project-name>')
if (-not $env:CODEGRAPH_ACCESS_TOKEN) { throw 'Access token is not configured' }
$headers = @{
    Authorization = "Bearer $env:CODEGRAPH_ACCESS_TOKEN"
    'X-Project-Id' = '<project-uuid>'
}
$summary = Invoke-RestMethod -Uri "$api/api/v1/security/sca/projects/$project/summary" -Headers $headers
$dependencies = Invoke-RestMethod -Uri "$api/api/v1/security/sca/projects/$project/dependencies?limit=20&offset=0" -Headers $headers
$summary.scan_status
$dependencies | Select-Object total, limit, offset, has_next, has_prev
$dependencies.items | Select-Object name, version, resolved_version, is_dev, is_direct, license

Для собранной сводки scan_status равен ready. Поле total содержит общее число пакетов, items — текущую страницу, а has_next показывает наличие следующей. Для следующей страницы увеличьте offset на limit.

При 401 проверьте учётные данные и способ авторизации; 404 означает неизвестный проект. Состояния сводки source-path-missing, source-path-invalid и scan-error указывают соответственно на незаданный путь, недоступный каталог или ошибку разбора. Сохраните ответ вместе с именем проекта и ревизией исходников.

Запустите типизированный сценарий AppSec

Используйте настроенное окружение из программного руководства, принятую задачу AppSec и необходимые сервисы CodeGraph. Сохраните пример в файл Python. Задайте в контексте проект, пространство имён (namespace), задачу и ссылки на отчёты. Настройте LLM для работы сценария. Сохраните инвентаризацию манифестов и предупреждения источников уязвимостей вместе с ответом.

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Проанализируй риски зависимостей, уязвимостей, лицензий и SBOM для ограниченного проекта.",
    employee_id="codegraph_appsec",
    scenario_id="scenario_20",
    event_type="appsec_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<revision-ref>", "<dependency-artifact-ref>"],
    },
)
result = invoke_role_bound_scenario_request(request)
if result.get("error"):
    raise RuntimeError(result["error"])
if not result.get("scenario_id") or not result.get("answer"):
    raise RuntimeError("Scenario returned no scenario identity or answer")
print(result["answer"])

В ответе сценария найдите пакеты, связанные с рисками, основания выводов и предложенные действия. Сопоставьте выводы с приложенными отчётами. После обновления пакетов повторите инвентаризацию и проверку уязвимостей, чтобы увидеть изменение состава и находок.

Связанные руководства

• SCA и SBOM
• Анализ цепочки поставок
• Каталог сценариев