Supply Chain no Node.js: Segurança

A segurança de Supply Chain no Node.js protege todo o caminho entre o código-fonte e o artefato executado em produção. Dependências vulneráveis são apenas uma parte do problema. A cadeia também inclui contas de mantenedores, registries, runners de CI, scripts de instalação, imagens base, tokens de publicação, artefatos, assinaturas e mecanismos de deploy.

Um atacante não precisa explorar diretamente sua API quando consegue comprometer um pacote, alterar um pipeline ou publicar uma versão falsa. Por isso, a proteção deve combinar identidade forte, privilégio mínimo, builds reproduzíveis, provenance, assinatura, SBOM, revisão de dependências e ambientes isolados.

Neste guia, você aprenderá a mapear a cadeia, proteger npm e CI/CD, reduzir scripts, evitar dependency confusion, assinar artefatos, gerar provenance, controlar imagens, revisar releases e responder a comprometimentos.

O que é Software Supply Chain?

A cadeia de software reúne pessoas, ferramentas e serviços usados para criar e entregar uma aplicação. O framework SLSA apresenta níveis e controles para integridade de builds. A CISA publica orientações para desenvolvedores e organizações.

Componentes da cadeia

• repositório Git;
• contas de desenvolvedores;
• dependências npm;
• registries públicos e privados;
• runners de CI;
• imagens base;
• scripts de build;
• gerenciadores de segredos;
• artefatos e releases;
• sistema de deploy.

Mapa de confiança

Documente quais identidades podem:

• alterar código;
• aprovar pull requests;
• executar workflows privilegiados;
• publicar pacotes;
• assinar imagens;
• promover artefatos;
• acessar produção.

Sem esse mapa, permissões antigas e integrações esquecidas permanecem invisíveis.

Proteja contas de mantenedores

Use MFA resistente a phishing, preferencialmente passkeys ou chaves de segurança. Consulte Passkeys no Node.js e WebAuthn no Node.js.

Branch protection

Exija revisão, status checks e histórico protegido para branches de release. Impedir push direto reduz alterações não revisadas.

CODEOWNERS

Arquivos de workflow, scripts de release, lockfiles e configurações de segurança devem exigir revisores específicos.

Commits assinados

Assinatura ajuda a verificar autoria, mas não substitui revisão ou proteção da conta. Uma chave comprometida ainda pode assinar código malicioso.

Dependências npm

Versione lockfiles e use npm ci. Consulte Segurança de Dependências no Node.js.

Dependency confusion

Um pacote interno sem scope pode ser confundido com um pacote público. Use nomes com scope:

@empresa/payments-sdk

Configure o registry do scope explicitamente.

.npmrc

@empresa:registry=https://registry.example.com/

Evite tokens persistentes no arquivo versionado.

Typosquatting

Confirme nome, mantenedor, repositório e histórico antes de instalar. Pacotes parecidos com bibliotecas populares podem ser maliciosos.

Scripts de instalação

Pacotes podem executar código durante npm install. Quando possível:

npm ci --ignore-scripts

Se scripts forem necessários, mantenha uma lista aprovada.

Runners isolados

Builds de pull requests não confiáveis não devem rodar em runners persistentes com segredos. Prefira ambientes efêmeros e limpos.

Segredos no CI

Entregue somente os segredos necessários à etapa. Um job de teste não precisa de credenciais de publicação.

Consulte Gestão de Segredos no Node.js.

Workflows de terceiros

Fixe actions e plugins por commit imutável, não apenas por tag mutável:

uses: owner/action@commit-sha

Revise permissões e conteúdo antes de adotar.

Permissões do workflow

Configure tokens com escopo mínimo:

permissions:
  contents: read

Conceda escrita apenas em jobs que realmente publicam.

OIDC no CI

Use identidade federada para acessar cloud sem armazenar chaves estáticas. O provedor emite credencial curta para o workflow autorizado.

Build hermético

Um build hermético reduz dependências externas não declaradas. Ele usa inputs conhecidos e evita baixar conteúdo arbitrário durante a compilação.

Build reproduzível

O mesmo código e inputs devem produzir resultado equivalente. Diferenças ajudam a detectar interferência ou dependências não controladas.

Não construir em produção

Produção deve receber um artefato já testado. Executar npm install durante o deploy permite mudanças externas depois da aprovação.

Promova o mesmo artefato

O artefato testado em homologação deve ser promovido para produção, em vez de ser reconstruído.

Provenance

Provenance registra:

• repositório;
• commit;
• workflow;
• runner;
• inputs;
• builder;
• hash do artefato.

Isso ajuda a responder de onde veio uma imagem ou pacote.

SBOM

Uma SBOM lista componentes e versões. Gere por release e associe ao artefato exato.

CycloneDX e SPDX

São formatos comuns de SBOM. Escolha o que integra melhor com scanners e inventário.

Assinatura de imagens

Assine imagens e valide a assinatura antes do deploy. A política deve conferir identidade do emissor e repositório esperado.

Hash não basta

Um hash confirma integridade apenas quando o valor esperado é confiável. A assinatura liga o artefato a uma identidade.

Registry imutável

