suphm 0.3.0

Supply chain health metrics: a CLI for analysing OSS package health, maintainer burnout, and supply-chain risk

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. See docs/github-token-setup.md.

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)

Documentation

• Getting Started - Installation and first steps
• Command Reference - All available commands
• API Integrations - Discovery sources and rate limits
• GitHub Token Setup - Increase rate limits (5000/hr)
• SerpAPI Setup - Optional fallback for discovery

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}")

See the API Reference for complete documentation.

Migration from older versions: See API Migration Guide

Configuration

GitHub Token (Recommended)

Set up a GitHub token for higher rate limits:

export GITHUB_TOKEN=ghp_your_token_here

See GitHub Token Setup for detailed instructions.

Cache Configuration

# Via environment variable
export SUPHM_CACHE_DIR=/custom/path

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

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on:

• Code of conduct
• Development setup
• Submitting pull requests
• Reporting issues

Support

For support and questions:

• GitHub Issues - Bug reports and feature requests
• Documentation - Complete project documentation

License

GNU Affero General Public License v3.0 - see LICENSE file for details.

Authors

See AUTHORS.md for a list of contributors.

---

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