safe-npm

Установщик npm, ориентированный на безопасность и защищающий ваши проекты от недавно скомпрометированных пакетов.

Зачем это нужно?

Атаки на цепочку поставок npm-пакетов представляют собой растущую угрозу. Злоумышленники иногда компрометируют легитимные пакеты:

• Кража учетных данных мейнтейнеров
• Публикация вредоносных обновлений популярных пакетов
• Захват заброшенных пакетов

Такие атаки часто происходят внезапно — пакет, который вчера был безопасным, сегодня может быть скомпрометирован. safe-npm защищает вас, устанавливая только те версии пакетов, которые были общедоступны в течение минимального времени (по умолчанию 90 дней). Это дает сообществу безопасности время на обнаружение и сообщение о вредоносных релизах до того, как они попадут в ваш проект.

Как это работает

Когда вы запускаете safe-npm install, происходит следующее:

1. Читает ваши зависимости из package.json или аргументов командной строки
2. Запрашивает npm registry для поиска всех доступных версий
3. Отфильтровывает версии, опубликованные позднее установленного порога минимального возраста
4. Выбирает самую новую версию, которая соответствует как вашим требованиям semver, так и требованиям к возрасту
5. Устанавливает безопасные версии с помощью npm

Например, если вы укажете react@^18, а вредоносный [email protected] был опубликован вчера, safe-npm установит последнюю версию, которой не менее 90 дней.

Установка

Установка из npm (рекомендуется)

# Install globally
npm install -g @dendronhq/safe-npm

# Now you can use it anywhere
safe-npm install

Сборка из исходного кода

# Clone and build
git clone <repository-url>
cd safe-npm
npm install
npm run build

# Link the binary globally
npm link

Базовое использование

Установка зависимостей из package.json

# Use the minimum age of 90 days (default)
safe-npm install

# Or specify your own minimum age
safe-npm install --min-age-days 120

Установка конкретных пакетов

# Install packages directly with version constraints
safe-npm install react@^18 lodash@^4.17.0

# These will be filtered to only use versions at least 90 days old
safe-npm install express --min-age-days 60

Пробный запуск для просмотра того, что будет установлено

# Preview which versions would be installed without actually installing
safe-npm install --dry-run

Параметры конфигурации

--min-age-days <n>

По умолчанию: 90

Минимальное количество дней с момента публикации версии пакета до возможности ее установки.

Пример: --min-age-days 120 требует, чтобы пакетам было не менее 4 месяцев.

Когда настраивать:

• Увеличьте для максимальной безопасности (например, 180 дней для критически важных производственных систем)
• Уменьшите, если вам нужны новые функции и вы готовы принять чуть больший риск (например, 30 дней)

--ignore <pkg1,pkg2>

Список пакетов, разделенных запятыми, которые обходят требование по возрасту. Эти пакеты по-прежнему будут соблюдать диапазоны semver, но игнорировать минимальный возраст.

Пример: --ignore typescript,@types/node

Когда использовать:

• Быстро развивающиеся пакеты, которым вы доверяете (например, TypeScript или инструменты сборки)
• Внутренние пакеты вашей организации
• Пакеты, где срочно нужны последние функции

--strict

Завершится с ошибкой, если ЛЮБАЯ зависимость не может быть разрешена до версии, удовлетворяющей требованию по возрасту.

Пример: safe-npm install --strict

Когда использовать:

• Конвейеры CI/CD, где вы хотите, чтобы сборки завершались ошибкой, а не пропускали проблемные пакеты
• Развертывания в производственной среде, где требуется уверенность

--dev / --prod-only

Управляет тем, какие зависимости из package.json обрабатываются.

Примеры:

• safe-npm install --dev - Установить только devDependencies
• safe-npm install --prod-only - Установить только production-зависимости

Когда использовать:

• Установка инструментов разработки с более строгими требованиями
• Производственные сборки, где нужны разные политики возраста для dev и prod зависимостей

--strategy <direct|overrides>

По умолчанию: direct

Как safe-npm устанавливает разрешенные версии:

direct - Напрямую устанавливает разрешенные версии с помощью npm install package@version

• Просто и понятно
• Хорошо подходит для одноразовых установок или скриптов

overrides - Записывает разрешенные версии в поле overrides файла package.json, затем запускает npm install

• Принудительно устанавливает версии во всем дереве зависимостей (включая транзитивные зависимости)
• Примечание: Эта функция в настоящее время отключена, так как она еще не работает корректно

--registry <url>

По умолчанию: https://registry.npmjs.org

Укажите альтернативный npm registry.

Пример: --registry https://registry.company.com

Когда использовать:

• Частные npm registry
• Зеркала или кэши

--dry-run

Показывает, что будет установлено, без внесения изменений.

Пример: safe-npm install --dry-run

Когда использовать:

• Тестирование конфигурации
• Понимание того, какие версии доступны
• Перед внесением изменений в производственные системы

Типичные сценарии работы

Защита нового проекта

# Create a new project
mkdir my-project && cd my-project
npm init -y

# Install dependencies safely
safe-npm install express@^4 lodash

# This creates package-lock.json with versions at least 90 days old

Аудит существующего проекта

# Check what versions would be installed with age requirements
safe-npm install --dry-run

# If you're happy, install them
safe-npm install

Интеграция с CI/CD

# In your CI pipeline, fail the build if any package can't meet age requirements
safe-npm install --strict --min-age-days 120

# Or allow newer packages for dev dependencies only
safe-npm install --prod-only --strict

Экстренные обновления

# Need to urgently update a specific package? Add it to ignore list
safe-npm install --ignore package-with-critical-fix

Тестирование

Проект включает набор тестов, которые вы можете запустить:

npm test

Для автоматического тестирования вы можете имитировать ответы registry с помощью фикстур:

export SAFE_NPM_FIXTURES=/path/to/fixtures.json
safe-npm install

Файл фикстур должен содержать JSON, отражающий ответы npm registry для каждого пакета.

Как это вас защищает

Реальный сценарий:

1. Популярный пакет popular-lib поддерживается доверенным разработчиком
2. Злоумышленник компрометирует учетные данные мейнтейнера в npm
3. Злоумышленник публикует [email protected] с вредоносным ПО
4. Проекты, использующие ^5.0.0, немедленно установят вредоносную версию
5. С safe-npm вы продолжите использовать 4.9.0 (последнюю версию 90+ дней назад)
6. Исследователи безопасности обнаруживают компрометацию и сообщают о ней
7. Вредоносная версия удаляется из публикации
8. Вы никогда не устанавливали скомпрометированную версию

Ограничения

• Не защищает от пакетов, которые были вредоносными с самого начала
• Задерживает доступ к легитимным новым функциям и исправлениям ошибок
• Требует доверия к тому, что старые версии не имеют необнаруженных уязвимостей
• Фильтрация по возрасту — это эвристика, а не гарантия

Философия

Безопасность — это компромиссы. safe-npm обменивает самые свежие обновления на защиту от внезапных компрометаций цепочки поставок. Это один из уровней стратегии глубокой эшелонированной защиты, которая также должна включать:

• Регулярные аудиты безопасности (npm audit)
• Проверка зависимостей перед добавлением новых пакетов
• Мониторинг уведомлений безопасности
• Использование lock-файлов для обеспечения воспроизводимых сборок
• Запуск в изолированных или контейнерных средах

Требования

• Node.js 18 или выше
• npm (для базовой установки)

Лицензия

ISC