clidey/deptrustCLI- und MCP-Server, der Paketversionen in 14+ Ökosystemen auf bekannte Schwachstellen prüft, darunter npm, PyPI, crates.io, Go-Module und GitHub Actions. Integriert sich über Hooks und Skills in KI-Agenten.
# deptrust
```text
__ __ __
___/ /___ ___ / /________ _______/ /_
/ _ / __ \/ _ \/ __/ ___/ / / / ___/ __/
/ __/ /_/ / __/ /_/ / / /_/ (__ ) /_
\__,_/\____/ .___/\__/_/ \__,_/____/\__/
/_/
```
deptrust ist ein CLI, das Paketversionen auf bekannte Schwachstellen in npm, PyPI, crates.io, Go-Modulen, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage, GitHub Actions und mehr prüft.
Es läuft lokal als CLI und als MCP-Server. Es ruft öffentliche Paketregistrierungs- und OSV-APIs direkt auf; es gibt keinen gehosteten deptrust-Dienst, dem man vertrauen oder den man konfigurieren müsste.
Dieses Tool entstand aus der Frustration darüber, dass KI-Agenten ständig alte Versionen verwenden.
## Inhalt
- [Umfang](#umfang)
- [CLI-Nutzung](#cli-nutzung)
- [Installation](#installation)
- [Agent-Setup](#agent-setup)
- [Manuelles MCP-Setup](#manuelles-mcp-setup)
- [MCP-Werkzeuge](#mcp-werkzeuge)
- [Nur-Skill-Nutzung](#nur-skill-nutzung)
- [Fehlerbehebung](#fehlerbehebung)
## Umfang
Unterstützte Ökosysteme:
- npm, einschließlich Scoped-Paketen wie `@clidey/ux`
- PyPI
- Cargo / crates.io
- Go-Module
- RubyGems
- NuGet
- Maven, mit Paketnamen im Format `groupId:artifactId`
- Packagist / Composer, mit Paketnamen im Format `vendor/package`
- pub.dev
- CocoaPods
- Hex.pm
- Hackage
- GitHub Actions, mit Paketnamen im Format `owner/repo` sowie Tags, Branch-Refs oder Commit-SHAs als Versionen
deptrust meldet derzeit bekannte Schwachstellen und gibt eine einfache Empfehlung:
| Höchste bekannte Schwere | Empfehlung |
| --- | --- |
| critical | block |
| high | block |
| medium / unknown | review |
| low | allow |
| none found | allow |
`allow` bedeutet, dass in den öffentlichen Datenquellen keine blockierende bekannte Schwachstelle gefunden wurde. Es beweist nicht, dass ein Paket sicher ist.
deptrust gibt außerdem Risikosignale aus, die keine CVEs sind. Beispielsweise wird eine in den letzten 72 Stunden veröffentlichte Version zur Prüfung markiert, damit ein Agent keine brandneue Veröffentlichung blind installiert.
Advisory-Anbieter werden parallel abgefragt:
- OSV
- GitHub Advisory Database, einschließlich geprüfter Advisories und Malware-Advisories
Die Abdeckung der Anbieter variiert je nach Ökosystem. Wenn deptrust die Registry-Metadaten auflösen kann, aber kein konfigurierter Schwachstellen-Anbieter dieses Ökosystem unterstützt, gibt es `unknown` zurück, anstatt das Paket als sicher zu behandeln.
Abdeckung der Anbieter:
| Ökosystem | Registry-Metadaten | OSV | GitHub Advisory DB |
| --- | --- | --- | --- |
| npm | yes | yes | yes |
| PyPI | yes | yes | yes |
| Cargo / crates.io | yes | yes | yes |
| Go-Module | yes | yes | yes |
| RubyGems | yes | yes | yes |
| NuGet | yes | yes | yes |
| Maven | yes | yes | yes |
| Packagist / Composer | yes | yes | yes |
| pub.dev | yes | yes | yes |
| CocoaPods | yes | no | yes |
| Hex.pm | yes | yes | yes |
| Hackage | yes | yes | no |
| GitHub Actions | yes | yes | yes |
Die JSON-Ausgabe enthält Felder zur Advisory-Abdeckung:
- `checked_providers`: Schwachstellen-Anbieter, die deptrust tatsächlich abgefragt hat
- `skipped_providers`: konfigurierte Anbieter, die übersprungen wurden, weil das Ökosystem nicht unterstützt wird
- `advisory_coverage`: `full`, `partial`, `none` oder `error`
- `advisory_coverage_reason`: kurze Erklärung für den Abdeckungswert
- `registry_verification`: `verified`, wenn die Registry-Metadaten die Version bestätigt haben, oder `unverified`, wenn eine Prüfung einer exakten Version nach einem vorübergehenden Registry-Fehler fortgesetzt wurde
- `registry_verification_reason`: der Registry-Fehler, wenn die Verifizierung nicht verfügbar war
Eine Prüfung einer exakten Version fragt Advisory-Anbieter weiterhin ab, wenn die Registry-Verifizierung vorübergehend nicht verfügbar ist. Dieses Ergebnis ist immer nicht installierbar und erhält niemals eine `allow`-Empfehlung. Prüfungen auf `latest`, unbekannte Pakete und definitiv nicht existierende Versionen erfordern weiterhin eine erfolgreiche Registry-Auflösung.
HTTP-Anfragen wiederholen `429`-, `502`-, `503`- und `504`-Antworten bis zu insgesamt drei Versuche. Wiederholungen verwenden kurze exponentielle Verzögerungen und beachten `Retry-After`-Werte von bis zu zwei Sekunden; längere vom Server angeforderte Wartezeiten schlagen schnell fehl, damit das CLI nicht hängen bleibt. Erschöpfte Advisory-Wiederholungen machen das Ergebnis unvollständig und verhindern eine `allow`-Empfehlung.
### GitHub-API-Authentifizierung
GitHub-Advisory-Database- und GitHub-Actions-API-Anfragen können ein kurzlebiges GitHub-App-Token mit minimalen Rechten verwenden. In CI übergibst du es über `DEPTRUST_GITHUB_TOKEN`:
```bash
DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20
```
Die Reihenfolge der Anmeldedaten ist `DEPTRUST_GITHUB_TOKEN`, `GITHUB_TOKEN`, dann `GH_TOKEN`. Für die lokale Nutzung wird der optionale GitHub-CLI-Fallback explizit mit `DEPTRUST_GITHUB_AUTH=gh deptrust check ...` aktiviert; er führt `gh auth token` ohne Rückfragen aus. Wenn keine Anmeldedaten verfügbar sind, arbeitet DepTrust ohne Authentifizierung weiter. Ein GitHub-API-Rate-Limit oder ein Berechtigungsfehler erzeugt `unknown` mit Diagnoseinformationen und wird niemals als reiner OSV-Erfolg behandelt.
DepTrust speichert, bündelt, cached, protokolliert, telemetriert oder gibt GitHub-Tokens niemals weiter. Authentifizierungs-Header werden nur an `https://api.github.com` gesendet.
## CLI-Nutzung
Eine exakte Version prüfen:
```bash
deptrust check npm lodash 4.17.20
```
Beispiel für eine normale Antwort:
```text
npm [email protected]: 2 known vulnerabilities found
recommendation: block
risk_score: 80
```
Die neueste Version prüfen:
```bash
deptrust check pypi requests latest
```
JSON zurückgeben:
```bash
deptrust check --json cargo serde latest
```
Ein Go-Modul prüfen:
```bash
deptrust check go golang.org/x/crypto latest
```
RubyGems, NuGet oder Maven prüfen:
```bash
deptrust check rubygems rails latest
deptrust check nuget Newtonsoft.Json latest
deptrust check maven org.apache.logging.log4j:log4j-core latest
```
Packagist, pub.dev, CocoaPods, Hex.pm, Hackage oder GitHub Actions prüfen:
```bash
deptrust check packagist monolog/monolog latest
deptrust check pub http latest
deptrust check cocoapods AFNetworking latest
deptrust check hex plug latest
deptrust check hackage aeson latest
deptrust check github-actions actions/checkout v7.0.0
deptrust check github-actions actions/checkout main
```
Bei GitHub Actions werden vollständige Commit-SHAs als gepinnt behandelt. Vollständige Semver-Tags wie `v4.2.2` werden ohne zusätzliches Pinning-Signal akzeptiert. Nur-Major-Tags wie `v4` und Branch-Refs wie `main` sind gültige Refs, aber deptrust fügt ein Review-Signal hinzu, weil sie sich verschieben können.
Beispiel für eine JSON-Antwort:
```json
{
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20",
"latest_version": "4.17.21",
"known_vulnerabilities_found": true,
"safe_to_use": false,
"should_install": false,
"risk_score": 80,
"recommendation": "block",
"classification": "vulnerable",
"reason": "Found 2 known vulnerability records.",
"next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
"summary": "lodash 4.17.20 has 2 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
"signals": [],
"checked_providers": [
"OSV",
"GitHub Advisory DB"
],
"skipped_providers": [],
"advisory_coverage": "full",
"advisory_coverage_reason": "all configured vulnerability providers were checked",
"registry_verification": "verified",
"vulnerabilities": [
{
"id": "GHSA-35jh-r3h4-6jhm",
"aliases": [
"CVE-2021-23337"
],
"cve_ids": [
"CVE-2021-23337"
],
"ghsa_ids": [
"GHSA-35jh-r3h4-6jhm"
],
"summary": "Command Injection in lodash",
"severity": "high",
"source": "OSV",
"advisory_url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm",
"affected_ranges": [
"SEMVER: introduced 0, fixed 4.17.21"
],
"fixed_versions": [
"4.17.21"
],
"references": [
{
"type": "ADVISORY",
"url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm"
}
]
}
],
"provider_errors": []
}
```
Die neueste Version nur vorschlagen, wenn keine bekannten Schwachstellen gefunden werden:
```bash
deptrust suggest npm lodash
```
Wenn die neueste Version nicht erlaubt ist, prüft `suggest` ältere bekannte Versionen und gibt die neueste Version mit einer `allow`-Empfehlung zurück.
Wenn Advisories behobene Versionen enthalten, prüft `suggest` zuerst diese vom Anbieter gemeldeten behobenen Versionen, bevor es die Versionsliste der Registry rückwärts durchläuft.
Zwei Versionen vergleichen:
```bash
deptrust compare npm lodash 4.17.20 4.17.21
```
Beispiel für eine Vergleichsantwort:
```text
lodash 4.17.20 -> 4.17.21 improves risk: score 80 to 0.
recommendation: allow
next_action: upgrade_to_target
```
Die installierte Version anzeigen:
```bash
deptrust version
```
## Installation
Der einfachste Installationsweg ist `npx` oder `pnpx`:
```bash
npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install
```
Der Standard-Installer ist geführt. Er installiert die Binärdatei, fragt, welche Agent-Integrationen konfiguriert werden sollen, zeigt die Ziele auf Benutzerebene an, bevor er etwas ändert, und fragt nach Bestätigung. Der geführte Installer aktiviert standardmäßig MCP, den Skill-Fallback und die Dependency-Sicherheits-Hooks für Codex und Claude Code. Füge für nicht-interaktive Nur-Binärdatei-Installationen `--yes` hinzu oder übergib explizite Integrationsflags.
Das erneute Ausführen des Installers ist sicher. Er lässt unveränderte MCP-, Skill- und Hook-Konfigurationen stillschweigend unangetastet. Wenn eine Integration auf eine alte deptrust-Binärdatei verweist oder sich deren verwaltete Konfiguration geändert hat, aktualisiert der Installer sie automatisch; Benutzer müssen MCP-Server nicht manuell entfernen und wieder hinzufügen. Angepasste Skills werden vor dem Ersetzen gesichert.
Um die Binärdatei, den Skill und die MCP-Einträge auf Benutzerebene zu entfernen:
```bash
npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall
```
Homebrew-Benutzer können aus dem Clidey-Tap installieren:
```bash
brew install clidey/tap/deptrust
```
Oder zuerst tappen und dann wie gewohnt installieren und aktualisieren:
```bash
brew tap clidey/tap
brew install deptrust
brew upgrade deptrust
```
Homebrew gibt nach der Installation einen Hinweis aus. Um das geführte Codex- und Claude-Code-Setup mit der Homebrew-Binärdatei selbst auszuführen (MCP-Registrierungen und Dependency-Sicherheits-Hooks):
```bash
deptrust setup
```
Das geführte Setup fragt, bevor es MCP- und Dependency-Sicherheits-Hooks aktiviert. Es lässt Registrierungen, die bereits die aktuelle Binärdatei verwenden, unverändert und gleicht bestehende DepTrust-Registrierungen ab, die auf einen älteren npm-, Homebrew- oder Quellinstallationspfad verweisen.
Go-Benutzer können direkt installieren:
```bash
go install github.com/clidey/deptrust/cmd/deptrust@latest
```
### Nix
Das Projekt bietet optionale Nix-Flake-Ausgaben für Benutzer, die bereits Nix verwenden. Das Flake kapselt die vorgefertigte Release-Binärdatei.
```bash
# Run without installing
nix run github:clidey/deptrust
# Install into your profile
nix profile install github:clidey/deptrust
```
Der normale [Release-Workflow](https://github.com/clidey/deptrust/blob/main/.github/workflows/release.yml) erzeugt die Nix-Hashes aus denselben Archiven, die er veröffentlicht, evaluiert das Flake vor der Veröffentlichung, baut und testet es dann gegen die veröffentlichten Assets, bevor er den Standard-Branch aktualisiert. `github:clidey/deptrust` kann kurzzeitig zurückliegen, während dieser Workflow läuft. Release-Tags zeigen auf den Quell-Commit von vor dem generierten Flake-Update und können weiterhin auf die vorherige Binärdatei verweisen; pinne einen Commit, dessen `flake.nix` die benötigte Version enthält, wenn Reproduzierbarkeit wichtig ist.
### Devbox
Für reproduzierbare Entwicklungsumgebungen verwende Devbox:
```bash
# Install Devbox first (if not already installed)
curl -fsSL https://get.jetify.dev/devbox | bash
# Initialize the environment
devbox shell
# Build the project
devbox run build
```
`devbox.json` begrenzt die Toolchain-Version und die eingecheckte `devbox.lock` pinnt die genauen Paketversionen und nixpkgs-Revisionen. Führe `devbox update` aus, wenn du diese Pins absichtlich aktualisieren möchtest.
Oder installiere Devbox über Homebrew:
```bash
brew install jetify-com/devbox/devbox
```
## Agent-Setup
Um deptrust zu installieren und alles zu registrieren, was der Installer ohne die geführten Eingabeaufforderungen konfigurieren kann:
```bash
npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all
```
`--all` installiert die Binärdatei, registriert Codex-MCP, wenn das `codex`-CLI verfügbar ist, installiert den Codex-Skill-Fallback, registriert Claude-Code-MCP, wenn das `claude`-CLI verfügbar ist, und installiert die Dependency-Sicherheits-Hooks für Codex und Claude Code.
Die Hooks sind `PreToolUse`-Hooks. Sie prüfen Paketinstallationsbefehle, bevor sie ausgeführt werden, und prüfen auch GitHub Actions, die über die Dateibearbeitungswerkzeuge des Agenten zu Workflow-Dateien hinzugefügt wurden. Ein Hook blockiert den Tool-Aufruf, wenn deptrust `review`, `block` oder `unknown` zurückgibt. Der Installer schreibt nur Hook-Konfiguration auf Benutzerebene: `~/.codex/hooks.json` für Codex und `~/.claude/settings.json` für Claude Code.
Wenn das `gh`-CLI verfügbar ist, bietet das geführte Setup außerdem an, dessen bestehenden lokalen Login für Hook-Prüfungen zu verwenden. Dies schreibt nur `DEPTRUST_GITHUB_AUTH=gh`, niemals ein GitHub-Token, sodass Hook-Subprozesse unauthentifizierte GitHub-API-Rate-Limits vermeiden können.
Verwende bei Bedarf schmalere Installationen:
```bash
npx @clidey/deptrust install --codex-mcp
npx @clidey/deptrust install --claude-code-mcp
npx @clidey/deptrust skills install
pnpx @clidey/deptrust@latest install --codex-mcp
pnpx @clidey/deptrust@latest install --claude-code-mcp
pnpx @clidey/deptrust@latest skills install
```
Nach dem MCP-Setup prüfen Agenten Pakete automatisch, bevor sie Updates oder Änderungen empfehlen. Der MCP-Server sendet Anweisungen, alle Abhängigkeitsversionen zu prüfen — einschließlich der Beantwortung von Fragen wie „Was kann ich aktualisieren?" oder „Welche Abhängigkeiten können sicher aktualisiert werden?" — bevor Empfehlungen gegeben werden.
Wenn du deptrust in einem Nicht-MCP-Kontext verwendest, erinnere deinen Agenten:
```text
Before listing, comparing, or recommending specific package versions, check them with deptrust. This includes answering "what can I update" — do not provide version recommendations until after checking for known vulnerabilities.
```
Konfiguriere für CI ein kurzlebiges GitHub-App-Token mit minimalen Rechten als `DEPTRUST_GITHUB_TOKEN` für den Prozess, der DepTrust ausführt. Für die lokale GitHub-CLI-Authentifizierung verwende `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`. DepTrust speichert niemals Tokens.
## Manuelles MCP-Setup
Wenn dein Client stdio-MCP-Server unterstützt, konfiguriere ihn so, dass er Folgendes ausführt:
```bash
/absolute/path/to/deptrust mcp
```
Viele Clients verwenden diese JSON-Struktur:
```json
{
"mcpServers": {
"deptrust": {
"command": "/absolute/path/to/deptrust",
"args": ["mcp"]
}
}
}
```
Für Codex kannst du es auch so hinzufügen:
```bash
codex mcp add deptrust -- /absolute/path/to/deptrust mcp
```
Für Claude Code:
```bash
claude mcp add --transport stdio deptrust -- /absolute/path/to/deptrust mcp
```
Bei `initialize` gibt der Server MCP-`instructions` zurück, die dem Agenten mitteilen, wann er diese Werkzeuge verwenden soll (bevor er eine Abhängigkeit hinzufügt, anhebt oder empfiehlt, oder wenn gefragt wird, ob eine Version sicher aktualisiert werden kann). Clients, die Serveranweisungen anzeigen, wenden dies automatisch an, sodass die manuelle Erinnerung oben optional und nicht erforderlich ist.
## MCP-Werkzeuge
### `check_package`
Prüft eine Paketversion und gibt bekannte Schwachstellen plus eine Empfehlung zurück.
```json
{
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20"
}
```
`version` kann weggelassen oder auf `latest` gesetzt werden. Wenn eine exakte Version nicht existiert, gibt deptrust einen Fehler zurück und schlägt die neueste explizite Version vor.
Die MCP-Ausgabe ist bewusst kompakt, damit Agenten entscheiden können, ob sie eine Abhängigkeit installieren, ohne vollständige Advisory-Texte in den Kontext zu ziehen. Wenn der Benutzer vollständige Details sehen möchte, kann der Agent den `full_response_command` ausführen.
Beispiel für eine kompakte strukturierte MCP-Ausgabe:
```json
{
"ecosystem": "npm",
"package": "vite",
"version": "7.0.0",
"latest_version": "8.0.16",
"known_vulnerabilities_found": true,
"safe_to_use": false,
"should_install": false,
"risk_score": 80,
"classification": "vulnerable",
"recommendation": "block",
"reason": "Found 7 known vulnerability records.",
"next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
"summary": "vite 7.0.0 has 7 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
"vulnerability_count": 7,
"vulnerability_counts": {
"critical": 0,
"high": 2,
"medium": 3,
"low": 2,
"unknown": 0
},
"highest_severity": "high",
"checked_providers": [
"OSV",
"GitHub Advisory DB"
],
"skipped_providers": [],
"advisory_coverage": "full",
"advisory_coverage_reason": "all configured vulnerability providers were checked",
"registry_verification": "verified",
"full_response_command": "deptrust check --json npm vite 7.0.0"
}
```
Die kompakte MCP-Antwort lässt das Schwachstellen-Array, Advisory-`details` und wiederholte `references` weg. Agenten sollten standardmäßig die Anzahl, die höchste Schwere, die Anbieterabdeckung, die Empfehlung und die nächste Aktion verwenden. Wenn der Benutzer vollständige Advisory-Details anfordert, führe den `full_response_command` aus.
Wenn der GitHub-Advisory-Zugriff ratenlimitiert oder nicht verfügbar ist, gibt MCP `unknown` zurück. Der Agent sollte proaktiv anbieten, ein Token zu konfigurieren und es erneut zu versuchen, die Version zu überspringen oder aufzuschieben, oder erst fortfahren, nachdem der Benutzer das ungelöste GitHub-Coverage-Risiko für diese exakte Version ausdrücklich akzeptiert hat. Diese Ausnahme muss klar als vom Benutzer akzeptierte Unsicherheit gekennzeichnet bleiben; sie darf nicht als `allow` oder als Beweis dafür gemeldet werden, dass die Version sicher ist.
### `suggest_safe_version`
Prüft zuerst die neueste Version. Wenn die neueste Version nicht erlaubt ist, prüft es zuerst die vom Anbieter gemeldeten behobenen Versionen, dann ältere bekannte Versionen, und schlägt die neueste Version mit einer `allow`-Empfehlung vor.
```json
{
"ecosystem": "npm",
"package": "lodash"
}
```
### `compare_versions`
Vergleicht eine aktuelle Version und eine Zielversion, einschließlich behobener und hinzugefügter Schwachstellen.
```json
{
"ecosystem": "npm",
"package": "lodash",
"from_version": "4.17.20",
"to_version": "4.17.21"
}
```
## Nur-Skill-Nutzung
Wenn du kein MCP möchtest, installiere den gebündelten Codex-Skill:
```bash
npx @clidey/deptrust skills install
```
Der Skill weist Codex an, das `deptrust`-CLI aufzurufen, bevor es npm-, PyPI-, Cargo-, Go-Modul-, RubyGems-, NuGet-, Maven-, Packagist-, pub.dev-, CocoaPods-, Hex.pm-, Hackage- und GitHub-Actions-Pakete installiert, aktualisiert oder empfiehlt.
## Fehlerbehebung
Wenn `deptrust` nicht gefunden wird:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
Wenn ein MCP-Client den Server nicht starten kann, finde den vollständigen Pfad:
```bash
which deptrust
```
Setze dann diesen absoluten Pfad in die MCP-Konfiguration.
Wenn eine Paketprüfung `unknown` zurückgibt, behandle das Paket nicht als sicher. Es bedeutet, dass deptrust keine vollständige Antwort von einem Advisory-Anbieter erhalten konnte oder die exakte Version nicht mit seiner Registry verifizieren konnte.