safe-npm

Um instalador npm focado em segurança que protege seus projetos contra pacotes recentemente comprometidos.

Por que isso existe?

Ataques à cadeia de suprimentos em pacotes npm são uma ameaça crescente. Atacantes às vezes comprometem pacotes legítimos ao:

• Roubar credenciais de mantenedores
• Publicar atualizações maliciosas em pacotes populares
• Assumir o controle de pacotes abandonados

Esses ataques geralmente acontecem de repente—um pacote que era seguro ontem pode estar comprometido hoje. safe-npm protege você instalando apenas versões de pacotes que estão disponíveis publicamente há um tempo mínimo (90 dias por padrão). Isso dá tempo para a comunidade de segurança descobrir e reportar lançamentos maliciosos antes que eles atinjam seu projeto.

Como funciona

Quando você executa safe-npm install, ele:

1. Lê suas dependências do package.json ou de argumentos da linha de comando
2. Consulta o registro npm para encontrar todas as versões disponíveis
3. Filtra versões publicadas mais recentemente do que o limite mínimo de idade
4. Seleciona a versão mais nova que atende aos requisitos semver E de idade
5. Instala as versões seguras usando o npm

Por exemplo, se você especificar react@^18 e um [email protected] malicioso tiver sido publicado ontem, o safe-npm instalará a versão mais recente que tenha pelo menos 90 dias em vez disso.

Instalação

Instalar a partir do npm (recomendado)

# Instalar globalmente
npm install -g @dendronhq/safe-npm

# Agora você pode usá-lo em qualquer lugar
safe-npm install

Compilar a partir do código-fonte

# Clonar e compilar
git clone <repository-url>
cd safe-npm
npm install
npm run build

# Linkar o binário globalmente
npm link

Uso básico

Instalar dependências do package.json

# Usar a idade mínima de 90 dias (padrão)
safe-npm install

# Ou especificar sua própria idade mínima
safe-npm install --min-age-days 120

Instalar pacotes específicos

# Instalar pacotes diretamente com restrições de versão
safe-npm install react@^18 lodash@^4.17.0

# Eles serão filtrados para usar apenas versões com pelo menos 90 dias
safe-npm install express --min-age-days 60

Simulação para ver o que seria instalado

# Visualizar quais versões seriam instaladas sem realmente instalar
safe-npm install --dry-run

Opções de configuração

--min-age-days <n>

Padrão: 90

O número mínimo de dias que uma versão de pacote deve ter sido publicada antes de poder ser instalada.

Exemplo: --min-age-days 120 exige que os pacotes tenham pelo menos 4 meses.

Quando ajustar:

• Aumente para máxima segurança (ex.: 180 dias para sistemas de produção críticos)
• Diminua se precisar de recursos mais recentes e aceitar um risco ligeiramente maior (ex.: 30 dias)

--ignore <pkg1,pkg2>

Uma lista separada por vírgulas de pacotes que ignoram o requisito de idade. Esses pacotes ainda respeitarão os intervalos semver, mas ignorarão a idade mínima.

Exemplo: --ignore typescript,@types/node

Quando usar:

• Pacotes de movimento rápido que você confia (como TypeScript ou ferramentas de build)
• Pacotes internos da sua organização
• Pacotes onde você precisa urgentemente dos recursos mais recentes

--strict

Sair com erro se QUALQUER dependência não puder ser resolvida para uma versão que atenda ao requisito de idade.

Exemplo: safe-npm install --strict

Quando usar:

• Pipelines de CI/CD onde você quer que os builds falhem em vez de pular pacotes problemáticos
• Implantações de produção onde você precisa de certeza

--dev / --prod-only

Controla quais dependências do package.json são processadas.

Exemplos:

• safe-npm install --dev - Instalar apenas devDependencies
• safe-npm install --prod-only - Instalar apenas dependências de produção

Quando usar:

• Instalar ferramentas de desenvolvimento com requisitos mais rigorosos
• Builds de produção onde você quer políticas de idade diferentes para dependências dev vs prod

--strategy <direct|overrides>

Padrão: direct

Como o safe-npm instala as versões resolvidas:

direct - Instala diretamente as versões resolvidas usando npm install package@version

• Simples e direto
• Bom para instalações únicas ou scripts

overrides - Escreve as versões resolvidas no campo de overrides do package.json, depois executa npm install

• Impõe versões em toda a árvore de dependências (incluindo dependências transitivas)
• Nota: Este recurso está atualmente desabilitado porque ainda não funciona corretamente

--registry <url>

Padrão: https://registry.npmjs.org

Especificar um registro npm alternativo.

Exemplo: --registry https://registry.company.com

Quando usar:

• Registros npm privados
• Espelhos ou caches

--dry-run

Mostrar o que seria instalado sem fazer alterações.

Exemplo: safe-npm install --dry-run

Quando usar:

• Testar sua configuração
• Entender quais versões estão disponíveis
• Antes de fazer alterações em sistemas de produção

Fluxos de trabalho comuns

Proteger um novo projeto

# Criar um novo projeto
mkdir my-project && cd my-project
npm init -y

# Instalar dependências com segurança
safe-npm install express@^4 lodash

# Isso cria o package-lock.json com versões de pelo menos 90 dias

Auditar um projeto existente

# Verificar quais versões seriam instaladas com requisitos de idade
safe-npm install --dry-run

# Se estiver satisfeito, instale-as
safe-npm install

Integração CI/CD

# Em seu pipeline CI, falhe o build se algum pacote não atender aos requisitos de idade
safe-npm install --strict --min-age-days 120

# Ou permitir pacotes mais novos apenas para dependências de desenvolvimento
safe-npm install --prod-only --strict

Atualizações de emergência

# Precisa atualizar um pacote específico com urgência? Adicione-o à lista de ignorados
safe-npm install --ignore package-with-critical-fix

Testes

O projeto inclui um conjunto de testes que você pode executar:

npm test

Para testes automatizados, você pode simular respostas do registro usando fixtures:

export SAFE_NPM_FIXTURES=/path/to/fixtures.json
safe-npm install

O arquivo de fixtures deve conter JSON que espelha as respostas do registro npm para cada pacote.

Como isso protege você

Cenário do mundo real:

1. Um pacote popular popular-lib é mantido por um desenvolvedor confiável
2. Um atacante compromete as credenciais npm do mantenedor
3. O atacante publica [email protected] com malware
4. Projetos que usam ^5.0.0 instalariam imediatamente a versão maliciosa
5. Com o safe-npm, você continuaria usando 4.9.0 (a versão mais recente de 90+ dias atrás)
6. Pesquisadores de segurança descobrem o comprometimento e o reportam
7. A versão maliciosa é removida da publicação
8. Você nunca instalou a versão comprometida

Limitações

• Não protegerá contra pacotes que eram maliciosos desde o início
• Atrasa o acesso a novos recursos legítimos e correções de bugs
• Exige confiança de que versões mais antigas não possuem vulnerabilidades não descobertas
• A filtragem baseada em idade é uma heurística, não uma garantia

Filosofia

Segurança é sobre trade-offs. O safe-npm troca atualizações de ponta por proteção contra comprometimentos súbitos da cadeia de suprimentos. É uma camada em uma estratégia de defesa em profundidade que também deve incluir:

• Auditorias de segurança regulares (npm audit)
• Revisão de dependências antes de adicionar novos pacotes
• Monitoramento de avisos de segurança
• Uso de arquivos de bloqueio (lock files) para garantir builds reproduzíveis
• Execução em ambientes isolados ou conteinerizados

Requisitos

• Node.js 18 ou superior
• npm (para a instalação subjacente)

Licença

ISC