clidey/deptrustCLI и MCP-сервер, который проверяет версии пакетов на наличие известных уязвимостей в 14+ экосистемах, включая npm, PyPI, crates.io, Go modules и GitHub Actions. Интегрируется с AI-агентами через хуки и скиллы.
# deptrust
```text
__ __ __
___/ /___ ___ / /________ _______/ /_
/ _ / __ \/ _ \/ __/ ___/ / / / ___/ __/
/ __/ /_/ / __/ /_/ / / /_/ (__ ) /_
\__,_/\____/ .___/\__/_/ \__,_/____/\__/
/_/
```
deptrust — это CLI, который проверяет версии пакетов на известные уязвимости в npm, PyPI, crates.io, Go-модулях, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage, GitHub Actions и других экосистемах.
Он работает локально как CLI и как MCP-сервер. Он напрямую обращается к API публичных реестров пакетов и OSV; не существует размещённого сервиса deptrust, которому нужно доверять или который нужно настраивать.
Этот инструмент родился из разочарования тем, что AI-агенты постоянно используют старые версии.
## Содержание
- [Область применения](#scope)
- [Использование CLI](#cli-usage)
- [Установка](#install)
- [Настройка агента](#agent-setup)
- [Ручная настройка MCP](#manual-mcp-setup)
- [MCP-инструменты](#mcp-tools)
- [Использование только со скиллом](#skill-only-use)
- [Устранение неполадок](#troubleshooting)
## Область применения
Поддерживаемые экосистемы:
- npm, включая scoped-пакеты, такие как `@clidey/ux`
- PyPI
- Cargo / crates.io
- Go-модули
- RubyGems
- NuGet
- Maven, с использованием имён пакетов `groupId:artifactId`
- Packagist / Composer, с использованием имён пакетов `vendor/package`
- pub.dev
- CocoaPods
- Hex.pm
- Hackage
- GitHub Actions, с использованием имён пакетов `owner/repo`, а также тегов, ссылок на ветки или SHA коммитов в качестве версий
deptrust в настоящее время сообщает об известных уязвимостях и даёт простую рекомендацию:
| Наивысшая известная серьёзность | Рекомендация |
| --- | --- |
| critical | block |
| high | block |
| medium / unknown | review |
| low | allow |
| none found | allow |
`allow` означает, что в публичных источниках данных не найдено ни одной блокирующей известной уязвимости. Это не доказывает, что пакет безопасен.
deptrust также выдаёт сигналы риска, которые не являются CVE. Например, версия, опубликованная за последние 72 часа, помечается для review, чтобы агент не устанавливал вслепую только что вышедший релиз.
Поставщики advisory опрашиваются параллельно:
- OSV
- GitHub Advisory Database, включая проверенные advisory и advisory о вредоносном ПО
Охват поставщиков зависит от экосистемы. Если deptrust может получить метаданные реестра, но ни один настроенный поставщик уязвимостей не поддерживает эту экосистему, он возвращает `unknown` вместо того, чтобы считать пакет безопасным.
Охват поставщиков:
| Экосистема | Метаданные реестра | OSV | GitHub Advisory DB |
| --- | --- | --- | --- |
| npm | да | да | да |
| PyPI | да | да | да |
| Cargo / crates.io | да | да | да |
| Go-модули | да | да | да |
| RubyGems | да | да | да |
| NuGet | да | да | да |
| Maven | да | да | да |
| Packagist / Composer | да | да | да |
| pub.dev | да | да | да |
| CocoaPods | да | нет | да |
| Hex.pm | да | да | да |
| Hackage | да | да | нет |
| GitHub Actions | да | да | да |
JSON-вывод содержит поля покрытия advisory:
- `checked_providers`: поставщики уязвимостей, к которым deptrust фактически обращался
- `skipped_providers`: настроенные поставщики, пропущенные из-за неподдерживаемой экосистемы
- `advisory_coverage`: `full`, `partial`, `none` или `error`
- `advisory_coverage_reason`: краткое объяснение значения покрытия
- `registry_verification`: `verified`, когда метаданные реестра подтвердили версию, или `unverified`, когда проверка точной версии продолжилась после временного сбоя реестра
- `registry_verification_reason`: ошибка реестра, когда проверка была недоступна
Проверка точной версии по-прежнему опрашивает поставщиков advisory, когда проверка реестра временно недоступна. Такой результат всегда непригоден к установке и никогда не получает рекомендацию `allow`. Проверки `latest`, неизвестных пакетов и заведомо несуществующих версий по-прежнему требуют успешного разрешения в реестре.
HTTP-запросы повторяются при ответах `429`, `502`, `503` и `504` до трёх попыток суммарно. Повторы используют короткие экспоненциальные задержки и учитывают значения `Retry-After` до двух секунд; более длительные ожидания, запрошенные сервером, быстро прерываются, чтобы CLI не зависал. Когда повторы advisory исчерпаны, результат становится неполным, и рекомендация `allow` не выдаётся.
### Аутентификация GitHub API
Запросы к GitHub Advisory Database и GitHub Actions API могут использовать кратковременный токен GitHub App с минимальными привилегиями. В CI передавайте его через `DEPTRUST_GITHUB_TOKEN`:
```bash
DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20
```
Приоритет учётных данных: `DEPTRUST_GITHUB_TOKEN`, затем `GITHUB_TOKEN`, затем `GH_TOKEN`. Для локального использования резервный вариант через GitHub CLI включается явно с помощью `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`; он выполняет `gh auth token` без запросов. Если учётные данные недоступны, DepTrust продолжает работу без аутентификации. Ошибка ограничения скорости GitHub API или прав доступа даёт результат `unknown` с диагностикой и никогда не расценивается как успех только по OSV.
DepTrust никогда не хранит, не встраивает, не кэширует, не регистрирует в журналах, не телеметрирует и не выводит токены GitHub. Заголовки аутентификации отправляются только на `https://api.github.com`.
## Использование CLI
Проверьте точную версию:
```bash
deptrust check npm lodash 4.17.20
```
Пример обычного ответа:
```text
npm [email protected]: 2 known vulnerabilities found
recommendation: block
risk_score: 80
```
Проверьте последнюю версию:
```bash
deptrust check pypi requests latest
```
Выведите JSON:
```bash
deptrust check --json cargo serde latest
```
Проверьте Go-модуль:
```bash
deptrust check go golang.org/x/crypto latest
```
Проверьте RubyGems, NuGet или Maven:
```bash
deptrust check rubygems rails latest
deptrust check nuget Newtonsoft.Json latest
deptrust check maven org.apache.logging.log4j:log4j-core latest
```
Проверьте Packagist, pub.dev, CocoaPods, Hex.pm, Hackage или GitHub Actions:
```bash
deptrust check packagist monolog/monolog latest
deptrust check pub http latest
deptrust check cocoapods AFNetworking latest
deptrust check hex plug latest
deptrust check hackage aeson latest
deptrust check github-actions actions/checkout v7.0.0
deptrust check github-actions actions/checkout main
```
Для GitHub Actions полные SHA коммитов считаются зафиксированными (pinned). Полные semver-теги, такие как `v4.2.2`, принимаются без дополнительного сигнала фиксации. Теги только с мажорной версией, такие как `v4`, и ссылки на ветки, такие как `main`, являются допустимыми ссылками, но deptrust добавляет сигнал review, поскольку они могут перемещаться.
Пример JSON-ответа:
```json
{
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20",
"latest_version": "4.17.21",
"known_vulnerabilities_found": true,
"safe_to_use": false,
"should_install": false,
"risk_score": 80,
"recommendation": "block",
"classification": "vulnerable",
"reason": "Found 2 known vulnerability records.",
"next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
"summary": "lodash 4.17.20 has 2 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
"signals": [],
"checked_providers": [
"OSV",
"GitHub Advisory DB"
],
"skipped_providers": [],
"advisory_coverage": "full",
"advisory_coverage_reason": "all configured vulnerability providers were checked",
"registry_verification": "verified",
"vulnerabilities": [
{
"id": "GHSA-35jh-r3h4-6jhm",
"aliases": [
"CVE-2021-23337"
],
"cve_ids": [
"CVE-2021-23337"
],
"ghsa_ids": [
"GHSA-35jh-r3h4-6jhm"
],
"summary": "Command Injection in lodash",
"severity": "high",
"source": "OSV",
"advisory_url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm",
"affected_ranges": [
"SEMVER: introduced 0, fixed 4.17.21"
],
"fixed_versions": [
"4.17.21"
],
"references": [
{
"type": "ADVISORY",
"url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm"
}
]
}
],
"provider_errors": []
}
```
Предлагайте последнюю версию только тогда, когда известных уязвимостей не найдено:
```bash
deptrust suggest npm lodash
```
Если последняя версия не разрешена, `suggest` проверяет более старые известные версии и возвращает самую новую версию с рекомендацией `allow`.
Когда advisory содержат исправленные версии, `suggest` сначала проверяет эти указанные поставщиком исправленные версии, а затем проходит по списку версий реестра в обратном порядке.
Сравните две версии:
```bash
deptrust compare npm lodash 4.17.20 4.17.21
```
Пример ответа на сравнение:
```text
lodash 4.17.20 -> 4.17.21 improves risk: score 80 to 0.
recommendation: allow
next_action: upgrade_to_target
```
Покажите установленную версию:
```bash
deptrust version
```
## Установка
Проще всего установить через `npx` или `pnpx`:
```bash
npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install
```
Установщик по умолчанию работает в интерактивном режиме с подсказками. Он устанавливает бинарный файл, спрашивает, какие интеграции агентов настроить, выводит пути назначения на уровне пользователя перед любыми изменениями и запрашивает подтверждение. Интерактивный установщик по умолчанию включает MCP, резервный скилл и хуки безопасности зависимостей для Codex и Claude Code. Добавьте `--yes` для неинтерактивной установки только бинарного файла или передайте явные флаги интеграций.
Повторный запуск установщика безопасен. Он молча оставляет без изменений конфигурации MCP, скилла и хуков. Если интеграция указывает на старый бинарный файл deptrust или его управляемая конфигурация изменилась, установщик обновляет её автоматически; пользователям не нужно вручную удалять и заново добавлять MCP-серверы. Кастомизированные скиллы сохраняются в резервную копию перед заменой.
Чтобы удалить бинарный файл, скилл и записи MCP на уровне пользователя:
```bash
npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall
```
Пользователи Homebrew могут установить из Clidey tap:
```bash
brew install clidey/tap/deptrust
```
Или сначала добавьте tap, затем устанавливайте и обновляйте как обычно:
```bash
brew tap clidey/tap
brew install deptrust
brew upgrade deptrust
```
Homebrew выводит напоминание после установки. Чтобы запустить интерактивную настройку Codex и Claude Code с использованием самого Homebrew-бинарного файла (регистрации MCP и хуки безопасности зависимостей):
```bash
deptrust setup
```
Интерактивная настройка запрашивает разрешение перед включением MCP и хуков безопасности зависимостей. Она не трогает регистрации, которые уже используют текущий бинарный файл, и приводит в соответствие существующие регистрации DepTrust, указывающие на более старый путь установки через npm, Homebrew или из исходников.
Пользователи Go могут установить напрямую:
```bash
go install github.com/clidey/deptrust/cmd/deptrust@latest
```
### Nix
Проект предоставляет опциональные выводы Nix flake для пользователей, которые уже используют Nix. Flake оборачивает предварительно собранный релизный бинарный файл.
```bash
# Run without installing
nix run github:clidey/deptrust
# Install into your profile
nix profile install github:clidey/deptrust
```
Обычный [рабочий процесс релиза](https://github.com/clidey/deptrust/blob/main/.github/workflows/release.yml) генерирует Nix-хеши из тех же архивов, которые публикует, оценивает flake перед публикацией, затем собирает и запускает его против опубликованных артефактов перед обновлением ветки по умолчанию. `github:clidey/deptrust` может кратковременно отставать, пока выполняется этот рабочий процесс. Теги релизов указывают на коммит исходников до сгенерированного обновления flake и могут по-прежнему ссылаться на предыдущий бинарный файл; когда воспроизводимость важна, фиксируйте коммит, чей `flake.nix` содержит нужную вам версию.
### Devbox
Для воспроизводимых сред разработки используйте Devbox:
```bash
# Install Devbox first (if not already installed)
curl -fsSL https://get.jetify.dev/devbox | bash
# Initialize the environment
devbox shell
# Build the project
devbox run build
```
`devbox.json` ограничивает версию инструментария, а зафиксированный в репозитории `devbox.lock` закрепляет точные версии пакетов и ревизии nixpkgs. Выполняйте `devbox update`, когда намеренно хотите обновить эти закреплённые версии.
Или установите Devbox через Homebrew:
```bash
brew install jetify-com/devbox/devbox
```
## Настройка агента
Чтобы установить deptrust и зарегистрировать всё, что установщик может настроить, без интерактивных подсказок:
```bash
npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all
```
`--all` устанавливает бинарный файл, регистрирует Codex MCP, когда доступен CLI `codex`, устанавливает резервный скилл Codex, регистрирует Claude Code MCP, когда доступен CLI `claude`, и устанавливает хуки безопасности зависимостей для Codex и Claude Code.
Эти хуки — хуки `PreToolUse`. Они проверяют команды установки пакетов до их выполнения, а также проверяют GitHub Actions, добавленные в файлы рабочих процессов через инструменты редактирования файлов агента. Хук блокирует вызов инструмента, когда deptrust возвращает `review`, `block` или `unknown`. Установщик записывает только конфигурацию хуков на уровне пользователя: `~/.codex/hooks.json` для Codex и `~/.claude/settings.json` для Claude Code.
Когда доступен CLI `gh`, интерактивная настройка также предлагает использовать его существующий локальный вход для проверок хуков. При этом записывается только `DEPTRUST_GITHUB_AUTH=gh`, никогда не токен GitHub, чтобы подпроцессы хуков могли избежать ограничений скорости неаутентифицированного GitHub API.
При желании используйте более точечные установки:
```bash
npx @clidey/deptrust install --codex-mcp
npx @clidey/deptrust install --claude-code-mcp
npx @clidey/deptrust skills install
pnpx @clidey/deptrust@latest install --codex-mcp
pnpx @clidey/deptrust@latest install --claude-code-mcp
pnpx @clidey/deptrust@latest skills install
```
После настройки MCP агенты будут автоматически проверять пакеты перед тем, как рекомендовать обновления или изменения. MCP-сервер отправляет инструкции проверять все версии зависимостей — в том числе при ответах на вопросы вроде «что я могу обновить» или «какие зависимости безопасно обновлять» — перед выдачей рекомендаций.
Если вы используете deptrust вне контекста MCP, напомните своему агенту:
```text
Before listing, comparing, or recommending specific package versions, check them with deptrust. This includes answering "what can I update" — do not provide version recommendations until after checking for known vulnerabilities.
```
Для CI настройте кратковременный токен GitHub App с минимальными привилегиями как `DEPTRUST_GITHUB_TOKEN` для процесса, выполняющего DepTrust. Для локальной аутентификации через GitHub CLI используйте `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`. DepTrust никогда не хранит токены.
## Ручная настройка MCP
Если ваш клиент поддерживает stdio MCP-серверы, настройте его на запуск:
```bash
/absolute/path/to/deptrust mcp
```
Многие клиенты используют такую JSON-структуру:
```json
{
"mcpServers": {
"deptrust": {
"command": "/absolute/path/to/deptrust",
"args": ["mcp"]
}
}
}
```
Для Codex вы также можете добавить его с помощью:
```bash
codex mcp add deptrust -- /absolute/path/to/deptrust mcp
```
Для Claude Code:
```bash
claude mcp add --transport stdio deptrust -- /absolute/path/to/deptrust mcp
```
При `initialize` сервер возвращает MCP `instructions`, сообщающие агенту, когда обращаться к этим инструментам (перед добавлением, обновлением или рекомендацией зависимости, или когда спрашивают, безопасно ли обновлять версию). Клиенты, отображающие серверные инструкции, применяют это автоматически, поэтому ручное напоминание выше является опциональным, а не обязательным.
## MCP-инструменты
### `check_package`
Проверяет версию пакета и возвращает известные уязвимости, а также рекомендацию.
```json
{
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20"
}
```
`version` может быть опущено или установлено в `latest`. Если точной версии не существует, deptrust возвращает ошибку и предлагает последнюю явно указанную версию.
Вывод MCP намеренно компактен, чтобы агенты могли решить, устанавливать ли зависимость, не подтягивая полные тексты advisory в контекст. Если пользователь просит показать полные сведения, агент может выполнить `full_response_command`.
Пример компактного структурированного вывода MCP:
```json
{
"ecosystem": "npm",
"package": "vite",
"version": "7.0.0",
"latest_version": "8.0.16",
"known_vulnerabilities_found": true,
"safe_to_use": false,
"should_install": false,
"risk_score": 80,
"classification": "vulnerable",
"recommendation": "block",
"reason": "Found 7 known vulnerability records.",
"next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
"summary": "vite 7.0.0 has 7 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
"vulnerability_count": 7,
"vulnerability_counts": {
"critical": 0,
"high": 2,
"medium": 3,
"low": 2,
"unknown": 0
},
"highest_severity": "high",
"checked_providers": [
"OSV",
"GitHub Advisory DB"
],
"skipped_providers": [],
"advisory_coverage": "full",
"advisory_coverage_reason": "all configured vulnerability providers were checked",
"registry_verification": "verified",
"full_response_command": "deptrust check --json npm vite 7.0.0"
}
```
Компактный ответ MCP опускает массив уязвимостей, `details` advisory и повторяющиеся `references`. По умолчанию агенты должны использовать счётчики, наивысшую серьёзность, охват поставщиков, рекомендацию и следующее действие. Если пользователь запрашивает полные сведения advisory, выполните `full_response_command`.
Когда доступ к GitHub advisory ограничен по скорости или недоступен, MCP возвращает `unknown`. Агент должен активно предложить настроить токен и повторить попытку, пропустить или отложить версию либо продолжить только после того, как пользователь явно примет неразрешённый риск покрытия GitHub для этой точной версии. Это исключение должно оставаться чётко помеченным как принятая пользователем неопределённость; его нельзя сообщать как `allow` или как доказательство безопасности версии.
### `suggest_safe_version`
Сначала проверяет последнюю версию. Если последняя не разрешена, сначала проверяет указанные поставщиком исправленные версии, затем более старые известные версии и предлагает самую новую версию с рекомендацией `allow`.
```json
{
"ecosystem": "npm",
"package": "lodash"
}
```
### `compare_versions`
Сравнивает текущую версию с целевой, включая устранённые и добавленные уязвимости.
```json
{
"ecosystem": "npm",
"package": "lodash",
"from_version": "4.17.20",
"to_version": "4.17.21"
}
```
## Использование только со скиллом
Если вы не хотите использовать MCP, установите встроенный скилл Codex:
```bash
npx @clidey/deptrust skills install
```
Скилл указывает Codex вызывать CLI `deptrust` перед установкой, обновлением или рекомендацией пакетов из npm, PyPI, Cargo, Go-модулей, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage и GitHub Actions.
## Устранение неполадок
Если `deptrust` не найден:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
Если MCP-клиент не может запустить сервер, найдите полный путь:
```bash
which deptrust
```
Затем укажите этот абсолютный путь в конфигурации MCP.
Если проверка пакета возвращает `unknown`, не считайте пакет безопасным. Это означает, что deptrust не смог получить полный ответ от поставщика advisory или не смог проверить точную версию в его реестре.