← Back

package-health-analyzer: The dependency report your compliance team needs before closing due diligence

9 min read
TypeScriptNPMSecurityComplianceSBOMDue Diligence

You're in the middle of due diligence and the compliance team asks: what licenses do the project's 200 dependencies have? Is there any GPL that would force us to release the code? Do any have known vulnerabilities? This CLI tool analyzes all dependencies in under 5 seconds and generates reports in 7 formats: JSON, CSV, Markdown, SPDX 2.3 SBOM, SARIF for GitHub, and NOTICE.txt for Apache compliance.

You’re in a funding round. The investment fund is doing technical due diligence and their compliance team sends a questionnaire. Question 47: “List all third-party software dependencies, their licenses, and confirm that none have copyleft terms that would force releasing source code”. You open package.json. You have 47 direct dependencies. You run npm ls and discover there are actually 847 packages counting transitives.

Now you need to find out each one’s license. Some are MIT, others Apache 2.0, others ISC. But somewhere in the tree there’s a package with GPL-3.0 that nobody remembers installing. If your product is SaaS, maybe it’s not a problem. If it’s distributed software, it could block the deal.

The compliance team also wants to know if any dependency has known vulnerabilities. And if any is abandoned, without updates for years. And if any is deprecated. And they need all this documented in a format they can attach to the due diligence report.

Doing this manually takes days. For each package you have to go to npm, look up the license, verify the GitHub repository, check for CVEs, review when the last update was. With 847 packages, it’s not feasible.

The solution: automated analysis in 5 seconds

package-health-analyzer is a CLI tool that analyzes all dependencies of a Node.js project and generates complete reports in seconds. No configuration needed. Install, run, and you have your report.

npm install -g package-health-analyzer
cd your-project
pha scan

In under 5 seconds you have a complete analysis: licenses for all packages, known vulnerabilities, age, maintenance status, popularity, and a health score from 0 to 100 for each dependency.

The 7 output formats

The tool generates reports in whatever format you need:

1. Terminal table (default)

pha scan

Shows a color-coded table indicating each dependency’s status. Green for healthy packages, yellow for warnings, red for critical issues. Useful for quick review during development.

2. Structured JSON

pha scan --format json --output report.json

Complete data for each dependency in JSON format. Includes all metadata: name, version, license, repository, last update, vulnerabilities, health score, and more. Ideal for programmatic processing or integration with other tools.

{
  "package": "express",
  "version": "5.2.1",
  "license": {
    "spdx": "MIT",
    "type": "permissive",
    "blueOakRating": "Gold",
    "commercialUse": true
  },
  "health": {
    "score": 95,
    "age": { "score": 100, "lastUpdate": "3 days ago" },
    "deprecation": { "score": 100, "deprecated": false },
    "repository": { "score": 80, "stars": 65000, "issues": 120 }
  },
  "vulnerabilities": []
}

3. CSV for Excel

pha scan --format csv --output report.csv

Exports data to CSV that you can open in Excel or Google Sheets. Perfect for compliance teams who prefer working with spreadsheets. They can filter, sort, and generate their own reports.

4. Markdown for documentation

pha scan --format markdown --output DEPENDENCIES.md

Generates a Markdown document with formatted tables. You can include it directly in project documentation or in the GitHub repository. Example output:

# Package Health Report

**Project:** my-project@1.0.0
**Generated:** 2026-01-08
**Total packages:** 47
**Average health:** 94/100
**Risk level:** Medium

| Package | Version | License | Health | Last Update | Issues |
|---------|---------|---------|--------|-------------|--------|
| express | 5.2.1 | MIT | 95/100 | 3 days ago | None |
| lodash | 4.17.21 | MIT | 88/100 | 1 year ago | None |
| moment | 2.30.1 | MIT | 72/100 | 2 years ago | ⚠️ Maintenance |

5. SBOM in SPDX 2.3 format

pha scan --format sbom --output sbom.json

