Анализ цепочки поставок проверяет происхождение и целостность зависимостей, доверие к издателям, метаданные реестров и сходство имён пакетов, которым могут пользоваться злоумышленники. SCA/SBOM описывает состав компонентов и известные уязвимости. Ответственный за безопасность сопоставляет оба отчёта перед решением о выпуске.
Используйте результаты при обновлении зависимостей и подготовке выпуска: найдите пакет или файл фиксации версий, разберите причину находки и назначьте исправление. Сохранённый отчёт связывает решение с проверенной рабочей копией.
Как устроен анализ
| Этап | Что обрабатывает CodeGraph | Результат |
|---|---|---|
| Реестр компонентов | Манифесты зависимостей и сведения о пакетном менеджере | Имя, версия, тип зависимости, экосистема, адрес реестра и лицензия. |
| Оценка доверия | Доступные сведения о сопровождающих, выпуске, политике безопасности, подписях, популярности и OpenSSF Scorecard | Взвешенная оценка от 0 до 10 и уровень риска. При отсутствии факторов используется значение 5.0. |
| Целостность | Хеш компонента, доступный установленный артефакт и файлы фиксации зависимостей | Результаты сравнения хеша и проверки lockfile. |
| Сходство имён | Имя пакета и каталог популярных пакетов его экосистемы | Похожее имя, расстояние между именами и предполагаемый способ подмены. |
| Скрипты сборки | Скрипты установки в рабочей копии | Подозрительные шаблоны с пояснениями для ревью. |
В отчёте trust поля maintainers и scorecard показывают данные, использованные
для оценки. Поле ecosystem в реестре выбирает каталог популярных пакетов
для автоматического сравнения имён. Для зависимостей из requirements.txt,
package.json и package-lock.json текущий CLI возвращает unknown.
В этом случае проверьте имя и издателя вручную в реестре пакетного менеджера
исходного манифеста.
В JSON-отчёте верхнее поле risk_level рассчитывается по массиву findings.
Поле components[].risk_level рассчитывается по оценке доверия отдельного компонента.
Например, при пустом findings общий уровень равен minimal, а оценка компонента
5.0 соответствует medium. Значения null в checksum_match и
lockfile_consistent означают, что соответствующее сравнение не выполнено.
При разборе отчёта сопоставляйте эти поля с данными о компоненте и причиной находки.
Подготовьте запуск
Установите CLI по руководству. Выполняйте примеры в PowerShell из корня репозитория CodeGraph. Укажите каталог с исходниками и файлами зависимостей:
$env:CODEGRAPH_ALLOW_LOCAL_PYTHON_CLI = '1'
$sourcePath = 'C:/projects/my-project'
if (-not (Test-Path -LiteralPath $sourcePath -PathType Container)) { throw 'Source directory missing' }
Замените $sourcePath своим путём. --path имеет приоритет над --project.
Без явного пути неразрешённое имя проекта или ошибка его поиска приводят к анализу текущего
каталога .. Поэтому для воспроизводимого запуска указывайте путь явно.
Выполните проверку
python -m src.cli supply-chain scan `
--path "$sourcePath" `
--format sarif `
--fail-on high `
--output 'supply-chain.sarif'
$scanExit = $LASTEXITCODE
Отчёт сохраняется в текущем каталоге и перезаписывает одноимённый файл.
Код 0 означает отсутствие находок на заданном пороге; 1 — находку уровня high или critical
при --fail-on high; 2 — ошибку сканирования зависимостей или анализа цепочки поставок.
Проверяйте $scanExit вместе с отчётом и сообщениями: существующий файл может остаться от прежнего запуска.
Без --fail-on найденные проблемы сами по себе не меняют код 0.
Сохраните ревизию проекта и сведения о свежести сетевых данных и кеша. Оценка риска помогает
разобрать находки; решение о выпуске принимает ответственный за безопасность.
Пример: найдите и исправьте шаблон в скрипте сборки
Для проверки этапа анализа скриптов создайте отдельный учебный каталог.
В нём нет зависимостей: пустые requirements.txt и poetry.lock позволяют
сосредоточиться на setup.py. CodeGraph читает этот файл и ищет шаблоны;
при сканировании он не запускает скрипт сборки.
Выполните команды в той же PowerShell-сессии из корня CodeGraph:
$demoPath = Join-Path ([System.IO.Path]::GetTempPath()) ('codegraph-supply-demo-' + [guid]::NewGuid().ToString('N'))
New-Item -ItemType Directory -Path $demoPath | Out-Null
Set-Content -LiteralPath (Join-Path $demoPath 'requirements.txt') -Value '' -Encoding UTF8
Set-Content -LiteralPath (Join-Path $demoPath 'poetry.lock') -Value '' -Encoding UTF8
Set-Content -LiteralPath (Join-Path $demoPath 'setup.py') -Value "eval('1 + 1')" -Encoding UTF8
$beforePath = Join-Path $demoPath 'before.json'
python -m src.cli supply-chain scan --path "$demoPath" --format json --fail-on high --output "$beforePath"
$beforeExit = $LASTEXITCODE
$before = Get-Content -LiteralPath $beforePath -Raw | ConvertFrom-Json
$before.findings | Select-Object finding_type, severity, component_name, evidence
if ($beforeExit -ne 1 -or @($before.findings).Count -ne 1) { throw 'Expected one high finding' }
Отчёт содержит одну находку: finding_type — suspicious_pattern,
severity — high, component_name — setup.py, в evidence указан line:1.
Код возврата — 1. Детектор отмечает вызов eval как динамическое выполнение
кода. При ревью реального проекта проверьте назначение вызова и входные данные.
В учебном примере удалите динамическое вычисление и повторите проверку:
Set-Content -LiteralPath (Join-Path $demoPath 'setup.py') -Value '# Reviewed build script: no dynamic evaluation' -Encoding UTF8
$afterPath = Join-Path $demoPath 'after.json'
python -m src.cli supply-chain scan --path "$demoPath" --format json --fail-on high --output "$afterPath"
$afterExit = $LASTEXITCODE
$after = Get-Content -LiteralPath $afterPath -Raw | ConvertFrom-Json
if ($afterExit -ne 0 -or @($after.findings).Count -ne 0) { throw 'Expected no findings after correction' }
Повторный запуск возвращает 0, массив findings пуст. Сравните before.json
и after.json: они сохраняют результат до изменения и после него. Оба отчёта
имеют total_components: 0, поскольку пример проверяет скрипт без зависимостей.
Для анализа компонентов используйте каталог своего проекта из предыдущего раздела.
Точечные проверки
python -m src.cli supply-chain trust --path "$sourcePath" --format json
python -m src.cli supply-chain typosquatting --path "$sourcePath"
Для реестра компонентов предназначен supply-chain registry, для отчёта по ГОСТ — gost-report.
Отчёт по ГОСТ группирует результаты для последующей проверки по требованиям.
Проверяйте параметры этих команд через --help установленной версии.
Для проверки происхождения компонентов и доверия используйте CLI или MCP-инструменты ниже. API SCA проекта предоставляет инвентаризацию компонентов и анализ уязвимостей, описанные в руководстве SCA/SBOM.
Работа через MCP
Выберите MCP-профиль для проверки безопасности по
руководству оператора и укажите имя проекта
в аргументе project. Для общего отчёта используется профиль codex:role:codegraph_appsec:mutation,
для отчёта доверия — codex:role:codegraph_appsec:read.
Инструменты получают каталог исходников из настройки проекта.
Пустое имя означает текущий рабочий каталог сервера MCP.
| Задача | Инструмент | Параметры и результат |
|---|---|---|
| Получить общий отчёт | codegraph_security_supply_chain_scan_run |
project — имя проекта; format — json, markdown, sarif или gost; language — ru или en. Аргумент fail_on задаёт порог: critical, high или medium. При достижении порога заголовок содержит THRESHOLD BREACHED. |
| Разобрать доверие к компонентам | codegraph_security_supply_chain_trust_report_get |
project — имя проекта; min_score — показать компоненты с оценкой ниже этого значения. Значение 0 показывает все компоненты. Результат содержит имя, версию, оценку доверия, уровень риска и использованные сведения. |
Проверьте каждую находку
- Найдите компонент или скрипт по имени и полю
evidence. Для зависимости сверьте версию, реестр, издателя и хеш артефакта. - Разберите причину находки: сходство имени, результат сравнения хеша, фактор оценки доверия или строку скрипта.
- Выберите действие: уточнить сведения об издателе, заменить пакет, обновить файл фиксации версий или изменить скрипт.
- Сохраните решение, ответственного и срок в задаче выпуска. Приложите отчёт и ревизию проекта.
- Повторите проверку после изменения и сравните результат с исходным отчётом.
Справочные материалы
Подробнее о составе компонентов и анализе уязвимостей: SCA и SBOM.