Sicherere Abhängigkeiten für Claude Code

Wenn KI-Codierungsassistenten wie Claude Pakete zu deinem Projekt hinzufügen, wählen sie oft einfach eine Version, die sich richtig anhört – ohne zu prüfen, ob sie bekannte Sicherheitsschwachstellen aufweist, ob das Paket noch aktiv gepflegt wird oder ob der Name nur einen Tippfehler von einem bösartigen Nachahmer entfernt ist.

safer-dependencies ist eine Sicherheitsschicht für Claude Code: Sie sitzt zwischen Claude und deinen Manifest-Dateien und führt ihre Sicherheitsprüfungen automatisch aus: Verwundbare Installationen werden blockiert, bevor sie ausgeführt werden, und eine riskante Version, die in ein Manifest geschrieben wurde, wird direkt nach dem Schreiben auf der Festplatte korrigiert. Sie erkennt und behebt riskante Abhängigkeiten – CVEs, Typosquats, verwaiste Pakete und Probleme mit dem Versionsalter, plus eine Abkühlphase für brandneue Veröffentlichungen – in npm, PyPI, RubyGems, Maven, Go, Rust und PHP (Composer). Siehe CAPABILITIES.md für genaue Angaben dazu, was abgedeckt ist und was nicht.

Neu hier? GETTING-STARTED.md führt dich in etwa fünf Minuten von Null zu einer funktionierenden Installation.

Sicherheit & Datenschutz: siehe SECURITY.md (Offenlegung von Schwachstellen), PRIVACY.md (Datenabfluss, keine Telemetrie) und CAPABILITIES.md (was das Tool abwehrt und was nicht).

Lizenz (Quellcode verfügbar – NICHT OSI „Open Source“): Kostenlose Nutzung und Änderung für eigene Zwecke, einschließlich gewinnorientierter/unternemensinterner Nutzung und der Entwicklung von Produkten, die du verkaufst. Eine separate kostenpflichtige Lizenz ist nur erforderlich, um die Software selbst zu monetarisieren – sie zu verkaufen, sie in ein Produkt oder einen Dienst zu integrieren, das/der verkauft wird, oder ihre Funktionalität Dritten gegen Gebühr anzubieten (einschließlich gehostet/SaaS/API). Weitergabe und abgeleitete Werke müssen die Lizenz beibehalten und dieses Projekt nennen. Siehe LICENSE (Abschnitt 4 für die kommerzielle Einschränkung); Anfragen für kommerzielle Lizenzen über github.com/robert-auger.

Inhalt

• Erste Schritte – von Null zu installiert in etwa fünf Minuten
• Was es tut
• Wie es funktioniert
  • Normaler Modus (manuell)
  • Abfangmodus (automatisch)
  • Vorinstallationsmodus (Bash-Hook)
  • Nachinstallationsmodus (Bash-Hook)
  • Post-Agent-Modus (Agent-Hook-Paar)
• Was es auslöst
• Was in diesem Repository enthalten ist
• Unterstützte Ökosysteme
• Installation
  • Konfiguration
• Warnstufen
• Prüfprotokoll
• Voraussetzungen
• FAQ

Erste Schritte

GETTING-STARTED.md führt dich in etwa fünf Minuten von Null zu einer funktionierenden Installation – Voraussetzungen, die interaktive Installation und die Verifizierung. Die vollständige Installationsreferenz (globale/Projekt-/manuelle Installationen, Windows-Besonderheiten, die Berechtigungs-Allowlist, Aktualisierung und Deinstallation) findest du unter 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 stuft verwundbare Versionen direkt auf eine sichere Version hoch – und blockiert eine bekanntermaßen verwundbare Installation, bevor sie überhaupt ausgeführt wird – sodass unsichere Pakete erkannt und korrigiert werden, ohne dass du fragen musst. Du kannst es jederzeit direkt aufrufen: „Ist [email protected] sicher?“, „Prüfe safer-dependencies-Setup“ oder „Zeige safer-dependencies-Statistiken“.

Was es tut

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

1. Herkunft – offizielle 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), sofern 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 – bekanntermaßen verwaiste Pakete (z. B. paperclip, request, pycrypto, github.com/dgrijalva/jwt-go) werden sofort hart blockiert, mit einem Vorschlag für einen Ersatz; Pakete ohne stabile Veröffentlichung seit 2+ Jahren erhalten eine hinweisende STALE:-Warnung. Hart blockierte Pakete werden aus dem Manifest entfernt und Claude fragt, wie es weitergehen 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).

