Automatizando Verificações de Segurança de Pacotes npm com npq

O npq audita um pacote npm antes de instalá-lo, enquanto o npm audit só reporta vulnerabilidades depois que o código já foi gravado em node_modules. Essa ordem é o ponto central: quando alguém audita a árvore de dependências, um script postinstall malicioso já pode ter sido executado na sua máquina. O npq move a verificação para antes da instalação — ele inspeciona metadados do pacote, idade, scripts e CVEs conhecidos no momento da solicitação de instalação, e então pergunta se você deseja continuar.

Este guia integra o npq ao seu terminal e a um hook de pré-commit, para que a auditoria ocorra no momento em que você busca dependências — não apenas quando você se lembra de executá-la.

npm install -g npq

A lacuna que o npq preenche

O npq é um auditor de segurança pré-instalação que executa um conjunto de verificações — chamadas de “marshalls” — contra os metadados de um pacote antes que o npm busque e execute qualquer código. Isso é o inverso do npm audit, que lê sua árvore de dependências instaladas e reporta CVEs após o fato. A campanha Shai-Hulud de 2025 explorou scripts de ciclo de vida que são executados durante a instalação, que é exatamente a janela que o npm audit não consegue cobrir e o npq consegue. A ferramenta é open source em lirantal/npq e foi criada por Liran Tal.

Instalar o npq e executar uma auditoria pontual

Instale o npq globalmente, depois use npq install no lugar de npm install para qualquer pacote que você queira verificar primeiro.

npm install -g npq
npq install express

O pacote npq no npm instala dois binários: npq e npq-hero. O primeiro executa uma auditoria explícita; o segundo é um wrapper npm substituto abordado na próxima seção. Quando você executa npq install express, o npq busca os metadados, executa seus marshalls, exibe os resultados e — se algo for sinalizado — solicita sua confirmação antes de delegar ao npm.

Um pacote sinalizado produz uma saída semelhante a esta:

warning Package has install scripts (preinstall, postinstall)
warning Package is older than 22 days? no — published 1 day ago
? Would you like to continue installing package(s)? (Y/n)

O prompt é o ponto de controle. Nada é instalado até que você responda, ou até que o temporizador de 15 segundos de continuação automática para avisos expire.

Criar alias de npm para npq-hero e torná-lo persistente

Para auditar cada instalação automaticamente, crie um alias de npm para npq-hero e registre o alias na configuração do seu shell. O npq-hero é o wrapper projetado para isso — ele repassa todos os subcomandos do npm (run, ci, publish e os demais) sem alterações, interceptando apenas as instalações para executar a auditoria primeiro.

echo "alias npm='npq-hero'" >> ~/.zshrc   # ou ~/.bashrc para bash
source ~/.zshrc

Com o alias configurado, npm install fastify passa pelos marshalls do npq antes que o npm busque o tarball. Crie o alias de npm para npq-hero em vez de para npq diretamente — npq é o binário de auditoria, enquanto npq-hero é o wrapper completo compatível com npm documentado no README do npq. Criar alias para o binário npq puro quebra subcomandos que o npq não implementa por conta própria.

O que o npq verifica de fato?

O npq executa um conjunto de verificações de segurança, chamadas de “marshalls”, que estão documentadas no README do npq. Elas se dividem em quatro categorias práticas:

Agrupá-los dessa forma mapeia como um ataque realmente se manifesta: um typosquat com um script postinstall e zero downloads aciona múltiplos marshalls ao mesmo tempo. Cada verificação é um sinal a ser avaliado, não um veredicto binário — o npq expõe os dados e deixa a decisão com você.

Desativar a continuação automática para revisão explícita

Por padrão, o prompt interativo do npq aguarda 15 segundos e então continua automaticamente a instalação quando apenas avisos estão presentes. Defina NPQ_DISABLE_AUTO_CONTINUE=true ou passe --disable-auto-continue para remover a contagem regressiva e forçar uma resposta explícita (y/N) antes que o npq delegue ao npm. Tanto a flag quanto a variável de ambiente estão documentadas no README do npq.

