depaudit

Unified dependency audit: license compliance, security vulnerabilities, and maintainer health in one CLI.

---

Why This Exists

Managing npm dependency risks requires juggling multiple tools:

Risk	Current Tool	Limitation
Security vulnerabilities	npm audit	No license checking
License compliance	license-checker	No security or health data
Maintainer health	Manual checking	No automation
Unified report	Snyk/FOSSA (SaaS)	Paid, requires account

depaudit unifies all three into a single, free CLI with zero accounts required. One command. Three dimensions of risk. Actionable output.

---

Quick Start

# Install globally
npm install -g depaudit

# Run full audit
depaudit

# Or use npx
npx depaudit

Features

License Compliance (depaudit license)

Analyzes every dependency's SPDX license for compatibility with your project:

• Parses compound SPDX expressions (MIT OR Apache-2.0, GPL-3.0 AND MIT)
• Detects incompatible transitive licenses (GPL dep in MIT project)
• Supports policy-based allowed/denied license lists
• Handles aliases (BSD -> BSD-2-Clause, Apache 2.0 -> Apache-2.0)
• Flags unknown and missing licenses

depaudit license

  License Compliance Report
  Compliant: 142 | Non-compliant: 2 | Unknown: 3

  ! gpl-package@1.2.0 - GPL-3.0-only (direct)
  ! copyleft-dep@0.5.0 - AGPL-3.0-only (transitive)

Security Scanning (depaudit security)

Scans for known CVEs and security advisories:

• Parses npm audit v1 and v2 JSON formats
• Severity classification: critical, high, moderate, low, info
• Shows available fix versions
• Supports advisory ignore lists with justification requirements

depaudit security

  Security Vulnerability Report
  Critical: 0 | High: 1 | Moderate: 3 | Low: 5

  [high] lodash - Prototype Pollution (fix: 4.17.21)
  [moderate] minimist - Prototype Pollution (fix: >=0.2.1)

Health Scoring (depaudit health)

Evaluates maintainer health for every dependency:

• Freshness (30%): Days since last publish
• Popularity (25%): Weekly download count tiers
• Maintainers (20%): Bus factor risk (single maintainer warning)
• Repository (15%): Has accessible source code
• Deprecation (10%): Marked as deprecated

depaudit health

  Package Health Report
  Healthy: 138 | At Risk: 7 | Abandoned: 2 | Unknown: 0

  [5/100] deprecated-pkg@1.0.0 (abandoned)
  [25/100] old-lib@0.3.0 (at-risk)

Unified Audit (depaudit audit)

Runs all three analyzers and produces a weighted overall score:

• Security: 45% weight (most critical)
• License: 30% weight
• Health: 25% weight

depaudit audit

  depaudit - Dependency Audit Report
  ──────────────────────────────────────────────────

  Overall Score: 87/100 (healthy)
  Dependencies: 147 total (12 direct, 135 transitive)
  Duration: 2340ms

  License Compliance
  Compliant:     142
  Non-compliant: 2
  Unknown:       3

  Security Vulnerabilities
  1 high | 3 moderate | 5 low

  Package Health
  Healthy:   138
  At risk:   7
  Abandoned: 2

  Policy Violations (4)
    [license/high] gpl-package@1.2.0
      License "GPL-3.0-only" is incompatible with project license "MIT"
    [security/high] lodash@4.17.20
      high: Prototype Pollution (GHSA-1234)

Output Formats

# Terminal output (default)
depaudit audit --format text

# JSON for programmatic consumption
depaudit audit --format json

# SARIF for GitHub Code Scanning / CI integration
depaudit audit --format sarif

CI Integration

# Fail CI if high+ severity issues found
depaudit audit --fail-on high

# Quick summary for CI logs
depaudit audit --quiet --fail-on high

Example GitHub Actions workflow:

- name: Dependency Audit
  run: npx depaudit audit --fail-on high --format sarif > depaudit.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: depaudit.sarif

Policy Configuration

Create .depauditrc.json with default settings:

depaudit init

Example policy:

{
  "allowedLicenses": ["MIT", "ISC", "BSD-2-Clause", "BSD-3-Clause", "Apache-2.0"],
  "deniedLicenses": ["GPL-3.0-only", "AGPL-3.0-only"],
  "minHealthScore": 30,
  "failOn": "high",
  "ignorePackages": [],
  "ignoreAdvisories": [],
  "requireJustification": true,
  "cacheTtl": 3600000
}

Programmatic API

import { audit, licenseAudit, securityAudit, healthAudit } from 'depaudit';

// Full audit
const result = await audit({
  path: './my-project',
  policy: { allowedLicenses: ['MIT', 'Apache-2.0', 'ISC'] },
  failOn: 'high',
});

console.log(result.score);        // 87
console.log(result.violations);   // PolicyViolation[]
console.log(result.license);      // LicenseReport
console.log(result.security);     // SecurityReport
console.log(result.health);       // HealthReport

// Individual audits
const licenses = await licenseAudit({ path: './my-project' });
const security = await securityAudit({ path: './my-project' });
const health = await healthAudit({ path: './my-project' });

CLI Reference

USAGE:
  depaudit [command] [options]

COMMANDS:
  audit       Run full audit (license + security + health) [default]
  license     Run license compliance check only
  security    Run security vulnerability scan only
  health      Run package health analysis only
  init        Create default .depauditrc.json policy file

OPTIONS:
  --format <text|json|sarif>   Output format (default: text)
  --fail-on <severity>         Exit 1 if severity >= threshold
  --depth <n>                  Limit dependency tree depth
  --cache-ttl <seconds>        Cache TTL for registry data (default: 3600)
  --policy <path>              Path to policy file
  --offline                    Skip registry/npm-audit network calls
  --dev                        Include devDependencies
  --quiet                      Only output summary line
  --path <dir>                 Project directory (default: cwd)
  -h, --help                   Show help
  -v, --version                Show version

Architecture

depaudit/
  src/
    cli.ts              # CLI entry point
    index.ts            # Programmatic API
    analyzers/
      license.ts        # SPDX license analysis
      security.ts       # CVE/advisory scanning
      health.ts         # Package health scoring
    core/
      resolver.ts       # Dependency tree resolution
      policy.ts         # Policy engine
      scorer.ts         # Unified risk scoring
      report.ts         # Multi-format report generation
    utils/
      spdx.ts           # SPDX expression parser
      registry.ts       # npm registry API client
      cache.ts          # In-memory TTL cache
    types.ts            # TypeScript type definitions

Scoring System

Overall Score (0-100)

Component	Weight	What it measures
Security	45%	CVE count and severity
License	30%	SPDX compliance ratio
Health	25%	Maintainer activity and popularity

Risk Levels

Score	Level	Meaning
80-100	Healthy	No significant risks
60-79	Low	Minor issues, monitor
40-59	Moderate	Action recommended
20-39	High	Immediate action needed
0-19	Critical	Urgent remediation required

Health Score Factors

Factor	Weight	Tiers
Freshness	30	<30d: full, <90d: 90%, <180d: 70%, <stale: 40%, >stale: 10%
Popularity	25	1M+: full, 100K+: 90%, 10K+: 70%, 1K+: 50%, 100+: 30%
Maintainers	20	3+: full, 2: 70%, 1: 40%, 0: 0%
Repository	15	exists: full, missing: 0%
Not deprecated	10	not deprecated: full, deprecated: instant 5/100

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (npm test)
4. Commit your changes
5. Push to the branch
6. Open a Pull Request