pkgxray — безопасность до установки для npm-пакетов, MCP-серверов и ИИ-агентов

Проверяйте npm-пакет или MCP-сервер до того, как установите или подключитесь к нему, и получайте детерминированный вердикт SAFE, REVIEW или BLOCK, подкреплённый доказательствами. Локальный статический анализ без зависимостей — обычные сканирования никогда не выполняют код пакета.

Сайт · Документация · Калибровка · Сообщить об ошибке

_{Реальные запуски: guard пропускает [email protected], затем блокирует образец, смоделированный по компрометации @solana/web3.js в 2024 году.}

Ключевые особенности

• Нулевые зависимости времени выполнения — чистый Node, работает полностью на вашей машине (статический проход ~25 мс).
• Обычные сканирования никогда не выполняют код пакета — tarball читается как байты в карантине.
• Детерминированные вердикты с доказательствами — каждая находка указывает файл и доказательство; в пути вынесения вердикта нет LLM, поэтому внедрённый текст не сможет им управлять.
• Создан для эпохи агентов — проверяйте MCP-серверы перед подключением, контролируйте установки, которые запускает агент, и повторно аудируйте активный MCP-трафик.
• Откалиброван и защищён от регрессий — ноль эвристических ложных блокировок среди топ-1000 самых скачиваемых пакетов, контроль в CI.

1. Быстрый старт · 2. Что сканирует и обнаруживает · 3. Вердикты · 4. Использование · 5. Интеграции · 6. Сравнение с аналогами · 7. Документация

Зачем

ИИ-ассистенты программирования устанавливают пакеты и подключаются к MCP-серверам на машинной скорости, часто без чтения кода человеком. Sonatype выявила более 454 600 новых вредоносных пакетов с открытым исходным кодом в отслеживаемых экосистемах в 2025 году, более 99% из них — в npm (Sonatype). npm audit спрашивает есть ли у этого известная CVE?; pkgxray также спрашивает что код реально делает — до того, как что-либо будет установлено.

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

1. Сканируйте заведомо безопасный пакет (устанавливать pkgxray не нужно):

npx --yes [email protected] guard npm:[email protected]

Он помещает tarball в карантин и выполняет статические проверки и проверки цепочки поставок — без npm install, без скриптов жизненного цикла, без выполнения кода пакета.

Decision: SAFE   Grade: A+ (99/100)
No high- or medium-risk indicators were found in the provided evidence.

Notes:
- INFO npm-vs-github-clean — npm tarball matches the linked GitHub repo at the
  published version. (15/16 files match GitHub @4.21.0)

2. Прочитайте вердикт:

SAFE — это не доказательство безвредности пакета; статический анализ не видит полезную нагрузку, загружаемую только во время выполнения. См. модель угроз.

3. Посмотрите BLOCK на прилагаемом инертном образце:

npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown

Образец — это инертный исходный текст, моделирующий чтение SSH-ключа через split-фрагменты и его эксфильтрацию — он никогда не выполняется. Он возвращает BLOCK (код выхода 2) с указанием файла и доказательств.

4. Добавьте его в свой рабочий процесс — повторные проверки и CI, MCP, установочный шлюз Hookshot.

Две модели выполнения. Сканирования guard и audit по умолчанию — статические — код пакета никогда не выполняется. Перечисление возможностей MCP-сервера может запустить его, и mcp-proxy выполняет его за шлюзом; опциональный canary — единственное намеренное исключение, которое выполняет пакет в песочнице для подтверждения поведения: он может подтвердить вредоносность, но никогда не докажет безопасность пакета. Полные границы: SECURITY.md.

Что сканирует и обнаруживает

Сканирует — pkgxray guard npm:name@version, github:owner/repo, локальную директорию, целые lock-файлы (npm, yarn, pnpm), MCP-серверы и расширения ИИ-агентов.

Обнаруживает — кражу учётных данных (включая пути с split-фрагментами), сбор метаданных облачных инстансов и хранилищ секретов, prompt-инъекции, Unicode-контрабанду, base64-нагрузки и загрузчики второй стадии, эксфильтрацию, персистентность (профиль оболочки, планировщик ОС и внедрённые CI/CD-конвейеры), самоудаляющиеся дропперы, репликацию registry-червей (npm publish во время установки), обфусцированное выполнение вычисляемых аргументов, известные CVE (через OSV, до загрузки), расхождение артефактов npm↔GitHub, троянизированные обновления (recheck) и злоупотребление поверхностью возможностей MCP.

Полная матрица покрытия — и известное слепое пятно «загрузка позже» — в модели угроз; таблица сравнения — на сайте.

Вердикты

Коды выхода стабильны и удобны для CI: 0 безопасно/разрешено · 2 блокировка · 3 проверка.

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

pkgxray guard npm:[email protected] [--format json]   # vet a package before install
pkgxray mcp --package npm:[email protected] npx some-mcp-server   # vet an MCP server; --recheck catches the rug-pull
pkgxray audit package-lock.json [--deep]               # also: yarn.lock, pnpm-lock.yaml, package.json
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

Один опциональный файл .pkgxray.json (читается каждой поверхностью) настраивает политику; нулевая конфигурация означает максимальную строгость. CVE нельзя исключить политикой, каждое ослабление выводится в лог, а сканирование, завершившееся ошибкой, по принципу fail-closed даёт review. Схема и инварианты: configuration.md · .pkgxray.example.json.

Интеграции

Один движок за каждой точкой входа. «Работает с» означает документированное руководство по настройке, а не интеграцию, одобренную вендором.

Сравнение с аналогами

Запускайте pkgxray вместе с npm audit / OSV-Scanner, а не вместо них — они отвечают на вопрос «известная ли это CVE?». В сравнении с инструментами той же ниши (поведенческая проверка цепочки поставок — Socket.dev, OpenSSF Package Analysis, Cisco MCP Scanner) полное сравнение возможностей — в docs/comparison.md и на сайте.

Обоснование

Калибровка «ноль ложных эвристических блокировок на топ-1000 самых скачиваемых пакетов» защищена от регрессий в CI (область и методология), а опубликованные прогоны находятся на pkgxray.ca/stats. Это утверждение ограничено набором самых устанавливаемых пакетов — это не заявление о нуле ложных блокировок на каждом пакете.

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

Начните с указателя документации.

Вклад в разработку

npm test                 # zero-dep node --test suite
npm run benchmark        # calibration corpus: precision/recall + 0-false-block gate
npm run validate:website # regenerate + validate the calibration pages

Пул-реквесты приветствуются — прочтите CONTRIBUTING.md и Кодекс поведения. Сообщайте об уязвимостях конфиденциально согласно SECURITY.md. Релизы публикуются в npm с провенансом (SLSA-аттестация) и проходят контроль тестами, калибровочным бенчмарком и собственной защитой цепочки поставок pkgxray.