Содержание

• Начало работы — от нуля до установки примерно за пять минут
• Что он делает
• Что его запускает
• Что в этом репозитории
• Поддерживаемые экосистемы
• Установка
  • Конфигурация
  • Изменение периода охлаждения
• Уровни предупреждений
• Как это работает
  • Обычный режим (ручной)
  • Режим перехвата (автоматический)
  • Режим перед установкой (Bash-хук)
  • Режим после установки (Bash-хук)
  • Режим после агента (пара хуков агента)
• Журнал аудита
• Требования
• FAQ

Начало работы

GETTING-STARTED.md проведёт вас от нуля до рабочей установки примерно за пять минут — предварительные требования, интерактивная установка и проверка. Для полного справочника по установке (глобальная/проектная/ручная установка, особенности Windows, список разрешённых разрешений, обновление и удаление) см. INSTALLATION.md.

Повседневное использование: после установки хуков ничего запускать не нужно — safer-dependencies работает автоматически в фоновом режиме. Когда Claude добавляет или устанавливает пакеты, он помечает рискованные зависимости и обновляет уязвимые версии до безопасной на месте — и блокирует установку с известной уязвимостью до её запуска — так что небезопасные пакеты обнаруживаются и исправляются без необходимости вас просить. Вы всё равно можете вызывать его напрямую в любое время: «безопасен ли [email protected]?», «проверь настройку safer-dependencies» или «покажи статистику safer-dependencies».

Что он делает

Когда Claude собирается добавить пакет в ваш проект, safer-dependencies перехватывает действие и выполняет 5 проверок:

1. Происхождение — официальный реестр, обнаружение typosquatting (npm/PyPI/RubyGems/Maven/crates.io), возраст пакета
2. Возраст версии — выбирает новейшую стабильную версию, опубликованную 7+ дней назад (окно охлаждения)
3. Сканирование уязвимостей — OSV API, с нативными инструментами экосистемы (npm audit, pip-audit, bundle audit), когда они доступны
4. Целостность hash-привязки — для строк PyPI requirements.txt с привязками --hash=sha256:... объявленный хэш проверяется на соответствие опубликованным хэшам PyPI; несовпадение выдаёт WARNING
5. Заброшенные и устаревшие пакеты — известные заброшенные пакеты (например, paperclip, request, pycrypto, github.com/dgrijalva/jwt-go) немедленно жёстко блокируются с предложенной заменой; пакеты без стабильного релиза в течение 2+ лет получают рекомендательное предупреждение STALE:. Жёстко заблокированные пакеты удаляются из манифеста, и Claude спросит, как действовать дальше; пакеты только с пометкой устаревших остаются на месте.

Если обнаружены проблемы, Claude выдаёт предупреждения и может отступить к более безопасной версии. Все проверки записываются в ~/.claude/safer-dependencies-audit-YYYY-MM.log (один файл на календарный месяц).

Что его запускает

Навык срабатывает автоматически, когда Claude:

Операции с манифестом / установкой

