@westbayberry/dg 1.0.56 → 1.0.57

package/README.md

@@ -1,10 +1,27 @@
 # @westbayberry/dg
 
-Behavioral supply chain security scanner for npm and Python. Reads what packages actually do — install hooks, credential access, network exfiltration, obfuscation — and blocks the PR before merge.
+Behavioral supply chain security for npm and Python. Reads what packages
+actually do — install hooks, credential access, network exfiltration,
+obfuscation — and gates risky installs before they touch your machine.
 
-**35 detectors · 99.66% catch rate on 155,704 packages · 0.66% FPR** — [published methodology](https://westbayberry.com/benchmark).
+**35 detectors · 99.66% catch rate on 155,704 packages · 0.66% FPR** —
+[published methodology](https://westbayberry.com/benchmark).
 
-Catches zero-day supply chain attacks CVE databases miss. `npm audit`, Snyk, and Dependabot passed the March 2026 axios RAT, the Shai-Hulud worm, and the chalk/debug hijack as clean. Behavioral scanning caught all three in seconds.
+## What `dg` actually does
+
+| Surface | What it does | Default mode |
+|---|---|---|
+| `dg npm install <pkg>` | Resolves the full dependency tree (top-level + transitive) without running install scripts, scans every package, then invokes the real `npm install` only if the verdict permits. Top-level versions are pinned to the exact version we scanned. Bare `dg npm install` honors `package-lock.json` pinned versions. | **block** |
+| `dg pip install <pkg>` | Resolves the full pip tree via `pip install --dry-run --report=-` (pip ≥ 23.0); scans the full set before invoking real `pip install`. On older pip, transitive scan is reported as unavailable and (in block mode) the install is refused. | **block** |
+| `dg scan` | Read-only audit. Diffs lockfiles and reports findings. Does **not** block anything by default. | warn |
+| `dg hook install` | Adds a pre-commit hook that runs `dg scan --mode block` when a lockfile change is staged. Quiet when nothing is wrong. | block |
+
+For maximum protection in CI/build pipelines, add `--strict` to the install
+wrapper. `--strict` implies `--dg-no-scripts` and refuses any partial-coverage
+scan (transitive enumeration must succeed).
+
+DG only activates when you intentionally invoke it, install the hook, or
+run it in CI. It does not globally hijack `npm`/`pip`.
 
 ## Install
 
@@ -18,29 +35,49 @@ Requires Node.js 18+.
 
 ```bash
 dg login
-dg scan
+dg scan          # read-only audit of the current project
 ```
 
-`dg scan` finds your lockfiles, diffs against `main`, and sends the changed package names and versions to the Dependency Guardian API. Results come back as a summary with severity, evidence, and safe-version recommendations.
+Scope-truthful output: a clean project shows
+`✓ Dependency Guardian checked 142 packages. No risky behavior found.`
+A flagged install shows only the warn/block packages with one-line
+reasons and a clear next step.
 
-Supports `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `requirements.txt`, `Pipfile.lock`, and `poetry.lock`.
+Supports `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`,
+`requirements.txt`, `Pipfile.lock`, and `poetry.lock`.
 
 ## Commands
 
 ```
-dg scan              Scan dependencies for supply chain threats
-dg npm install <pkg> Scan packages before installing them
+dg scan              Read-only audit of the project's lockfiles
+dg status            Show your auth state, plan tier, and whether protection is on
 dg login / logout    Manage authentication
-dg hook install      Install git pre-commit hook
+dg npm install <pkg> Protective install wrapper (default mode: block)
+dg pip install <pkg> Protective install wrapper (default mode: block)
+dg protect           Opt this project in to auto-protection on every install
+dg protect off       Disable opt-in protection in this project
+dg wrap              Print the shell-alias snippet without writing a project marker
+dg hook install      Install a git pre-commit hook that gates lockfile diffs
+dg hook uninstall    Remove the git pre-commit hook
+dg publish-check     Self-scan before `npm publish` / `pip upload`
 dg update            Check for and install the latest version
 ```
 
+Full reference: <https://westbayberry.com/docs/cli-reference>
+
 ## Common Options
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--mode <mode>` | `warn` | `block` / `warn` / `off` |
-| `--json` | | Output raw JSON (for CI parsing) |
+| `--mode <mode>` | `warn` for `scan`, `block` for install wrappers | `block` / `warn` / `off` |
+| `--details` | off | Verbose table view (the older format) |
+| `--explain` | off | Plain-English explanation of findings |
+| `--json` | off | Stable machine-readable JSON (CI) |
+| `--ci` | auto when `CI=1` | Deterministic output, no spinners |
+| `--dg-force` | off | Bypass a block (visible in output, audit-friendly) |
+| `--dg-no-scripts` | off | Pass `--ignore-scripts` to the real install |
+| `--strict` | off | Refuse partial-coverage scans + auto `--dg-no-scripts` |
+| `--quiet` | off | Suppress login + update nudges (still prints findings) |
 | `--workspace <dir>` | | Scan a specific workspace subdirectory |
 
 ## Exit Codes
@@ -86,5 +123,7 @@ export DO_NOT_TRACK=1
 ## Links
 
 - [Dashboard](https://westbayberry.com/dashboard)
-- [Documentation](https://westbayberry.com/docs)
+- [Documentation](https://westbayberry.com/docs) — setup walkthrough
+- [CLI reference](https://westbayberry.com/docs/cli-reference) — every command and flag
 - [Pricing](https://westbayberry.com/pricing)
+- [Changelog](https://github.com/WestBayBerry/dependency-guardian-action/blob/main/CHANGELOG.md)