@westbayberry/dg 1.0.42 → 1.0.46

package/README.md

@@ -1,6 +1,6 @@
 # @westbayberry/dg
 
-Supply chain security scanner for npm and Python dependencies. Scans lockfile changes against 26+ detectors to catch malicious packages, typosquatting, dependency confusion, credential theft, and obfuscated code before they reach production.
+Supply chain security scanner for npm and Python dependencies. Scans lockfile changes for malicious packages, typosquatting, dependency confusion, and credential theft before they reach production.
 
 ## Install
 
@@ -17,166 +17,68 @@ dg login
 dg scan
 ```
 
-The CLI walks your directory tree and finds npm lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`) and Python dependency files (`requirements.txt`, `Pipfile.lock`, `poetry.lock`). If multiple projects are found, an interactive selector lets you pick which ones to scan.
+`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.
 
-Only changed packages are scanned by default — `dg` diffs your lockfile against the git merge-base with `main` to find what's new or updated.
+Supports `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `requirements.txt`, `Pipfile.lock`, and `poetry.lock`.
 
 ## Commands
 
 ```
-dg scan [options]        Scan dependencies for supply chain threats
-dg npm install <pkg>     Scan packages before installing them
-dg login                 Authenticate with your WestBayBerry account
-dg logout                Remove saved credentials
-dg hook install          Install git pre-commit hook
-dg hook uninstall        Remove the pre-commit hook
-dg update                Check for and install the latest version
-dg wrap                  Show instructions to alias npm to dg
+dg scan              Scan dependencies for supply chain threats
+dg npm install <pkg> Scan packages before installing them
+dg login / logout    Manage authentication
+dg hook install      Install git pre-commit hook
+dg update            Check for and install the latest version
 ```
 
