suphm — Supply Chain Health Metrics

A command-line tool that scores OSS package health, maintainer sustainability, and supply-chain risk across npm, PyPI, Cargo, Maven, Go, and direct GitHub repositories. Pulls metrics from registry APIs, GitHub, and the source repository itself; outputs structured JSON for downstream consumption.

Features

• Multi-Ecosystem Support: Analyze packages from npm, PyPI, Cargo, Maven, and Go
• Health Scoring: Comprehensive package health assessment (0-100 score)
• Burnout Detection: Identify maintainer sustainability risks
• CHAOSS Metrics: Bus factor, pony factor, elephant factor analysis
• Company Affiliation Enrichment: Automatic contributor company detection via GitHub API (when token provided)
• Tarball Inspection: License detection (via osslili), copyright extraction, binary-file detection by extension and magic bytes, hardened against zip-slip and decompression bombs
• GitHub Integration: Stars, forks, issues, PRs, and release metrics
• Flexible Output: JSON reports for integration with other tools

How It Works

suphm runs a comprehensive 7-step analysis pipeline:

1. Discovery - Fetch package metadata from deps.dev, ecosyste.ms, and package registries
2. Clone - Download the source repository for deep analysis
3. Git Metrics - Calculate CHAOSS metrics (bus factor, contributors, companies)
4. GitHub API - Gather community health indicators (stars, forks, issues, PRs)
5. Tarball Scan - Analyze package contents for licenses, copyrights, and binary files
6. Health Score - Compute overall package health across multiple dimensions
7. Burnout Score - Assess maintainer sustainability and stress indicators

Installation

Requirements

• Python 3.10+
• The git command-line binary on PATH (used to clone source repositories for git-history analysis)
• Optional: a GitHub personal access token (GITHUB_TOKEN or SUPHM_GITHUB_TOKEN) to lift the unauthenticated 60 req/hr cap to 5 000 req/hr.

From PyPI

pip install suphm

From source

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

Quick Start

# Analyze a package
suphm analyze pkg:npm/express

# Save results to file
suphm analyze pkg:pypi/requests --output report.json

# Analyze different ecosystems
suphm analyze pkg:cargo/serde
suphm analyze pkg:maven/org.opensearch/opensearch
suphm analyze pkg:go/github.com/hashicorp/terraform

# Discovery only (no deep analysis)
suphm discover pkg:npm/lodash

Usage

CLI Commands

# Full package analysis
suphm analyze pkg:npm/express --output analysis.json

# Metadata discovery only
suphm discover pkg:pypi/requests

# View cache information
suphm cache info

# Clear cache
suphm cache clear --all

# Check version
suphm --version

Supported Package URL (PURL) Formats

# npm packages
pkg:npm/express
pkg:npm/@babel/core@7.24.0

# PyPI packages
pkg:pypi/requests
pkg:pypi/requests@2.31.0

# Cargo (Rust) packages
pkg:cargo/serde
pkg:cargo/tokio@1.32.0

# Maven packages
pkg:maven/org.opensearch/opensearch
pkg:maven/org.apache.commons/commons-lang3@3.12.0

# Go modules
pkg:go/github.com/hashicorp/terraform

# GitHub repositories
pkg:github/expressjs/express

Output Format

The tool outputs JSON reports with the following metrics:

Health Score (0-100)

• Commit activity and release frequency
• Contributor diversity (bus factor, pony factor)
• Issue/PR responsiveness
• License compliance
• Branch protection and security

Burnout Score (0-100)

• Issue backlog pressure
• Response time gaps
• Triage overhead
• Workload concentration
• Activity decline trends

Additional Metrics

• CHAOSS metrics (bus/pony/elephant factors)
• GitHub community health (stars, forks, issues, PRs)
• License information
• Binary file detection (by extension and magic bytes)

Using as a Python Library

suphm can also be used as a library in your Python applications:

from pathlib import Path
from suphm.metrics.git import GitMetricsAnalyzer

# Analyze a git repository
analyzer = GitMetricsAnalyzer(Path("/path/to/repo"))
result = analyzer.analyze()

# Access metrics for different time windows
metrics_90d = result.time_windows["90_days"]
print(f"Commits (90d): {metrics_90d.total_commits}")
print(f"Bus factor: {metrics_90d.bus_factor}")
print(f"License: {result.license_changes.current_license}")

Configuration

GitHub Token (Recommended)

Set up a GitHub token for higher rate limits:

export GITHUB_TOKEN=ghp_your_token_here

Cache Configuration

# Via environment variable
export SUPHM_CACHE_DIR=/custom/path

# Or in ~/.suphm/config.yaml
cache:
  directory: /custom/path

Documentation

• Getting Started
• Command Reference
• Python Library API
• Health Score Calculation
• API Integrations
• GitHub Token Setup
• SerpAPI Setup

Support

• GitHub Issues — bug reports and feature requests

License

GNU Affero General Public License v3.0. See the LICENSE file in the source repository for the full text.

Part of the SEMCL.ONE ecosystem for comprehensive OSS compliance and code analysis.