@westbayberry/dg 1.0.42 → 1.0.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +27 -125
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @westbayberry/dg
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  ## Install
6
6
 
@@ -17,166 +17,68 @@ dg login
17
17
  dg scan
18
18
  ```
19
19
 
20
- 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.
20
+ `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.
21
21
 
22
- 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.
22
+ Supports `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `requirements.txt`, `Pipfile.lock`, and `poetry.lock`.
23
23
 
24
24
  ## Commands
25
25
 
26
26
  ```
27
- dg scan [options] Scan dependencies for supply chain threats
28
- dg npm install <pkg> Scan packages before installing them
29
- dg login Authenticate with your WestBayBerry account
30
- dg logout Remove saved credentials
31
- dg hook install Install git pre-commit hook
32
- dg hook uninstall Remove the pre-commit hook
33
- dg update Check for and install the latest version
34
- dg wrap Show instructions to alias npm to dg
27
+ dg scan Scan dependencies for supply chain threats
28
+ dg npm install <pkg> Scan packages before installing them
29
+ dg login / logout Manage authentication
30
+ dg hook install Install git pre-commit hook
31
+ dg update Check for and install the latest version
35
32
  ```
36
33
 
37
- ## What It Detects
38
-
39
- Each package is analyzed by 26+ detectors covering:
40
-
41
- | Category | Examples |
42
- |----------|----------|
43
- | **Code execution** | `child_process` spawning, `eval`/`Function` calls, shell command injection |
44
- | **Network exfiltration** | HTTP/WebSocket/DNS/gRPC calls, URL obfuscation, data exfil patterns |
45
- | **Credential theft** | Reading SSH keys, browser tokens, cloud credentials, `.npmrc`/`.pypirc` |
46
- | **Install scripts** | Suspicious `preinstall`/`postinstall` hooks, download-and-execute chains |
47
- | **Obfuscation** | Hex/unicode encoding, string reconstruction, phantom eval, minified payloads |
48
- | **Supply chain** | Typosquatting, dependency confusion, version squatting, borrowed repo URLs |
49
- | **Persistence** | Writing to shell configs, cron jobs, systemd units, SSH `authorized_keys` |
50
- | **Behavioral** | Time-gated payloads, purpose mismatch, runtime evasion, binary addons |
51
- | **Reputation** | Missing/fake GitHub repos, ghost packages, low download counts |
52
-
53
- Findings include severity (1–5), confidence (0–1), and code evidence with file paths and line numbers.
54
-
55
- ## Scan Options
34
+ ## Common Options
56
35
 
57
36
  | Flag | Default | Description |
58
37
  |------|---------|-------------|
59
38
  | `--mode <mode>` | `warn` | `block` / `warn` / `off` |
60
- | `--max-packages <n>` | `200` | Max packages per scan |
61
39
  | `--json` | | Output raw JSON (for CI parsing) |
62
- | `--scan-all` | | Scan all packages, not just changed |
63
- | `--base-lockfile <path>` | | Explicit base lockfile for diff |
64
40
  | `--workspace <dir>` | | Scan a specific workspace subdirectory |
65
- | `--debug` | | Show discovery, batching, and timing info |
66
41
 
67
42
  ## Exit Codes
68
43
 
69
- | Code | Meaning | CI Action |
70
- |------|---------|-----------|
71
- | `0` | Pass | Continue |
72
- | `1` | Warning | Advisory — review recommended |
73
- | `2` | Block | Fail the pipeline |
74
- | `3` | Error | Internal error (auth, network, etc.) |
75
-
76
- ## Configuration
77
-
78
- 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.
44
+ | Code | Meaning |
45
+ |------|---------|
46
+ | `0` | Pass |
47
+ | `1` | Warning |
48
+ | `2` | Block |
49
+ | `3` | Error |
79
50
 
80
- ### `.dgrc.json`
81
-
82
- ```json
83
- {
84
- "apiKey": "dg_...",
85
- "mode": "block",
86
- "maxPackages": 200
87
- }
88
- ```
89
-
90
- ### Environment Variables
91
-
92
- | Variable | Description |
93
- |----------|-------------|
94
- | `DG_API_URL` | API base URL |
95
- | `DG_MODE` | `block` / `warn` / `off` |
96
- | `DG_DEBUG` | Set to `1` for diagnostic output |
97
- | `DG_WORKSPACE` | Workspace subdirectory |
98
-
99
- ## CI Setup
100
-
101
- ### GitHub Actions
102
-
103
- ```yaml
104
- - name: Scan dependencies
105
- run: |
106
- npx @westbayberry/dg login
107
- npx @westbayberry/dg scan --mode block --json
108
- ```
109
-
110
- ### Any CI
51
+ ## CI
111
52
 
112
53
  ```bash
113
54
  npx @westbayberry/dg login
114
55
  npx @westbayberry/dg scan --mode block --json
115
56
  ```
116
57
 
117
- The `--json` flag outputs machine-readable results. Exit code `2` signals a blocked scan — wire it into your pipeline to fail the build.
118
-
119
- ### Monorepo / Workspace
120
-
121
- Scan a specific workspace:
122
-
123
- ```bash
124
- dg scan --workspace packages/api
125
- ```
58
+ Wire exit code `2` into your pipeline to fail the build.
126
59
 
127
- Or let `dg` discover all projects and pick interactively.
128
-
129
- 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.
130
-
131
- ## Git Hook
132
-
133
- Block commits that introduce risky dependencies:
134
-
135
- ```bash
136
- dg hook install
137
- ```
138
-
139
- 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`.
140
-
141
- ## npm Wrapper
142
-
143
- Scan packages before they're installed:
144
-
145
- ```bash
146
- dg npm install express lodash
147
- ```
148
-
149
- 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.
60
+ ## Configuration
150
61
 
151
- To make this the default for all `npm install` commands:
62
+ Settings come from CLI flags, environment variables, or a `.dgrc.json` file in the project or home directory. CLI flags take precedence.
152
63
 
153
- ```bash
154
- echo 'alias npm="dg npm"' >> ~/.zshrc
64
+ ```json
65
+ {
66
+ "apiKey": "dg_...",
67
+ "mode": "block"
68
+ }
155
69
  ```
156
70
 
157
- ## Python Support
158
-
159
- Python projects are detected alongside npm. The scanner reads:
160
-
161
- - `requirements.txt` — `name==version` pins
162
- - `Pipfile.lock` — default and develop sections
163
- - `poetry.lock` — `[[package]]` entries
71
+ ## Telemetry
164
72
 
165
- Python packages are analyzed through the same detection engine against the PyPI registry.
73
+ 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.
166
74
 
167
- ## Telemetry & Privacy
168
-
169
- 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.
170
-
171
- Opt out at any time by setting either environment variable before running `dg`:
75
+ Opt out:
172
76
 
173
77
  ```bash
174
78
  export DG_TELEMETRY=0 # or
175
79
  export DO_NOT_TRACK=1
176
80
  ```
177
81
 
178
- 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`.
179
-
180
82
  ## Links
181
83
 
182
84
  - [Dashboard](https://westbayberry.com/dashboard)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@westbayberry/dg",
3
- "version": "1.0.42",
3
+ "version": "1.0.43",
4
4
  "description": "Supply chain security scanner for npm and Python dependencies — detects malicious packages, typosquatting, dependency confusion, and 26+ attack patterns",
5
5
  "bin": {
6
6
  "dependency-guardian": "dist/index.mjs",