Blocking behavior
Dependency Guardian assigns each package a verdict — block, warn, or pass — from a numeric risk score. This page explains how that decision is made, what the CLI does with it, and how to wire it into GitHub so risky pull requests can't merge. There are no modes or policy flags to configure: the verdict comes from the server and the CLI enforces it the same way everywhere.
What the CLI does with a verdict
One consistent rule — no --mode, no off switch.
| Verdict | What happens |
|---|---|
| block | The high-risk package is refused. On an npm install / pip install in a terminal you're asked to confirm (y/N, default No); in CI or a git hook it's refused outright. The commit hook blocks the commit. |
| warn | Reported with explanations; the install / commit proceeds. |
| pass | Clean — proceeds untouched. |
Exit code is binary: 0 when the action is allowed, non-zero when a block-level package is refused — so git hooks and shells can gate on it directly.
Fail-open: if a scan can't complete (network or API error), dg exits 0 and lets the install / commit through. An outage never blocks your work.
How packages get scored
Every package gets a single 0–100 risk score. Higher = riskier. The score drives the verdict above.
| Score | Verdict |
|---|---|
| 0 – 59 | pass |
| 60 – 69 | warn (reported, proceeds) |
| 70 – 100 | block (refused) |
The score is computed from detectors: install-script analysis, network access patterns, secret-path reads, obfuscation, typosquat distance, publisher reputation, version-diff anomalies, sandbox behavior, and others. A package can fire multiple detectors; the engine combines them with severity weights into the final score. The server is the source of truth for the verdict — the CLI never re-derives it.
The verdict is per package. A scan's overall result is the worst across all scanned packages: one block-level dependency in a 200-package tree is enough to block.
Overriding a block
Sometimes you've reviewed a flagged package and know it's safe in context. In an interactive terminal, the install prompt lets you confirm the override (y); the default is to refuse. In CI / non-interactive runs there is no override — fix or pin the dependency and re-run. For the git pre-commit hook, the standard git escape hatch applies: git commit --no-verify.
Wiring it into GitHub (merge protection)
With the GitHub App installed, Dependency Guardian publishes a status check on every pull request. Use a branch ruleset to make that check required.
- Go to your repo → Settings → Rules → Rulesets
- Click New branch ruleset
- Name it (e.g. “Dependency Guardian”)
- Set Enforcement status to Active
- Under Target branches, add your default branch (usually main)
- Enable Require status checks to pass
- Search for Dependency Guardian and select it
- Click Create
Note: the check only appears after Dependency Guardian has run at least once against your repo. On private repositories, GitHub Rulesets require a Team or Enterprise plan.
See also
- CLI Reference — every command, the binary exit codes, and the public env vars
- Integrations — webhooks for scan events, Slack notifications