# Ambas as formas funcionam
NPQ_DISABLE_AUTO_CONTINUE=true npq install
npq install --disable-auto-continue

Isso transforma o npq em uma etapa de revisão deliberada — útil no seu terminal e dentro de um hook de commit do git, onde alguém está presente para responder ao prompt. Não se trata de um modo de falha não-interativo documentado: o prompt ainda espera uma resposta, e o npq não anuncia uma flag que converta cada pacote sinalizado em uma saída automática com código de erro.

Rotear o pnpm pelo npq

O npq delega ao gerenciador de pacotes especificado em NPQ_PKG_MGR, portanto a mesma camada de auditoria cobre o pnpm. Defina a variável por comando para usos pontuais, ou incorpore-a a um alias de shell para uso diário.

# Auditorias pontuais via pnpm
NPQ_PKG_MGR=pnpm npq install fastify

# Fazer o pnpm sempre passar pelo npq
alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"
echo 'alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"' >> ~/.zshrc

A variável NPQ_PKG_MGR, listada no README do npq, indica ao npq-hero qual gerenciador de pacotes invocar após a aprovação na auditoria. A forma com alias oferece a mesma garantia para o pnpm que o alias npm oferece para o npm: nenhuma instalação prossegue até que os marshalls sejam executados.

Adicionar um hook de pré-commit com husky

Capture dependências arriscadas antes que sejam commitadas executando o npq a partir de um hook de pré-commit do husky. Isso audita as dependências declaradas em package.json sempre que você faz um commit, sendo mais valioso em commits que alteram os manifestos de dependências.

Instale o husky e inicialize-o (sintaxe do husky v9):

npm install --save-dev husky
npx husky init

Em seguida, escreva o hook em .husky/pre-commit:

# .husky/pre-commit
if git diff --cached --name-only | grep -qE 'package(-lock)?\.json'; then
  npx npq
fi

A verificação com git diff --cached restringe a auditoria aos commits que realmente alteram package.json ou package-lock.json, para que commits não relacionados não paguem o custo da auditoria. O npx npq puro (sem o subcomando install) audita as dependências declaradas em package.json e sai com código de erro quando problemas são encontrados. Como o Husky bloqueia commits quando um hook sai com código de erro, isso transforma o hook em um controle rígido de pré-commit. O comando npx husky init e o formato de script simples em .husky/pre-commit seguem a convenção do husky v9; a v8 usava uma sintaxe diferente com husky add, então confirme a versão instalada antes de copiar trechos mais antigos.

Limitações honestas: heurísticas, não provas

Os marshalls do npq são sinais heurísticos, não provas de malícia. Um pacote publicado ontem com zero downloads é suspeito pelas verificações de idade e popularidade do npq — mas todo pacote legítimo novo começa exatamente nessa situação. O npq reduz o ruído a um conjunto de sinais ponderados e deixa a decisão com você; ele não classifica, e não pode classificar, a intenção. Trate uma instalação sinalizada como um convite para ler o pacote, não como uma ameaça confirmada.

O npq também não substitui o npm audit ou o Socket — ele os complementa. As três ferramentas cobrem janelas diferentes:

O npq captura sinais pré-instalação; o npm audit captura CVEs em pacotes já presentes no disco; o Socket adiciona monitoramento comportamental contínuo do seu grafo de dependências após o merge. Combinar o controle de instalação do npq com --ignore-scripts como padrão (e ferramentas como LavaMoat allow-scripts para as dependências que genuinamente precisam de scripts de ciclo de vida) fecha a maior parte da superfície de ataque no momento da instalação.

Conclusão

Criar um alias de npm para npq-hero e controlar commits com um hook do husky coloca a mesma auditoria pré-instalação em todos os lugares onde você busca dependências — terminal local e commit. Comece com a instalação global e o alias de shell, depois configure o hook do husky na próxima vez que tocar nos manifestos de dependências. Os marshalls são heurísticas, então leia o que eles sinalizam — mas ler um aviso é sempre melhor do que descobrir um payload de postinstall depois que ele já foi executado.

Perguntas Frequentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.