Wie es funktioniert

Die Fähigkeit arbeitet in fünf Modi (unten zusammengefasst; die tiefste Design-Begründung findest du in skills/safer-dependencies.md):

Normaler Modus (manuell)

Wenn Claude gerade dabei ist, einen import zu schreiben, ein Paket zu einem Manifest hinzuzufügen oder eine Sperrdatei zu aktualisieren, läuft die Fähigkeit inline in deiner Sitzung:

1. Fragt die Paket-Registry nach stabilen Versionen ab
2. Wählt automatisch die neueste Version aus, die vor 7+ Tagen veröffentlicht wurde (deterministisch – kein LLM-Urteil)
3. Prüft auf bekannte Schwachstellen über Ökosystem-Tools und die OSV-API
4. Verifiziert Paketsignaturen, sofern verfügbar
5. Gibt Warnungen aus, wenn Probleme gefunden werden, und pinnt die genaue Version
6. Protokolliert das Ergebnis im Prüfpfad

Die Versionsauswahl wird von eigenständigen Python-Skripten übernommen, die mit der Fähigkeit gebündelt sind, nicht vom LLM, das Regeln interpretiert. Der Befehl gibt SELECTED: <version> aus und Claude verwendet genau diese Version.

Abfangmodus (automatisch)

Konfiguriere .claude/settings.json mit einem PostToolUse-Hook, um eine automatische, transparente Paketverifizierung zu aktivieren:

1. Claude schreibt eine Manifest-Datei (z. B. package.json) mit der ursprünglich angeforderten Version – die Datei landet auf der Festplatte
2. Der PostToolUse-Hook feuert unmittelbar nach Abschluss des Schreibvorgangs und ruft safer-dependencies-shim.sh auf
3. Der Shim liest die Datei, parst die deklarierten Pakete und führt alle Sicherheitsprüfungen aus (Typosquat, verwaist, CVE, Veraltetheit, Hash-Pin)
4. Wenn Korrekturen erforderlich sind, schreibt der Shim das Manifest direkt auf der Festplatte neu – mit sicheren Versionen (oder entfernt Einträge, für die es keine sichere Version gibt)
5. Der Shim gibt Signale (UPDATED:, BLOCKED:, WARNING:, STALE:, MAJOR-UPDATE-CONFIRM:, REFACTOR-REQUIRED:, REGRESSION:, TYPOSQUAT-CONFIRM:, VERIFY:, ) über auf stdout aus. geht einem voraus, wenn das Prüfprotokoll zeigt, dass (Datei, Paket) zuvor bereits auf dasselbe sichere Ziel korrigiert wurde – das heißt, ein Unteragent oder ein veralteter Plan hat eine bekanntermaßen verwundbare Version wieder eingeführt, und der Orchestrator sollte die zuvor genehmigte Version wiederherstellen, anstatt den Major-Bump neu zu entscheiden.

Design-Hinweis – Form C (korrigierend nach dem Schreiben): Der Hook blockiert KEINE Schreibvorgänge. Jede verwundbare Version landet zuerst auf der Festplatte und wird dann innerhalb desselben Tool-Use-Zyklus automatisch korrigiert. Dies ist eine bewusste Entscheidung gegenüber einem blockierenden PreToolUse-Design – siehe FAQ.md für die Abwägungen.

