trustlock

Um controlador de admissão de dependências nativo do Git. Avalia sinais de confiança em cada alteração de dependência.

Como funciona

O trustlock é executado como um hook de pré-commit do Git (modo consultivo) e uma verificação de CI (modo de imposição):

• Consultivo (pré-commit): avisa sobre violações, sai com 0, avança a linha de base confiável quando todos os pacotes são admitidos.
• Imposição (--enforce): bloqueia em caso de violações, sai com 1, nunca avança a linha de base.

Sinais de confiança avaliados por pacote:

• Cooldown — há quanto tempo a versão foi publicada no registro
• Proveniência — se o pacote possui atestações SLSA
• Fixação — se o lockfile usa versões exatas
• Scripts de instalação — se o pacote executa scripts no momento da instalação
• Origens — se o pacote vem do registro, de uma URL git, de um caminho local ou de uma URL
• Novas dependências — primeiras adições ao projeto
• Surpresa transitiva — salto inesperado na contagem de dependências transitivas
• Mudança de publicador — se a identidade do publicador do pacote mudou entre versões

Instalação

npm install -g trustlock

Requer Node.js >= 18.3.

Lockfiles suportados

Início rápido

Fluxo 1 — Integração de um projeto

# 1. Inicializar o trustlock no projeto
trustlock init

# 2. Instalar o hook de pré-commit do Git
trustlock install-hook

# 3. Opcionalmente, revisar a postura atual das dependências
trustlock audit

Após init, o trustlock cria:

• .trustlockrc.json — configuração de política
• .trustlock/baseline.json — snapshot de dependências confiáveis
• .trustlock/approvals.json — registros de aprovação
• .trustlock/.cache/ — cache do registro (ignorado pelo git)

Faça commit de .trustlockrc.json e .trustlock/baseline.json no seu repositório.

Fluxo 2 — Verificar e admitir uma atualização de dependência

# Execute a instalação da dependência normalmente
npm install [email protected]

# A verificação trustlock é executada automaticamente via hook de pré-commit.
# Para executá-la manualmente:
trustlock check

# Saída quando todos os pacotes são admitidos:
# ✔ [email protected] — admitido

Quando todos os pacotes passam, trustlock check avança a linha de base automaticamente (apenas no modo consultivo) e sai com 0.

Fluxo 3 — Lidar com uma dependência bloqueada

# Um novo pacote falha na regra de cooldown:
trustlock check
# ✖ [email protected] — bloqueado
#   exposição:cooldown  Publicado há 2h (política exige 72h)
#   Execute para aprovar: trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# Aprove a substituição e depois verifique novamente:
trustlock approve [email protected] \
  --override cooldown \
  --reason "Necessário para a funcionalidade X; verificado como seguro pela revisão da equipe" \
  --expires 7d

trustlock check
# ✔ [email protected] — admitido com aprovação

Fluxo 4 — Comparar postura de dependências entre projetos

# Detectar desvios de versão e inconsistências de proveniência entre pacotes do monorepo
trustlock audit --compare packages/frontend packages/backend packages/shared

Comandos

Perfis de política

O trustlock inclui dois perfis internos selecionáveis com --profile:

# Usar perfil strict no CI
trustlock check --enforce --profile strict

Herança de política organizacional

Equipes podem centralizar a política em uma URL compartilhada e estendê-la por repositório:

{
  "extends": "https://policy.example.com/trustlockrc.json",
  "cooldown_hours": 96
}

As configurações do repositório só podem endurecer a política organizacional — a imposição mínima impede que repositórios reduzam limites obrigatórios definidos pela organização.

Documentação

• USAGE.md — Referência completa de comandos, todas as flags, códigos de saída, mensagens de erro
• POLICY-REFERENCE.md — Todas as opções de .trustlockrc.json
• ARCHITECTURE.md — Decisões de design e mapa de módulos
• examples/ — Exemplos de configuração e fluxo de CI

Integração com CI

Adicione o trustlock ao seu pipeline de CI:

# GitHub Actions — veja examples/ci/github-actions.yml
- run: npx trustlock check --enforce

Consulte examples/ para configurações de GitHub Actions, Lefthook e Husky.

Onde o trustlock se encaixa na linha do tempo

O trustlock avalia as alterações no lockfile no momento do commit. Ele não intercepta nem isola o npm install. Se um pacote malicioso executa um script de pós-instalação, isso acontece antes do trustlock tomar conhecimento. O trustlock impede que o lockfile comprometido seja commitado e mesclado, limitando o estrago a uma única máquina de desenvolvedor, em vez de toda a equipe e produção. Para bloqueio de scripts em tempo de instalação, use --ignore-scripts ou os controles padrão de script de ciclo de vida do pnpm.

O que o trustlock NÃO faz

• Não é um scanner de malware — o trustlock não inspeciona o código-fonte do pacote nem detecta assinaturas conhecidas de malwares. Use um scanner dedicado para isso.
• Não é uma sandbox de instalação — o trustlock não intercepta o npm install. Use --ignore-scripts para isso.
• Não é um rastreador de CVE — use npm audit ou Snyk para bancos de dados de vulnerabilidades.
• Não é um verificador de licenças — use license-checker ou similar.
• Não substitui o pnpm trustPolicy ou o npm min-release-age — esses são controles do lado do servidor, aplicados pelo registro. O trustlock é um portão de admissão do lado do cliente, na fronteira do repositório.

Sobre

O trustlock foi construído a partir da frustração com o quão passiva é a toolchain padrão do Node.js em relação ao que realmente entra em um projeto. npm install buscará qualquer coisa — um pacote publicado há dois minutos, um que executa scripts arbitrários no momento da instalação, um que trocou de tarball do registro para uma URL git da noite para o dia — e o único feedback que você recebe é um diff do lockfile.

O modelo de ameaça que o trustlock aborda é estreito, mas real: a janela entre o momento em que uma versão maliciosa é publicada e o momento em que é removida ou sinalizada. Scanners de vulnerabilidade operam após o fato. O trustlock opera no ponto de admissão, antes que qualquer coisa chegue ao seu repositório ou ao seu CI.

O design é intencionalmente mínimo. O trustlock não tem dependências em tempo de execução — ele próprio é uma ferramenta de risco zero na cadeia de suprimentos. Ele não substitui um scanner de vulnerabilidades nem uma auditoria de dependências; ele impõe continuidade de confiança. Uma vez que uma versão está na sua linha de base, ela é confiável. Qualquer novidade precisa conquistar a admissão de acordo com a política que você declarou.

O fluxo de aprovação existe para equipes que precisam de uma saída de emergência sem perder a auditabilidade. Cada substituição tem timestamp, é limitada a regras específicas e expira. clean-approvals é um comando de primeira classe, não um pensamento posterior.