np-audit — Auditor de pacotes npm

Análise de segurança estática para pacotes npm — detecta scripts de ciclo de vida ofuscados, vulnerabilidades conhecidas e padrões maliciosos antes de serem executados. Substituição direta para npm install e npm ci.

Zero dependências. Apenas módulos nativos do Node.js. < 100 kB no download.

npx np-audit scan express

npm install -g np-audit
npa scan                     # scan all deps
npa install                  # audit then install
alias npm='npa'              # use as drop-in replacement

---

Marshallers

A detecção é dividida em marshallers modulares — cada um detecta um único sinal de ataque:

Marshaller	O que detecta	Pontuação
eval/dynamic-exec	eval(), new Function(), eval indireto, vm.*, setTimeout com string	8
obfuscator.io	Padrões de nomenclatura de variáveis _0x (saída do obfuscator.io)	9–80
high-entropy-string	Strings longas ou cadeias de concatenação com alta entropia de Shannon	6
hex-escape-density	Sequências de escape densas \xNN e \uXXXX	5–50
fromCharCode	String.fromCharCode com muitos argumentos, grandes arrays de códigos de caracteres decimais	7
encoded-decode	Decodificação Base64/hex (atob, Buffer.from) opcionalmente combinada com eval	3–8
child-process	require('child_process'), exec, spawn, fork, worker_threads	5
hex-array	Grandes números de valores literais hexadecimais 0x	7–60
process-env	Acesso a process.env (sinal de exfiltração de credenciais)	3
network-call	require('https'), fetch(), dns, net, tls	4
filesystem-manipulation	fs.writeFile, chmod, symlink (persistência de backdoor)	3–4
runtime-download	Baixa e executa runtimes externos (Bun, Deno)	9–50
vscode-autorun	Tarefas do VS Code com runOn: folderOpen (execução automática)	30
known-vulnerability	CVEs conhecidas via API do Snyk ou OSV.dev	4–6 (WARN), 80 (malicious)

As pontuações escalam com a gravidade — contagens mais altas de indicadores de ofuscação produzem pontuações mais altas. O veredito final é baseado na maior pontuação individual entre todos os marshallers.

Veja CONTRIBUTING.md para saber como escrever marshallers personalizados.

---

Verificação de Vulnerabilidades (CVE)

Cada pacote verificado é checado contra bancos de dados de vulnerabilidades conhecidas junto com a análise de código.

Padrão: OSV.dev (nenhuma configuração necessária)

Funciona imediatamente — consulta a API gratuita do OSV.dev para vulnerabilidades conhecidas e avisos de pacotes maliciosos.

Opcional: API do Snyk (dados mais ricos)

# Environment variable
export SNYK_API_TOKEN=your-token-here

# Or via Snyk CLI
snyk auth

Ordem de resolução do token: SNYK_API_TOKEN → SNYK_TOKEN → ~/.config/configstore/snyk.json

Gravidade	Pontuação	Veredito
Pacote malicioso	80	DANGER
10+ vulnerabilidades	6	WARN
5–9 vulnerabilidades	5	WARN
1–4 vulnerabilidades	4	WARN

CVEs não maliciosas produzem avisos (warnings), mas nunca bloqueiam a instalação. Apenas pacotes confirmados como maliciosos acionam DANGER.

---

Uso

Comandos

Comando	Apelido	Descrição
npa install [package]	npa i	Audita e depois executa npm install
npa ci	—	Audita e depois executa npm ci
npa scan [package]	npa s	Apenas verifica, sem instalar
npa config get	npa c get	Mostrar configuração atual
npa config set <key> <value>	npa c set	Atualizar um valor de configuração
npa alias --install	—	Instalar alias do shell
npa alias --uninstall	—	Remover alias do shell

Qualquer comando não reconhecido é encaminhado para o npm (por exemplo, npa run test, npa publish).

Flags

Flag	Alias	Funciona com	Descrição
--review	-r	install, ci	Modo interativo — escolha quais scripts permitir
--json	—	install, ci, scan	Saída JSON legível por máquina
--no-dev	—	install, ci, scan	Pular devDependencies
--verbose	—	all	Mostrar progresso do download e detalhes extras
--version	-v	—	Exibir versão e sair
--help	-h	—	Exibir ajuda e sair

Modo interativo --review

npa install --review

  npa --review mode
  Use ↑/↓ to navigate, SPACE to toggle, ENTER to confirm, q to quit

  Found 3 package(s) with install scripts:

     [✓ allow] [email protected]       postinstall: post-install.js     OK
   ▶ [✗ deny ] [email protected]       postinstall: install.js          DANGER (score: 9)
     [✓ allow] @scope/[email protected]     postinstall: install.js          WARN (score: 5)

  2 allowed  1 denied

---

Configuração

A configuração é armazenada em ~/.npmauditor.json (global) e pode ser substituída por projeto com .npmauditor.json.

npa config get                              # Show current config
npa config set blockScore 6                 # Block at score 6+
npa config set skipPackages '["esbuild"]'   # Trust specific packages
npa config set skipScopes '["@types"]'      # Trust entire scopes

Todas as chaves de configuração