Beispielsignal:``` UPDATED: aiohttp 3.8.5 → 3.9.0 (HIGH: 33 CVEs fixed)

Der übergeordnete Agent nutzt 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 Vorabprüfung von Paketmanager-Installationsbefehlen zu aktivieren. Dieser ergänzt den Intercept-Modus (ersetzt ihn jedoch nicht) — zusammen bilden sie eine mehrschichtige Verteidigung.

1. Claude versucht einen Bash-Toolaufruf (z. B. `npm install [email protected]`)
2. Der `PreToolUse`-Hook wird ausgelöst, bevor der Aufruf ausgeführt wird, und ruft `safer-dependencies-pretooluse-bash.sh` auf
3. Ein reiner Bash-Frühfilter scheidet Nicht-PM-Befehle in ~115 ms frühzeitig aus (ohne Python-Aufruf), sodass `git status` / `ls` / `npm test` auf dem Hot Path vernachlässigbare Kosten verursachen
4. Bei erkannten Paketmanager-Installationen (`npm`/`pnpm`/`yarn` `install`/`i`/`add`) tokenisiert der Helfer über `shlex`, extrahiert jedes `pkg@version`-Argument und sendet es per POST an OSV
5. Bei jedem verwundbaren konkreten Pin gibt der Hook `permissionDecision: "deny"` zurück, mit einer GHSA-ID + CVSS + Zusammenfassung pro Befund sowie einem Hinweis, den Skill safer-dependencies aufzurufen
6. Die Installation wird nie ausgeführt — kein Netzwerkabruf, keine Postinstall-Skripte

**Warum es 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 irgendein Audit ausgelöst wird; `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 das, was der Benutzer **eingegeben** hat (`pkg@version`-Argumente in der Befehlszeile). Er kann den transitiven Abhängigkeitsbaum nicht sehen, den der Resolver tatsächlich installieren wird. Der **Post-Install-Modus** (weiter unten) prüft die Lockfile, sobald die Installation abgeschlossen ist — die beiden Modi ergänzen sich, sind nicht redundant.

**Geltungsbereich:** 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) sowie Maven über den Intercept-Modus (Maven-Abhängigkeiten werden normalerweise in `pom.xml`/`build.gradle` deklariert und nicht über ein CLI-Verb hinzugefügt).

> **Bekannte Lücke:** Das Maven-CLI unterstützt zwar direkte Downloads über `mvn dependency:get -Dartifact=group:art:version` und `mvn dependency:copy`. Dieser Hook erkennt diese Aufrufe jedoch noch nicht. Wenn Sie sie regelmäßig verwenden, fängt der vorhandene Post-Write-Shim weiterhin alles ab, was in Ihrem Manifest landet, aber der Pre-Fetch-Schutz gilt nur für die oben aufgeführten Ökosysteme. Wird als Folgeaufgabe nachverfolgt.

Erkannte Syntax pro Ökosystem:

| PM | Verben | Konkrete-Pin-Syntax |
|---|---|---|
| `npm`, `pnpm`, `yarn`, `bun` | `install`, `i`, `add` (plus `yarn`/`pnpm dlx`, `bun x`, `yarn create`) | `[email protected]`, `@scope/[email protected]` |
| `npx` | (ohne Verb — das Paket ist das erste Positionsargument) | `[email protected]` |
| `deno` | `add`, `install` | `npm:[email protected]` (npm-präfixierte Spezifikationen) |
| `pip`, `pip3`, `pipx`, `pipenv`, `uv`, `uvx`, `poetry` | `install` (pip/pip3/pipx/pipenv) / `add` (uv/poetry) / ohne Verb (uvx) | `pkg==1.2.3` (auch Extras `pkg[extra]==X` werden unterstützt) |
| `gem`, `bundle` | `install` (gem) / `add` | `-v 1.2.3`, `--version 1.2.3`, `--version=1.2.3` (separates Flag) |
| `go` | `get`, `install` | `[email protected]` (muss gemäß Go-Modulen das `v`-Präfix enthalten) |
| `cargo` | `add`, `install` | `[email protected]` |

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

**Fehlermodus:** Fail-open. Jeder Fehler (fehlendes Python, Netzwerkstörung, fehlerhafte Eingabe) endet mit Exit-Code 0 und ohne Ausgabe, sodass bash fortfahren kann. Der Intercept-Modus läuft weiterhin nach der Installation, sodass ein fehlgeschlagener Pre-Flight-Check elegant auf den bestehenden Schutz zurückfällt.

