# Package Health Backup > Predictive dependency Trust Score scanning, pre-install gating (Shield), and hardcoded-secret detection (LeakGuard) for npm, PyPI, Cargo, and Go — CLI, GitHub Action, VS Code extension, and MCP server. - **Type:** MCP server - **Install:** `agentstack add mcp-seunfola-package-health-backup` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Seunfola](https://agentstack.voostack.com/s/seunfola) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Seunfola](https://github.com/Seunfola) - **Source:** https://github.com/Seunfola/package-health-backup - **Website:** https://package-health-backup-1.onrender.com ## Install ```sh agentstack add mcp-seunfola-package-health-backup ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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): ```json { "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`): ```yaml - 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. ```bash 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: ```json { "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: ```bash export DEPVAULT_API_URL=https://your-deployment.example.com ``` ### 2. Use the shield manually Run the shield before you install a dependency: ```bash # 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: ```bash # 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: ```bash 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: ```bash # 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) ```bash # 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 ```bash pnpm install ``` ## Running the API ```bash # development pnpm run start # watch mode pnpm run start:dev # production mode pnpm run start:prod ``` ## Testing ```bash # unit tests pnpm run test # test coverage pnpm run test:cov ``` ## Monitoring (Prometheus + Grafana) The backend exposes Prometheus metrics at `GET /metrics`. ```bash 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](https://github.com/Seunfola) - **Source:** [Seunfola/package-health-backup](https://github.com/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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-seunfola-package-health-backup - Seller: https://agentstack.voostack.com/s/seunfola - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.