Não permita sobrescrever tags de release. Use digest:

image@sha256:...

Tags como latest são convenientes, mas não identificam conteúdo imutável.

Imagens base

Fixe por digest e atualize regularmente. Uma imagem base antiga pode conter vulnerabilidades no sistema operacional.

Multi-stage build

Leve para a imagem final apenas runtime e dependências necessárias. Consulte Docker Multi-stage para Node.js.

Usuário não root

Execute a aplicação com usuário sem privilégio. Uma dependência comprometida terá menos capacidade no container.

Filesystem read-only

Quando possível, monte o filesystem como somente leitura e use diretórios temporários controlados.

Network egress

Builds e aplicações não precisam acessar qualquer endereço. Limite saída para registries, APIs e serviços aprovados.

Pacotes internos

Use registry privado, scopes e autenticação. Não publique acidentalmente código interno no npm público.

Token de publicação

Use token específico, curta duração e com MFA ou trusted publishing. Não reutilize token pessoal.

Trusted publishing

Quando o registry suporta identidade federada, permita publicação apenas pelo workflow e repositório aprovados.

Two-person rule

Releases críticas podem exigir aprovação separada da pessoa que criou o artefato.

Separação de ambientes

Credenciais de homologação não devem promover produção. Use projetos, contas e secrets distintos.

Policy as Code

Políticas podem bloquear deploy quando:

• imagem não está assinada;
• provenance está ausente;
• origem não é aprovada;
• vulnerabilidade excede o limite;
• imagem roda como root;
• tag não é imutável.

Exceções

Uma exceção deve ter justificativa, owner, prazo e controle compensatório. Não use listas permanentes sem revisão.

Advisories de segurança

Monitore dependências, runtime, imagens e ferramentas de CI. O risco pode surgir depois da release.

Inventário de produção

Saiba quais serviços executam cada versão. Sem inventário, a equipe não consegue localizar rapidamente um pacote vulnerável.

Logs de auditoria

Registre publicação, assinatura, promoção, alteração de workflow e uso de tokens. Consulte Logs de Auditoria no Node.js.

Detecção de mudança

Alerte quando:

• um workflow ganha permissão;
• um token novo é criado;
• uma tag é sobrescrita;
• um pacote muda de owner;
• um build usa runner inesperado;
• uma imagem não assinada aparece.

Resposta a incidente

1. Interromper publicação.
2. Revogar tokens.
3. Identificar versões afetadas.
4. Remover artefatos comprometidos.
5. Reconstruir em ambiente limpo.
6. Rotacionar segredos.
7. Verificar produção.
8. Comunicar consumidores.

Pacote comprometido

Não basta atualizar o package.json. Revise se o pacote executou scripts no CI, acessou segredos ou alterou artefatos.

Runner comprometido

Recrie o runner, revogue credenciais usadas e considere todos os artefatos produzidos no período como suspeitos.

Replay de artefato

Um atacante pode tentar promover uma versão antiga vulnerável. Políticas devem verificar versão, assinatura e aprovação.

Testes do pipeline

Crie testes que confirmem:

• PR externo não recebe segredo;
• job de teste não publica;
• imagem sem assinatura é bloqueada;
• tag não pode ser sobrescrita;
• deploy usa digest;
• provenance corresponde ao commit.

Chaos de segurança

Simule token revogado, registry indisponível e assinatura inválida. O pipeline deve falhar fechado.

Canary

Promova uma nova release gradualmente e monitore. Consulte Canary Deploy no Node.js.

Rollback seguro

O rollback deve usar artefato assinado e conhecido. Não reconstrua uma versão antiga durante o incidente.

Desenvolvimento local

Desenvolvedores não precisam de tokens de publicação permanentes. Use ambientes separados e credenciais curtas.

Pre-commit

Scanners podem detectar segredos, arquivos sensíveis e alterações suspeitas no lockfile antes do push.

Revisão do lockfile

Observe novos pacotes, URLs de origem, scripts e mudanças inesperadas de versão.

Erros comuns

• Focar apenas em vulnerabilidades: pipeline e identidade ficam expostos.
• Tags mutáveis: conteúdo muda depois da aprovação.
• Runner persistente: um job contamina o próximo.
• Segredos em todos os jobs: scripts podem roubá-los.
• Build em produção: artefato difere do testado.
• Sem provenance: origem não pode ser comprovada.
• Token pessoal de publicação: acesso não é controlado.

Boas práticas

• Proteja identidades com passkeys.
• Use branch protection.
• Fixe dependências e actions.
• Use runners efêmeros.
• Reduza permissões do CI.
• Gere SBOM e provenance.
• Assine artefatos.
• Promova o mesmo artefato.
• Valide políticas no deploy.
• Mantenha plano de incidente.

Conclusão

A segurança de Supply Chain no Node.js protege mais que dependências. Ela controla identidades, pipelines, registries, artefatos e promoções até produção.

Builds isolados, provenance, assinaturas, SBOM e privilégio mínimo tornam alterações rastreáveis e verificáveis. Quando produção aceita apenas artefatos aprovados e imutáveis, um comprometimento em uma etapa deixa de se propagar silenciosamente por toda a cadeia.