allow means no blocking known vulnerability was found in the public data sources. It does not prove that a package is safe.

deptrust also emits risk signals that are not CVEs. For example, a version published in the last 72 hours is marked for review so an agent does not blindly install a brand-new release.

Advisory providers are queried in parallel:

• OSV
• GitHub Advisory Database, including reviewed advisories and malware advisories

Provider coverage varies by ecosystem. If deptrust can resolve registry metadata but no configured vulnerability provider supports that ecosystem, it returns unknown instead of treating the package as safe.

Provider coverage:

The JSON output includes advisory coverage fields:

• checked_providers: vulnerability providers deptrust actually queried
• skipped_providers: configured providers skipped because the ecosystem is unsupported
• advisory_coverage: full, partial, none, or error
• advisory_coverage_reason: short explanation for the coverage value
• registry_verification: verified when registry metadata confirmed the version, or unverified when an exact-version check continued after a transient registry failure
• registry_verification_reason: the registry error when verification was unavailable

An exact-version check still queries advisory providers when registry verification is temporarily unavailable. That result is always non-installable and never receives an allow recommendation. Checks for latest, unknown packages, and definitively nonexistent versions still require successful registry resolution.

HTTP requests retry 429, 502, 503, and 504 responses up to three total attempts. Retries use short exponential delays and honor Retry-After values up to two seconds; longer server-requested waits fail fast so the CLI does not hang. Exhausted advisory retries make the result incomplete and prevent an allow recommendation.

GitHub API authentication

GitHub Advisory Database and GitHub Actions API requests can use a short-lived, least-privilege GitHub App token. In CI, pass it through DEPTRUST_GITHUB_TOKEN:

DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20

The credential precedence is DEPTRUST_GITHUB_TOKEN, GITHUB_TOKEN, then GH_TOKEN. For local use, the optional GitHub CLI fallback is enabled explicitly with DEPTRUST_GITHUB_AUTH=gh deptrust check ...; it runs gh auth token without prompting. If no credential is available, DepTrust continues unauthenticated. A GitHub API rate-limit or permission failure produces unknown with diagnostics and is never treated as an OSV-only success.

DepTrust never stores, bundles, caches, logs, telemeters, or emits GitHub tokens. Authentication headers are sent only to https://api.github.com.

CLI Usage

Check an exact version:

deptrust check npm lodash 4.17.20

Example normal response:

npm lodash@4.17.20: 2 known vulnerabilities found
recommendation: block
risk_score: 80

Check the latest version:

deptrust check pypi requests latest

Return JSON:

deptrust check --json cargo serde latest

Check a Go module:

deptrust check go golang.org/x/crypto latest

Check RubyGems, NuGet, or Maven:

deptrust check rubygems rails latest
deptrust check nuget Newtonsoft.Json latest
deptrust check maven org.apache.logging.log4j:log4j-core latest

Check Packagist, pub.dev, CocoaPods, Hex.pm, Hackage, or GitHub Actions:

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

For GitHub Actions, full commit SHAs are treated as pinned. Full semver tags such as v4.2.2 are accepted without an extra pinning signal. Major-only tags such as v4 and branch refs such as main are valid refs, but deptrust adds a review signal because they can move.

Example JSON response:

{
  "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": []
}

Suggest the latest version only when no known vulnerabilities are found:

deptrust suggest npm lodash

If the latest version is not allowed, suggest checks older known versions and returns the newest version with an allow recommendation.

When advisories include fixed versions, suggest checks those provider-reported fixed versions first before walking back through the registry version list.

Compare two versions:

deptrust compare npm lodash 4.17.20 4.17.21

Example compare response:

lodash 4.17.20 -> 4.17.21 improves risk: score 80 to 0.
recommendation: allow
next_action: upgrade_to_target

Show the installed version:

deptrust version

Install

The easiest install path is npx or pnpx:

npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install

The default installer is guided. It installs the binary, asks which agent integrations to configure, prints the user-level destinations before changing anything, and asks for confirmation. The guided installer defaults to enabling MCP, the skill fallback, and dependency safety hooks for Codex and Claude Code. Add --yes for non-interactive binary-only installs, or pass explicit integration flags.

Rerunning the installer is safe. It silently leaves unchanged MCP, skill, and hook configuration alone. If an integration points at an old deptrust binary or its managed configuration has changed, the installer updates it automatically; users do not need to manually remove and re-add MCP servers. Customized skills are backed up before replacement.

To remove the user-level binary, skill, and MCP entries:

npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall

Homebrew users can install from the Clidey tap:

brew install clidey/tap/deptrust

Or tap first, then install and upgrade as usual:

brew tap clidey/tap
brew install deptrust
brew upgrade deptrust

Homebrew prints a reminder after installation. To run the guided Codex and Claude Code MCP setup using the Homebrew binary itself:

deptrust setup

Go users can install directly:

go install github.com/clidey/deptrust/cmd/deptrust@latest

Nix

The project provides optional Nix flake outputs for users who already use Nix. The flake wraps the prebuilt release binary.

# Run without installing
nix run github:clidey/deptrust

# Install into your profile
nix profile install github:clidey/deptrust

The normal release workflow generates the Nix hashes from the same archives it publishes, evaluates the flake before publishing, then builds and runs it against the published assets before updating the default branch. github:clidey/deptrust may briefly lag while that workflow is running. Release tags point to the source commit from before the generated flake update and may still reference the previous binary; pin a commit whose flake.nix contains the version you need when reproducibility matters.

Devbox

For reproducible development environments, use Devbox:

# 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 constrains the toolchain version and the committed devbox.lock pins the exact package versions and nixpkgs revisions. Run devbox update when you intentionally want to refresh those pins.

Or install Devbox via Homebrew:

brew install jetify-com/devbox/devbox

Agent Setup

To install deptrust and register everything the installer can configure without the guided prompts:

npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all

--all installs the binary, registers Codex MCP when the codex CLI is available, installs the Codex skill fallback, registers Claude Code MCP when the claude CLI is available, and installs the Codex and Claude Code dependency safety hooks.

The hooks are PreToolUse hooks. They check package install commands before they run, and they also check GitHub Actions added to workflow files through