Inhalt

• Erste Schritte – von null zu installiert in etwa fünf Minuten
• Was es tut
• Was es auslöst
• Was in diesem Repository ist
• Unterstützte Ökosysteme
• Installation
  • Konfiguration
  • Ändern der Abkühlphase
• Warnstufen
• Wie es funktioniert
  • Normaler Modus (Manuell)
  • Abfangmodus (Automatisch)
  • Vorinstallationsmodus (Bash-Hook)
  • Nachinstallationsmodus (Bash-Hook)
  • Post-Agent-Modus (Agent-Hook-Paar)
• Prüfprotokoll
• Anforderungen
• FAQ

Erste Schritte

GETTING-STARTED.md führt Sie in etwa fünf Minuten von null zu einer funktionierenden Installation – Voraussetzungen, die interaktive Installation und die Verifizierung. Für die vollständige Installationsreferenz (globale/Projekt-/manuelle Installationen, Windows-Besonderheiten, die Berechtigungs-Allowlist, Aktualisierung und Deinstallation) siehe INSTALLATION.md.

Tägliche Nutzung: Sobald die Hooks installiert sind, gibt es nichts auszuführen – safer-dependencies arbeitet automatisch im Hintergrund. Wenn Claude Pakete hinzufügt oder installiert, kennzeichnet es riskante Abhängigkeiten und aktualisiert verwundbare Versionen direkt an Ort und Stelle auf eine sichere Version – und blockiert eine bekannte verwundbare Installation, bevor sie überhaupt ausgeführt wird – sodass unsichere Pakete erkannt und korrigiert werden, ohne dass Sie fragen müssen. Sie können es jederzeit direkt aufrufen: „Ist [email protected] sicher?", „prüfe safer-dependencies Setup" oder „zeige safer-dependencies Statistiken".

Was es tut

Wenn Claude kurz davor ist, ein Paket zu Ihrem Projekt hinzuzufügen, greift safer-dependencies ein und führt 5 Prüfungen durch:

1. Herkunft – offizielles Registry, Typosquat-Erkennung (npm/PyPI/RubyGems/Maven/crates.io), Paketalter
2. Versionsalter – wählt die neueste stabile Version aus, die vor 7+ Tagen veröffentlicht wurde (Abkühlfenster)
3. Schwachstellenscan – OSV-API, mit ökosystemeigenen Tools (npm audit, pip-audit, bundle audit), wenn verfügbar
4. Hash-Pin-Integrität – für PyPI requirements.txt-Zeilen mit --hash=sha256:...-Pins wird der deklarierte Hash gegen die von PyPI veröffentlichten Hashes validiert; eine Abweichung erzeugt eine WARNUNG
5. Verwaiste & veraltete Pakete – bekannte verwaiste Pakete (z. B. paperclip, request, pycrypto, github.com/dgrijalva/jwt-go) werden sofort hart blockiert mit einem vorgeschlagenen Ersatz; Pakete ohne stabile Veröffentlichung in 2+ Jahren erhalten eine Hinweis-Warnung STALE:. Hart blockierte Pakete werden aus dem Manifest entfernt und Claude fragt, wie fortgefahren werden soll; nur veraltete Pakete bleiben an Ort und Stelle.

Wenn Probleme gefunden werden, gibt Claude Warnungen aus und kann auf eine sicherere Version zurückgehen. Alle Prüfungen werden in ~/.claude/safer-dependencies-audit-YYYY-MM.log protokolliert (eine Datei pro Kalendermonat).

Was es auslöst

Die Skill wird automatisch ausgelöst, wenn Claude:

Manifest-/Installationsoperationen

