Skip to content

SPEC.md

Latest commit

 

History

History
115 lines (78 loc) · 3.62 KB

SPEC.md

File metadata and controls

115 lines (78 loc) · 3.62 KB

license-patrol — Project Specification

25. license-patrol

Scan dependencies across any language for license compliance --- free, fast, and CI-ready.

Language Python 3.10+

Distribution PyPI (pip install license-patrol) + GitHub Action

Build Time 7--10 days

License MIT

Category Compliance / Security / Language-Agnostic

Problem

CISA's 2025 SBOM minimum elements now require license as a mandatory field. PCI DSS 4.0 controls 6.3.2 and 11.3.1.1 mandate production SBOM management. Commercial tools (FOSSA, Snyk) exist but cost thousands per year. No good free, language-agnostic CLI scans dependencies across multiple ecosystems, checks against a configurable policy, and produces actionable reports for compliance.

Solution

A free CLI tool that discovers dependencies across Python (pip/poetry/uv), JavaScript (npm/yarn/pnpm), Go (go.mod), Rust (cargo), PHP (composer), and C# (NuGet), resolves their licenses, and evaluates them against a configurable allow/deny/review policy. Produces reports in multiple formats for compliance documentation.

Core Features

  • Multi-ecosystem scanning: Parses lockfiles and manifest files for pip, npm, composer, cargo, go, and NuGet. Auto-detects project type.

  • License resolution: Resolves license identifiers from package metadata (PyPI, npmjs, crates.io, etc.) and falls back to LICENSE file content analysis using a SPDX classifier.

  • Policy engine: Configurable .license-patrol.toml with allow, deny, and review lists. Supports SPDX expressions and license families (e.g., allow: [MIT, Apache-2.0, BSD-*]).

  • Report generation: Outputs to terminal table, JSON, CSV, SPDX SBOM (2.3), and CycloneDX BOM formats.

  • CI integration: Exit code 1 if any dependency violates the policy. GitHub Action available with PR comment support.

  • Override system: Manual license overrides for packages with missing or incorrect metadata, stored in config.

Technical Architecture

Python CLI with a plugin architecture for ecosystem support. Each ecosystem plugin implements discover_dependencies() and resolve_license() methods. License classification uses a lightweight SPDX license text classifier (TF-IDF similarity against SPDX license templates). Policy evaluation supports SPDX license expressions with AND/OR logic. SBOM generation uses the spdx-tools and cyclonedx-python-lib libraries.

CLI / API Surface

license-patrol scan # auto-detect and scan

license-patrol scan --ecosystems py,npm # specific ecosystems

license-patrol scan --policy strict # built-in strict policy

license-patrol report --format spdx # SPDX SBOM output

license-patrol report --format cyclonedx # CycloneDX BOM output

license-patrol init # generate config template

Key Dependencies

  • httpx

  • rich

  • typer

  • spdx-tools (SBOM generation)

  • cyclonedx-python-lib

  • tomli

Scope Boundaries

In scope: Multi-ecosystem dependency discovery, license resolution, policy evaluation, SPDX and CycloneDX SBOM generation, CI integration.

Out of scope: Vulnerability scanning (use Safety/Snyk). License text generation. Legal advice. Enterprise features (audit trails, approval workflows).

Success Criteria

  • Correctly resolves licenses for 95%+ of dependencies in a multi-language monorepo

  • SPDX output validates against the SPDX spec

  • Free alternative to FOSSA/Snyk for license compliance

  • Useful for CISA SBOM requirements and PCI DSS 4.0 audits