adamsjack711-ux/pkgxrayБезопасность перед установкой для AI-агентов, npm-пакетов и MCP-серверов. Локальный статический анализ без внешних зависимостей; обычные сканирования никогда не выполняют код пакетов.
<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — анализируйте пакеты до их установки" width="820"> # pkgxray — безопасность до установки для npm-пакетов, MCP-серверов и ИИ-агентов Проверяйте npm-пакет или MCP-сервер **до** того, как установите или подключитесь к нему, и получайте детерминированный вердикт `SAFE`, `REVIEW` или `BLOCK`, подкреплённый доказательствами. Локальный статический анализ без зависимостей — обычные сканирования никогда не выполняют код пакета. [](https://www.npmjs.com/package/pkgxray) [](https://www.npmjs.com/package/pkgxray) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-test.yml) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-benchmark.yml) [](LICENSE) [**Сайт**](https://pkgxray.ca) · [**Документация**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**Калибровка**](https://pkgxray.ca/stats) · [**Сообщить об ошибке**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="pkgxray guard пропускает [email protected] с вердиктом SAFE A+, затем блокирует троянизированный образец с вердиктом BLOCK F и находкой HIGH по доступу к учётным данным" width="820"> <sub>Реальные запуски: <code>guard</code> пропускает <code>[email protected]</code>, затем блокирует образец, смоделированный по компрометации <code>@solana/web3.js</code> в 2024 году.</sub> </div> ## Ключевые особенности - **Нулевые зависимости времени выполнения** — чистый Node, работает полностью на вашей машине (статический проход ~25 мс). - **Обычные сканирования никогда не выполняют код пакета** — tarball читается как байты в карантине. - **Детерминированные вердикты с доказательствами** — каждая находка указывает файл и доказательство; в пути вынесения вердикта нет LLM, поэтому внедрённый текст не сможет им управлять. - **Создан для эпохи агентов** — проверяйте MCP-серверы перед подключением, контролируйте установки, которые запускает агент, и повторно аудируйте активный MCP-трафик. - **Откалиброван и защищён от регрессий** — ноль эвристических ложных блокировок среди топ-1000 самых скачиваемых пакетов, контроль в CI. > **[1. Быстрый старт](#quick-start)** · [2. Что сканирует и обнаруживает](#what-it-scans--detects) · [3. Вердикты](#verdicts) · [4. Использование](#usage) · [5. Интеграции](#integrations) · [6. Сравнение с аналогами](#how-it-compares) · [7. Документация](#documentation) ## Зачем ИИ-ассистенты программирования устанавливают пакеты и подключаются к MCP-серверам на машинной скорости, часто без чтения кода человеком. Sonatype выявила **более 454 600 новых вредоносных пакетов с открытым исходным кодом в отслеживаемых экосистемах в 2025 году**, более 99% из них — в npm ([Sonatype](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)). `npm audit` спрашивает *есть ли у этого известная CVE?*; pkgxray также спрашивает *что код реально делает* — до того, как что-либо будет установлено. ## Быстрый старт **1. Сканируйте заведомо безопасный пакет** (устанавливать pkgxray не нужно): ```bash npx --yes [email protected] guard npm:[email protected] ``` Он помещает tarball в карантин и выполняет статические проверки и проверки цепочки поставок — без `npm install`, без скриптов жизненного цикла, без выполнения кода пакета. <details> <summary>Пример вывода</summary> ```text 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) ``` </details> **2. Прочитайте вердикт:** | Вердикт | Код выхода | Значение | |---|---:|---| | `SAFE` | `0` | Нет индикаторов высокого или среднего риска; политика по умолчанию разрешает продвижение. | | `REVIEW` | `3` | Доказательства неполны, или привилегированная возможность требует проверки человеком. | | `BLOCK` | `2` | Приведены доказательства высокой серьёзности — отклонить или расследовать. | `SAFE` — это не доказательство безвредности пакета; статический анализ не видит полезную нагрузку, загружаемую только во время выполнения. См. [модель угроз](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md). **3. Посмотрите BLOCK на прилагаемом инертном образце:** ```bash npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown ``` Образец — это инертный исходный текст, моделирующий чтение SSH-ключа через split-фрагменты и его эксфильтрацию — **он никогда не выполняется**. Он возвращает `BLOCK` (код выхода `2`) с указанием файла и доказательств. **4. Добавьте его в свой рабочий процесс** — [повторные проверки и CI](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck), [MCP](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#the-pkgxray-mcp-server), [установочный шлюз Hookshot](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot). > **Две модели выполнения.** Сканирования `guard` и `audit` по умолчанию — **статические** — > код пакета никогда не выполняется. Перечисление возможностей MCP-сервера может запустить его, и > `mcp-proxy` выполняет его за шлюзом; опциональный > [`canary`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) — единственное намеренное исключение, которое > *выполняет* пакет в песочнице для подтверждения поведения: он может подтвердить > вредоносность, но никогда не докажет безопасность пакета. Полные границы: [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope). ## Что сканирует и обнаруживает **Сканирует** — `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. Полная матрица покрытия — и известное слепое пятно «загрузка позже» — в [модели угроз](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md); таблица сравнения — на [сайте](https://pkgxray.ca/#catches). ## Вердикты | Вердикт | Что делать | |---|---| | `SAFE` | Устанавливайте. По умолчанию из карантина продвигается только `safe`. | | `REVIEW` | Изучите карантинную копию перед продвижением. | | `BLOCK` | Не устанавливайте. Каждая находка указывает файл и доказательства. | Коды выхода стабильны и удобны для CI: **`0`** безопасно/разрешено · **`2`** блокировка · **`3`** проверка. ## Использование ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [`.pkgxray.example.json`](https://github.com/adamsjack711-ux/pkgxray/blob/main/.pkgxray.example.json). ## Интеграции Один движок за каждой точкой входа. «Работает с» означает документированное руководство по настройке, а не интеграцию, одобренную вендором. | Где | Что делает | Руководство | |---|---|---| | Агенты программирования — Codex, Claude Code, Cursor, Windsurf | Контролирует установки и предоставляет агенту инструменты аудита | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | MCP-клиенты | Проверяет сервер перед подключением; запускает сам pkgxray как MCP-сервер | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | Останавливает сборку, когда зависимость нарушает политику | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | Установочный шлюз — Hookshot | Запускает `guard` для каждого пакета, который агент пытается установить | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | Шлюз MCP времени выполнения | Проксирует активный MCP-сервер и пропускает каждый вызов инструмента через шлюз | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | Мониторинг зависимостей | Повторно проверяет установленные зависимости и заранее проверяет обновления по расписанию | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## Сравнение с аналогами Запускайте pkgxray *вместе* с `npm audit` / OSV-Scanner, а не вместо них — они отвечают на вопрос *«известная ли это CVE?»*. В сравнении с инструментами той же ниши (поведенческая проверка цепочки поставок — Socket.dev, OpenSSF Package Analysis, Cisco MCP Scanner) полное сравнение возможностей — в [docs/comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) и на [сайте](https://pkgxray.ca/#comparison). ## Обоснование **Калибровка «ноль ложных эвристических блокировок на топ-1000 самых скачиваемых пакетов»** защищена от регрессий в CI ([область и методология](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)), а опубликованные прогоны находятся на [pkgxray.ca/stats](https://pkgxray.ca/stats). Это утверждение ограничено набором самых устанавливаемых пакетов — это не заявление о нуле ложных блокировок на каждом пакете. ## Документация | Документ | Что описывает | |---|---| | [architecture.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/architecture.md) · [design.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design.md) | Конвейер, поверхности, принципы | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | Область применения, слепые пятна, позиция по prompt-инъекциям | | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) · [mcp-registry.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp-registry.md) | Проверка MCP, прокси времени выполнения, запись в реестре | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | Опциональная поведенческая canary-проверка | | [configuration.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [reference.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md) | `.pkgxray.json`, политика критичности, `recheck`, кэш-сервер | | [benchmark.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md) · [comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) | Калибровка и сравнение с аналогами | | [compatibility.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/compatibility.md) · [json-schema.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/json-schema.md) | Контракт 1.0, схема `--format json` | Начните с [указателя документации](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md). ## Вклад в разработку ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md) и [Кодекс поведения](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md). Сообщайте об уязвимостях конфиденциально согласно [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md). Релизы публикуются в npm с провенансом (SLSA-аттестация) и проходят контроль тестами, калибровочным бенчмарком и собственной защитой цепочки поставок pkgxray. <div align="center"> <sub>Создано <a href="https://github.com/adamsjack711-ux">Jack Adams-Lovell</a> · <a href="https://github.com/adamsjack711-ux/pkgxray/blob/main/LICENSE">MIT</a> · <a href="https://pkgxray.ca">pkgxray.ca</a></sub> </div>
