trustlock

Un contrôleur d'admission de dépendances natif Git. Évalue les signaux de confiance à chaque changement de dépendance.

Comment ça fonctionne

trustlock s'exécute en tant que hook pre-commit Git (mode consultatif) et une vérification CI (mode enforcement) :

• Consultatif (pre-commit) : avertit en cas de violations, sortie 0, avance la base de confiance lorsque tous les paquets sont admis.
• Enforcement (--enforce) : bloque en cas de violations, sortie 1, n'avance jamais la base de confiance.

Signaux de confiance évalués par paquet :

• Cooldown — temps écoulé depuis la publication de la version dans le registre
• Provenance — si le paquet possède des attestations SLSA
• Pinning — si le fichier de verrouillage utilise des versions exactes
• Scripts d'installation — si le paquet exécute des scripts au moment de l'installation
• Sources — si le paquet provient du registre, d'une URL git, d'un chemin local ou d'une URL
• Nouvelles dépendances — premières ajouts au projet
• Surprise transitive — saut inattendu du nombre de dépendances transitives
• Changement d'éditeur — si l'identité de l'éditeur du paquet a changé entre les versions

Installation

npm install -g trustlock

Nécessite Node.js >= 18.3.

Fichiers de verrouillage pris en charge

Démarrage rapide

Workflow 1 — Intégration d'un projet

# 1. Initialize trustlock in your project
trustlock init

# 2. Install the Git pre-commit hook
trustlock install-hook

# 3. Optionally review your current dependency posture
trustlock audit

Après init, trustlock crée :

• .trustlockrc.json — configuration de la politique
• .trustlock/baseline.json — instantané des dépendances de confiance
• .trustlock/approvals.json — enregistrements d'approbation
• .trustlock/.cache/ — cache du registre (ignoré par git)

Commitez .trustlockrc.json et .trustlock/baseline.json dans votre dépôt.

Workflow 2 — Vérifier et admettre une mise à jour de dépendance

# Run dep install as normal
npm install [email protected]

# trustlock check runs automatically via the pre-commit hook.
# To run it manually:
trustlock check

# Output when all packages are admitted:
# ✔ [email protected] — admitted

Lorsque tous les paquets passent, trustlock check avance automatiquement la base de confiance (mode consultatif uniquement) et sort avec 0.

Workflow 3 — Gérer une dépendance bloquée

# A new package fails the cooldown rule:
trustlock check
# ✖ [email protected] — blocked
#   exposure:cooldown  Published 2h ago (policy requires 72h)
#   Run to approve: trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# Approve the override, then re-check:
trustlock approve [email protected] \
  --override cooldown \
  --reason "Needed for feature X; verified safe by team review" \
  --expires 7d

trustlock check
# ✔ [email protected] — admitted with approval

Workflow 4 — Comparer la posture des dépendances entre projets

# Detect version drift and provenance inconsistencies across monorepo packages
trustlock audit --compare packages/frontend packages/backend packages/shared

Commandes

Profils de politique

trustlock propose deux profils intégrés sélectionnables avec --profile :

# Use strict profile in CI
trustlock check --enforce --profile strict

Héritage de politique d'organisation

Les équipes peuvent centraliser la politique dans une URL partagée et l'étendre par dépôt :

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

Les configurations de dépôt ne peuvent que resserrer la politique d'organisation — l'application plancher empêche les dépôts de réduire les seuils imposés par l'organisation.

Documentation

• USAGE.md — Référence complète des commandes, tous les drapeaux, codes de sortie, messages d'erreur
• POLICY-REFERENCE.md — Toutes les options de .trustlockrc.json
• ARCHITECTURE.md — Décisions de conception et carte des modules
• examples/ — Exemples de configuration et de workflow CI

Intégration CI

Ajoutez trustlock à votre pipeline CI :

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

Voir examples/ pour les configurations GitHub Actions, Lefthook et Husky.

##Où se place trustlock dans la chronologie

Trustlock évalue les changements de fichier de verrouillage au moment du commit. Il n'intercepte ni ne sandboxe npm install. Si un paquet malveillant exécute un script post-install, cela se produit avant que trustlock ne le voie. Trustlock empêche le fichier de verrouillage compromis d'être commité et fusionné, contenant ainsi le rayon d'explosion à une seule machine de développeur au lieu de toute l'équipe et de la production. Pour le blocage des scripts au moment de l'installation, utilisez --ignore-scripts ou les contrôles de scripts de cycle de vie par défaut de pnpm.

Ce que trustlock ne fait PAS

• Pas un scanner de malware — trustlock n'inspecte pas le code source des paquets ni ne détecte les signatures malveillantes connues. Utilisez un scanner dédié pour cela.
• Ce n'est pas un bac à sable au moment de l'installation — trustlock n'intercepte pas npm install. Utilisez --ignore-scripts pour cela.
• Pas un traqueur de CVE — utilisez npm audit ou Snyk pour les bases de données de vulnérabilités.
• Pas un vérificateur de licence — utilisez license-checker ou similaire.
• Pas un remplacement pour pnpm trustPolicy ou min-release-age de npm — ce sont des contrôles côté serveur appliqués par le registre. trustlock est une porte d'admission côté client à la limite du dépôt.

À propos

trustlock a été construit par frustration face à la passivité de la chaîne d'outils Node.js standard concernant ce qui est réellement intégré dans un projet. npm install va chercher n'importe quoi — un paquet publié il y a deux minutes, un qui exécute des scripts arbitraires au moment de l'installation, un qui est passé d'une archive de registre à une URL git du jour au lendemain — et le seul retour que vous obtenez est un diff du fichier de verrouillage.

Le modèle de menace auquel trustlock répond est étroit mais réel : la fenêtre entre le moment où une version malveillante est publiée et celui où elle est retirée ou signalée. Les scanners de vulnérabilités opèrent après coup. trustlock opère au point d'admission, avant que quoi que ce soit n'atterrisse dans votre dépôt ou votre CI.

La conception est intentionnellement minimale. trustlock n'a aucune dépendance d'exécution — c'est lui-même un outil à risque zéro de chaîne d'approvisionnement. Il ne remplace pas un scanner de vulnérabilités ou un audit de dépendances ; il applique la continuité de la confiance. Une fois qu'une version est dans votre base de confiance, elle est considérée comme fiable. Tout ce qui est nouveau doit gagner son admission selon la politique que vous déclarez.

Le flux d'approbation existe pour les équipes qui ont besoin d'une porte de sortie sans perdre en auditabilité. Chaque dérogation est horodatée, limitée à des règles spécifiques et expire. clean-approvals est une commande de premier ordre, non une réflexion après coup.