Как проверить зависимости и установочный скрипт GitHub-проекта
Проверка происхождения релиза, lockfile, install-скриптов и прав. Примеры npm, pip-audit и ShellCheck с объяснением границ каждого инструмента.
Установка зависимостей, сторонних пакетов, необходимых проекту, иногда запускает код ещё до первого старта приложения. Поэтому вопрос, как проверить зависимости GitHub-проекта, начинается с чтения файлов и проверки происхождения выпуска. Сканер известных уязвимостей пригодится позже, когда понятны состав пакетов и действия установщика.
Особенно важно разобраться с установочным скриптом до выполнения. Иногда команда, выглядящая как загрузка пакета, запускает сборку, скачивает дополнительные файлы или меняет настройки системы. Если сначала установить проект, а потом изучать его зависимости, часть действий уже произойдёт.
Вложенные друг в друга открытые коробки рядом с ноутбуком и лупой.
Проверьте происхождение репозитория и релиза
Сопоставьте репозиторий с официальным сайтом проекта. Проверьте имя владельца посимвольно, историю изменений, предыдущие выпуски и адреса загрузок. Поддельная копия может имитировать название и README, основной файл с описанием проекта, поэтому внешнее сходство не решает вопрос происхождения.
Для скачанного файла готовой программы найдите опубликованные контрольные суммы, подпись или аттестацию сборки (attestation), если разработчик их предоставляет. Аттестация представляет подписанное заявление о том, где и как был собран файл. Контрольная сумма подтверждает совпадение байтов с выбранным эталоном. Если файл и эталон получены из одного подменённого места, сама сумма не устанавливает доверие к автору.
GitHub artifact attestations связывают готовый файл с происхождением сборки. Проверка должна учитывать ожидаемый репозиторий и workflow, сценарий автоматической сборки. Attestation подтверждает заявленное происхождение в пределах механизма проверки, но не заменяет анализ безопасности исходников.
Сохраните точный коммит, идентификатор состояния исходников, и хеш, контрольную сумму загруженного файла. Такой результат полезнее записи «скачано с GitHub», потому что платформа содержит множество владельцев и постоянно изменяющиеся версии.
Схема: четыре проверки перед запуском.
Разберите прямые и транзитивные зависимости
Прямая зависимость указана самим проектом. Транзитивная приходит через другой пакет. Поэтому список из пяти строк в package.json или requirements.txt не означает, что установятся только пять компонентов.
Lockfile, файл закреплённых зависимостей, фиксирует выбранные версии и другие сведения для конкретной экосистемы. Он помогает повторять сборку, но не объявляет зависимости безопасными. Проверьте согласованность lockfile с основным перечнем зависимостей, источники пакетов, локальные пути, прямые ссылки на Git-репозитории и сторонние реестры, каталоги доступных пакетов.
| Элемент | Вопрос при проверке | Следующее действие |
|---|---|---|
| Имя пакета | Совпадает ли с официальным названием | Сверить страницу проекта и реестр |
| Версия | Зафиксирована ли она и поддерживается ли | Проверить выпуск и сообщения об уязвимостях |
| Источник | Откуда менеджер получит пакет | Просмотреть адреса, реестры и конфигурацию |
| Хеш | Какие именно байты ожидаются | Сравнить с доверенным описанием сборки |
| Транзитивная связь | Как пакет попал в проект | Найти родительскую зависимость |
| Установочное действие | Выполняется ли код при установке | Прочитать соответствующий скрипт |
У Python просмотрите раздел build-system в pyproject.toml. Сборочная система и её зависимости тоже участвуют в установке. Файл requirements.txt способен содержать дополнительные параметры, ссылки и включения других файлов. Поэтому до автоматического анализа прочитайте сам входной документ.
Прочитайте установочный скрипт как программу
Откройте скрипт в текстовом редакторе и проследите последовательность команд. Найдите загрузки, запуск других файлов, запрос повышенных прав, запись в системные каталоги, создание служб и изменение конфигурации оболочки. Для каждой операции должен существовать понятный ответ: зачем она нужна выбранной программе?
Особенно внимательно просмотрите команды, которые получают текст из сети и сразу передают его интерпретатору, программе исполнения команд. До запуска сохраните файл, проверьте его источник и прочитайте содержимое. При этом один просмотр не фиксирует удалённые файлы, которые скрипт скачает позже. Их адреса, версии и проверку целостности нужно оценивать отдельно.
Обфускация, намеренное запутывание кода, скрытое отключение защитных средств или запрос доступа к чужим данным требуют объяснения автора до эксперимента. Само наличие административной команды не доказывает вредоносность: установка драйвера и регистрация службы действительно используют системные права. Решение зависит от назначения и прозрачности действия.
ShellCheck помогает находить ошибки скриптов Bash, sh и других поддерживаемых командных оболочек, например проблемы кавычек и переносимости. Официальный проект описывает его как анализатор ошибок. Чистый отчёт ShellCheck не означает отсутствие намеренно вредоносной команды.
Что проверить у npm-проекта
Для примеров используется npm, менеджер JavaScript-пакетов. Сначала прочитайте package.json, lockfile и проектный .npmrc. В scripts изучите preinstall, install, postinstall, а также команды сборки и запуска. Проверьте, не перенаправляет ли конфигурация установку в неожиданный реестр пакетов.
После проверки происхождения, в отдельной среде, установка по существующему согласованному lockfile выглядит так:
npm ci --ignore-scripts --no-audit
Параметр --no-audit отключает автоматический запрос аудита во время установки. Загрузка пакетов по-прежнему обращается к их источникам; отдельный аудит ниже передаёт сведения о зависимостях в реестр пакетов.
Команда меняет локальную среду зависимостей и пересоздаёт node_modules. Она не является простым чтением файлов. Флаг --ignore-scripts отключает предусмотренные package.json установочные скрипты, но явный последующий npm run всё равно исполняет выбранную команду. Поведение объясняет документация npm ci.
Для проекта с lockfile сохраните отчёт об известных уязвимостях:
npm audit --ignore-scripts --json > npm-audit.json
Проверьте код завершения и содержание отчёта, включая ошибки сети и неполные данные. Не используйте автоматическое исправление с изменением версий до оценки совместимости. Документация npm audit описывает обращение к реестру пакетов. Учитывайте передачу сведений о зависимостях при работе с закрытыми проектами.
Как использовать pip-audit без ложного чувства проверки
pip-audit сопоставляет Python-пакеты с известными уязвимостями. Он не анализирует весь исходный код на вредоносное поведение. Документация прямо предупреждает, что разрешение произвольных зависимостей способно выполнять действия, сравнимые с установкой. Поэтому незнакомый requirements.txt нельзя считать безопасным входом только потому, что команда называется аудитом.
Команды ниже сверены с интерфейсом pip-audit 2.9.0, которому нужен Python 3.9 или новее. Подготовьте проверенный текстовый список прямых и транзитивных зависимостей с точными версиями, без произвольных URL и установочных опций. Сохраните его как requirements-reviewed.txt в отдельной папке аудита. Инструмент обращается к сервису сведений об уязвимостях, которому становятся доступны имена и версии проверяемых пакетов.
Для инструмента используйте venv, отдельный набор Python-пакетов. Он не ограничивает доступ программы к файлам и сети. В Linux или macOS создайте среду и обращайтесь к её Python напрямую:
python3 -m venv .audit-venv
.audit-venv/bin/python -m pip install "pip-audit==2.9.0"
.audit-venv/bin/python -m pip_audit --no-deps --disable-pip -r requirements-reviewed.txt -f json -o pip-audit.json
Для PowerShell с установленным Python 3.12:
py -3.12 -m venv .audit-venv
.\.audit-venv\Scripts\python.exe -m pip install "pip-audit==2.9.0"
.\.audit-venv\Scripts\python.exe -m pip_audit --no-deps --disable-pip -r requirements-reviewed.txt -f json -o pip-audit.json
Это образец запуска для заранее проверенного списка. Результат сканирования вашего проекта здесь не предполагается: его нужно получить и прочитать после выполнения команды.
Флаги отключают разрешение зависимостей через pip в указанном режиме. Неполный список даст неполную проверку: отсутствующий пакет не станет проверенным автоматически. Ограничения параметров и модель безопасности описаны в документации выпуска 2.9.0.
Для повторяемой установки применяют фиксированные версии и хеши. Документация pip описывает режим --require-hashes и установку только готовых пакетов, без сборки исходных дистрибутивов, через --only-binary. Хеши защищают целостность выбранных файлов, а доверие к самому пакету устанавливается отдельно.
Как интерпретировать находки и отсутствие находок
Запись в базе уязвимостей требует проверки затронутых версий, исправления и условий эксплуатации. Не всякая проблема одинаково применима к вашему сценарию, но отсутствие очевидного использования функции тоже не следует считать доказанным исключением.
С другой стороны, пустой отчёт отражает только проверенную область и состояние базы в момент запроса. Он не исключает новые уязвимости, намеренно вредоносные действия и проблемы компонентов вне поддерживаемой экосистемы. GitHub Dependabot работает с графом зависимостей и сведениями об известных проблемах, что задаёт границы его результата.
Сохраните дату, версии инструментов, входной список, полный отчёт и перечень пропусков. Такой пакет позволяет повторить проверку после обновления базы. Одной зелёной строки из терминала для этого недостаточно.
Частые вопросы
Lockfile гарантирует безопасные пакеты?
Нет. Он помогает зафиксировать выбранный набор версий. В этот набор способны входить уязвимые или нежелательные компоненты. Происхождение и поведение проверяют отдельно.
Разрешено ли запускать скрипт, если ShellCheck не нашёл ошибок?
Результат говорит о проверяемых ошибках кода командной оболочки. Он не отвечает на вопрос, допустимы ли действия программы с вашими файлами и правами.
pip-audit заменяет чтение requirements.txt?
Нет. Сначала нужно понять содержимое входного файла и выбранный режим. Некоторые операции разрешения зависимостей требуют исполнения сборочных действий.
Стоит ли автоматически исправлять все находки?
Сначала определите применимость и совместимую исправленную версию. После изменения зависимостей повторите функциональную проверку. Автоматическое обновление без проверки способно нарушить работу проекта.
Что записать перед первым запуском
Перед запуском у вас должны быть объяснения для загрузок, записи файлов и запрошенных прав. Отчёт сканера сохраните вместе с датой и перечнем пропущенных компонентов. Если скрипт всё ещё содержит непонятное действие с системными правами, вернитесь к этой строке: зелёный отчёт по зависимостям не отвечает на вопрос, зачем она нужна.