Package Health Backup

DepVault Engine

DepVault is a blazing-fast, Universal Predictive Risk Engine for Agents and Humans.

> Looking for full usage docs? See the [DepVault User Guide](docs/USER_GUIDE.md) — covers LeakGuard secret detection, the License Policy Engine, depvault.json in full, the cloud dashboard, CI/CD, editor integration, and MCP, all in one place.

Why DepVault Outshines the Rest

Standard scanners like npm audit or Google OSV only look at binary states: Does a known CVE exist right now? Yes or No?

We outshine them because DepVault is a Predictive Risk Engine, not just a vulnerability scanner. We catch things before a CVE is even filed because we analyze:

• Structural Risk: Is a critical package (w >= 0.3) unmaintained?
• Freshness & Abandonware: Has the author ghosted the project for 3 years?
• Toxic Licenses: Did the maintainer switch to a restrictive GPL license?
• Pre-release Instability: Is someone trying to sneak a -beta tag into production?

Because we built our logic around a centralized abstract ecosystem provider, DepVault natively supports JavaScript (NPM), Python (PyPI), Rust (Cargo), and Go flawlessly with the exact same mathematical data pipeline!

AI-Ready (MCP Server)

DepVault ships a standalone Model Context Protocol (MCP) server — any MCP-compatible coding agent (Claude Code, Cursor, Windsurf, etc.) can call it directly, no local install or account required. This is the fastest way for an agent to check a dependency's Trust Score before adding it to a project, or audit everything already in one.

Add this to your agent's MCP config (.mcp.json for Claude Code, .cursor/mcp.json for Cursor, or your client's equivalent):

{
  "mcpServers": {
    "depvault": {
      "command": "npx",
      "args": ["-y", "@deepvaultscan/mcp-server"]
    }
  }
}

That's it — no build step, no API key. It exposes two tools:

• scan_package_health — Trust Score (0-100) for a single package (ecosystem, packageName, optional version). Use before adding a new dependency.
• scan_repository — Trust Score, a compact reason ("Highlights: secure, popular" / "Penalties: vulnerabilities, restrictive license"), and known vulnerabilities for every dependency in a project's manifest (package.json, requirements.txt, pyproject.toml, Pipfile, Cargo.toml, or go.mod). Use to audit an existing project.

If you already have the full CLI installed, depvault mcp starts the same kind of server directly from your local install instead. (SBOM generation is available via the depvault sbom CLI command, not yet exposed as an MCP tool.)