• Добавляет или обновляет пакет в package.json, requirements.txt, Gemfile, pom.xml, build.gradle, Cargo.toml, go.mod или любом другом поддерживаемом манифесте
• Записывает import, require или use для пакета, ещё не объявленного в манифесте
• Генерирует или обновляет lock-файл (проверяются только новые/изменённые записи)
• Запускает установку через менеджер пакетов через Bash (npm install, bundle install, poetry install, uv sync, go mod tidy и т. д.) — Pre-Install проверяет аргументы команды, Post-Install проверяет полученный lock-файл
• Записывает Dockerfile или CI-пайплайн (.github/workflows/*.yml и т. д.), содержащие шаги установки с закреплёнными версиями через менеджер пакетов

Вопросы выбора и рекомендаций

• Сравнение библиотек/фреймворков: «стоит ли использовать axios или node-fetch?», «moment vs dayjs?», «что лучше X или Y?»
• Запросы рекомендаций: «какой хороший HTTP-клиент для Python?», «порекомендуй библиотеку логирования для Go», «какой пакет обрабатывает CSV в Node?»
• Выбор версии: «какую версию Django мне использовать?», «последний стабильный Flask?»

Выражения намерения использовать (до добавления)

• «Я хочу использовать FastAPI для этого», «я думаю добавить Celery», «мы рассматриваем Prisma как ORM», «давай используем Tailwind»

Вопросы о здоровье и доверии к пакетам

• «moment.js всё ещё поддерживается?», «этот gem ещё активен?», «X заброшен?», «X достиг конца жизни (EOL)?», «можно ли доверять этому пакету?», «когда faker обновлялся в последний раз?»

Команды скаффолдинга

• npx create-react-app, npm create vite@latest, django-admin startproject, rails new, cargo new + cargo add, «создай новый проект FastAPI»

Неявные добавления пакетов (запросы функций, подразумевающие новую зависимость)

• «Добавь кэширование Redis в приложение», «подключись к Postgres», «добавь JWT-аутентификацию», «напиши код для отправки email» — срабатывает, когда в манифесте ещё нет пакета для этой возможности

Миграция и перенос

• «Мигрируй с requests на httpx», «перейди с CRA на Vite», «перенеси с moment на date-fns» — проверяет входящий пакет

Он не срабатывает для:

• Импортов из стандартной библиотеки (os, fs, java.util.* и т. д.)
• Уже объявленных зависимостей, которые не изменяются
• Академического обсуждения внутренней работы пакета («объясни reconciler в React», «как работает модульное разрешение webpack?») — вопросы сравнения и выбора всё же срабатывают
• Установки приложений уровня ОС, сред выполнения или расширений IDE (сам Python, Docker, Homebrew, расширения VS Code)

Что в этом репозитории

Это набор навык + хуки, а не один файл навыка. Полная установка разворачивает следующие компоненты:

Одного файла навыка недостаточно — без хуков автоматический вызов зависит от того, решит ли Claude обратиться к навыку. Установите все пять компонентов для полного покрытия; многие навыки и слэш-команды внутренне отправляют субагентов, поэтому пара Post-Agent важна, даже если вы никогда явно не запускаете субагента. (См. FAQ.md о том, почему навык сам по себе не может гарантировать покрытие.)

Поддерживаемые экосистемы

Установка

Новичок в проекте? Начните с GETTING-STARTED.md. Краткая версия:```bash git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

Те же глаголы работают и вне сеанса Claude:```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14

Родительский агент использует эти сигналы для выявления затронутого кода и его рефакторинга по мере необходимости.

Режим предварительной установки (Bash-хук)

Настройте .claude/settings.json с хуком PreToolUse:Bash, чтобы включить предварительную проверку команд установки пакетного менеджера. Это дополняет (но не заменяет) режим перехвата — вместе они образуют многоуровневую защиту.

1. Claude пытается выполнить вызов Bash-инструмента (например, npm install [email protected])
2. Хук PreToolUse срабатывает до выполнения вызова и запускает safer-dependencies-pretooluse-bash.sh
3. Чистый bash-фильтр раннего этапа отсекает команды, не относящиеся к пакетным менеджерам, примерно за 115 мс (без вызова Python), поэтому git status / ls / npm test несут незначительные издержки на горячем пути
4. Для распознанных установок пакетных менеджеров (npm/pnpm/yarn install/i/add) помощник разбивает команду на токены через shlex, извлекает каждый аргумент pkg@version и отправляет POST-запрос в OSV
5. Любая уязвимая конкретная версия → хук возвращает permissionDecision: "deny" с идентификатором GHSA для каждой находки + CVSS + кратким описанием, а также подсказкой вызвать навык safer-dependencies
6. Установка не выполняется — ни сетевых запросов, ни postinstall-скриптов

Зачем это нужно в дополнение к режиму перехвата: пост-записывающий шим не видит Bash. npm install [email protected] выполняется до конца (и postinstall-скрипты запускаются) до того, как сработает аудит; npm install -g typosquat-pkg вообще не записывает манифест проекта. Режим предварительной установки структурно закрывает эти пробелы.

Режим предварительной установки видит только то, что пользователь ввёл (аргументы pkg@version в командной строке). Он не видит транзитивное дерево, которое резолвер фактически установит. Режим после установки (ниже) проверяет lockfile после завершения установки — эти два режима дополняют друг друга, а не дублируют.

Область применения: CLI пакетных менеджеров, охваченные здесь, покрывают пять экосистем (npm/pnpm/yarn/bun/npx/deno, pip/pip3/pipx/pipenv/uv/uvx/poetry, gem/bundle, go, cargo), плюс Maven через режим перехвата (зависимости Maven обычно объявляются в pom.xml/build.gradle, а не добавляются через CLI-команду).

Известный пробел: CLI Maven поддерживает прямую загрузку через mvn dependency:get -Dartifact=group:art:version и mvn dependency:copy. Этот хук пока не распознаёт такие вызовы. Если вы используете их регулярно, существующий пост-записывающий шим всё равно перехватит всё, что попадёт в ваш манифест, но защита до загрузки применяется только к экосистемам, перечисленным выше. Отслеживается как последующая задача.

Распознаваемый синтаксис по экосистемам:

Диапазонные версии (npm ^4.17, pip >=, poetry ^/~, Go @latest) и неуказанные версии передаются в режим перехвата после установки — пост-записывающий шим проверяет всё, что выберет резолвер. Автоматическая перезапись на безопасную версию запланирована как последующая задача.

Режим отказа: отказ-открытый. Любая ошибка (отсутствие Python, сбой сети, некорректный ввод) завершается кодом 0 без вывода, позволяя bash продолжить работу. Режим перехвата всё равно запускается после установки, поэтому сбой предварительной проверки плавно деградирует до существующей защиты.

Пример отказа:``` safer-dependencies pre-flight audit blocked this install. Vulnerable pinned version(s) detected:

• [email protected] → GHSA-35jh-r3h4-6jhm (CVSS:7.4): Command Injection in lodash Re-run with a patched version, or invoke the safer-dependencies skill for a recommended pin.

Режим после агента (пара хуков агента)

Четыре режима выше срабатывают только для вызовов инструментов корневой сессии. Когда корневая сессия отправляет субагента (через инструмент Agent — многие навыки и слэш- команды делают это внутренне), вызовы Write/Edit/Bash субагента обходят все эти режимы. Режим после агента — это реактивная страховочная сеть для этого пробела.

1. Хук PreToolUse:Agent (safer-dependencies-pretooluse-agent.sh) запускается непосредственно перед каждой отправкой агента и создаёт файл-маркер в /tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel (с откатом к имени только с PPID, когда идентификатор сессии недоступен)
2. Субагент выполняется и может записывать манифесты или файлы блокировок
3. Хук PostToolUse:Agent (safer-dependencies-posttooluse-agent.sh) запускается после возврата вызова агента, находит с помощью find каждый манифест и файл блокировки новее маркера и проверяет каждый через тот же путь шима
4. Результаты отображаются как additionalContext для следующего хода корневой сессии; маркер удаляется

Вложенные субагенты покрываются автоматически — PostToolUse:Agent корневой сессии срабатывает только после того, как вся работа внешнего агента (включая всё, что он отправил) окажется на диске. Единственный пробел — глобальная установка, которая не записывает манифест или файл блокировки (npm install -g …): сканировать нечего. Как и другие хуки, он завершается открыто — любая ошибка (отсутствующий маркер, отсутствующий шим, нечитаемая полезная нагрузка) молча выходит с кодом 0. Полное обоснование дизайна находится в skills/safer-dependencies.md.

Журнал аудита

Каждая проверка записывается в ~/.claude/safer-dependencies-audit-YYYY-MM.log (один файл на календарный месяц, где YYYY-MM — год-месяц по UTC) как одна строка JSON. Переопределите полный путь с помощью переменной окружения SAFE_DEP_AUDIT_LOG (при её установке суффикс даты не добавляется). Файлы также ротируются по размеру, когда превышают SAFE_DEP_LOG_MAX_BYTES (по умолчанию 10 МиБ; установите 0 для отключения). Установите SAFE_DEP_MODEL, чтобы переопределить значение модели, записываемое в source.model в каждой записи — полезно для A/B-сравнений между версиями моделей.

Все пять режимов добавляют записи в один и тот же файл. Каждая запись содержит блок source (схема 2.2), определяющий, какой компонент её записал:

source.model записывает модель Claude Code, активную в сессии (например, "claude-sonnet-4-6"). Присутствует в схеме 2.1+; записи, созданные более старыми установками, опускают это поле. Команда статистики корректно переходит к "unknown", когда оно отсутствует.

Фильтруйте по source.component с помощью jq:```bash jq -r '.source.component' audit.log | sort | uniq -c | sort -rn jq -c 'select(.source.component == "bash.pretooluse")' audit.log

Surface every silent fail-open across all hooks:

jq -c 'select(.source.mode == "fail_open") | {component: .source.component, reason: .fail_open.reason, ts}' audit.log

Это предоставляет удобочитаемые сводки активности, влияния на безопасность и показателей производительности, извлечённые из этих журналов аудита.

Формы записей (схема 2.2). Три различные формы используют один и тот же заголовок ts / schema / source:

Записи аудита: режим перехвата (Intercept Mode) выполняет полный конвейер (происхождение, возраст версии, OSV, abandoned/stale, typosquat, подписи), поэтому все массивы могут заполняться. Режим предварительной установки (Pre-Install Mode) сегодня выполняет только OSV, поэтому abandoned / stale / typosquat / signatures всегда пусты. Отправка после установки (аудит lockfile) записывается под shim.posttooluse с findings, заполняемыми строками WARNING: от аудиторов lockfile. Массив notes содержит информационные сигналы NOTE: (например, манифест пропущен, так как не закреплён).

Схема 2.2 добавила — аддитивно — четыре поля к lockfile-записям аудита: lockfile, manifest_ref, relation_summary (классификация direct/transitive/unknown каждого отмеченного пакета относительно парного манифеста) и блок policy, фиксирующий действующий уровень transitive. Это обновление обратно совместимо: читатели записей 2.1 допускают новые поля, а поле source.model остаётся присутствующим начиная с 2.1.```json { "ts": "2026-04-19T12:34:56Z", "schema": "2.2", "source": { "component": "shim.posttooluse", "script": "shim.sh", "hook": "PostToolUse:Write", "tool": "Write", "mode": "intercept", "model": "claude-sonnet-4-6" }, "file": "/path/to/project/package.json", "ecosystem": "npm", "checked": ["[email protected]", "[email protected]"], "findings": ["UPDATED: express 4.18.2 → 4.22.1 (HIGH: 1 CVE fixed)"], "abandoned": [], "stale": [], "typosquat": [], "unknown": [], "signatures": [], "notes": [], "clean": ["[email protected]"] }

Fail-open Mode example (Post-Install Bash hook called with no shim adjacent — broken install):```json { "ts": "2026-05-03T07:14:11Z", "schema": "2.2", "source": { "component": "bash.posttooluse", "script": "safer-dependencies-posttooluse-bash.sh", "hook": "PostToolUse", "tool": "Bash", "mode": "fail_open", "model": "claude-sonnet-4-6" }, "fail_open": { "reason": "shim_missing", "detail": "/home/alice/.claude/skills/safer-dependencies" } }