DepGraph CLI

DepGraph is a supply chain security tool that lives in your terminal, scans an npm package plus its current registry-resolved dependency tree projection for attack signals, and tells you why a package looks suspicious before you ship it.

Run it before every install. Use the JSON output in CI. Agent friendly 🤖

Get Started

Install globally:

npm install -g @synsoftworks/depgraph-cli

Run without installing:

npx -p @synsoftworks/depgraph-cli depgraph --help

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

Detect a supported lockfile in the current project root:

depgraph scan --project . --json

Append a review outcome to a stored scan finding:

depgraph review <record_id> --target package_finding:axios@1.14.0 --outcome benign --notes "reviewed by analyst"

Inspect local dataset coverage:

depgraph eval

Plain-Text Example

Plain-text output from a real scan:

Scan: plain-crypto-js@0.0.1-security.0
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:
- plain-crypto-js@0.0.1-security.0 [critical 1.00] via plain-crypto-js@0.0.1-security.0
  target: package_finding:plain-crypto-js@0.0.1-security.0
  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:
- plain-crypto-js@0.0.1-security.0 [critical 1.00]

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:axios@1.14.0: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.

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

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

Local Data Model

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

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

Status

DepGraph is pre-v1 and under active development. Core scanning works. Some dependency types degrade gracefully rather than fully enriching. See the roadmap for what's coming.

Roadmap

Shipped

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

Coming Soon

• pnpm and yarn lockfile support
• advisory database integration
• sensitive import analysis
• explain command
• CI/CD GitHub Action
• depgraph.sh

Future

• pip / cargo / gem ecosystem support
• maintainer history signals
• organization-level scan aggregation

Philosophy

DepGraph follows a simple rule: data first, presentation second.

Each command produces structured scan data first, then renders it for either a human terminal session or an agent-oriented JSON consumer. The CLI is designed to work well for both without mixing business logic into presentation.

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.