CCDA-CLI - Supply Chain Security Metrics

A command-line tool for analyzing software packages across ecosystems (npm, PyPI, Cargo, Maven, Go). Provides health scores, maintainer burnout risk, and comprehensive supply chain security metrics to help developers make informed decisions about their dependencies.

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)
• Supply Chain Security: License compliance, binary detection, suspicious file scanning
• GitHub Integration: Stars, forks, issues, PRs, and release metrics
• Flexible Output: JSON reports for integration with other tools

How It Works

ccda-cli 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, binaries, and suspicious files
6. Health Score - Compute overall package health across multiple dimensions
7. Burnout Score - Assess maintainer sustainability and stress indicators

Installation

pip install ccda-cli

For development:

git clone https://github.com/SemClone/ccda-cli.git
cd ccda-cli
pip install -e .

Quick Start

# Analyze a package
ccda-cli analyze pkg:npm/express

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

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

# Discovery only (no deep analysis)
ccda-cli discover pkg:npm/lodash

Usage

CLI Commands

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

# Metadata discovery only
ccda-cli discover pkg:pypi/requests

# View cache information
ccda-cli cache info

# Clear cache
ccda-cli cache clear --all

# Check version
ccda-cli --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 and suspicious file detection

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

ccda-cli can also be used as a library in your Python applications:

from pathlib import Path
from ccda_cli.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["90d"]
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 CCDA_CACHE_DIR=/custom/path

# Or in ~/.ccda/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.