Generates a Software Bill of Materials (SBOM) in SPDX 2.3 format, the industry standard. This format is required by regulations like the U.S. cybersecurity executive order and is aligned with CISA SBOM 2025.

The SBOM includes:

{
  "spdxVersion": "SPDX-2.3",
  "SPDXID": "SPDXRef-DOCUMENT",
  "name": "my-project-sbom",
  "packages": [
    {
      "SPDXID": "SPDXRef-Package-express-5.2.1",
      "name": "express",
      "versionInfo": "5.2.1",
      "licenseConcluded": "MIT",
      "downloadLocation": "https://registry.npmjs.org/express/-/express-5.2.1.tgz"
    }
  ],
  "relationships": [
    {
      "spdxElementId": "SPDXRef-DOCUMENT",
      "relationshipType": "DESCRIBES",
      "relatedSpdxElement": "SPDXRef-Package-my-project-1.0.0"
    }
  ]
}

6. SARIF for GitHub Code Scanning

pha scan --format sarif --output results.sarif

Generates a SARIF 2.1.0 file compatible with GitHub Code Scanning. You can upload it to GitHub and see dependency issues directly in the repository’s Security tab, alongside other security analyses.

7. NOTICE.txt for Apache compliance

pha generate-notice --output NOTICE.txt

Generates a NOTICE.txt file following the Apache Software Foundation format. This file is required when distributing software that includes Apache 2.0 licensed components. It lists all dependencies with their copyright attributions and patent notices.

NOTICE

This product includes software developed by third parties.

===========================================================
express - Fast, unopinionated, minimalist web framework
Version: 5.2.1
License: MIT
Copyright (c) 2009-2025 TJ Holowaychuk <tj@vision-media.ca>
Copyright (c) 2013-2025 Roman Shtylman <shtylman+expressjs@gmail.com>
Copyright (c) 2014-2025 Douglas Christopher Wilson <doug@somethingdoug.com>
===========================================================

[... continues for each dependency ...]

Check a package before installing

Before adding a new dependency, you can verify its health:

pha check express

The output shows detailed package information:

📦 Package: express@5.2.1
📅 Published: 3 days ago
📊 Status: Active

📜 License Analysis
   SPDX: MIT
   Type: permissive
   Blue Oak Rating: Gold
   Commercial Use: ✓ Allowed

🏥 Health Score: 95/100
   ├─ Age: 100/100
   ├─ Deprecation: 100/100
   ├─ License: 100/100
   └─ Repository: 80/100

✅ Result: OK - No issues detected

This lets you make informed decisions before adding dependencies to the project. If the package has a problematic license or is abandoned, you know before installing it.

Configuration by project type

Different project types have different license requirements. A startup selling SaaS can use AGPL without problems. A company distributing on-premise software cannot. An open source project can use GPL. A proprietary commercial project cannot.

The tool includes 8 predefined profiles:

pha init

The interactive wizard asks what type of project you have:

Each profile automatically adjusts which licenses are acceptable, which generate warnings, and which block the analysis.

Problematic license detection

The tool classifies licenses using the SPDX database (221 licenses) and Blue Oak Council ratings:

Permissive licenses (Gold/Silver): MIT, Apache 2.0, BSD, ISC. You can use the code in commercial projects without significant restrictions.

Weak copyleft licenses (Bronze): LGPL, MPL. You can use the code but with certain attribution or modification release obligations.

Strong copyleft licenses (Lead): GPL, AGPL. If you use this code, you may have to release your source code. AGPL additionally applies to software accessed over a network.

Restrictive licenses: SSPL, Commons Clause. Additional restrictions that may prevent commercial use.

For commercial projects, the tool marks in red any dependency with GPL, AGPL, or SSPL, and generates an error exit code for CI/CD integrations:

pha scan --fail-on=warning
echo $?  # 2 if critical issues found

Vulnerability analysis

