Dependency Health Monitor (DHM)

Comprehensive health assessments for Python project dependencies.

Features

• Health Scoring: Weighted composite scores based on security, maintenance, community, and popularity
• Vulnerability Detection: Real-time scanning via OSV database with open vs fixed classification
• Maintenance Analysis: Identifies abandoned, deprecated, or archived packages
• License Evaluation: Categorizes licenses (permissive, copyleft, weak copyleft)
• Manifests & Lockfiles: Reads pyproject.toml, requirements*.txt, poetry.lock, uv.lock, Pipfile.lock
• Installed-Env Scanning: --installed reports on the versions actually installed, not latest-on-PyPI
• Transitive Analysis: --include-transitive covers the full dependency graph (direct vs transitive tagged)
• SBOM Export: Emit a CycloneDX 1.5 SBOM with health annotations (-f cyclonedx)
• Caching: SQLite-based caching reduces API calls and improves performance
• CI/CD Ready: Exit codes for pipeline integration

Installation

pip install dependency-health-monitor

Or install from source:

git clone https://github.com/jeremylaratro/dhm.git
cd dhm
pip install -e ".[dev]"

Quick Start

Command Line

# Scan current project
dhm scan

# Check a single package
dhm check requests

# Find alternatives for a problematic package
dhm alternatives urllib3

# Output as JSON for CI/CD
dhm scan -f json -o report.json

# Fail CI if high+ severity issues found
dhm scan --fail-on high

# Include transitive dependencies (uses a lockfile if present, else the installed env)
dhm scan --include-transitive

# Scan what's actually installed in the current environment
dhm scan --installed

# Emit a CycloneDX SBOM (with health annotations) for supply-chain tooling
dhm scan --include-transitive -f cyclonedx -o sbom.cdx.json

Python Library

import asyncio
from dhm import check, scan

async def main():
    # Check a single package
    report = await check("requests")
    print(f"{report.package.name}: Grade {report.health.grade}")
    print(f"  Security: {report.health.security_score:.0f}")
    print(f"  Open vulnerabilities: {len(report.health.open_vulnerabilities)}")

    # Scan a project directory
    reports = await scan(".")
    for r in reports:
        if r.health.has_open_vulnerabilities:
            print(f"⚠️  {r.package.name} has {len(r.health.open_vulnerabilities)} open vulns")

asyncio.run(main())

Synchronous API (for non-async contexts):

from dhm import check_sync, scan_sync

report = check_sync("flask")
print(f"Flask health: {report.health.grade} ({report.health.overall:.0f}/100)")

reports = scan_sync("/path/to/project")
unhealthy = [r for r in reports if r.health.is_concerning]

Health Score Algorithm

DHM calculates a composite health score using weighted components:

Grade Thresholds:

Vulnerability Classification

DHM distinguishes between open and fixed vulnerabilities:

• Open: Affects your installed version - action required
• Fixed: Was present in older versions but patched in yours - historical only

report = await check("aiohttp", version="3.13.3")

# Only shows vulnerabilities affecting version 3.13.3
for vuln in report.health.open_vulnerabilities:
    print(f"🔴 {vuln.id}: {vuln.title}")
    if vuln.fixed_version:
        print(f"   Fix: Upgrade to {vuln.fixed_version}")

Caching

DHM caches API responses to improve performance and reduce rate limiting:

# View cache statistics
dhm cache --stats

# Clear all cached data
dhm cache --clear

# Remove only expired entries
dhm cache --cleanup

# Invalidate specific data
dhm cache --invalidate 'github:%'

CI/CD Integration

# GitHub Actions example
- name: Check dependency health
  run: |
    pip install dependency-health-monitor
    dhm scan --fail-on high -f json -o dhm-report.json

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

Environment Variables

License

MIT - See LICENSE for details.