dep-inspect

Find the dependencies you actually need to review, not a wall of noise.

dep-inspect is a local-first CLI for reviewing npm packages before adoption and enforcing dependency risk policy in CI. It surfaces high-confidence, actionable risks first so you can spend time on the packages that matter instead of triaging hundreds of low-value alerts.

Why Use It

• more practical dependency triage than npm audit alone
• high-confidence defaults tuned for human review
• useful both before install and in CI
• no SaaS account required
• JSON output for automation
• SQLite cache for fast repeat scans

Why Not npm audit?

npm audit is useful data, but the default experience is often too noisy for fast decisions.

dep-inspect is opinionated:

• prioritize actionable signal over completeness
• default to high-confidence checks
• keep heuristic-heavy checks behind --strict
• optimize for real-world developer workflows

Quick Start

Run without installing:

npx dep-inspect scan

Inspect a package before adding it:

dep-inspect inspect eslint

Enable stricter checks when you want more context:

dep-inspect inspect eslint --strict

Scan the current project:

dep-inspect scan

Show the full package-by-package breakdown:

dep-inspect scan --details

Use it in CI:

dep-inspect ci --github

Generate a starter policy file:

dep-inspect init

What inspect Checks

dep-inspect inspect <package> analyzes one package version before you install it.

By default it checks:

• known vulnerabilities from OSV
• maintainer deprecation notices
• license policy violations, including missing licenses
• install-time scripts: preinstall, install, postinstall, and prepare
• maintenance risk based on publish age

inspect includes GitHub repository data by default when the package metadata points to a GitHub repo. That means it can also use repository health data such as archived status and contributor counts in the output for a single package review.

What scan Checks

dep-inspect scan analyzes the dependencies in the current project by reading package.json and the lockfile, then evaluating each unique package in the resolved dependency graph.

By default it checks the same policy-backed package signals as inspect across your dependency tree:

• vulnerabilities
• deprecated packages
• license violations
• install-time scripts
• unmaintained packages based on age since last publish

By default, scan does not fetch GitHub data. Use --github when you want repository-backed maintenance context such as archived repositories.

Strict Mode

If you want more context, --strict enables additional lower-confidence or more heuristic-heavy signals:

• single maintainer warnings
• unusual or non-standard license risk warnings
• missing repository metadata notes
• version lag or prerelease notes
• dependency footprint notes for large or deeply nested trees

Those checks are useful in some teams, but they are intentionally not part of the standard path.

Severity Model

dep-inspect uses three severity tiers instead of a single opaque score:

• critical: immediate action recommended; blocks CI by default
• warning: review recommended; may block CI if your policy says so
• info: context for human decision-making; does not block CI by default

Default policy severity is:

• critical: high/critical vulnerabilities, deprecated packages, license violations
• warning: install scripts, unmaintained packages
• off by default unless enabled with --strict or policy overrides: single maintainer, license risk, dependency footprint, missing repository, version risk

Vulnerability findings are severity-aware:

• high/critical advisories stay critical
• medium advisories become warning
• low advisories become warning for direct dependencies and info for transitives
• transitive issues are still scanned, but they are capped at warning by default and shown under the direct dependency that introduces them
• by default, only direct dependency findings can block because non-direct findings are capped at warning

Why a Package Gets Flagged

Flags are evidence-based and category-specific rather than score-based.

• Vulnerability: OSV returned one or more advisories for the exact package version; the reported severity is derived from the highest advisory severity and whether the package is direct or transitive
• Deprecated: the npm package metadata includes a maintainer deprecation notice
• License violation: the package license is denied, missing, or not allowed by policy
• Install scripts: the package runs install lifecycle scripts that execute during dependency installation
• Unmaintained: the latest publish date is older than the configured threshold, or the GitHub repo is archived when GitHub data is enabled
• Single maintainer: the package has one or zero npm maintainers
• License risk: the license is uncommon or non-standard rather than explicitly denied
• Missing repository: the package does not provide a usable repository link
• Version risk: the inspected version is a prerelease or at least two major versions behind latest
• Dependency footprint: the resolved tree is unusually large, deep, or duplicated

Installation

If the package is published to npm:

npx dep-inspect inspect lodash

Or install globally:

npm install -g dep-inspect
dep-inspect --help

From source:

pnpm install
pnpm build
node dist/index.js --help

Commands

Command	Purpose
inspect <package>	Quick package review before installation
scan	Concise project dependency scan
ci	Policy gate for pipelines
report	Detailed dependency report
deep-inspect <package>	Registry-resolved transitive inspection for one package
init	Create .dep-inspect.json
cache stats	Show cache statistics
cache clear	Clear cached data

Useful flags:

• --details: show the full breakdown instead of the concise default summary
• --strict: enable heuristic-heavy checks and extra context
• --github: include GitHub repository health data where supported
• --json: emit machine-readable output

Output Philosophy

The default output is optimized for fast triage:

• one verdict
• a short list of packages to review first
• enough context to decide whether to keep investigating

If you want every category and package detail, use --details.

Example Policy File

Run dep-inspect init to generate a starter config:

{
  "severity": {
    "vulnerability": "critical",
    "deprecated": "critical",
    "license-violation": "critical",
    "install-scripts": "warning",
    "unmaintained": { "level": "warning", "thresholdDays": 730 },
    "single-maintainer": "off",
    "license-risk": "off",
    "dependency-footprint": "off",
    "missing-repository": "off",
    "version-risk": "off"
  },
  "licenses": {
    "unknown": "warning"
  },
  "ci": {
    "failOn": "critical"
  },
  "waivers": []
}

CI Usage

dep-inspect ci exits with:

• 0 when policy passes
• 1 when policy fails
• 2 when the tool cannot complete

Example GitHub Actions step:

- name: Audit dependencies
  run: pnpm exec dep-inspect ci --github
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md before reporting vulnerabilities.

License

MIT. See LICENSE.