tayyabt/trustlockUm controlador de admissão de dependências nativo do Git. Avalia sinais de confiança em cada alteração de dependência e bloqueia commits ou builds quando pacotes falham na política da sua equipe. Hook de pré-commit + portão de CI com fluxo de aprovação integrado.
Um controlador de admissão de dependências nativo do Git. Avalia sinais de confiança em cada alteração de dependência.
O trustlock é executado como um hook de pré-commit do Git (modo consultivo) e uma verificação de CI (modo de 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:
npm install -g trustlock
Requer Node.js >= 18.3.
| Lockfile | Ecossistema | Versões |
|---|---|---|
package-lock.json | npm | v1, v2, v3 |
pnpm-lock.yaml | pnpm | v5, v6, v9 |
yarn.lock | yarn | classic (v1), berry (v2/v3) |
requirements.txt | Python (pip) | — |
uv.lock | Python (uv) | — |
# 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.
# 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.
# 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
# Detectar desvios de versão e inconsistências de proveniência entre pacotes do monorepo
trustlock audit --compare packages/frontend packages/backend packages/shared
| Comando | Descrição |
|---|---|
trustlock init | Inicializa o trustlock no projeto atual |
trustlock check | Avalia as alterações de dependência em relação à política |
trustlock approve <pkg>@<ver> | Aprova um pacote bloqueado |
trustlock audit | Escaneia toda a árvore de dependências para avaliar a postura de confiança |
trustlock audit --compare <dir...> | Compara a postura de dependências entre vários projetos |
trustlock clean-approvals | Remove entradas de aprovação expiradas |
trustlock install-hook | Instala o hook de pré-commit do Git |
O trustlock inclui dois perfis internos selecionáveis com --profile:
| Perfil | Efeito |
|---|---|
strict | Cooldown de 168h, proveniência exigida para todos os pacotes |
relaxed | Cooldown de 24h, sem bloqueio por regressão de proveniência ou mudança de publicador |
# Usar perfil strict no CI
trustlock check --enforce --profile strict
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.
.trustlockrc.jsonAdicione 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.
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.
--ignore-scripts para isso.npm audit ou Snyk para bancos de dados de vulnerabilidades.license-checker ou similar.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.