@westbayberry/dg

Dependency Guardian is a supply-chain firewall for npm and PyPI. The dg CLI checks a package against the scanner before its code can run, so a malicious install is blocked before its install scripts execute, not flagged afterward. It scans published package artifacts from the registry; your source code stays on your machine.

Built by Mckeane McBrearty at WestBayBerry, open source under Apache-2.0. Releases publish from GitHub Actions through npm's Trusted Publisher OIDC, never from a personal machine. The scanner's findings land in the OpenSSF malicious-packages database, including a 37-package React Native campaign from the npm account sproger that had gone unreported for over a year (OSSF PR #1322).

Install

npm install -g @westbayberry/dg

Requires Node.js >= 22.14. The install adds only the dg binary and runs no lifecycle scripts of its own. The published tarball ships an npm-shrinkwrap.json, so every install resolves the exact dependency tree the release was audited with. Nothing touches your shell until you run dg setup.

Quickstart

dg login      # free account
dg scan       # audit the current project's lockfiles

dg scan reads your lockfiles and asks the scanner for a verdict on each dependency. It installs nothing and runs no package scripts. Exit 0 is clean, 2 means a block-level package was found.

The install firewall

Prefix any install command with dg and the package is checked before its bytes reach your package manager:

dg npm install lodash
dg pnpm add react
dg pip install requests
dg cargo add serde

It proxies just that command, hashes each artifact as it downloads, and refuses a blocked one before delivery. Supported prefixes: npm, npx, pnpm, pnpx, Yarn classic, pip, pipx, uv, uvx, and cargo. To protect bare npm install / pip install and your AI coding agents too, run dg setup (one consent screen, reversible with dg uninstall).

Common commands

| Command | What it does | | --- | --- | | dg scan [path] | Audit a project's lockfiles for malicious dependencies | | dg verify npm:react@18 | Check a published package before you install it | | dg sbom [path] | CycloneDX 1.5 SBOM for the resolved tree | | dg licenses [path] | SPDX license report grouped by risk | | dg audit [path] | Pre-publish check of a package of your own | | dg agents | Route AI coding agents' installs through the firewall | | dg setup / dg uninstall | Install or remove the shell and agent hooks | | dg doctor | Diagnose setup, PATH, auth, and service state |

Run dg <command> --help for flags, or dg --help-all for the complete list. The full reference is at westbayberry.com/docs/cli-reference.

Verdicts and exit codes

Every result is one of three states the scanner returns: PASS, WARN, or BLOCK, and the exit code follows it. The server is the verdict source. The CLI never derives one from a local score, and if the scanner is unreachable it marks the report rather than passing silently.

Exit codes

The stable exit codes are 0 pass, 1 warn, 2 block, 4 analysis incomplete, 10 nothing to scan, and 70 unexpected CLI error. Some commands return 64 when a command unavailable or gated on this platform is requested. Machine-readable output includes a schemaVersion field so CI parsers can pin a contract.

dg sbom

dg sbom [path] inventories the resolved dependency tree as CycloneDX 1.5. Interactive terminals can show scanner verdicts for npm and PyPI components; --json or --output writes the raw SBOM for CI.

dg audit

dg audit [path] is a pre-publish check for a package of your own. Inspects exactly the resolved publish set of one package, never the whole repo. Basic checks run 100% locally. On paid plans, and only when enabled, deep behavioral analysis uploads a packed copy for scanning; raw bytes are not retained, and only verdict metadata plus redacted findings reach your dashboard.

dg agents

dg agents installs or checks native pre-command hooks for supported AI coding agents so their package-manager calls route through the same install firewall. Run dg agents --check in CI or a workstation audit to verify the wiring.

dg decisions

dg decisions list shows remembered warn-level decisions for the current project. dg decisions revoke removes one. Blocks can never be acknowledged away.

dg cooldown

dg cooldown shows the effective new-release quarantine and exemptions. dg cooldown exempt <name> records a project exemption in dg.json; user-level cooldown.exempt applies everywhere.

In CI

Set DG_API_KEY (a dg_live_* key from Settings -> CI keys) and run dg scan. The CLI auto-detects CI and switches to non-interactive output; add --sarif -o dg.sarif to write findings for upload. On GitHub, the GitHub App is the zero-config path and posts a PR status check.

Privacy

No telemetry, no crash reporter, no analytics. The CLI talks to the network only when a command needs it: scanning sends package names and versions from your lockfiles, and the scanner pulls the artifacts itself; the firewall sends each artifact's name, version, and SHA-256. Your source never leaves your machine. Detail: westbayberry.com/docs/telemetry.

What dg sends to the API

Authenticated scans send DG_API_KEY with package names, versions, ecosystem, registry host, lockfile integrity, and artifact hashes where available. Install firewall calls send the public package identity and artifact hash needed for a verdict. Source files, local paths, stack traces, and crash reports are not sent.

Development

git clone https://github.com/WestBayBerry/DG_CLI.git
cd DG_CLI
npm install
npm run build
npm test

Requires Node.js >= 22.14. Run the built CLI from source with node dist/bin/dg.js --help, and npm run check for typecheck, lint, and format checks. Issues and pull requests are welcome.

Documentation

• Getting started
• CLI reference: every command, flag, and exit code
• Blocking behavior
• Integrations
• Telemetry

Reporting a vulnerability

Please report security issues privately through GitHub's private vulnerability reporting rather than a public issue.

License

Apache-2.0. See LICENSE.