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

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

Richtlinienprofile

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

# 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.

Das Bedrohungsmodell, das trustlock adressiert, ist eng, aber real: das Zeitfenster zwischen der Veröffentlichung einer bösartigen Version und dem Zeitpunkt, an dem sie entfernt oder gekennzeichnet wird. Schwachstellenscanner arbeiten nachträglich. trustlock arbeitet am Eintrittspunkt, bevor etwas in Ihr Repository oder Ihre CI gelangt.

Das Design ist bewusst minimal. trustlock hat keine Laufzeitabhängigkeiten – es ist selbst ein Tool mit null Supply-Chain-Risiko. Es ersetzt weder einen Schwachstellenscanner noch eine Abhängigkeitsprüfung; es erzwingt Vertrauenskontinuität. Sobald eine Version in Ihrer Baseline ist, wird ihr vertraut. Alles Neue muss sich die Zulassung gemäß der von Ihnen erklärten Richtlinie verdienen.

Der Genehmigungs-Workflow existiert für Teams, die eine Notluke benötigen, ohne die Prüfbarkeit zu verlieren. Jede Übersteuerung ist mit Zeitstempel versehen, auf bestimmte Regeln beschränkt und läuft ab. clean-approvals ist ein erstklassiger Befehl, kein nachträglicher Einfall.