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.

Site · Documentação · Calibração · Relatar um bug

_{Execuções reais: guard libera [email protected], depois bloqueia uma amostra modelada a partir do comprometimento de 2024 do @solana/web3.js.}

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 · 2. O que ele verifica e detecta · 3. Vereditos · 4. Uso · 5. Integrações · 6. Como ele se compara · 7. Documentação

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). 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):

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.

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. Leia o veredito:

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.

3. Veja um BLOCK no fixture inerte fornecido:

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, MCP, portão de instalação 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 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.

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; uma tabela de comparação lado a lado está no site.

Vereditos

Os códigos de saída são estáveis e amigáveis para CI: 0 seguro/permitido · 2 bloqueio · 3 revisão.

Uso

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 · .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.

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 e no site.

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), e as execuções publicadas estão em 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

Comece pelo índice da documentação.

Como contribuir

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 e o Código de Conduta. Reporte vulnerabilidades em particular de acordo com o 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.