Skip to content

Latest commit

 

History

History
217 lines (171 loc) · 16.4 KB

supply-chain.md

File metadata and controls

217 lines (171 loc) · 16.4 KB

Цепочка поставок (supply-chain)

Инвентаризация и аудит внешнего кода, попадающего к пользователю: runtime- зависимости Python и вендоренные веб-ассеты. Инвентарь собран (аудит 2026-07-20, раунд 2, зона supply-chain). Канонический источник по теме — этот файл; SECURITY.md даёт короткий указатель.

Проект намеренно держит поверхность цепочки поставок узкой: 3 прямые runtime- зависимости и ноль CDN/сетевых загрузок в браузере — все веб-ассеты вендорены и коммитятся как готовые артефакты. Это и есть главная защита; ниже — инвентарь и результаты аудита.

Runtime-зависимости Python

Прямые (pyproject.toml → [project].dependencies) — три; остальное транзитивно. Полное замыкание (pipdeptree -p requests,psutil,rich):

Пакет Версия Ограничение Лицензия Роль
requests 2.34.2 >=2.34.2,<3.0 (прямая) Apache-2.0 HTTP к Stepik API
psutil 7.2.2 >=5.9,<8.0 (прямая) BSD-3-Clause замер RSS/CPU раннера
rich 15.0.0 >=13.0,<16.0 (прямая) MIT консольный вывод
certifi 2026.7.22 транзитивно (requests) MPL-2.0 CA-бандл TLS
charset-normalizer 3.4.9 транзитивно (requests) MIT детект кодировки
idna 3.18 транзитивно (requests) BSD-3-Clause IDNA-хостнеймы
urllib3 2.7.0 транзитивно (requests) MIT HTTP-транспорт
markdown-it-py 4.2.0 транзитивно (rich) MIT Markdown в rich
mdurl 0.1.2 транзитивно (markdown-it-py) MIT URL-парсинг для md
Pygments 2.20.0 транзитивно (rich) BSD-2-Clause подсветка синтаксиса

Все лицензии — пермиссивные (Apache-2.0 / BSD / MIT) либо file-level weak-copyleft (MPL-2.0 у certifi — только CA-бандл, совместимо с MIT-проектом при редистрибуции). Копилефт-конфликтов с лицензией проекта (MIT) нет.

Верхние границы версий (<3.0 / <8.0 / <16.0) в pyproject.toml держатся осознанно: мажорный апгрейд с возможными несовместимостями не должен приезжать молча (инвариант CLAUDE.md — зависимости не добавляются/не двигаются без явного решения).

Результат аудита

pip-audit по замыканию против PyPI Advisory Database (2026-07-22):

No known vulnerabilities found

Известных уязвимостей в runtime-зависимостях нет.

Про источник данных. В окружении аудита прокси блокирует api.osv.dev (OSV-сервис — 403 Forbidden), поэтому кросс-проверка через OSV не выполнялась; без такого прокси доступны оба сервиса (pip-audit --vulnerability-service osv). PyPI Advisory DB (дефолт pip-audit) отработал полностью.

Как перепроверить локально

pip install pip-audit          # ad-hoc-инструмент, НЕ добавляется в pyproject.toml
pipdeptree -p requests,psutil,rich   # посмотреть транзитивные версии замыкания
pip-audit                      # аудит текущего окружения против PyPI Advisory DB

pip-audit не является ни runtime-, ни dev-зависимостью проекта (его нет в pyproject.toml) — ставится по требованию.

Вендоренные веб-ассеты (web/static/)

Веб-оболочка (--serve) не грузит ничего из CDN: все JS/CSS/шрифты вендорены и коммитятся как готовые артефакты. Поверхность цепочки поставок здесь — сами файлы в репозитории, а не сетевые загрузки в рантайме.

CodeMirror 6 (vendor/codemirror-bundle@6.mjs)

Единый self-contained ESM-бандл (редактор кода), собран esbuild ОДИН РАЗ вне репозитория из реальных npm-пакетов — ни Node.js, ни бандлера в рантайме/CI. Лицензия MIT (vendor/LICENSE). Полный состав (13 npm-пакетов с пин-версиями), рецепт воспроизводимой пересборки и правила бампа — vendor/VERSIONS.md.

Целостность. SHA256 бандла зафиксирован в vendor/VERSIONS.md (раздел «Integrity») и сверяется тестом tests/test_packaging.py на каждом прогоне CI: 360 КБ минифицированного стороннего JS уходят и в каждую --serve-сессию, и в опубликованный wheel, а в диффе выглядят как «файл изменён». Хеш — якорь для ревью, а не защита от злонамеренного коммита, который правит и бандл, и строку хеша: он делает такую правку явной и намеренной. Тем же тестом закреплена и вторая ручная проверка из VERSIONS.md — отсутствие Node-зависимых импортов (events/tty/process/async_hooks), которые вернулись бы вместе с debug-путём новой версии пакета и упали бы уже в браузере. При намеренной пересборке хеш обновляется тем же PR.

Шрифты (web/static/fonts/)

Subsetted woff2 (latin + cyrillic), тоже без CDN:

Шрифт Начертание Лицензия Источник
Inter UI-текст SIL OFL 1.1 rsms/inter
JetBrains Mono моноширинный (код) SIL OFL 1.1 JetBrains/JetBrainsMono

Текст лицензии — web/static/fonts/LICENSE. OFL разрешает встраивание и редистрибуцию в составе ПО; reserved font names не переиспользуются (шрифты только субсеттятся, не форкаются под тем же именем).

Прочие статические файлы

app.js / app.css / content.js / core.js / grade.js / sandbox.js / downloader.js / trace-player.js — собственный код проекта, не вендор; под лицензией самого проекта (MIT). В инвентарь цепочки поставок не входят.

