trustlock

Ein Git-nativer Dependency Admission Controller. Bewertet Vertrauenssignale bei jeder Abhängigkeitsänderung.

Funktionsweise

trustlock wird als Git Pre-Commit-Hook (Advisory-Modus) und als CI-Prüfung (Enforce-Modus) ausgeführt:

• Advisory (Pre-Commit): Warnt bei Verstößen, beendet mit Exit-Code 0, aktualisiert die vertrauenswürdige Baseline, wenn alle Pakete zugelassen sind.
• Enforce (--enforce): Blockt bei Verstößen, beendet mit Exit-Code 1, aktualisiert die Baseline nie.

Pro Paket ausgewertete Vertrauenssignale:

• Cooldown – Zeit seit der Veröffentlichung der Version im Registry
• Provenance – ob das Paket SLSA-Attestierungen besitzt
• Pinning – ob die Lockdatei exakte Versionen verwendet
• Install scripts – ob das Paket Skripte zur Installationszeit ausführt
• Sources – ob das Paket aus dem Registry, einer Git-URL, einem lokalen Pfad oder einer URL stammt
• New dependencies – erstmalige Hinzufügungen zum Projekt
• Transitive surprise – unerwarteter Sprung in der Anzahl transitiver Abhängigkeiten
• Publisher change – ob sich die Publisher-Identität des Pakets zwischen Versionen geändert hat

Installation

npm install -g trustlock

Erfordert Node.js >= 18.3.

Unterstützte Lockfiles

Lockfile	Ökosystem	Versionen
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)	—

Schnellstart

Workflow 1 – Ein Projekt einrichten

# 1. trustlock im Projekt initialisieren
trustlock init

# 2. Den Git Pre-Commit-Hook installieren
trustlock install-hook

# 3. Optional: Aktuelle Abhängigkeitssituation überprüfen
trustlock audit

Nach init erstellt trustlock:

• .trustlockrc.json – Richtlinienkonfiguration
• .trustlock/baseline.json – vertrauenswürdiger Abhängigkeits-Snapshot
• .trustlock/approvals.json – Genehmigungsdatensätze
• .trustlock/.cache/ – Registry-Cache (in .gitignore)

Committen Sie .trustlockrc.json und .trustlock/baseline.json in Ihr Repository.

Workflow 2 – Ein Abhängigkeitsupdate prüfen und zulassen

# Normale Installation der Abhängigkeit
npm install [email protected]

# trustlock check wird automatisch über den Pre-Commit-Hook ausgeführt.
# Manuelle Ausführung:
trustlock check

# Ausgabe, wenn alle Pakete zugelassen sind:
# ✔ [email protected] — zugelassen

Wenn alle Pakete bestehen, aktualisiert trustlock check die Baseline automatisch (nur Advisory-Modus) und beendet mit Exit-Code 0.

Workflow 3 – Mit einer blockierten Abhängigkeit umgehen

# Ein neues Paket fällt durch die Cooldown-Regel:
trustlock check
# ✖ [email protected] — blockiert
#   exposure:cooldown  Vor 2h veröffentlicht (Richtlinie erfordert 72h)
#   Zum Zulassen ausführen: trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# Übersteuerung genehmigen, dann erneut prüfen:
trustlock approve [email protected] \
  --override cooldown \
  --reason "Wird für Feature X benötigt; durch Team-Review als sicher bestätigt" \
  --expires 7d

trustlock check
# ✔ [email protected] — mit Genehmigung zugelassen

Workflow 4 – Abhängigkeitssituation über Projekte hinweg vergleichen

# Versionsabweichungen und Provenance-Inkonsistenzen in Monorepo-Paketen erkennen
trustlock audit --compare packages/frontend packages/backend packages/shared

Befehle

Befehl	Beschreibung
trustlock init	trustlock im aktuellen Projekt initialisieren
trustlock check	Abhängigkeitsänderungen gegen die Richtlinie prüfen
trustlock approve <pkg>@<ver>	Ein blockiertes Paket zulassen
trustlock audit	Den gesamten Abhängigkeitsbaum auf Vertrauenswürdigkeit scannen
trustlock audit --compare <dir...>	Abhängigkeitssituation über mehrere Projekte hinweg vergleichen
trustlock clean-approvals	Abgelaufene Genehmigungseinträge entfernen
trustlock install-hook	Den Git Pre-Commit-Hook installieren

Richtlinienprofile

trustlock enthält zwei integrierte Profile, die mit --profile ausgewählt werden können:

Profil	Wirkung
strict	168h Cooldown, Provenance für alle Pakete erforderlich
relaxed	24h Cooldown, kein Block bei Provenance-Regression oder Publisher-Änderung

# Striktes Profil in CI verwenden
trustlock check --enforce --profile strict
## Vererbung von Organisationsrichtlinien

Teams können Richtlinien in einer gemeinsamen URL zentralisieren und pro Repo erweitern:

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

Repo-Konfigurationen können Organisationsrichtlinien nur verschärfen – eine Mindestdurchsetzung verhindert, dass Repos von der Organisation vorgegebene Schwellenwerte unterschreiten.

Dokumentation

• USAGE.md – Vollständige Befehlsreferenz, alle Flags, Exit-Codes, Fehlermeldungen
• POLICY-REFERENCE.md – Jede Option von .trustlockrc.json
• ARCHITECTURE.md – Designentscheidungen und Modulübersicht
• examples/ – Konfigurations- und CI-Workflow-Beispiele

CI-Integration

Fügen Sie trustlock in Ihre CI-Pipeline ein:

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

Siehe examples/ für GitHub Actions-, Lefthook- und Husky-Konfigurationen.

Wo trustlock im Zeitverlauf steht

Trustlock bewertet Lockfile-Änderungen zum Commit-Zeitpunkt. Es fängt nicht in npm install ab oder sandboxt es. Falls ein bösartiges Paket ein Postinstall-Skript ausführt, geschieht dies, bevor trustlock es sieht. Trustlock verhindert, dass die kompromittierte Lockdatei committet und gemerged wird, und begrenzt den Schadensradius auf eine einzelne Entwicklermaschine statt auf das gesamte Team und die Produktion. Für die Blockierung von Skripten zur Installationszeit verwenden Sie --ignore-scripts oder die standardmäßigen Lifecycle-Skriptkontrollen von pnpm.

Was trustlock NICHT tut

• Kein Malware-Scanner – trustlock untersucht keinen Paketquellcode und erkennt keine bekannten bösartigen Signaturen. Verwenden Sie dafür einen dedizierten Scanner.
• Keine Installationszeit-Sandbox – trustlock fängt npm install nicht ab. Verwenden Sie dafür --ignore-scripts.
• Kein CVE-Tracker – verwenden Sie npm audit oder Snyk für Schwachstellendatenbanken.
• Kein Lizenzprüfer – verwenden Sie license-checker oder Ähnliches.
• Kein Ersatz für pnpm trustPolicy oder min-release-age von npm – das sind serverseitige Kontrollen, die vom Registry durchgesetzt werden. trustlock ist ein clientseitiges Admission-Gate an der Repository-Grenze.

Über

trustlock wurde aus Frustration darüber entwickelt, wie passiv die standardmäßige Node.js-Toolchain gegenüber dem ist, was tatsächlich in ein Projekt gelangt. npm install holt alles – ein vor zwei Minuten veröffentlichtes Paket, eines, das bei der Installation beliebige Skripte ausführt, eines, das über Nacht von einem Registry-Tarball zu einer Git-URL gewechselt hat – und das einzige Feedback ist ein Lockfile-Diff.