DepGraph scores npm packages and their transitive dependencies against behavioral signals, publish age, version velocity, and registry deprecation. It tells you exactly why something looks suspicious. Signature-based scanners miss what DepGraph catches by design.

Run it before every install. Use the JSON output in CI. Built for agents.

Get Started

Install globally:

npm install -g @synsoftworks/depgraph-cli

Run without installing:

npx @synsoftworks/depgraph-cli scan axios

Quick Start

Show help:

depgraph --help

Scan a package with plain terminal output:

depgraph scan axios --no-tui --depth 2

Scan the same package with JSON output:

depgraph scan axios --json --depth 2

Scan a local project from an explicit lockfile path:

depgraph scan --package-lock ./package-lock.json
depgraph scan --pnpm-lock ./pnpm-lock.yaml

Detect a supported lockfile in the current project root:

depgraph scan --project . --json

--project will resolve either package-lock.json or pnpm-lock.yaml when present.

Append a review outcome to a stored scan finding:

depgraph review <record_id> --target package_finding:[email protected] --outcome benign --notes "reviewed by analyst"

Check how many of your scanned packages have full metadata enrichment versus degraded coverage:

depgraph eval

Plain-Text Example

Plain-text output from a real scan:

Scan: [email protected]
Mode: registry_package
Target: plain-crypto-js
Overall risk: critical (1.00)
Total scanned: 1
Suspicious packages: 1

Changed edges in current tree view:
- none

Findings:
- [email protected] [critical 1.00] via [email protected]
  target: package_finding:[email protected]
  explanation: package was published 1 day(s) ago; package has only 1 published version(s); package is an npm security placeholder or tombstone for a previously malicious package

Current tree view:
- [email protected] [critical 1.00]

Summary Example

Compact summary output for CI logs or quick review:

[email protected]

review (0.64)

- packages requiring review: 1
- findings with security-related signals: 1
- packages that appear safe: 13

JSON Example

Use --json when DepGraph is being called from CI, scripts, or agents. JSON mode bypasses terminal rendering and emits a deterministic result shape.

depgraph scan axios --json --depth 2

Trimmed example:

{
  "record_id": "2026-04-02T00:00:00.000Z:[email protected]:depth=2",
  "scan_mode": "registry_package",
  "scan_target": "axios",
  "baseline_record_id": null,
  "requested_depth": 2,
  "threshold": 0.4,
  "root": {
    "name": "axios",
    "version": "1.14.0",
    "risk_score": 0.32,
    "risk_level": "safe"
  },
  "findings": [],
  "total_scanned": 9,
  "suspicious_count": 0,
  "overall_risk_score": 0.32,
  "overall_risk_level": "safe"
}

This mode is intended for automation, CI checks, and agent tooling that needs machine-readable output instead of terminal formatting.

CI Integration

Use --summary for compact, deterministic scan results in CI logs.

- name: Scan dependencies
  run: depgraph scan --project . --summary

Exit code is 1 when any findings exist, 0 when all packages appear safe.

Current Scan Modes

• registry_package scans start from an npm package spec and resolve structure from registry metadata
• package_lock scans start from a local package-lock.json and read dependency structure from the lockfile itself
• pnpm_lock scans start from a local pnpm-lock.yaml importer view and normalize it into the same dependency graph shape used by other scan modes

package_lock scanning currently supports package-lock.json with lockfileVersion >= 2 and a packages map only.

pnpm_lock scanning currently supports pnpm-lock.yaml importer-backed project scans with a packages snapshot map. Local workspace:, link:, and file: dependency references are reported as unsupported rather than projected dishonestly.

Local Data Model

DepGraph now persists repo-local history under .depgraph/:

This history powers baseline diffing and the depgraph eval dataset readiness report.

• scans.jsonl for immutable scan records
• review-events.jsonl for append-only review annotations

Status

Core scanning is stable. Registry package scanning, lockfile scanning (npm and pnpm), baseline diffing, and CI integration all work reliably today. Some dependency types — private packages, workspace references, local file links — degrade gracefully rather than failing.

Pre-v1. Interfaces may change before 1.0.

Roadmap

v0.2 — Shipped

• [x] npm package scanning with traversal
• [x] rich Ink terminal UI and plain text mode
• [x] deterministic JSON output for agents and CI
• [x] local scan persistence and append-only review history
• [x] projected dependency edge delta against prior baseline
• [x] package-lock.json project scanning
• [x] pnpm-lock.yaml project scanning
• [x] graceful degradation for private and non-registry dependencies
• [x] finding-level review targets and source-precedence label integrity
• [x] local dataset evaluation
• [x] depgraph.sh

v0.3 — In Progress

• [ ] yarn lockfile support
• [ ] explain command
• [ ] CI/CD GitHub Action

Later

• [ ] sensitive import analysis
• [ ] maintainer history signals
• [ ] organization-level scan aggregation

Contributing

See CONTRIBUTING.md for local setup, workflow, and contribution guidelines.

Security

If you believe you found a security issue in DepGraph itself, see SECURITY.md.

License

DepGraph is available under the MIT License.