GitHub Actions — исполняемая часть цепочки поставок

Actions — самый привилегированный участок цепочки: они исполняются с токеном репозитория, видят секреты своих job'ов и публикуют релизы. Инвентарь ниже перечисляет всё, что запускается в .github/workflows/.

Action Где Зачем Права
actions/checkout все четыре workflow клон репозитория чтение
actions/setup-python ci.yml, release.yml установка интерпретатора —
actions/upload-artifact / download-artifact ci.yml обмен coverage между job'ами матрицы —
actions/cache ci.yml кеш браузеров Playwright —
pypa/gh-action-pypi-publish release.yml публикация на PyPI OIDC-токен публикации
softprops/action-gh-release release.yml создание GitHub Release запись releases
anthropics/claude-code-action claude.yml, claude-code-review.yml AI-ассистент по упоминанию и авто-ревью PR secrets.CLAUDE_CODE_OAUTH_TOKEN; токен job'а — чтение (contents/pull-requests/issues/actions)

Политика пиннинга — по SHA, не по тегу. Каждый uses: в репозитории указывает полный commit SHA с тегом в комментарии (actions/checkout@3d3c42e5… # v7.0.1). Тег в GitHub мутабелен: владелец action может передвинуть v7 на другой коммит, и обновление приедет молча в следующий же прогон. SHA этого не позволяет. При бампе меняются оба — и SHA, и комментарий с версией.

Модель угроз двух AI-workflow. claude.yml и claude-code-review.yml запускают агента на содержимом PR и issue, то есть на тексте, который пишет кто угодно. Отсюда два ограничения, которые нужно держать при их правке:

  • pull_request_target не используется — на PR из форка секрет агенту не выдаётся, ревью просто не запускается. Это осознанное ограничение, а не поломка: «очевидная починка» переключением на pull_request_target дала бы чужому коду доступ к секретам репозитория;
  • в репозиторий токен job'а только читает — contents/pull-requests/ issues объявлены read, плюс actions: read для чтения логов CI. Сверх них объявлен id-token: write, и это не оговорка: он не даёт никакого доступа к содержимому репозитория, а разрешает job'у запросить у GitHub короткоживущий OIDC-токен, которым агент подтверждает, откуда он запущен. Раньше здесь было сказано просто «только чтение», и читатель, сверяя документ с permissions в workflow, находил лишнюю строку без объяснения;
  • инструкции из тела PR/issue — данные, а не команды: содержимое пишет кто угодно и может пытаться перенаправить агента (prompt injection), поэтому набор инструментов задан явно, а расширять права этих workflow нельзя без отдельного разбора.

Публикация на PyPI живёт в отдельном job'е release.yml с OIDC — API-токена PyPI в секретах репозитория нет, и скомпрометированный workflow ревью не получает права публикации.

Провенанс собственного дистрибутива

Инвентарь выше отвечает за код, приходящий в проект. Обратная сторона — что о своём происхождении заявляет пакет, который проект отдаёт наружу. Связь «дистрибутив ↔ репозиторий» выражена в метаданных, а не только в README: [project.urls] (Homepage, Repository, Changelog, Issues) и authors из pyproject.toml попадают в METADATA wheel'а и PKG-INFO sdist'а, поэтому со страницы пакета на PyPI видны исходники, история изменений и issue-трекер — установившему через pipx не нужно искать проект поиском.

Лицензия объявлена SPDX-выражением (PEP 639: license = "MIT" + license-files), а не классификатором. Классификаторов License :: … в classifiers нет намеренно: setuptools>=77 на пару «SPDX-выражение + классификатор лицензии» падает с InvalidConfigError ещё до сборки, а в метаданных лицензия и так присутствует полем License-Expression.

Проверить, что метаданные не разъехались:

python -m build              # sdist + wheel в dist/
python -m twine check dist/* # метаданные валидны для загрузки на PyPI

Состав [project.urls]/authors/classifiers закреплён тестами (tests/test_packaging.py), поэтому потерянная ссылка или протухший version-классификатор ловятся прогоном, а не глазами на странице пакета.

Мониторинг в CI

Джоб supply-chain в .github/workflows/ci.yml — информационный, не блокирующий (continue-on-error: true): устанавливает пакет + pip-audit и аудитит окружение (надмножество runtime-замыкания) против PyPI Advisory DB на каждый PR/push. Новая CVE в requests / urllib3 / … не валит несвязанный PR, но всплывает аннотацией ::warning:: в сводке прогона — сигнал мейнтейнеру обновить границы версий. Ручной аудит выше остаётся точкой отсчёта (дата + результат), а CI-джоб держит сигнал свежим между ручными прогонами.

Три исхода, а не два

pip-audit выходит с ненулевым кодом и когда нашёл уязвимость, и когда упал сам — не разрешился индекс, оборвалась сеть, Advisory DB не ответила. Пока шаг судил по коду возврата, оба случая печатались одинаково («найдена уязвимость»), а так как джоб не блокирующий, тихий отказ инструмента выглядел ровно как чистое замыкание.

Разница ведёт к разным действиям: «проверили — чисто» закрывает вопрос, а «проверить не удалось» означает, что сегодня о безопасности зависимостей мы не знаем ничего. Поэтому pip-audit вызывается с --format=json --output=, а исход называет scripts/check_pip_audit_report.py по наличию отчёта, а не по коду: код у краха и у находки совпадает, а отчёт краш не оставляет.

Код Исход
0 аудит отработал, уязвимостей нет
1 уязвимости найдены — ::warning:: с числом
2 аудит не отработал (отчёта нет или он нечитаем) — ::warning:: об этом

Разбор живёт скриптом, а не строкой YAML, чтобы у него были тесты: иначе получился бы ещё один guard, зелёный независимо от того, работает ли он.