dependency-radar 0.8.1 → 0.9.0

package/README.md

@@ -1,5 +1,11 @@
 # Dependency Radar
 
+[![npm version](https://img.shields.io/npm/v/dependency-radar.svg)](https://www.npmjs.com/package/dependency-radar)
+[![CI](https://github.com/JosephMaynard/dependency-radar/actions/workflows/ci.yml/badge.svg)](https://github.com/JosephMaynard/dependency-radar/actions/workflows/ci.yml)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12839/badge)](https://www.bestpractices.dev/projects/12839)
+[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/JosephMaynard/dependency-radar?label=openssf%20scorecard)](https://securityscorecards.dev/viewer/?uri=github.com/JosephMaynard/dependency-radar)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Dependency Radar inspects your Node.js dependency graph and makes structural risk visible.
 
 Unlike basic audit tools, it builds the graph from lockfiles, understands PNPM workspaces, validates declared vs inferred licences, and highlights structural risks before they become production problems.
@@ -14,16 +20,55 @@ npx dependency-radar
 
 This runs a scan against the current project and writes a self-contained `dependency-radar.html` report you can open locally, share with teammates, or attach to tickets and documentation.
 
+You can see a [Dependency Radar example report](https://www.dependency-radar.com/examples/dependency-radar.html).
+
 ---
 
 ![Dependency Radar – dependency list view](./docs/screenshot-01.jpg)
-*List view: search, filter, and drill into every dependency — licence, vulnerabilities, install risk, depth, origins, and more.*
+*List view: search, filter, and drill into every dependency, licence, vulnerabilities, install risk, depth, origins, and more.*
+
+![Dependency Radar – expanded dependency](./docs/screenshot-03.jpg)
+*Expanded dependency view: scan the key risk signals first, then drill into status, scope, origins, install behaviour, licence, vulnerabilities, and upgrade blockers.*
 
 ![Dependency Radar – interactive dependency graph view](./docs/screenshot-02.jpg)
 *Graph view: explore the full dependency tree visually, with direct, dev, and transitive relationships at a glance.*
 
 ---
 
+## Before you run a random `npx` command
+
+It is reasonable to be cautious about running a new CLI tool inside your project.
+
+Dependency Radar is designed to be inspectable and low-friction to evaluate:
+
+- the CLI has no runtime npm dependencies
+- scans run on your machine
+- Dependency Radar does not modify your `package.json`, lockfile, or installed dependencies
+- Dependency Radar does not upload your source code or generated reports during a normal CLI scan
+- reports are written to disk as local files
+- the only default network activity is package-manager-backed audit and outdated checks, which query the configured package registry for dependency metadata
+- use `--offline` for a no-registry-call scan
+
+You can inspect the source on GitHub, view the npm package metadata, or start with an offline scan:
+
+```bash
+npx dependency-radar --offline
+```
+
+Security issues should be reported privately; see [SECURITY.md](./SECURITY.md).
+
+## What the CLI accesses
+
+| Area | What happens |
+|---|---|
+| Project files | Reads package manifests, lockfiles, and installed dependency metadata |
+| `node_modules` | Reads package metadata and selected files for dependency analysis |
+| Output files | Writes reports/SBOMs only where requested |
+| Network | Runs package-manager audit/outdated checks by default, which query the configured package registry for dependency metadata |
+| Offline mode | `--offline` skips audit, outdated, signature verification, and targeted registry enrichment checks |
+| Source code upload | No source code or generated reports are uploaded during a normal CLI scan |
+| Project mutation | Dependency Radar does not install, update, remove, or rewrite dependencies |
+
 ## What you get
 
 - **Vulnerability scanning** — runs `npm audit` / `pnpm audit` / `yarn audit` and surfaces advisories with severity, fix availability, and reachability heuristics
@@ -33,11 +78,14 @@ This runs a scan against the current project and writes a self-contained `depend
 - **Import usage heuristics** — classifies each dependency's runtime impact (`runtime`, `build`, `testing`, `tooling`, `mixed`) based on where it's imported in your source
 - **Full transitive tree** — shows depth, parent relationships, fan-in/fan-out, and dependency origins
 - **Workspace support** — works across npm, pnpm, and Yarn workspaces
-- **CI-friendly** — `--fail-on` flag lets you enforce licence and vulnerability policies in pipelines
+- **CI-friendly** — `--fail-on` flag lets you enforce licence, vulnerability, and compare-mode dependency change policies in pipelines
 - **Review-friendly outputs** — emit JSON, SARIF, CycloneDX SBOM, or SPDX SBOM artifacts from the same local scan
 - **Change comparison** — compare a fresh scan with a previous `dependency-radar.json` to see added dependencies, removed dependencies, version changes, and new findings
-- **Lockfile supply-chain signals** — flags git/local/tarball sources, missing integrity, unexpected registry hosts, and optional npm signature/provenance verification
-- **Completely offline-capable** — use `--offline` to skip registry calls; all package metadata is read from local `node_modules`
+- **Source review signals** — flags git, local file, and non-registry tarball dependency sources
+- **Lockfile integrity signals** — flags missing integrity data and unexpected registry hosts
+- **Local execution review signals** — flags install-time behavior and bounded local execution capability signals
+- **Packaging and registry review signals** — flags packaging cues, optional npm signature/provenance results, and limited registry-metadata heuristics applied only to packages already flagged as suspicious
+- **Offline-capable** — use `--offline` to skip registry calls; dependency metadata is still read from local `node_modules`
 - **Single self-contained HTML file** — no server needed; open it locally, attach it to a ticket, or share it with your team
 
 ## When should you use this?
@@ -50,10 +98,13 @@ This runs a scan against the current project and writes a self-contained `depend
 
 ## What it is not
 
-- Not a CI service or hosted scanning platform
-- Not a replacement for dedicated security scanners
-- Not a bundler or build tool
+Dependency Radar is a review and triage tool. It makes dependency risk easier to see, but it does not make security decisions for you.
+
+- Not a hosted scanning platform or CI service
+- Not a malware detector or guarantee that a package is safe
+- Not a replacement for dedicated security scanners, manual review, or threat modelling
 - Not a dependency updater
+- Not a bundler, package manager, or build tool
 
 ## Why this exists
 
@@ -70,7 +121,7 @@ Dependency Radar exists to make those hidden signals visible in one place, from
 
 ## Need to share findings with leadership?
 
-The CLI tool is free and fully functional forever.
+The CLI tool is free and fully functional forever. It does not require an account or upload during normal use.
 
 If you need to communicate dependency risk beyond engineering (CTO, compliance, security, clients, or investors), the optional premium service adds executive summaries, presentation-ready reports, and deeper enrichment signals that are not available in the standard local scan.
 
@@ -78,6 +129,8 @@ These include ecosystem and maintenance insights such as whether a dependency is
 
 See https://dependency-radar.com for details.
 
+The free CLI does not require an account or upload. The optional premium service is separate and only applies if you choose to use it.
+
 ---
 
 ## Usage
@@ -102,7 +155,7 @@ The `scan` command is the default and can also be run explicitly as `npx depende
 | `--target-node <major>` | Add Node major compatibility findings based on local `engines.node` metadata |
 | `--audit-signatures` | Run `npm audit signatures` for registry signature/provenance verification (opt-in; skipped with `--offline`) |
 | `--schema` | Print the current Dependency Radar JSON schema, or write it with `--out <path>` |
-| `--offline` | Skip `npm audit` and `npm outdated` (useful for offline/air-gapped scans) |
+| `--offline` | Skip registry lookups: `npm audit`, `npm outdated`, signature checks, and targeted registry enrichment |
 | `--json` | Output JSON instead of HTML (`dependency-radar.json`) |
 | `--timestamp` | Add a local timestamp to generated report filenames (`dependency-radar.YYYY-MM-DD_HH-mm-ss.html`) |
 | `--no-report` | Run analysis only; no HTML/JSON output written |
@@ -174,6 +227,38 @@ npx dependency-radar compare ./dependency-radar-before.json --json --offline
 
 The comparison highlights added dependencies, removed dependencies, one-version package changes, new findings, and resolved findings. This is useful in pull requests and release checks.
 
+Compare mode can also fail CI when a dependency change introduces a new risky trait compared with a committed JSON baseline:
+
+```bash
+npx dependency-radar compare ./dependency-radar-baseline.json --offline --fail-on new-supply-chain-signal,new-install-script,new-child-process
+```
+
+This is intentionally not a generic "any dependency changed" gate. It is a review guardrail for targeted local signals such as a newly introduced install script, native build surface, CLI executable, direct dependency, local execution capability signal, packaging signal, or lockfile supply-chain source signal. These signals mean "review this change"; they are not malware verdicts.
+
+Local execution capability signals are derived by bounded static inspection of lifecycle script commands, referenced install files, package `bin` targets, entry files, and a small capped subset of text-like package source files. Dependency Radar currently reports signals such as child process APIs, network access references, environment access, home directory access, SSH-related references, and obfuscation-like code shape. Scanning is capped by file count and bytes per file so large packages do not become expensive to inspect.
+
+Packaging signals are local metadata/content cues such as declared bundled dependencies or an embedded `npm-shrinkwrap.json`. They are review aids for unusual packaging patterns, not proof of compromise.
+
+### Targeted registry enrichment for suspicious packages
+
+Dependency Radar can perform a small number of targeted npm registry metadata lookups for packages that already show local review signals, such as install hooks, native bindings, executable bins, supply-chain source signals, or suspicious execution/packaging signals.
+
+This enrichment is bounded and selective:
+- it does not query every dependency
+- it is capped to 10 suspicious package names per scan
+- it is skipped when `--offline` is used
+
+When metadata is available, Dependency Radar may derive additional review signals such as:
+- recently published package
+- recently published installed version
+- low release history
+- package reactivated after a long dormant period
+- recent patch activity on an older major version line
+
+These are heuristic review signals, not proof that a package is malicious or compromised.
+
+These signals can appear in the report, JSON output, compare mode, and CI fail rules when supported by the current scan and baseline data.
+
 ### CI policy enforcement (`--fail-on`)
 
 ```
@@ -192,8 +277,44 @@ Supported rules:
 | `unknown-licence` | Fail if at least one dependency has neither declared nor inferred licence data |
 | `supply-chain-source` | Fail if lockfile source signals detect git/local/tarball sources, missing integrity, or unexpected registry hosts |
 
+The following rules are evaluated only by `compare <previous dependency-radar.json>` and use the previous JSON report as the baseline:
+
+| Rule | Description |
+|---|---|
+| `new-supply-chain-signal` | Fail if the current scan has a lockfile supply-chain signal that was not present in the baseline for the same package, or was not present at all when the signal is not package-specific |
+| `new-install-script` | Fail if a dependency now exposes install lifecycle hooks and the baseline did not show install hooks for that package |
+| `new-native-binding` | Fail if a dependency now exposes native build or binary surface and the baseline did not show native surface for that package |
+| `new-bin` | Fail if a dependency now declares a package `bin` executable and the baseline did not show a `bin` for that package |
+| `new-direct-dependency` | Fail if a package is now direct and was not direct in the baseline |
+| `new-child-process` | Fail if a dependency newly shows local child process API usage |
+| `new-network-access` | Fail if a dependency newly shows local network access references |
+| `new-env-access` | Fail if a dependency newly shows local environment variable access |
+| `new-home-access` | Fail if a dependency newly shows local home directory access |
+| `new-ssh-usage` | Fail if a dependency newly shows SSH-related path, command, or environment references |
+| `new-obfuscation-signal` | Fail if a dependency newly shows an obfuscation-like local code shape |
+| `new-bundled-dependencies` | Fail if a dependency newly declares bundled dependencies |
+| `new-shrinkwrap` | Fail if a dependency newly contains an embedded `npm-shrinkwrap.json` |
+| `new-recent-package` | Fail if a dependency newly shows the `recent-package` registry review signal |
+| `new-recent-version` | Fail if a dependency newly shows the `recent-version` registry review signal |
+| `new-low-release-history` | Fail if a dependency newly shows the `low-release-history` registry review signal |
+| `new-reactivated-package` | Fail if a dependency newly shows the `reactivated-package` registry review signal |
+| `new-old-major-patch` | Fail if a dependency newly shows the `old-major-new-patch` registry review signal |
+
 When rules are violated, Dependency Radar prints `✖ Policy violations detected:` and exits `1`. Unknown rules also exit `1` with a clear error message.
 
+For compare-mode delta rules, the failure output includes the package and the specific change, for example:
+
+```text
+- 1 new install script surface
+  - lodash@4.17.21 introduced install hooks: postinstall
+- 1 new execution signal: child-process
+  - foo@1.2.3 introduced execution signal: child-process
+- 1 new registry risk signal: recent-version
+  - bar@4.5.6 introduced registry risk signal: recent-version
+```
+
+To use this in CI, commit a known-good JSON report, regenerate it intentionally when reviewed dependency changes are accepted, and compare pull requests against that file.
+
 ### Example: open the generated report using the system default:
 
 ```bash
@@ -337,6 +458,7 @@ When you run `npx dependency-radar` (or `dependency-radar scan`), the CLI execut
    - Source import graph (static import/require parsing in `src/` or project root)
    - Lockfile supply-chain source signals
    - Optional npm registry signature/provenance verification (`--audit-signatures`)
+   - Targeted npm registry metadata for up to 10 packages that already show local or supply-chain review signals (skipped with `--offline`)
 6. Normalize outputs into one internal shape and merge workspace package results.
    - PNPM lock/CLI dependency trees are filtered to installed-only packages (non-installed optional/platform variants are dropped)
 7. Resolve and crawl installed package directories in `node_modules` to collect local metadata:
@@ -346,10 +468,10 @@ When you run `npx dependency-radar` (or `dependency-radar scan`), the CLI execut
    - License declaration + `LICENSE` file inference/validation
    - Advisory summaries and severity/risk rollups
    - Root-cause/origin and runtime-impact heuristics
-   - Install-time execution signals
+   - Install-time execution signals, local execution capability signals, packaging signals, and targeted registry metadata review signals
    - Local package metadata (`description`, links, deprecation, TypeScript type availability, installed file count, CLI `bin` presence)
 9. Build normalized findings from the aggregated dependency model:
-   - Vulnerabilities, license review items, install-time execution surface, native bindings, deprecated packages, target Node compatibility findings, lockfile source signals, and npm signature/provenance failures
+   - Vulnerabilities, license review items, install-time execution surface, local execution capability signals, packaging signals, targeted registry metadata review signals, native bindings, deprecated packages, target Node compatibility findings, lockfile source signals, and npm signature/provenance failures
 10. Write final output as one of:
    - `dependency-radar.html` (self-contained report), or
    - `dependency-radar.json` (raw aggregated model)
@@ -358,13 +480,13 @@ When you run `npx dependency-radar` (or `dependency-radar scan`), the CLI execut
    - SPDX SBOM (`--format spdx` / `--sbom spdx`)
 11. Remove `.dependency-radar/` unless `--keep-temp` is set.
 
-The scan is local-first: package metadata is read from `node_modules`; only audit/outdated commands require registry access.
+The scan runs on your machine: package metadata is read from `node_modules`. Audit/outdated commands, optional signature checks, and targeted registry enrichment require registry access and are skipped or disabled with `--offline`.
 
 The `explain` command reuses this same pipeline with report writing disabled, then filters the in-memory model down to a single package for terminal output.
 
 ### `node_modules` crawling details
 
-- Dependency metadata is read from installed package directories, not from registry documents.
+- Dependency metadata is read from installed package directories. Targeted registry enrichment reads only npm metadata for a capped set of already suspicious packages during online scans.
 - Package resolution is workspace-aware and PNPM-aware, including `.pnpm` virtual store paths.
 - License discovery checks common file variants such as `LICENSE`, `LICENCE`, `COPYING`, and `NOTICE` (with or without extensions like `.md`).
 
@@ -700,8 +822,8 @@ For full details and any future changes, see `src/types.ts`.
 ## Notes
 
 - The target project must have dependencies installed (run `npm install`, `pnpm install`, or `yarn install` first).
-- The scan runs on your machine and does not upload your code or dependencies anywhere.
-- `npm audit`, `pnpm audit`, `yarn npm audit` and their corresponding `outdated` commands perform registry lookups; use `--offline` for offline-only scans.
+- The scan runs on your machine and does not upload your source code or generated reports during a normal CLI scan.
+- `npm audit`, `pnpm audit`, `yarn npm audit`, corresponding `outdated` commands, optional npm signature checks, and targeted registry enrichment perform registry lookups; use `--offline` for offline-only scans.
 - On some Yarn Berry setups, `yarn outdated` is not available; the scan continues and marks outdated data as unavailable.
 - A temporary `.dependency-radar/` folder is created during the scan to store intermediate tool output.
 - Use `--keep-temp` to retain this folder for debugging; otherwise it is deleted automatically.
@@ -713,6 +835,10 @@ For full details and any future changes, see `src/types.ts`.
 
 ## Development
 
+### Testing expectations
+
+New or changed user-facing functionality should include automated tests where practical. For larger dependency graph, package manager, report output, or supply-chain signal changes, run the relevant fixture tests as well as the unit tests.
+
 ### Setup
 
 ```bash
@@ -771,3 +897,38 @@ This opens the report UI in your browser with sample data covering all dependenc
 - `report-ui/sample-data.json` – Sample data for development
 - `report-ui/types.ts` – Client-side TypeScript types
 - `src/report-assets.ts` – Auto-generated file with bundled CSS/JS (do not edit directly)
+
+### Contributing
+
+Bug reports and pull requests are welcome via GitHub.
+
+For bug reports, please include:
+
+- the Dependency Radar version
+- your package manager and version
+- your Node.js version
+- the command you ran
+- what you expected to happen
+- what actually happened
+- any relevant error output
+
+Please remove secrets, private package names, or sensitive project details before sharing logs or reports.
+
+For pull requests, small focused changes are easiest to review. Before opening a PR, please make sure the project builds and the relevant tests pass:
+
+```bash
+npm run build
+npm run test:unit
+```
+
+For larger dependency graph, package manager, report output, or supply-chain signal changes, also run the relevant fixture tests where practical.
+
+Please do not report suspected security vulnerabilities in public issues. See [SECURITY.md](./SECURITY.md) for private reporting guidance.
+
+
+
+## Releases and changelog
+
+Release notes are published through [GitHub Releases](https://github.com/JosephMaynard/dependency-radar/releases), which act as the project changelog.
+
+Each release summarises notable changes, fixes, and compatibility notes where relevant.