**Beispiel einer Verweigerung:**```
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-Install-Modus (Bash-Hook)

Konfigurieren Sie .claude/settings.json mit einem PostToolUse:Bash-Hook, um die Prüfung nach Bash-Befehlen zu aktivieren. Er führt drei unabhängige Scans gegen das cwd des Befehls aus, die jeweils eine Lücke schließen, die die anderen Hooks nicht abdecken können:

• Scan A — Lockdateien. Nach einem erfolgreichen Installationsbefehl (npm install, bundle install, poetry install, uv sync, go mod tidy, usw.) prüft er kürzlich geänderte Lockdateien (package-lock.json, Gemfile.lock, poetry.lock, uv.lock, go.sum, yarn.lock, pnpm-lock.yaml, Pipfile.lock). Dies schließt die Lücke bei transitiven CVEs, die Pre-Install nicht sehen kann: Der Benutzer hat pkg@version eingegeben, aber der Resolver könnte Dutzende von transitiven Abhängigkeiten hinzugezogen haben, die niemand benannt hat.

So läuft ein Scan ab:

1. Claude führt einen Bash-Tool-Aufruf aus
2. Der PostToolUse-Hook feuert nach Abschluss des Befehls und ruft safer-dependencies-posttooluse-bash.sh auf
3. Ein reiner Bash-Frühfilter schließt Befehle, die kein Scan-Gate erfüllen, in ~115 ms kurz (dieselbe Fast-Path-Konvention wie bei Pre-Install), sodass ls / git / cat nur vernachlässigbare Kosten verursachen
4. Jeder Scan durchläuft cwd mit find -maxdepth 5 (deckt Monorepo-Layouts ab; schließt node_modules, .git, .venv, venv aus) und sucht nach Dateien, die innerhalb der letzten 60 s geändert wurden — überschreibbar über SAFE_DEP_POSTINSTALL_MTIME_WINDOW
5. Für jede kürzlich geänderte Datei (Scan A/B) erzeugt der Hook eine synthetische -Payload und leitet sie an den vorhandenen Shim weiter — die Lockdatei- und Manifest-Prüfer des Shims laufen unverändert, ohne duplizierte Logik

Was es erkennt, aber Pre-Install nicht: transitive Schwachstellen. Ein harmlos aussehendes bundle install kann [email protected] (CVE-2025-27610) als transitive Abhängigkeit von sinatra nachziehen — der Benutzer hat rack nie eingegeben, sodass Pre-Install es nicht sehen kann, aber Post-Install liest das aufgelöste Gemfile.lock und meldet die CVE.

Umfang: Scan A schreibt aufgelöste Versionen nicht neu — die Auto-Correct-Regel gilt nur für Manifeste, die Claude direkt geschrieben hat. Bei transitiven CVEs besteht die Lösung typischerweise darin, „die direkte Abhängigkeit zu aktualisieren, von der die transitive stammt“, was menschliches Urteilsvermögen erfordert. Scan B wendet dagegen Auto-Correct an, weil er Manifeste über denselben Shim-Pfad prüft wie der Intercept-Modus. Scan A wird übersprungen, wenn die Prüfstufe transitive auf off gesetzt ist (config set checks.transitive off).

Fehlermodus: Fail-open, wie bei den anderen Hooks. Jeder Fehler (fehlender Shim, fehlerhafte Payload, Python nicht verfügbar) endet still mit Exit-Code 0.

Beispiel-WARNUNG:``` WARNING: [email protected] in lock file has GHSA-29mw-wpgm-hmr9, GHSA-35jh-r3h4-6jhm

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

