Installation

Requirements: Python 3.11 or later.

From Source

git clone https://github.com/jaredmladner/depscore.git
cd depscore
pip install .

With Dev Dependencies

pip install ".[dev]"

Verify Install

depscore --version
# depscore, version 0.1.0

Configuration

depscore reads configuration from environment variables. Copy .env.example to .env and fill in your credentials.

cp .env.example .env

CLI Reference

depscore scan

The primary command. Parses an SBOM, enriches all dependencies, scores them, and writes a report.

depscore scan [OPTIONS]

Options

Examples

# Basic scan with JSON output
depscore scan --sbom ./sbom.json

# Scan with HTML dashboard
depscore scan --sbom ./sbom.json --html

# Explicit format, custom output directory
depscore scan --sbom ./sbom.json --format cyclonedx --output ./reports --html

# Rules-only mode (free, no Anthropic key needed)
depscore scan --sbom ./sbom.json --no-ai --html

Exit Codes

SBOM Formats

CycloneDX JSON

depscore supports CycloneDX JSON (spec versions 1.4 and later). The file must contain a bomFormat: "CycloneDX" key. Components are parsed from the top-level components array with PURL and external references.

SPDX JSON

depscore supports SPDX JSON 2.3+. Packages are extracted from the packages array. External document references and externalRefs are used to resolve repository URLs and ecosystems.

Auto-Detection

When --format auto (the default), depscore inspects the file content: if it contains CycloneDX or bomFormat it uses the CycloneDX parser; otherwise it falls back to SPDX.

Generating SBOMs with Syft

Syft is the recommended tool for generating SBOMs.

# Install Syft (macOS)
brew install anchore/syft/syft

# Install Syft (Linux/macOS via curl)
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh

# Scan a directory → CycloneDX JSON
syft dir:. -o cyclonedx-json > sbom.json

# Scan a container image → SPDX JSON
syft ubuntu:latest -o spdx-json > sbom.spdx.json

# Then score it
depscore scan --sbom sbom.json --html

Scoring

Dimensions & Weights

Hybrid Scoring (Rules + AI)

depscore blends two scoring layers for each dependency:

• Rules layer (40%) — deterministic math on raw metrics: days since last commit, CVE count, version prefix, release frequency, etc.
• AI layer (60%) — claude-sonnet-4-6 receives all enriched signals and returns a score with written reasoning per dimension.

# Blend formula (per dimension)
final_score = (rules_score × 0.40) + (ai_score × 0.60)

The AI weight is configurable via DEPSCORE_AI_BLEND_WEIGHT. If AI scoring fails or --no-ai is used, depscore automatically falls back to rules-only scoring and flags "ai_available": false in the output.

Grade Thresholds

API Cost Estimates

AI scoring uses claude-sonnet-4-6, billed per token at Anthropic API rates.

Output Formats

JSON Report

Written to <output-dir>/depscore-report.json. Contains the full scoring results for every dependency.

{
  "overall_sbom_score": 74.3,
  "overall_sbom_grade": "C",
  "total_dependencies": 42,
  "grade_distribution": { "A": 8, "B": 12, "C": 14, "D": 6, "F": 2 },
  "dimension_averages": {
    "security_posture": 65.1,
    "maintainability": 70.5,
    "maturity": 81.2,
    "community_health": 77.8
  },
  "scores": [
    {
      "dependency_name": "requests",
      "version": "2.31.0",
      "overall": 88.4,
      "overall_grade": "A",
      "security_posture": {
        "score": 74.0, "confidence": 0.85,
        "reasoning": "One high CVE in last 6 months despite strong security posture..."
      },
      "ai_available": true,
      "scored_at": "2026-04-06T14:00:00Z"
    }
  ],
  "generated_at": "2026-04-06T14:01:23Z",
  "depscore_version": "0.1.0"
}

HTML Dashboard

Generated when --html is passed. Written to <output-dir>/depscore-report.html.

• Self-contained single file — no web server required, works offline
• Overall SBOM score gauge and grade distribution chart
• Per-dimension radar chart showing average scores
• Sortable, filterable dependency table with score bars and grade badges
• Per-dependency drill-down panel with CVE list, OpenSSF Scorecard checks, and Claude AI reasoning per dimension

Docker

Build

docker build -t depscore .

Run — JSON output

docker run --rm \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v /path/to/sbom.json:/sbom/sbom.json:ro \
  -v $(pwd)/report:/output \
  depscore scan --sbom /sbom/sbom.json --output /output

Run — HTML dashboard + rules-only

docker run --rm \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  -v /path/to/sbom.json:/sbom/sbom.json:ro \
  -v $(pwd)/report:/output \
  depscore scan --sbom /sbom/sbom.json --output /output --html --no-ai

Mount your SBOM at /sbom/ (read-only) and collect output from /output/.

Environment Variables

FAQ