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