-## What It Detects
-
-Each package is analyzed by 26+ detectors covering:
-
-| Category | Examples |
-|----------|----------|
-| **Code execution** | `child_process` spawning, `eval`/`Function` calls, shell command injection |
-| **Network exfiltration** | HTTP/WebSocket/DNS/gRPC calls, URL obfuscation, data exfil patterns |
-| **Credential theft** | Reading SSH keys, browser tokens, cloud credentials, `.npmrc`/`.pypirc` |
-| **Install scripts** | Suspicious `preinstall`/`postinstall` hooks, download-and-execute chains |
-| **Obfuscation** | Hex/unicode encoding, string reconstruction, phantom eval, minified payloads |
-| **Supply chain** | Typosquatting, dependency confusion, version squatting, borrowed repo URLs |
-| **Persistence** | Writing to shell configs, cron jobs, systemd units, SSH `authorized_keys` |
-| **Behavioral** | Time-gated payloads, purpose mismatch, runtime evasion, binary addons |
-| **Reputation** | Missing/fake GitHub repos, ghost packages, low download counts |
-
-Findings include severity (1–5), confidence (0–1), and code evidence with file paths and line numbers.
-
-## Scan Options
+## Common Options
 
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--mode <mode>` | `warn` | `block` / `warn` / `off` |
-| `--max-packages <n>` | `200` | Max packages per scan |
 | `--json` | | Output raw JSON (for CI parsing) |
-| `--scan-all` | | Scan all packages, not just changed |
-| `--base-lockfile <path>` | | Explicit base lockfile for diff |
 | `--workspace <dir>` | | Scan a specific workspace subdirectory |
-| `--debug` | | Show discovery, batching, and timing info |
 
 ## Exit Codes
 
-| Code | Meaning | CI Action |
-|------|---------|-----------|
-| `0` | Pass | Continue |
-| `1` | Warning | Advisory — review recommended |
-| `2` | Block | Fail the pipeline |
-| `3` | Error | Internal error (auth, network, etc.) |
-
-## Configuration
-
-Settings can come from CLI flags, environment variables, or a `.dgrc.json` config file (searched in the current directory, then `~/`). CLI flags take highest precedence.
+| Code | Meaning |
+|------|---------|
+| `0` | Pass |
+| `1` | Warning |
+| `2` | Block |
+| `3` | Error |
 
-### `.dgrc.json`
-
-```json
-{
-  "apiKey": "dg_...",
-  "mode": "block",
-  "maxPackages": 200
-}
-```
-
-### Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `DG_API_URL` | API base URL |
-| `DG_MODE` | `block` / `warn` / `off` |
-| `DG_DEBUG` | Set to `1` for diagnostic output |
-| `DG_WORKSPACE` | Workspace subdirectory |
-
-## CI Setup
-
-### GitHub Actions
-
-```yaml
-- name: Scan dependencies
-  run: |
-    npx @westbayberry/dg login
-    npx @westbayberry/dg scan --mode block --json
-```
-
-### Any CI
+## CI
 
 ```bash
 npx @westbayberry/dg login
 npx @westbayberry/dg scan --mode block --json
 ```
 
-The `--json` flag outputs machine-readable results. Exit code `2` signals a blocked scan — wire it into your pipeline to fail the build.
-
-### Monorepo / Workspace
-
-Scan a specific workspace:
-
-```bash
-dg scan --workspace packages/api
-```
+Wire exit code `2` into your pipeline to fail the build.
 
-Or let `dg` discover all projects and pick interactively.
-
-Discovery walks your directory tree up to 8 levels deep and skips `node_modules`, `.git`, `dist`, `build`, virtualenvs, and any directory whose name starts with a dot (`.github`, `.config`, etc.). If you keep lockfiles inside a dot-directory on purpose, pass `--workspace` to target it directly.
-
-## Git Hook
-
-Block commits that introduce risky dependencies:
-
-```bash
-dg hook install
-```
-
-This adds a pre-commit hook that runs `dg scan --mode block` whenever a lockfile is staged. If any package is flagged as high-risk, the commit is rejected. Remove it with `dg hook uninstall`.
-
-## npm Wrapper
-
-Scan packages before they're installed:
-
-```bash
-dg npm install express lodash
-```
-
-Packages are resolved and scanned through the API. If a package is blocked, you'll get a confirmation prompt — press `y` to install anyway, or use `--dg-force` to skip the prompt.
+## Configuration
 
-To make this the default for all `npm install` commands:
+Settings come from CLI flags, environment variables, or a `.dgrc.json` file in the project or home directory. CLI flags take precedence.
 
-```bash
-echo 'alias npm="dg npm"' >> ~/.zshrc
+```json
+{
+  "apiKey": "dg_...",
+  "mode": "block"
+}
 ```
 
-## Python Support
-
-Python projects are detected alongside npm. The scanner reads:
-
-- `requirements.txt` — `name==version` pins
-- `Pipfile.lock` — default and develop sections
-- `poetry.lock` — `[[package]]` entries
+## Telemetry
 
-Python packages are analyzed through the same detection engine against the PyPI registry.
+The CLI sends anonymous crash reports to Sentry (error message, stack trace, Node version, OS, CLI version). It never sends package names, file paths, API keys, or scan results. API keys and home directory paths are redacted before transmission.
 
-## Telemetry & Privacy
-
-The CLI sends anonymous crash reports to Sentry to help us catch bugs. What's sent: error message, stack trace, Node version, OS, CLI version, and the command that was run. What's **never** sent: package names, file paths, API keys, lockfile contents, or any scan results. API keys matching `dg_live_*` / `dg_test_*` and home directory paths are redacted before transmission.
-
-Opt out at any time by setting either environment variable before running `dg`:
+Opt out:
 
 ```bash
 export DG_TELEMETRY=0      # or
 export DO_NOT_TRACK=1
 ```
 
-Update-check behavior: `dg scan` checks npm once every 24 hours for a newer version and prints a banner if one exists. The check is automatically skipped in CI (`process.env.CI` set) and in `--json` mode. The CLI will never install an update without you explicitly running `dg update`.
-
 ## Links
 
 - [Dashboard](https://westbayberry.com/dashboard)