Как проверить GitHub-репозиторий до npm install

00 · Модель риска

npm install не равен пассивному скачиванию файлов.

npm поддерживает lifecycle-события. Во время установки проекта или пакета могут выполняться preinstall, install, postinstall и другие связанные этапы. Для git-зависимостей наличие некоторых scripts также может привести к сборке перед упаковкой. [2] [1]

Код, запущенный под твоим пользователем, получает его файловые и сетевые возможности. Поэтому рабочая машина с SSH-ключами, активной сессией облачной CLI, кошельком, production .env и доступом к корпоративной сети является плохим местом для первого эксперимента.

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

01 · До установки

Сделай снимок и собери поверхность выполнения.

1. Шаг 1

   Проверь адрес и владельца.

   Убедись, что имя организации и репозитория совпадает с официальной ссылкой проекта. Похожие названия и forks — чужие ответвления проекта — могут выглядеть убедительно. Посмотри профиль владельца, связанные сайты и историю владения.

2. Шаг 2

   Зафиксируй версию.

   Запиши полный commit SHA — уникальный идентификатор конкретного состояния файлов. GitHub позволяет скачать снимок ветки, тега или commit, но только commit однозначно фиксирует просмотренное состояние. Тег — удобная подпись версии, но его владелец технически может переназначить. [7]

3. Шаг 3

   Скачай без запуска.

   Клонирование или архив нужны для статического чтения. Не открывай неизвестные исполняемые файлы и не запускай setup-команды из README.

4. Шаг 4

   Найди точки выполнения.

   Ищи scripts, shell-файлы, child_process, exec, spawn, downloads, eval, Docker entrypoints, git submodules и workflows.

Что можно делать до установки. Читать файлы как текст, искать слова, просматривать историю и сравнивать изменения. Чего пока не делать: запускать бинарники, открывать макросы, выполнять команды из README, собирать Docker-образ и подключать расширения редактора, которые проект рекомендует установить. Цель первого этапа — понять, какие команды вообще существуют, не выполняя их.

Если тебе сначала нужно научиться ориентироваться в интерфейсе, прочитай базовый гайд по GitHub, а затем разбор структуры чужого репозитория.

03 · Репозиторий

Смотри не только на автора, но и на изменение риска во времени.

Изучи последние изменения, открытые сообщения о проблемах, опубликованные версии, теги, участников и SECURITY.md. Важен контекст: давно ли менялись install scripts, кто добавил новую зависимость, совпадает ли опубликованная версия с исходным commit, не был ли проект внезапно переписан после долгой паузы.

Зафиксированный tag удобен, но commit SHA точнее описывает проверенное состояние. Если через неделю ветка main изменится, старый отчёт нельзя автоматически переносить на новый код. Для каждой повторной установки сравни manifest, lock-файл и scripts с проверенной версией.

OpenSSF Scorecard автоматизирует часть сигналов о практиках проекта. Используй его как повод для вопросов, а не как печать «код безопасен». [11]

04 · Цепочка поставки

Lock-файл фиксирует дерево, но не делает его добрым.

Манифест объявляет прямые зависимости, а lock-файл записывает точные выбранные версии, их вложенные зависимости и контрольные значения целостности. GitHub dependency graph и dependency review помогают увидеть прямые и транзитивные пакеты, изменения и известные уязвимости. [8] [9]

Проверь, что lock-файл существует, соответствует выбранному package manager и изменялся вместе с package.json. Ищи неожиданные registry, git URLs, локальные пути, новые install scripts и резкий рост дерева. После допустимого первого осмотра npm ci использует существующий lock-файл и завершится ошибкой, если он не совпадает с manifest, вместо обновления lock-файла. [4]

npm audit signatures может проверить цифровые подписи каталога и подтверждение происхождения уже скачанных пакетов. Provenance — запись о происхождении сборки — связывает публикацию с исходным commit и процессом сборки, но документация npm не превращает этот сигнал в гарантию отсутствия вредоносного кода. [5] [6]

05 · Изоляция

Первый запуск должен потерять ценность сразу после удаления среды.

Создай одноразовую виртуальную машину или другой изолированный контур. Внутри не должно быть боевого .env, личного SSH-агента, браузерных профилей, активных входов в облачные CLI, кошельков, рабочих репозиториев и доступа к пользовательским данным. Используй отдельного пользователя без административных прав и минимальный сетевой доступ.