It also supports an opt-in auto-scan on install — either per-install via DEPVAULT_AUTO_SCAN=1, or persistently via a one-time npx @deepvaultscan/mcp-server --enable-auto-scan so you don't have to keep setting the env var. Off by default, and report-only unless you additionally opt into --block-on-critical (fails the install if a dependency has a known CRITICAL-severity vulnerability — read the caveat in its own README before relying on it: it only covers installs where this package's own postinstall fires, not a general install-time gate). See [apps/mcp-server/README.md](apps/mcp-server/README.md#optional-auto-scan-on-install) for exactly when it does and doesn't fire.

GitHub Action (CI/CD)

Add dependency Trust Score gating to any repo's CI — no DepVault account, no backend, no separate install step. It's not an npm/pip package you download; GitHub Actions fetches it directly from this repo by reference, the same way you'd add any other action from the Marketplace. Add this step to a workflow (typically .github/workflows/*.yml, on pull_request):

- uses: actions/checkout@v4
- uses: Seunfola/package-health-backup/apps/github-action@v1
  with:
    fail-below: '80'   # optional — omit to use depvault.json's threshold instead

Every run writes a job summary and a single, self-updating PR comment listing every scanned package with its score, known vulnerabilities, and the reason it scored that way — then fails the job if the average score is below your threshold. Full inputs/outputs, depvault.json integration, and the difference between this and the backend-dependent Gatekeeper policy engine are documented in [apps/github-action/README.md](apps/github-action/README.md).

> Pin @v1, not @main. Referencing a moving branch means a future change to this repo could silently alter what runs in your CI. Until the v1 tag exists, pin to a specific commit SHA instead of a branch name.

LeakGuard (Secret Detection)

DepVault also detects hardcoded secrets — API keys, tokens, private keys, database connection strings — committed to your repository, using the same embedded engine across the CLI, a pre-commit hook, CI, your editor, and the MCP server. No separate binary to install, no account required to use it locally.

depvault leakguard scan                 # scan the working tree
depvault leakguard scan --staged        # fast pass over what's about to be committed
depvault leakguard scan --fail-on high  # CI-style exit-code gate

The reference GitHub workflow in this repo (.github/workflows/depvault-gatekeeper.yml) runs this alongside the Trust Score scan and reports both under a single PR comment. See the [User Guide's LeakGuard section](docs/USER_GUIDE.md#3-leakguard--secret-detection--remediation) for the full command reference, severity/liveness model, depvault.json configuration, and incident-response workflow (--playbook, --interactive, rotation scripts).

Enterprise Features

• DepVault HealthScan: Our proprietary vulnerability scanner built over the OSV data graph.
• Universal Support: One mathematical risk engine supporting package.json, requirements.txt, pyproject.toml, Pipfile, Cargo.toml, and go.mod.
• DepVault Shield: A zero-trust pre-install gatekeeper. Run depvault shield add to block toxic or vulnerable packages before they touch your machine.
• Dynamic Risk Policies: Configure your project's risk tolerance (Low, Medium, High) in depvault.json.
• The "Time Machine": Tracks 30-day historical Trust Scores to visualize technical debt reduction.
• Legal Compliance Scanner: Automatically penalizes toxic copyleft licenses (e.g., GPL, AGPL) to prevent legal liability.

DepVault Shield

DepVault Shield acts like a security gate for installs: it evaluates a package before it is added to your machine, shows the package's trust score, explains why it is blocked, and stops the install if the package fails the policy check.

> The CLI is not yet published to the public npm registry. Until it is, depvault works built from this repo: pnpm install && pnpm --filter cli build, then run node apps/cli/dist/index.js (or pnpm --filter cli exec depvault). Everything below describes real, working commands — just not yet an npm install -g depvault away. The [GitHub Action](#github-action-cicd) runs this same CLI via npx, so it depends on the same publish.

1. Configure the shield

Create a depvault.json file in the project you want to protect:

{
  "riskLevel": "high"
}

Supported values for riskLevel are low, medium, and high. The shield uses this setting to decide how strict the gate should be.

You can also point the CLI at a different backend deployment:

export DEPVAULT_API_URL=https://your-deployment.example.com

2. Use the shield manually

Run the shield before you install a dependency:

# Pre-scan one package, then install it if it passes
depvault shield express@4.18.2

# Audit the dependencies already present in the current project
depvault shield audit

# View the current project's risk configuration
depvault shield status

If a package is blocked, the shield prints:

• the package's score,
• the reason it failed policy,
• and the fact that installation was prevented before the package manager ran.

3. Gate every install automatically

depvault shield only checks the one command you run. It does not automatically intercept a plain npm install/pip install/etc.

To protect every install in a shell, install the hooks:

# Prints ready-to-paste shell wrapper functions for npm, pnpm, yarn, pip, cargo, and go
depvault hooks install

# Also installs a git pre-commit hook that blocks commits below a health threshold
depvault hooks install --git

Paste the printed bash/zsh block into ~/.bashrc/~/.zshrc, or the PowerShell block into your $PROFILE, then reload your shell. From then on, plain npm install (or pnpm add/yarn add/pip install/cargo add/go get) is routed through depvault shield --check-only first.

4. Override the shield when you really need to

If you have a legitimate reason to install a package anyway, use the explicit override flag:

depvault shield express@4.18.2 --force

That bypasses the gate and proceeds with the install, but the output makes it clear that this was an intentional override and may be audited.

5. Offline/cache behavior

Scoring a package needs to reach the backend or the public registries/OSV directly. The one real offline capability is a pre-synced verdict cache:

# While online: download signed PASS/WARN/BLOCK verdicts for every dependency in the current project
depvault shield sync

If the backend becomes unreachable, depvault shield falls back to the local cache at ~/.depvault/verdicts.cache. Packages already in that cache still get a real verdict offline, but packages not in the cache are treated as fail-closed and blocked unless you override them with --force.

Re-run depvault shield sync periodically so the cache stays fresh.

The MCP server has no equivalent cache at all — every one of its tool calls is always live.

Quick Start (Docker)

# From the project root
docker-compose up --build

This boots:

• The NestJS Backend (Port 3000)
• The MongoDB Database (Port 27017)

The Angular frontend (../web) has its own Dockerfile but isn't wired into this compose file yet — its production build bakes in a fixed API URL at build time (environment.prod.ts), so serving it against this local backend needs its own build configuration first. Until then, run the frontend separately per web/README.md and point it at http://localhost:3000.

Local Setup

pnpm install

Running the API

# development
pnpm run start

# watch mode
pnpm run start:dev

# production mode
pnpm run start:prod

Testing

# unit tests
pnpm run test

# test coverage
pnpm run test:cov

Monitoring (Prometheus + Grafana)

The backend exposes Prometheus metrics at GET /metrics.

GRAFANA_ADMIN_PASSWORD=choose-a-real-password pnpm run monitoring:up

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3001 (login: admin / the GRAFANA_ADMIN_PASSWORD you set — there is no default password)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Seunfola
• Source: Seunfola/package-health-backup
• License: MIT
• Homepage: https://package-health-backup-1.onrender.com

Install and usage instructions live in the source repository linked above.