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

Сценарий 20 инвентаризирует манифесты зависимостей и формирует свидетельства Software Composition Analysis. Он отвечает на вопросы о составе пакетов, известных уязвимостях из настроенного источника, лицензиях для проверки и SBOM для зафиксированной ревизии. Полноту и актуальность источника, юридическую допустимость лицензии и безопасность обновления для выпуска проверяют отдельные процедуры.

Выберите поверхность

Выполните ограниченную CLI-проверку

Запускайте команды из рабочей копии с нужными манифестами:

python -m src.cli deps scan PATH --include-dev --max-depth 10
python -m src.cli deps check-vulns --path PATH --severity medium --fail-on high --output vulnerabilities.json

scan распознаёт семейства манифестов, реализованные текущими парсерами. check-vulns строит новый граф для PATH, применяет заданную область и записывает JSON только при наличии --output. Вместе с артефактом сохраните ревизию, путь, параметры include-dev/direct/depth/package limit, переопределение экосистемы, порог серьёзности и код завершения.

Другие зарегистрированные команды дают отдельные виды свидетельств:

python -m src.cli deps list --direct --format json
python -m src.cli deps graph --format mermaid --depth 3 --output dependencies.mmd
python -m src.cli deps licenses --check-compliance --allow MIT Apache-2.0 --deny GPL-3.0
python -m src.cli deps health
python -m src.cli deps update --conservative

Список разрешённых и запрещённых лицензий задаёт оператор как рабочую policy. deps update печатает предложения и оставляет манифест и lock-файл без изменений. Health score — эвристика по наблюдаемому графу; разрешение выпуска оформляется отдельно.

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

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

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

Используйте REST API зарегистрированного проекта

Текущий router подключён под /api/v1/security/sca и требует зарегистрированный проект с корректным корнем исходников. Основные read-only маршруты:

• 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;
• GET /api/v1/security/sca/projects/{project_name}/sbom.

Интерпретируйте 404 как неизвестный проект, 409 — как неполную конфигурацию проекта, а ошибку сканирования или источника — как несобранное свидетельство. Сохраняйте ответ вместе с идентификатором проекта и основой ревизии.

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

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)

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

Контракт источников

• src/cli/docs_suite/deps_commands.py — зарегистрированный CLI и запись результатов;
• src/api/routers/analysis_suite/dependencies.py и src/api/app_routers.py — project-scoped REST-маршруты;
• src/dependencies/vulnerability.py — источники, сеть, учётные данные и кеш;
• src/config/domain_sections/unified_config_security_sections.py — значения SCA по умолчанию;
• src/workflow/scenarios/domain_checks/dependencies_analysis.py — анализ сценария 20;
• src/digital_employees/runtime/scenarios/employee_scenario_invocation.py — условная ответственность AppSec.

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

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