1. 01CommitЗафиксирован SHA
2. 02СредаОдноразовая и пустая
3. 03InstallСначала без scripts
4. 04DiffФайлы и процессы
5. 05RunТолько изученная команда
6. 06УдалениеСреда уничтожена

Записывай команды и сетевые назначения. Если функциональность требует ключ, используй отдельную тестовую учётную запись или токен с минимальными правами, лимитом и возможностью немедленного отзыва. Не подключай внутрь контейнера домашний каталог или Docker socket — управляющий разъём локального Docker. Через него процесс внутри контейнера часто может создавать новые контейнеры и добираться до ресурсов основной машины, поэтому такая «изоляция» становится номинальной.

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

Инцидент

Если подозрительный код уже запускался, считай доступные ему секреты раскрытыми.

1. Сразу

   Останови процесс и изолируй среду.

   Отключи её от сети, не продолжай эксперименты на той же машине.

2. Секреты

   Отзови и замени доступные ключи с чистого устройства.

   Начни с наиболее привилегированных: облако, GitHub, каталог пакетов, SSH, базы, платежи, AI API. Удаление значения из файла не отзывает его. [10]

3. Сессии

   Заверши активные сессии и проверь журналы.

   Ищи новые ключи, выданные приложениям OAuth-разрешения, опубликованные версии, публикации пакетов, входы и сетевую активность.

4. Восстановление

   Пересоздай среду из доверенного образа.

   Не полагайся на ручное удаление найденного файла, если код работал с правами пользователя.

5. Профилактика

   Зафиксируй причину и новый gate.

   Добавь правило, которое не позволит повторить запуск на рабочей машине.

Промпт для Claude

Статический анализ без install, run и сетевых запросов.

Скачать полный промпт. Передай Claude только локальную копию репозитория без секретов.

Выполни только статический анализ уже скачанных текстовых файлов. Не устанавливай зависимости, не запускай код, package scripts, binaries, Docker, workflows и сетевые запросы. Не меняй файлы.

Проверь package.json, lifecycle scripts и вызываемые ими файлы, lock-файлы, git / URL / file зависимости, spawn / exec / eval, downloads, запись вне проекта, обфускацию и сбор окружения.

Каждый вывод пометь как «проверено статически», «требует изолированного теста» или «требует security-специалиста».

Верни вердикт «не запускать / нужен ручной разбор / допустим изолированный тест», таблицу с file:line, полный список команд без выполнения, план одноразового первого запуска и неизвестные зоны. После отчёта остановись.

FAQ

Частые вопросы перед первым запуском репозитория.

Если у проекта много звёзд, проверка всё равно нужна?

Да. Звёзды показывают внимание к проекту, а не безопасность конкретного commit. Аккаунт владельца может быть взломан, новая версия — отличаться от старой, зависимость — сменить владельца, а вредоносный код — появиться только в одном релизе.

Можно ли безопасно выполнить npm install --ignore-scripts на рабочем ноутбуке?

Флаг уменьшает один класс риска, но не превращает незнакомый проект в доверенный. Остаются сетевые запросы менеджера пакетов, уязвимости инструментов, случайный последующий запуск и доступ к рабочим файлам. Для неизвестного источника всё равно лучше одноразовая среда без секретов.

Docker-контейнера достаточно?

Только если он действительно ограничен. Подключённый домашний каталог, Docker socket, привилегированный режим, рабочие переменные окружения и свободный доступ во внутреннюю сеть разрушают границу. Для высокого риска понятнее отдельная одноразовая виртуальная машина.

Claude может доказать, что код безопасен?

Нет. Статический анализ показывает, что видно в предоставленных файлах. Он не подтверждает поведение скачиваемых компонентов, облачную конфигурацию и скрытую инфраструктуру. Поэтому отчёт должен отдельно перечислять, что проверено чтением, что требует изолированного запуска и что нужно передать security-специалисту.

Что делать, если репозиторий уже запускался рядом с настоящими токенами?

Остановить среду, с чистого устройства отозвать доступные токены и сессии, проверить журналы и публикации, затем пересоздать рабочую среду из доверенного образа. Удаление папки проекта не отменяет украденный ключ и не доказывает, что на машине ничего не осталось.