trustlock

Git-родной контроллер допуска зависимостей. Оценивает сигналы доверия при каждом изменении зависимостей.

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

trustlock работает как Git-хук pre-commit (рекомендательный режим) и как проверка в CI (режим принуждения):

• Рекомендательный (pre-commit): предупреждает о нарушениях, завершается с кодом 0, обновляет доверенную базовую линию, когда все пакеты допущены.
• Принудительный (--enforce): блокирует при нарушениях, завершается с кодом 1, никогда не обновляет базовую линию.

Сигналы доверия, оцениваемые для каждого пакета:

• Остывание — сколько времени прошло с момента публикации версии в реестре
• Происхождение — есть ли у пакета SLSA-аттестации
• Фиксация — использует ли файл блокировки точные версии
• Скрипты установки — выполняет ли пакет скрипты во время установки
• Источники — поступает ли пакет из реестра, git-URL, локального пути или URL
• Новые зависимости — первые добавления в проект
• Транзитивный сюрприз — неожиданный скачок количества транзитивных зависимостей
• Смена издателя — изменилась ли личность издателя пакета между версиями

Установка

npm install -g trustlock

Требуется Node.js >= 18.3.

Поддерживаемые файлы блокировки

Быстрый старт

Рабочий процесс 1 — Подключение проекта

# 1. Инициализация trustlock в вашем проекте
trustlock init

# 2. Установка Git-хука pre-commit
trustlock install-hook

# 3. Опционально: просмотр текущей ситуации с зависимостями
trustlock audit

После init trustlock создаёт:

• .trustlockrc.json — конфигурация политик
• .trustlock/baseline.json — снимок доверенных зависимостей
• .trustlock/approvals.json — записи об утверждениях
• .trustlock/.cache/ — кеш реестра (игнорируется git)

Зафиксируйте .trustlockrc.json и .trustlock/baseline.json в своём репозитории.

Рабочий процесс 2 — Проверка и допуск обновления зависимостей

# Выполните обычную установку зависимостей
npm install [email protected]

# trustlock check запускается автоматически через хук pre-commit.
# Для ручного запуска:
trustlock check

# Вывод, когда все пакеты допущены:
# ✔ [email protected] — допущен

Когда все пакеты проходят проверку, trustlock check автоматически обновляет базовую линию (только в рекомендательном режиме) и завершается с кодом 0.

Рабочий процесс 3 — Обработка заблокированной зависимости

# Новый пакет не проходит правило «остывания»:
trustlock check
# ✖ [email protected] — заблокирован
#   exposure:cooldown  Опубликован 2ч назад (политика требует 72ч)
#   Запустите для утверждения: trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# Утвердите переопределение, затем перепроверьте:
trustlock approve [email protected] \
  --override cooldown \
  --reason "Необходимо для функции X; безопасность подтверждена ревью команды" \
  --expires 7d

trustlock check
# ✔ [email protected] — допущен с утверждением

Рабочий процесс 4 — Сравнение профиля зависимостей между проектами

# Обнаружение расхождений версий и несоответствий происхождения в пакетах монорепозитория
trustlock audit --compare packages/frontend packages/backend packages/shared

Команды

Профили политик

trustlock поставляется с двумя встроенными профилями, выбираемыми через --profile:

# Использовать строгий профиль в CI
trustlock check --enforce --profile strict

Наследование политик организации

Команды могут централизовать политику в общем URL и расширять её для каждого репозитория:

{
  "extends": "https://policy.example.com/trustlockrc.json",
  "cooldown_hours": 96
}

Конфигурации репозиториев могут только ужесточать политику организации — защита от понижения порогов предотвращает снижение обязательных порогов организации.

Документация

• USAGE.md — Полная справка по командам, все флаги, коды завершения, сообщения об ошибках
• POLICY-REFERENCE.md — Все опции .trustlockrc.json
• ARCHITECTURE.md — Архитектурные решения и карта модулей
• examples/ — Примеры конфигураций и рабочих процессов CI

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

Добавьте trustlock в ваш пайплайн CI:

# GitHub Actions — см. examples/ci/github-actions.yml
- run: npx trustlock check --enforce

Смотрите examples/ для конфигураций GitHub Actions, Lefthook и Husky.

Где trustlock расположен во временной шкале

Trustlock оценивает изменения файла блокировки в момент фиксации. Он не перехватывает и не изолирует npm install. Если вредоносный пакет выполняет скрипт postinstall, он выполняется до того, как trustlock его увидит. Trustlock предотвращает фиксацию и слияние скомпрометированного файла блокировки, ограничивая радиус поражения одной машиной разработчика вместо всей команды и продакшена. Для блокировки скриптов во время установки используйте --ignore-scripts или стандартные средства управления скриптами жизненного цикла pnpm.

Что trustlock НЕ делает

• Не является сканером вредоносного ПО — trustlock не проверяет исходный код пакетов и не обнаруживает подписанные вредоносные сигнатуры. Используйте для этого специализированный сканер.
• Не является изолятором времени установки — trustlock не перехватывает npm install. Используйте для этого --ignore-scripts.
• Не является трекером уязвимостей (CVE) — используйте npm audit или Snyk для баз данных уязвимостей.
• Не является проверкой лицензий — используйте license-checker или аналоги.
• Не заменяет pnpm trustPolicy или npm min-release-age — это серверные средства контроля, применяемые реестром. trustlock — это клиентский шлюз допуска на границе репозитория.

О проекте

trustlock был создан из разочарования в том, насколько пассивен стандартный инструментарий Node.js в отношении того, что на самом деле попадает в проект. npm install загрузит что угодно — пакет, опубликованный две минуты назад, тот, который запускает произвольные скрипты при установке, тот, который за ночь переключился с tarball из реестра на git-URL — и единственная обратная связь, которую вы получаете, — это diff файла блокировки.

Угроза, которую решает trustlock, узкая, но реальная: промежуток между публикацией вредоносной версии и её удалением или обнаружением. Сканеры уязвимостей работают постфактум. trustlock работает в точке допуска, до того как что-либо попадает в ваш репозиторий или CI.

Дизайн намеренно минималистичен. trustlock не имеет зависимостей времени выполнения — сам по себе является инструментом с нулевым риском цепочки поставок. Он не заменяет сканер уязвимостей или аудит зависимостей; он обеспечивает непрерывность доверия. Как только версия попадает в вашу базовую линию, она считается доверенной. Всё новое должно заслужить допуск в соответствии с объявленной вами политикой.

Рабочий процесс утверждений существует для команд, которым требуется запасной выход без потери возможности аудита. Каждое переопределение имеет временную метку, ограничено конкретными правилами и имеет срок действия. clean-approvals — это полноценная команда, а не запоздалая мысль.