npm audit

Como funciona o npm audit

O npm audit envia uma descrição das dependências do seu projeto para o seu registo predefinido e pede as vulnerabilidades conhecidas. Precisa de um package-lock.json ou de um ficheiro shrinkwrap, porque é assim que sabe que versões tem. Consulte a documentação do npm para mais pormenores.

npm audit                       # report everything
npm audit --omit=dev            # skip dev dependencies
npm audit --audit-level=high    # fail only on high or critical
npm audit --json                # machine-readable output

Como ler o relatório

• A gravidade vem do aviso de segurança. Indica a gravidade da falha em geral, não a gravidade para si.
• O caminho da dependência mostra o que trouxe o pacote. A maioria das conclusões são dependências transitivas, e a correção está normalmente no pacote acima.
• Desenvolvimento ou produção. Uma falha numa ferramenta de testes não chega aos utilizadores, mas continua a ser executada no seu build, pelo que não a deve ignorar por completo.

Se obtiver uma lista longa, comece pelo que está a ser explorado e pelo que é distribuído. Consulte como priorizar vulnerabilidades.

npm audit fix, e quando não o forçar

Comando	O que faz	Risco
npm audit fix	Aplica atualizações compatíveis dentro dos seus intervalos de versões	Baixo. Execute os seus testes na mesma, porque faz uma instalação completa
npm audit fix --force	Permite também alterações fora dos seus intervalos, incluindo versões major	Alto. Pode estragar a sua aplicação, e o npm diz para não o usar sem uma ideia clara do que pretende

Se não houver uma correção disponível, pode atualizar o pacote pai ou usar o campo overrides no package.json para forçar uma versão transitiva corrigida. Teste-a, porque o pacote pai não foi compilado com essa versão.

Executar o npm audit na CI

Por predefinição, o npm audit termina com um código diferente de zero quando encontra alguma coisa, o que faz o job falhar em cada aviso de baixa gravidade. As equipas definem normalmente um limiar. Tenha em conta que --audit-level apenas altera o limiar de falha e não filtra o relatório.

- run: npm ci
- run: npm audit --omit=dev --audit-level=high

Uma verificação como esta também pode fazer falhar um build sem qualquer alteração de código, porque foi publicado um novo aviso de segurança durante a noite. Decida quem é responsável por essa falha antes de ativar a verificação. Para saber mais, consulte onde executar análises SCA.

O que escapa ao npm audit

• Tudo o que está fora do npm. A sua imagem base, os pacotes do sistema operativo, as ferramentas Python e as GitHub Actions não estão no package-lock.json.
• Código obtido durante a instalação. Os scripts de instalação podem descarregar ficheiros que nenhum lockfile regista. Consulte o que um lockfile não regista.
• Novos pacotes maliciosos. Faz a correspondência com avisos publicados, pelo que um pacote ainda sem aviso passa sem qualquer alerta.
• O que já foi distribuído. Analisa o projeto que tem à frente. Um novo aviso para a versão do ano passado só aparece se alguém o voltar a executar nessa versão.
• Se está afetado. Não sabe se o seu código usa a função vulnerável. A análise de alcançabilidade trata disso.

O npm audit signatures é um comando à parte que verifica as assinaturas do registo e as atestações de proveniência dos pacotes que instalou. Verifica de onde veio um pacote, não se é seguro.

npm audit e CRACI

Continue a executar o npm audit nos pull requests. É gratuito e apanha cedo os problemas conhecidos. O CRACI cobre o que ele não consegue ver: como seu runner de GitHub Actions, regista cada pacote que cada job efetivamente obteve do npm e de qualquer outra origem, incluindo pacotes restaurados de caches de CI e ficheiros obtidos por hooks de instalação. Depois, continua a verificar a SBOM do que foi distribuído à medida que são publicadas novas vulnerabilidades. Consulte as melhores ferramentas de SCA ou geração de SBOM durante o build.

npm audit: perguntas frequentes

O que faz o npm audit?

Envia uma descrição das suas dependências para o registo do npm, verifica-as face a avisos de segurança conhecidos e reporta os pacotes vulneráveis, com a respetiva gravidade e a forma como entraram no seu projeto.

O npm audit fix é seguro?

O npm audit fix simples é normalmente seguro, porque se mantém dentro dos seus intervalos de versões, mas execute os seus testes depois. O npm audit fix --force pode instalar novas versões major e estragar a sua aplicação.

Porque é que o npm audit mostra tantas vulnerabilidades?

A maioria vem de dependências transitivas e de ferramentas de desenvolvimento. Use --omit=dev para se concentrar no que é distribuído e priorize pela exploração e pela exposição, não pela contagem.

Como ignorar uma vulnerabilidade no npm audit?

O npm audit não tem uma lista de exclusões integrada. As equipas usam o campo overrides para alterar a versão, um limiar com --audit-level ou uma ferramenta wrapper que regista as conclusões aceites.

O npm audit precisa de um lockfile?

Sim, por predefinição precisa de um package-lock.json ou de um ficheiro shrinkwrap. Pode contornar isso com --no-package-lock, mas os resultados poderão então diferir entre execuções.

O npm audit deteta malware?

Só depois de ter sido publicado um aviso de segurança para o pacote. Um novo pacote malicioso não tem aviso, pelo que não será reportado no dia em que surge.