trustlock

Un admission controller per dipendenze nativo Git. Valuta i segnali di fiducia a ogni modifica delle dipendenze.

Come funziona

trustlock viene eseguito come hook pre-commit Git (modalità advisory) e come controllo CI (modalità enforce):

• Advisory (pre-commit): avvisa in caso di violazioni, esce con 0, aggiorna la baseline di fiducia quando tutti i pacchetti sono ammessi.
• Enforce (--enforce): blocca in caso di violazioni, esce con 1, non aggiorna mai la baseline.

Segnali di fiducia valutati per ogni pacchetto:

• Cooldown — da quanto tempo la versione è stata pubblicata nel registro
• Provenienza — se il pacchetto possiede attestazioni SLSA
• Pinning — se il file di lock utilizza versioni esatte
• Script di installazione — se il pacchetto esegue script durante l'installazione
• Origini — se il pacchetto proviene dal registro, da un URL git, da un percorso locale o da un URL
• Nuove dipendenze — aggiunte per la prima volta al progetto
• Sorpresa transitiva — aumento inaspettato del numero di dipendenze transitive
• Cambio publisher — se l'identità del publisher del pacchetto è cambiata tra versioni

Installazione

npm install -g trustlock

Richiede Node.js >= 18.3.

Lockfile supportati

Avvio rapido

Flusso 1 — Inizializzare un progetto

# 1. Inizializza trustlock nel tuo progetto
trustlock init

# 2. Installa l'hook Git pre-commit
trustlock install-hook

# 3. Opzionalmente, verifica la postura corrente delle dipendenze
trustlock audit

Dopo init, trustlock crea:

• .trustlockrc.json — configurazione della policy
• .trustlock/baseline.json — snapshot delle dipendenze fidate
• .trustlock/approvals.json — registri delle approvazioni
• .trustlock/.cache/ — cache del registro (ignorata da git)

Esegui il commit di .trustlockrc.json e .trustlock/baseline.json nel repository.

Flusso 2 — Verificare e ammettere un aggiornamento di dipendenza

# Esegui una normale installazione di dipendenze
npm install [email protected]

# trustlock check viene eseguito automaticamente tramite l'hook pre-commit.
# Per eseguirlo manualmente:
trustlock check

# Output quando tutti i pacchetti sono ammessi:
# ✔ [email protected] — ammesso

Quando tutti i pacchetti superano il controllo, trustlock check aggiorna automaticamente la baseline (solo in modalità advisory) ed esce con 0.

Flusso 3 — Gestire una dipendenza bloccata

# Un nuovo pacchetto non supera la regola di cooldown:
trustlock check
# ✖ [email protected] — bloccato
#   exposure:cooldown  Pubblicato 2 ore fa (la policy richiede 72h)
#   Esegui per approvare: trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# Approva l'override, poi riesegui il controllo:
trustlock approve [email protected] \
  --override cooldown \
  --reason "Necessario per la funzionalità X; verificato sicuro dal team" \
  --expires 7d

trustlock check
# ✔ [email protected] — ammesso con approvazione

Flusso 4 — Confrontare la postura delle dipendenze tra progetti

# Rileva drift di versione e incongruenze di provenienza tra pacchetti del monorepo
trustlock audit --compare packages/frontend packages/backend packages/shared

Comandi

Profili di policy

trustlock include due profili integrati selezionabili con --profile:

# Usa il profilo strict in CI
trustlock check --enforce --profile strict

Ereditarietà della policy organizzativa

I team possono centralizzare la policy in un URL condiviso ed estenderla per singolo repository:

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

Le configurazioni dei repository possono solo inasprire la policy organizzativa — l'enforcement minimo impedisce ai repository di ridurre le soglie imposte dall'organizzazione.

Documentazione

• USAGE.md — Riferimento completo ai comandi, tutti i flag, codici di uscita, messaggi di errore
• POLICY-REFERENCE.md — Ogni opzione di .trustlockrc.json
• ARCHITECTURE.md — Decisioni di design e mappa dei moduli
• examples/ — Esempi di configurazione e workflow CI

Integrazione CI

Aggiungi trustlock alla tua pipeline CI:

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

Vedi examples/ per configurazioni GitHub Actions, Lefthook e Husky.

Dove si colloca trustlock nella timeline

Trustlock valuta le modifiche al lockfile al momento del commit. Non intercetta né esegue il sandboxing di npm install. Se un pacchetto malevolo esegue uno script postinstall, quell'esecuzione avviene prima che trustlock lo veda. Trustlock impedisce che il lockfile compromesso venga committato e unito, contenendo il raggio di esplosione a una singola macchina sviluppatore anziché all'intero team e alla produzione. Per il blocco degli script in fase di installazione, usa --ignore-scripts o i controlli predefiniti del ciclo di vita di pnpm.

Cosa trustlock NON fa

• Non è uno scanner di malware — trustlock non ispeziona il codice sorgente dei pacchetti né rileva firme note di malware. Usa uno scanner dedicato per quello.
• Non è un sandbox in fase di installazione — trustlock non intercetta npm install. Usa --ignore-scripts per quello.
• Non è un tracker CVE — usa npm audit o Snyk per i database di vulnerabilità.
• Non è un verificatore di licenze — usa license-checker o simili.
• Non sostituisce pnpm trustPolicy o min-release-age di npm — si tratta di controlli lato server applicati dal registro. trustlock è un gate di ammissione lato client al confine del repository.

Informazioni

trustlock è nato dalla frustrazione per quanto passivo sia il toolchain standard di Node.js riguardo a ciò che viene effettivamente introdotto in un progetto. npm install recupera qualsiasi cosa — un pacchetto pubblicato due minuti fa, uno che esegue script arbitrari in fase di installazione, uno che è passato da un tarball del registro a un URL git durante la notte — e l'unico feedback che ottieni è un diff del lockfile.

Il modello di minaccia affrontato da trustlock è ristretto ma reale: la finestra tra quando una versione malevola viene pubblicata e quando viene rimossa o segnalata. Gli scanner di vulnerabilità operano dopo il fatto. trustlock opera al punto di ammissione, prima che qualcosa arrivi nel tuo repository o nella tua CI.

Il design è intenzionalmente minimale. trustlock non ha dipendenze a runtime — è esso stesso uno strumento a rischio zero di supply chain. Non sostituisce uno scanner di vulnerabilità o un audit delle dipendenze; impone la continuità della fiducia. Una volta che una versione è nella tua baseline, è considerata fidata. Qualsiasi cosa di nuovo deve guadagnarsi l'ammissione secondo la policy che hai dichiarato.

Il flusso di approvazione esiste per i team che hanno bisogno di una via di fuga senza perdere la tracciabilità. Ogni override è timestampato, limitato a regole specifiche e scade. clean-approvals è un comando di prima classe, non un ripensamento.