With a GitHub token, the tool queries the GitHub Advisory Database to detect known vulnerabilities:

export GITHUB_TOKEN=your_token
pha scan

The report includes CVEs associated with each vulnerable package:

{
  "package": "lodash",
  "version": "4.17.15",
  "vulnerabilities": [
    {
      "id": "CVE-2021-23337",
      "severity": "high",
      "title": "Command Injection in lodash",
      "fixedIn": "4.17.21"
    }
  ]
}

The token is stored encrypted with AES-256-GCM and cleared from memory after each use. It never appears in logs or command output.

Health metrics

Each dependency receives a score from 0 to 100 based on seven dimensions:

Age: Time since last update. A package updated a week ago scores 100. One without updates for 3 years scores low.

Deprecation: Whether the package is marked as deprecated on npm. Deprecated = 0 points in this dimension.

License: License type according to project profile. MIT in commercial project = 100. GPL in commercial project = 0.

Vulnerabilities: Known CVEs. No vulnerabilities = 100. Critical vulnerability = 0.

Popularity: Weekly downloads on npm. Indicates adoption and likelihood of continued maintenance.

Repository: GitHub stars, open vs closed issues, commit frequency. Indicates upstream project health.

Update frequency: Release cadence. Regular releases indicate active maintenance.

The final score is a configurable weighted average. By default, vulnerabilities and license carry more weight than popularity.

CI/CD integration

You can integrate the analysis into your CI pipeline to block merges that introduce problematic dependencies:

# GitHub Actions
- name: Analyze dependencies
  run: |
    npm install -g package-health-analyzer
    pha scan --fail-on=warning --format json --output health-report.json

- name: Upload SBOM
  uses: actions/upload-artifact@v3
  with:
    name: sbom
    path: health-report.json

The exit code indicates the result:

Performance

Complete analysis of a typical project (50-100 dependencies) takes under 5 seconds:

  1. Discovery and metadata (1-2 seconds): Reads package.json and package-lock.json, fetches npm metadata.
  2. Multidimensional analysis (1-2 seconds): Evaluates licenses, searches for vulnerabilities, calculates scores.
  3. Dependency tree (1 second): Builds the dependency graph, detects duplicates and cycles.
  4. Scoring and recommendations (<1 second): Calculates final scores and generates recommendations.
  5. Output formatting (<1 second): Generates the report in the requested format.

Results are cached in memory. Subsequent scans of the same project take under 1 second while data remains fresh.

Real use cases

Investment due diligence

The investment fund’s compliance team needs a dependency inventory with licenses. You generate the SBOM in SPDX format and the report in CSV. They can verify there are no copyleft licenses that would compromise intellectual property.

pha scan --format sbom --output sbom-due-diligence.json
pha scan --format csv --output dependencies-licenses.csv

Security audit

The security team needs to know what known vulnerabilities the dependencies have. You generate the SARIF report and upload it to GitHub Code Scanning.

pha scan --format sarif --output security-audit.sarif
gh api repos/{owner}/{repo}/code-scanning/sarifs -f sarif=@security-audit.sarif

License compliance for distribution

You’re going to distribute software that includes Apache 2.0 dependencies. You need to generate the NOTICE.txt required by the license.

pha generate-notice --output NOTICE.txt

Verification before adding dependencies

Before installing a new package, you verify it doesn’t have license or security issues.

pha check package-name

Continuous monitoring

You integrate the analysis into CI so every PR verifies that new dependencies comply with project policies.

pha scan --project-type commercial --fail-on=warning

Tool security

The tool implements multiple security layers:

Installation and requirements

npm install -g package-health-analyzer

Requirements:

The code is on GitHub

The package is published on NPM as package-health-analyzer. Source code is at github.com/686f6c61/package-health-analyzer.

In the repository you’ll find output examples at examples/express-project-outputs with all formats generated for a real Express project.

The license is MIT. If you find bugs or have suggestions for new metrics or output formats, open an issue on GitHub.