• Ein Paket in package.json, requirements.txt, Gemfile, pom.xml, build.gradle, Cargo.toml, go.mod oder einem anderen unterstützten Manifest hinzufügt oder aktualisiert
• Ein import, require oder use für ein Paket schreibt, das nicht bereits im Manifest deklariert ist
• Eine Lock-Datei generiert oder aktualisiert (prüft nur neue/geänderte Einträge)
• Eine Paketmanager-Installation über Bash ausführt (npm install, bundle install, poetry install, uv sync, go mod tidy, usw.) – Pre-Install prüft die Befehlsargumente, Post-Install prüft die resultierende Lock-Datei
• Ein Dockerfile oder CI-Workflow schreibt (.github/workflows/*.yml, usw.), das gepinnte Paketmanager-Installationsschritte enthält

Auswahl- & Empfehlungsfragen

• Bibliotheks-/Framework-Vergleiche: „sollte ich axios oder node-fetch verwenden?", „moment vs dayjs?", „welches ist besser X oder Y?"
• Empfehlungsanfragen: „Was ist ein guter HTTP-Client für Python?", „empfiehl eine Logging-Bibliothek für Go", „welches Paket verarbeitet CSV in Node?"
• Versionsauswahl: „Welche Version von Django sollte ich verwenden?", „neuestes stabiles Flask?"

Absichtserklärungen zur Nutzung (vor dem Hinzufügen)

• „Ich möchte FastAPI dafür verwenden", „Ich denke darüber nach, Celery hinzuzufügen", „wir schauen uns Prisma als ORM an", „lass uns Tailwind verwenden"

Fragen zu Paketgesundheit und Vertrauen

• „Wird moment.js noch gepflegt?", „ist dieses Gem noch aktiv?", „ist X verwaist?", „ist X EOL?", „kann ich diesem Paket vertrauen?", „wann wurde faker zuletzt aktualisiert?"

Scaffolding-Befehle

• npx create-react-app, npm create vite@latest, django-admin startproject, rails new, cargo new + cargo add, „ein neues FastAPI-Projekt bootstrappen"

Implizite Paket-Hinzufügungen (Feature-Anfragen, die eine neue Abhängigkeit implizieren)

• „Redis-Caching zur App hinzufügen", „mit Postgres verbinden", „JWT-Auth hinzufügen", „Code zum Senden von E-Mails schreiben" – wird ausgelöst, wenn kein Paket für diese Fähigkeit bereits im Manifest vorhanden ist

Migration und Portierung

• „Von requests zu httpx migrieren", „von CRA zu Vite wechseln", „von moment zu date-fns portieren" – prüft das eingehende Paket

Es wird nicht ausgelöst für:

• Standardbibliotheks-Importe (os, fs, java.util.*, usw.)
• Bereits deklarierte Abhängigkeiten, die nicht geändert werden
• Akademische Diskussion darüber, wie ein Paket intern funktioniert („erkläre Reacts Reconciler", „wie funktioniert webpacks Modulauflösung?") – Vergleichs- und Auswahlfragen lösen weiterhin aus
• Installation von Betriebssystem-Apps, Laufzeiten oder IDE-Erweiterungen (Python selbst, Docker, Homebrew, VS-Code-Erweiterungen)

Was in diesem Repository ist

Dies ist ein Skill + Hook-Bundle, keine einzelne Skill-Datei. Eine vollständige Installation stellt diese Komponenten bereit:

Die Skill-Datei allein reicht nicht aus – ohne Hooks hängt die automatische Auslösung davon ab, dass Claude sich entscheidet, die Skill zu verwenden. Installieren Sie alle fünf Komponenten für vollständige Abdeckung; viele Skills und Slash-Befehle starten intern Subagenten, daher ist das Post-Agent-Paar wichtig, selbst wenn Sie nie explizit einen spawnen. (Siehe FAQ.md für den Grund, warum eine Skill allein keine Abdeckung garantieren kann.)

Unterstützte Ökosysteme

Installation

Neu im Projekt? Beginnen Sie mit GETTING-STARTED.md. Die Kurzversion:```bash git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

Die gleichen Verben funktionieren auch außerhalb einer Claude-Sitzung:```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14

Das übergeordnete Agent verwendet diese Signale, um betroffenen Code zu identifizieren und bei Bedarf zu refaktorieren.

Pre-Install-Modus (Bash-Hook)

Konfigurieren Sie .claude/settings.json mit einem PreToolUse:Bash-Hook, um die Vorab-Prüfung von Paketmanager-Installationsbefehlen zu aktivieren. Dies ergänzt (ersetzt nicht) den Intercept-Modus – zusammen bilden sie eine mehrschichtige Verteidigung.

1. Claude versucht einen Bash-Toolaufruf (z. B. npm install [email protected])
2. Der PreToolUse-Hook feuert, bevor der Aufruf ausgeführt wird, und ruft safer-dependencies-pretooluse-bash.sh auf
3. Ein reiner-Bash-Frühfilter leitet Nicht-PM-Befehle in ca. 115 ms um (kein Python-Aufruf), sodass git status / ls / npm test nur vernachlässigbare Kosten auf dem heißen Pfad verursachen
4. Für erkannte Paketmanager-Installationen (npm/pnpm/yarn install/i/add) tokenisiert das Hilfsprogramm über shlex, extrahiert jedes pkg@version-Argument und sendet es per POST an OSV
5. Jeder verwundbare konkrete Pin → der Hook gibt permissionDecision: "deny" zurück, mit einer GHSA-ID pro Befund + CVSS + Zusammenfassung, plus einem Hinweis, die safer-dependencies-Skill aufzurufen
6. Die Installation wird nie ausgeführt – kein Netzwerkabruf, keine Postinstall-Skripte

Warum dies zusätzlich zum Intercept-Modus existiert: Der Post-Write-Shim ist gegenüber Bash blind. npm install [email protected] läuft vollständig durch (und Postinstall-Skripte werden ausgeführt), bevor eine Prüfung feuert; npm install -g typosquat-pkg schreibt überhaupt kein Projektmanifest. Der Pre-Install-Modus schließt diese Lücken strukturell.

Der Pre-Install-Modus sieht nur, was der Benutzer eingegeben hat (pkg@version-Argumente auf der Befehlszeile). Er kann den transitiven Baum, den der Resolver tatsächlich installieren wird, nicht sehen. Post-Install-Modus (unten) prüft die Lockfile, sobald die Installation abgeschlossen ist – die beiden Modi ergänzen sich, sind nicht redundant.

Umfang: Die hier abgedeckten Paketmanager-CLIs umfassen fünf Ökosysteme (npm/pnpm/yarn/bun/npx/deno, pip/pip3/pipx/pipenv/uv/uvx/poetry, gem/bundle, go, cargo), plus Maven über den Intercept-Modus (Maven-Abhängigkeiten werden typischerweise in pom.xml/build.gradle deklariert, nicht über ein CLI-Verb hinzugefügt).

Bekannte Lücke: Die Maven-CLI unterstützt zwar direkte Downloads über mvn dependency:get -Dartifact=group:art:version und mvn dependency:copy. Dieser Hook erkennt diese Aufrufe noch nicht. Wenn Sie sie regelmäßig verwenden, fängt der bestehende Post-Write-Shim weiterhin alles ab, was in Ihr Manifest gelangt, aber der Vorab-Fetch-Schutz gilt nur für die oben aufgeführten Ökosysteme. Als Folgeaufgabe erfasst.

Pro-Ökosystem erkannte Syntax:

Bereichs-Pins (npm ^4.17, pip >=, poetry ^/~, Go @latest) und nicht spezifizierte Versionen werden nach der Installation an den Intercept-Modus durchgereicht – der Post-Write-Shim prüft, was auch immer der Resolver auswählt. Automatisches Umschreiben auf eine sichere Version ist als Folgeaufgabe geplant.

Fehlermodus: Fail-open. Jeder Fehler (Python fehlt, Netzwerkstörung, fehlerhafte Eingabe) beendet mit 0 und ohne Ausgabe, sodass Bash fortfahren kann. Der Intercept-Modus läuft weiterhin nach der Installation, sodass eine fehlgeschlagene Vorabprüfung auf bestehenden Schutz zurückfällt.

Beispiel für eine Ablehnung:``` safer-dependencies pre-flight audit blocked this install. Vulnerable pinned version(s) detected:

• [email protected] → GHSA-35jh-r3h4-6jhm (CVSS:7.4): Command Injection in lodash Re-run with a patched version, or invoke the safer-dependencies skill for a recommended pin.

Post-Agent-Modus (Agent-Hook-Paar)

Die vier oben genannten Modi greifen nur bei Tool-Aufrufen der Root-Session. Wenn die Root-Session einen Subagenten auslöst (über das Agent-Tool – viele Skills und Slash-Befehle tun dies intern), umgehen die Write/Edit/Bash-Aufrufe des Subagenten alle diese Modi. Der Post-Agent-Modus ist das reaktive Sicherheitsnetz für diese Lücke.

1. Ein PreToolUse:Agent-Hook (safer-dependencies-pretooluse-agent.sh) wird unmittelbar vor jeder Agent-Auslösung ausgeführt und erstellt eine Sentinel-Datei unter /tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel (mit Fallback auf einen nur-PPID-Namen, wenn keine Session-ID verfügbar ist)
2. Der Subagent wird ausgeführt und kann Manifeste oder Lockfiles schreiben
3. Ein PostToolUse:Agent-Hook (safer-dependencies-posttooluse-agent.sh) wird nach der Rückkehr des Agent-Aufrufs ausgeführt, sucht per find nach jedem Manifest und Lockfile, das neuer als die Sentinel-Datei ist, und prüft jedes über denselben Shim-Pfad
4. Ergebnisse werden als additionalContext an die nächste Runde der Root-Session übergeben; die Sentinel-Datei wird entfernt

Verschachtelte Subagenten werden automatisch abgedeckt – der PostToolUse:Agent-Hook der Root-Session feuert erst, nachdem die gesamte Arbeit des äußeren Agents (einschließlich allem, was dieser ausgelöst hat) auf der Festplatte liegt. Die eine Lücke ist eine globale Installation, die kein Manifest oder Lockfile schreibt (npm install -g …): Es gibt nichts zu scannen. Wie die anderen Hooks schlägt er offen fehl – jeder Fehler (fehlende Sentinel-Datei, fehlender Shim, unlesbare Nutzlast) wird mit Exit-Code 0 still beendet. Die vollständige Design-Begründung befindet sich in skills/safer-dependencies.md.

Audit-Log

Jede Prüfung wird in ~/.claude/safer-dependencies-audit-YYYY-MM.log protokolliert (eine Datei pro Kalendermonat, wobei YYYY-MM das UTC-Jahr-Monat ist) als einzelne JSON-Zeile. Überschreiben Sie den vollständigen Pfad mit der Umgebungsvariable SAFE_DEP_AUDIT_LOG (wenn gesetzt, wird das Datumssuffix nicht angehängt). Dateien werden außerdem größenbasiert rotiert, wenn sie SAFE_DEP_LOG_MAX_BYTES überschreiten (Standard 10 MiB; auf 0 setzen, um zu deaktivieren). Setzen Sie SAFE_DEP_MODEL, um den Modellwert zu überschreiben, der in source.model in jedem Eintrag geschrieben wird – nützlich für A/B-Vergleiche zwischen Modellversionen.

Alle fünf Modi hängen an dieselbe Datei an. Jeder Eintrag enthält einen source-Block (Schema 2.2), der angibt, welche Komponente ihn geschrieben hat:

source.model zeichnet das in der Session aktive Claude-Code-Modell auf (z. B. "claude-sonnet-4-6"). Vorhanden in Schema 2.1+; Einträge, die von älteren Installationen geschrieben wurden, lassen das Feld aus. Der Statistikbefehl degradiert elegant auf "unknown", wenn es fehlt.

Filtern Sie nach source.component mit jq:```bash jq -r '.source.component' audit.log | sort | uniq -c | sort -rn jq -c 'select(.source.component == "bash.pretooluse")' audit.log

Surface every silent fail-open across all hooks:

jq -c 'select(.source.mode == "fail_open") | {component: .source.component, reason: .fail_open.reason, ts}' audit.log

Dies liefert menschenlesbare Zusammenfassungen von Aktivität, Sicherheitsauswirkungen und Leistungskennzahlen, die aus diesen Audit-Protokollen extrahiert wurden.

Eintragsformen (Schema 2.2). Drei unterschiedliche Formen teilen sich denselben ts / schema / source-Kopf:

Audit-Einträge: Der Intercept-Modus führt die vollständige Pipeline aus (Provenienz, Versionsalter, OSV, abandoned/stale, Typosquatting, Signaturen), sodass alle Arrays befüllt werden können. Der Pre-Install-Modus führt heute nur OSV aus, daher sind abandoned / stale / typosquat / signatures immer leer. Die Post-Install-Dispatch (Lockfile-Audit) schreibt unter shim.posttooluse, wobei findings durch WARNING:-Zeichenfolgen aus den Lockfile-Auditoren befüllt wird. Das notes-Array trägt informative NOTE:-Signale (z. B. Manifest-übersprungen-weil-nicht-gepinnt).

Schema 2.2 fügte — additiv — vier Felder zu Lockfile-Audit-Einträgen hinzu: lockfile, manifest_ref, relation_summary (eine direkte/transitive/unbekannte Klassifizierung jedes markierten Pakets gegenüber dem zugehörigen Manifest) sowie einen policy-Block, der die geltende transitive-Stufe aufzeichnet. Das Update ist abwärtskompatibel: Leser von 2.1-Einträgen tolerieren die neuen Felder, und das Feld source.model bleibt ab 2.1 vorhanden.```json { "ts": "2026-04-19T12:34:56Z", "schema": "2.2", "source": { "component": "shim.posttooluse", "script": "shim.sh", "hook": "PostToolUse:Write", "tool": "Write", "mode": "intercept", "model": "claude-sonnet-4-6" }, "file": "/path/to/project/package.json", "ecosystem": "npm", "checked": ["[email protected]", "[email protected]"], "findings": ["UPDATED: express 4.18.2 → 4.22.1 (HIGH: 1 CVE fixed)"], "abandoned": [], "stale": [], "typosquat": [], "unknown": [], "signatures": [], "notes": [], "clean": ["[email protected]"] }

Fail-open-Modus-Beispiel (Post-Install-Bash-Hook, der ohne angrenzenden Shim aufgerufen wird — fehlerhafte Installation):```json { "ts": "2026-05-03T07:14:11Z", "schema": "2.2", "source": { "component": "bash.posttooluse", "script": "safer-dependencies-posttooluse-bash.sh", "hook": "PostToolUse", "tool": "Bash", "mode": "fail_open", "model": "claude-sonnet-4-6" }, "fail_open": { "reason": "shim_missing", "detail": "/home/alice/.claude/skills/safer-dependencies" } }