Die vier oben genannten Modi greifen nur bei **Root-Session**-Toolaufrufen. Wenn die Root-Session einen Subagenten entsendet (ü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 jedem Agent-Dispatch ausgeführt und erstellt eine Sentinel-Datei unter `/tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel` (fällt auf einen reinen PPID-Namen zurück, wenn keine Session-ID verfügbar ist)
2. Der Subagent wird ausgeführt und kann Manifests oder Lock-Dateien schreiben
3. Ein `PostToolUse:Agent`-Hook (`safer-dependencies-posttooluse-agent.sh`) wird ausgeführt, nachdem der Agent-Aufruf zurückkehrt, durchsucht per `find` jedes Manifest und jede Lock-Datei, die neuer als die Sentinel-Datei ist, und prüft jede über denselben Shim-Pfad
4. Ergebnisse werden als `additionalContext` an den nächsten Turn der Root-Session übergeben; die Sentinel-Datei wird entfernt

Verschachtelte Subagenten sind automatisch abgedeckt — der `PostToolUse:Agent` der Root-Session feuert erst, nachdem die gesamte Arbeit des äußeren Agents (einschließlich allem, was *er* entsendet hat) auf der Platte liegt. Die eine Lücke ist eine globale Installation, die kein Manifest oder keine Lock-Datei schreibt (`npm install -g …`): Es gibt nichts zu scannen. Wie die anderen Hooks ist er fail-open — jeder Fehler (fehlende Sentinel-Datei, fehlender Shim, unlesbare Nutzdaten) endet still mit Exit 0. Die vollständige Design-Begründung befindet sich in `skills/safer-dependencies.md`.

## Was es auslöst

Der Skill wird automatisch ausgelöst, wenn Claude:

**Manifest-/Installationsvorgänge**
- Fügt ein Paket in `package.json`, `requirements.txt`, `Gemfile`, `pom.xml`, `build.gradle`, `Cargo.toml`, `go.mod` oder einem anderen unterstützten Manifest hinzu oder aktualisiert es
- Schreibt ein `import`, `require` oder `use` für ein Paket, das noch nicht im Manifest deklariert ist
- Erzeugt oder aktualisiert eine Lock-Datei (prüft nur neue/geänderte Einträge)
- Führt eine Paketmanager-Installation über Bash aus (`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
- Schreibt ein `Dockerfile` oder einen CI-Workflow (`.github/workflows/*.yml`, usw.), der festgelegte Paketmanager-Installationsschritte einbettet

**Auswahl- und 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?"

**Nutzungsabsichten (vor dem Hinzufügen)**
- „Ich möchte FastAPI dafür verwenden", „Ich überlege, Celery hinzuzufügen", „Wir schauen uns Prisma als ORM an", „Lass uns Tailwind verwenden"

**Fragen zu Paketgesundheit und Vertrauen**
- „Wird moment.js noch gewartet?", „Ist dieses Gem noch aktiv?", „Ist X verlassen?", „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-Requests, die eine neue Abhängigkeit implizieren)**
- „Füge Redis-Caching zur App hinzu", „Verbinde mit Postgres", „Füge JWT-Auth hinzu", „Schreibe Code zum Senden von E-Mails" — wird ausgelöst, wenn noch kein Paket für diese Fähigkeit 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

Er wird **nicht** ausgelöst für:

- Importe aus der Standardbibliothek (`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 jedoch weiterhin aus
- Installation von Betriebssystem-Apps, Laufzeiten oder IDE-Erweiterungen (Python selbst, Docker, Homebrew, VS-Code-Erweiterungen)

## Was in diesem Repo enthalten ist

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

| Datei | Rolle |
|---|---|
| `skills/safer-dependencies.md` | Der **Skill** (`SKILL.md` nach der Installation). Beschreibt Prüfverfahren und enthält einen Verwaltungsmodus für Installation/Statistiken. |
| `skills/safer-dependencies-shim.sh` | `PostToolUse:Write`/`Edit`-Hook — prüft Manifest- und Lockfile-Schreibvorgänge und korrigiert verwundbare Versionen direkt an Ort und Stelle (Intercept-Modus). |
| `skills/safer-dependencies-pretooluse-bash.sh` | `PreToolUse:Bash`-Hook — Pre-Flight-OSV-Prüfung von Paketmanager-Installationsbefehlen; verweigert verwundbare konkrete Pins, bevor die Installation ausgeführt wird (Pre-Install-Modus). |
| `skills/safer-dependencies-posttooluse-bash.sh` | `PostToolUse:Bash`-Hook — Post-Flight-Prüfung nach Bash-Befehlen; erkennt transitive CVEs in frisch geschriebenen Lockfiles, in per `sed`/`jq`/Skripten bearbeiteten Manifesten und in der aufgelösten Umgebung von einfachem `pip install` (Post-Install-Modus). |
| `skills/safer-dependencies-pretooluse-agent.sh` + `skills/safer-dependencies-posttooluse-agent.sh` | `PreToolUse:Agent` + `PostToolUse:Agent`-Hook-Paar — schließt die Subagent-Abdeckungslücke. Die Modi 2–4 greifen nur bei Root-Session-Tool-Aufrufen, sodass jedes Manifest, das ein Subagent schreibt, sie umgeht. Post-Agent prüft alles, was der Subagent geschrieben hat, nachdem jeder Agent-Tool-Aufruf zurückkehrt (Post-Agent-Modus). |
| `skills/scripts/` | Gemeinsame Python-Bibliothek (`safedep/`) und eigenständige Resolver-Skripte, die von allen Hooks verwendet werden. |
| `skills/scripts/safer_dependencies_manager.py` | Verwaltungsmodul für interaktive Installation, Nutzungsstatistiken und Setup-Validierung. |

Die Skill-Datei allein reicht nicht — ohne Hooks hängt die automatische Auslösung davon ab, dass Claude sich entscheidet, den Skill zu verwenden. Installiere alle fünf Teile für eine vollständige Abdeckung; viele Skills und Slash-Befehle entsenden intern Subagenten, daher ist das Post-Agent-Paar wichtig, selbst wenn du nie explizit einen erzeugst. (Siehe [FAQ.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md#why-a-skill-alone-is-not-sufficient) für den Grund, warum ein Skill allein keine Abdeckung garantieren kann.)

## Unterstützte Ökosysteme

| Ökosystem | Manifest | Lock-Datei |
|-----------|----------|-----------|
| npm | `package.json` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
| PyPI | `requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py`, `setup.cfg` | `Pipfile.lock`, `poetry.lock`, `uv.lock` |
| RubyGems | `Gemfile`, `*.gemspec` | `Gemfile.lock` |
| Maven | `pom.xml`, `build.gradle`, `libs.versions.toml` | -- |
| Go | `go.mod` | `go.sum` |
| Rust | `Cargo.toml` | `Cargo.lock` |
| PHP (Composer) | `composer.json` | `composer.lock` |

## Installation

Neu im Projekt? Beginne mit **[GETTING-STARTED.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/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

Der Installer fragt nach dem Geltungsbereich (global vs. Projekt) und danach, welche Hooks aktiviert werden sollen, und schreibt dann settings.json für Sie — sowohl die Hook-Einträge als auch die Berechtigungs-Allowlist, die es den Prüfbefehlen des Skills ermöglicht, bei jeder Prüfung ohne Genehmigungsdialog ausgeführt zu werden.

Alles Weitere zur Installation findet sich in INSTALLATION.md, der einzigen Referenz für die Installationsmechanik: manuelle Installationen Datei für Datei (global und auf Projektebene), Windows-Besonderheiten, Post-Agent-Hooks, die Berechtigungs-Allowlist, Verifizieren der Einrichtung, Aktualisieren, Festpinnen an ein Release-Tag und Deinstallieren.

Nach der Installation erfolgt die tägliche Verwaltung über natürliche Sprache an Claude — install safer-dependencies (erneut ausführen / Hooks ändern), show safer-dependencies stats, check safer-dependencies setup — oder über das /safer-dependencies-Menü. Aktualisieren ist ebenfalls in der Sitzung möglich: /safer-dependencies update wendet das neueste Release an (update --check für einen Probelauf, update --rollback zum Rückgängigmachen); siehe INSTALLATION.md für das Vertrauensmodell.

Plattform-Hinweis: macOS, Linux und Windows werden unterstützt. Windows benötigt Git für Windows (liefert bash) und Python 3 im PATH — kein WSL erforderlich. Die praktischen Tests konzentrierten sich bisher auf macOS und Windows; die Linux-Unterstützung wird durch die automatisierte CI-Matrix abgedeckt.

Konfiguration

Zwei Dinge sind nach der Installation konfigurierbar:

• Berechtigungs-Allowlist — genehmigt die schreibgeschützten Prüfbefehle des Skills vorab (die exakten npm audit- / bundle audit-Regeln und die eigenen Resolver-Skripte des Skills), sodass Prüfungen jedes Mal ohne Genehmigungsdialog ablaufen; curl wird niemals vorab genehmigt, und npm view / pip-audit sind per Opt-in über das Convenience-Profil verfügbar. Der interaktive Installer schreibt die Kerneinträge für Sie; bei manuellen Installationen wird der vollständige Block von Hand hinzugefügt. Vollständiger Block und Begründung: INSTALLATION.md → Berechtigungs-Allowlist.
• Sicherheitsrichtlinie — das Cooldown-Fenster/der Cooldown-Modus für das Release-Alter und eine off/warn/block-Stufe pro Prüfung für jeden Prüftyp, bearbeitet mit /safer-dependencies config und gespeichert in ~/.config/safer-dependencies/config.toml. Schema und Stufensemantik: .

Warnstufen

Audit-Protokoll

Jede Prüfung wird als einzelne JSON-Zeile in ~/.claude/safer-dependencies-audit-YYYY-MM.log protokolliert (eine Datei pro Kalendermonat, wobei YYYY-MM der UTC-Jahresmonat ist). Der vollständige Pfad kann mit der Umgebungsvariable SAFE_DEP_AUDIT_LOG überschrieben werden (wenn gesetzt, wird das Datumssuffix nicht angehängt). Dateien werden außerdem nach Größe 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 jedem Eintrag unter source.model 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 Sitzung aktive Claude-Code-Modell auf (z. B. "claude-sonnet-4-6"). In Schema 2.1+ vorhanden; Einträge von älteren Installationen lassen das Feld weg. Der Stats-Befehl fällt bei fehlendem Feld elegant auf "unknown" zurück.

Filtern Sie mit jq nach source.component:```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

Für eine einfachere Analyse frage Claude nach Nutzungsstatistiken, anstatt Logs manuell zu parsen:```
"Show safer-dependencies stats for the last month"

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

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

Audit-Einträge: Im Intercept-Modus wird die vollständige Pipeline ausgeführt (Provenienz, Versionsalter, OSV, verwaist/veraltet, Typosquat, Signaturen), sodass alle Arrays befüllt werden können. Der Pre-Install-Modus führt derzeit nur OSV aus, daher sind abandoned / stale / typosquat / signatures immer leer. Der Post-Install-Dispatch (Lockfile-Audit) schreibt unter shim.posttooluse, wobei findings mit WARNING:-Zeichenfolgen aus den Lockfile-Auditoren befüllt wird. Das notes-Array enthält informative NOTE:-Signale (z. B. manifest-skipped-because-unpinned).

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) und einen policy-Block, der die geltende transitive-Stufe aufzeichnet. Der Versionssprung 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]"] }

Pre-Install-Modus-Beispiel (Bash-Hook, verwundbarer Pin verweigert):```json
{
  "ts": "2026-04-23T06:56:21Z",
  "schema": "2.2",
  "source": {
    "component": "bash.pretooluse",
    "script": "pretooluse-bash.sh",
    "hook": "PreToolUse:Bash",
    "tool": "Bash",
    "mode": "intercept",
    "model": "claude-sonnet-4-6"
  },
  "file": "bash:npm install [email protected] [email protected]",
  "ecosystem": "npm",
  "checked": ["[email protected]", "[email protected]"],
  "findings": [
    "BLOCKED: [email protected] GHSA-35jh-r3h4-6jhm (CVSS:3.1/...): Command Injection in lodash"
  ],
  "abandoned": [],
  "stale": [],
  "typosquat": [],
  "unknown": [],
  "signatures": [],
  "notes": [],
  "clean": ["[email protected]"]
}

Beispiel für den Fail-open-Modus (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" } }

Ein Fail-Open-Eintrag besagt: „Dieser Hook wurde ausgelöst, ist aber ohne Auditierung vorzeitig beendet worden, weil eine erforderliche Voraussetzung fehlte." Verwenden Sie den jq-Filter oben (`select(.source.mode == "fail_open")`), um jedes Ereignis eines stillen Schutzverlusts in Ihrem Log sichtbar zu machen.

Wenn der Shim im Dry-Run-Modus läuft (`SAFE_DEP_DRY_RUN=1`), enthalten die Einträge außerdem `"mode": "dry_run"`, sodass die Analyse im Nachhinein reine Audit-Aufrufe herausfiltern kann.

## Anforderungen

- Python 3.9+ (die Hooks prüfen dies und fallen bei älteren Interpretern auf Fail-Open zurück)
- `curl` (für Registry-API-Aufrufe und OSV-Schwachstellenprüfungen)
- Ökosystem-Tools (optional, der Skill greift bei fehlenden Tools auf die OSV-API zurück):
  - `npm` für npm-Pakete
  - `pip-audit` für Python-Pakete
  - `bundle` für Ruby-Pakete
  - `dependency-check` für Java-Pakete

## FAQ

Die Begründung der Designentscheidungen (warum `PostToolUse` statt `PreToolUse`, warum Signaturen nicht verifiziert werden, warum Skripte und Shim dupliziert werden, Stolperfallen beim Skill-Laden usw.) ist in [`FAQ.md`](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md) dokumentiert.