adamsjack711-ux/pkgxraySegurança de pré-instalação para agentes de IA, pacotes npm e servidores MCP. Análise estática local zero-dep; varreduras normais nunca executam código de pacote.
<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — analise pacotes antes de instalá-los" width="820"> # pkgxray — segurança pré-instalação para pacotes npm, servidores MCP e agentes de IA Inspecione um pacote npm ou servidor MCP **antes** de instalá-lo ou conectar-se a ele e obtenha um veredito determinístico e fundamentado em evidências: `SAFE`, `REVIEW` ou `BLOCK`. Análise estática local, sem dependências — verificações normais nunca executam o código do pacote. [](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) [**Site**](https://pkgxray.ca) · [**Documentação**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**Calibração**](https://pkgxray.ca/stats) · [**Relatar um bug**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="pkgxray guard liberando [email protected] com um veredito SAFE A+, e depois bloqueando uma amostra trojanizada com um veredito BLOCK F e uma descoberta de acesso a credenciais de ALTA gravidade" width="820"> <sub>Execuções reais: <code>guard</code> libera <code>[email protected]</code>, depois bloqueia uma amostra modelada a partir do comprometimento de 2024 do <code>@solana/web3.js</code>.</sub> </div> ## Destaques - **Zero dependências em tempo de execução** — Node puro, roda inteiramente na sua máquina (passada estática de ~25 ms). - **Verificações normais nunca executam o código do pacote** — o tarball é lido como bytes em quarentena. - **Vereditos determinísticos e citados** — cada descoberta nomeia o arquivo e a evidência; nenhum LLM no caminho do veredito, então texto injetado não pode direcioná-lo. - **Feito para a era dos agentes** — avalie servidores MCP antes de conectar, controle as instalações que um agente executa e reavalie o tráfego MCP ao vivo. - **Calibrado e protegido contra regressões** — zero bloqueios falsos heurísticos nos 1000 pacotes mais baixados, aplicado em CI. > **[1. Início rápido](#quick-start)** · [2. O que ele verifica e detecta](#what-it-scans--detects) · [3. Vereditos](#verdicts) · [4. Uso](#usage) · [5. Integrações](#integrations) · [6. Como ele se compara](#how-it-compares) · [7. Documentação](#documentation) ## Por quê Os assistentes de codificação com IA instalam pacotes e se conectam a servidores MCP na velocidade da máquina, muitas vezes sem que um humano leia o código. A Sonatype identificou **mais de 454.600 novos pacotes de código aberto maliciosos nos ecossistemas monitorados em 2025**, mais de 99% deles no npm ([Sonatype](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)). O `npm audit` pergunta *isso tem algum CVE conhecido?*; o pkgxray também pergunta *o que o código realmente faz* — antes que qualquer coisa seja instalada. ## Início rápido **1. Verifique um pacote conhecidamente benigno** (nenhuma instalação do pkgxray é necessária): ```bash npx --yes [email protected] guard npm:[email protected] ``` Ele prepara o tarball em quarentena e executa as verificações estáticas e de cadeia de suprimentos — sem `npm install`, sem scripts de ciclo de vida, sem execução de código do pacote. <details> <summary>Exemplo de saída</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. Leia o veredito:** | Veredito | Saída | Significado | |---|---:|---| | `SAFE` | `0` | Nenhum indicador de alto ou médio risco; a política padrão permite a promoção. | | `REVIEW` | `3` | As evidências estão incompletas ou uma capacidade privilegiada precisa de revisão humana. | | `BLOCK` | `2` | Evidências citadas de alta gravidade — rejeite ou investigue. | O `SAFE` não é uma prova de que um pacote é inofensivo; a análise estática não consegue ver uma carga útil baixada apenas em tempo de execução. Consulte o [modelo de ameaças](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md). **3. Veja um BLOCK no fixture inerte fornecido:** ```bash npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown ``` O fixture é um texto-fonte inerte que modela a leitura e a exfiltração de uma chave SSH dividida em strings — **ele nunca é executado**. Ele retorna `BLOCK` (saída `2`) com o arquivo e as evidências citados. **4. Adicione-o ao seu fluxo de trabalho** — [reverificações e 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), [portão de instalação Hookshot](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot). > **Dois modelos de execução.** As verificações padrão `guard` e `audit` são **estáticas** — o código do pacote nunca é executado. A enumeração de um servidor MCP pode iniciá-lo, e o `mcp-proxy` o executa atrás de um portão; o [`canary`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) opcional é a única exceção deliberada que *executa* o pacote em uma sandbox para confirmar o comportamento — ele pode confirmar malícia, mas nunca provar que um pacote é seguro. Limite completo: [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope). ## O que ele verifica e detecta **Verificações** — `pkgxray guard npm:name@version`, `github:owner/repo`, um diretório local, lockfiles inteiros (`npm`, `yarn`, `pnpm`), servidores MCP e extensões de agentes de IA. **Detecta** — roubo de credenciais (incl. caminhos de fragmentos divididos), coleta de metadados de instância de nuvem e de armazenamento de segredos, injeção de prompt, contrabando Unicode, payloads base64 e carregadores de estágio 2, exfiltração, persistência (perfil de shell, agendador do SO e fluxos de CI/CD injetados), droppers autodestrutivos, replicação de worm no registro (`npm publish` no momento da instalação), execução ofuscada de argumentos computados, CVEs conhecidos (via OSV, antes do download), divergência de artefatos npm↔GitHub, atualizações trojanizadas (`recheck`) e abuso da superfície de capacidades do MCP. A matriz de cobertura completa — e o ponto cego conhecido de "baixar depois" — está no [modelo de ameaças](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md); uma tabela de comparação lado a lado está no [site](https://pkgxray.ca/#catches). ## Vereditos | Veredito | Você deve | |---|---| | `SAFE` | Instale. Somente `safe` promove para fora da quarentena por padrão. | | `REVIEW` | Inspecione a cópia em quarentena antes de promover. | | `BLOCK` | Não instale. Cada descoberta nomeia o arquivo e as evidências. | Os códigos de saída são estáveis e amigáveis para CI: **`0`** seguro/permitido · **`2`** bloqueio · **`3`** revisão. ## Uso ```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 ``` Um `.pkgxray.json` opcional (lido por todas as superfícies) ajusta a política; configuração zero significa máximo rigor. CVEs nunca podem ser ignorados, todo afrouxamento é impresso, e uma verificação que gera erro falha fechada em `review`. Esquema e invariantes: [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). ## Integrações Um único mecanismo por trás de cada ponto de entrada. "Funciona com" significa um guia de configuração documentado, não uma integração endossada pelo fornecedor. | Onde | O que faz | Guia | |---|---|---| | Agentes de codificação — Codex, Claude Code, Cursor, Windsurf | Controla as instalações e expõe as ferramentas de auditoria ao agente | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | Clientes MCP | Avalia um servidor antes de conectar; executa o próprio pkgxray como um servidor MCP | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | Faz o build falhar quando uma dependência viola a política | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | Portão de instalação — Hookshot | Executa `guard` em todo pacote que um agente tenta instalar | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | Portão MCP em tempo de execução | Faz proxy de um servidor MCP ativo e controla cada chamada de ferramenta | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | Monitoramento de dependências | Reavalia dependências instaladas e pré-avalia atualizações em um agendamento | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## Como ele se compara Execute o pkgxray *junto com* `npm audit` / OSV-Scanner, não no lugar deles — eles respondem *"CVE conhecido?"*. Contra ferramentas da mesma categoria (avaliação comportamental da cadeia de suprimentos — Socket.dev, OpenSSF Package Analysis, Cisco MCP Scanner), a comparação completa de capacidades está em [docs/comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) e no [site](https://pkgxray.ca/#comparison). ## Evidências A **calibração de zero bloqueios falsos heurísticos nos 1000 pacotes mais baixados** é protegida contra regressões em CI ([escopo e metodologia](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)), e as execuções publicadas estão em [pkgxray.ca/stats](https://pkgxray.ca/stats). Essa afirmação está limitada ao conjunto mais instalado — não é uma alegação de zero bloqueios falsos em todos os pacotes. ## Documentação | Doc | O que cobre | |---|---| | [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) | Pipeline, superfícies, princípios | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | Escopo, pontos cegos, postura sobre injeção de 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) | Avaliação MCP, proxy em tempo de execução, entrada no registro | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | O canário comportamental opcional | | [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`, política de gravidade, `recheck`, servidor de cache | | [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) | Calibração e como ele se compara | | [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) | Contrato 1.0, esquema `--format json` | Comece pelo [índice da documentação](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md). ## Como contribuir ```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 ``` Pull requests são bem-vindos — leia o [CONTRIBUTING.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md) e o [Código de Conduta](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md). Reporte vulnerabilidades em particular de acordo com o [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md). As versões são publicadas no npm com proveniência (atestação SLSA), condicionadas aos testes, ao benchmark de calibração e à própria proteção da cadeia de suprimentos do pkgxray. <div align="center"> <sub>Construído por <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>
