github-license-scanner 0.1.0__py3-none-any.whl

gls/models.py

@@ -0,0 +1,148 @@
+"""
+Shared data models for the GitHub License Scanner.
+
+All modules import dataclasses from here to avoid circular dependencies
+and keep a single source of truth for scan-related structures.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+
+@dataclass
+class Dependency:
+    """A single package declared in a dependency manifest file."""
+
+    name: str
+    version_spec: str | None
+    ecosystem: str  # npm | pypi | cargo | go | rubygems | composer | maven | gradle
+    source_file: str  # path inside the repository, e.g. "package.json"
+    is_dev: bool = False  # True for dev/test/build-only dependencies
+
+
+@dataclass
+class PackageLicense:
+    """License information resolved for one dependency."""
+
+    name: str
+    ecosystem: str
+    license_id: str | None  # SPDX-like id or raw registry string
+    risk: str  # permissive | weak_copyleft | strong_copyleft | unknown
+    source_file: str
+    license_url: str | None = None
+    version_spec: str | None = None
+    is_dev: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ReplacementSuggestion:
+    """Suggested permissive alternative for a problematic package."""
+
+    package: str
+    ecosystem: str
+    license_id: str | None
+    alternatives: list[str]
+    note: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class DeployAdvice:
+    """One deploy platform recommendation with rationale."""
+
+    platform: str
+    score: int  # higher is better match
+    reasons: list[str]
+    docs_url: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ScanResult:
+    """Full analysis result for a single GitHub repository."""
+
+    owner: str
+    repo: str
+    url: str
+    repo_license: str | None
+    packages: list[PackageLicense] = field(default_factory=list)
+    # license_id -> list of packages using that license
+    grouped: dict[str, list[PackageLicense]] = field(default_factory=dict)
+    can_sell_closed: bool = True
+    forces_open_source: bool = False
+    has_weak_copyleft: bool = False
+    has_unknown_licenses: bool = False
+    verdict_summary: str = ""
+    copyright_notice: str = ""
+    replacements: list[ReplacementSuggestion] = field(default_factory=list)
+    deploy_advice: list[DeployAdvice] = field(default_factory=list)
+    scanned_at: str = ""
+    errors: list[str] = field(default_factory=list)
+    # False when GitHub/network failed before a reliable verdict
+    scan_complete: bool = True
+    # Extra metadata used by deploy advisor / UI
+    primary_language: str | None = None
+    description: str | None = None
+    topics: list[str] = field(default_factory=list)
+    dependency_files: list[str] = field(default_factory=list)
+    has_dockerfile: bool = False
+    # Risk score 0 (safest) … 100 (highest copyleft / uncertainty pressure)
+    risk_score: int = 0
+    risk_score_label: str = "n/a"
+    # Counts after prod/dev split (filled by analyzer)
+    prod_package_count: int = 0
+    dev_package_count: int = 0
+    # Strong copyleft only in dev deps (warning, does not force open by default)
+    strong_copyleft_dev_only: bool = False
+    # True when AGPL/network-copyleft signals were detected (extra SaaS caution)
+    has_network_copyleft: bool = False
+
+    def to_history_entry(self) -> dict[str, Any]:
+        """Compact dict suitable for history.json persistence."""
+        return {
+            "owner": self.owner,
+            "repo": self.repo,
+            "url": self.url,
+            "repo_license": self.repo_license,
+            "scanned_at": self.scanned_at,
+            "can_sell_closed": self.can_sell_closed,
+            "forces_open_source": self.forces_open_source,
+            "scan_complete": self.scan_complete,
+            "package_count": len(self.packages),
+            "risk_score": self.risk_score,
+            "has_network_copyleft": self.has_network_copyleft,
+            # Truncate free text for privacy / storage hygiene
+            "verdict_summary": (self.verdict_summary or "")[:500],
+        }
+
+    def risk_counts(self, *, prod_only: bool = False) -> dict[str, int]:
+        """Count packages by risk category."""
+        counts = {
+            "permissive": 0,
+            "weak_copyleft": 0,
+            "strong_copyleft": 0,
+            "unknown": 0,
+        }
+        for pkg in self.packages:
+            if prod_only and pkg.is_dev:
+                continue
+            key = pkg.risk if pkg.risk in counts else "unknown"
+            counts[key] += 1
+        return counts
+
+    @property
+    def prod_packages(self) -> list[PackageLicense]:
+        return [p for p in self.packages if not p.is_dev]
+
+    @property
+    def dev_packages(self) -> list[PackageLicense]:
+        return [p for p in self.packages if p.is_dev]

gls/rate_limit.py

@@ -0,0 +1,64 @@
+"""
+Simple in-process sliding-window rate limiter.
+
+Used to reduce abuse of the scan pipeline (GitHub API + registries) when the
+web UI is exposed beyond localhost. Not a substitute for reverse-proxy limits
+(nginx, Cloudflare, etc.) in production.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import defaultdict, deque
+
+
+class SlidingWindowRateLimiter:
+    """Thread-safe sliding window counter keyed by client id."""
+
+    def __init__(self, max_calls: int, window_seconds: float) -> None:
+        if max_calls < 1:
+            raise ValueError("max_calls must be >= 1")
+        if window_seconds <= 0:
+            raise ValueError("window_seconds must be > 0")
+        self.max_calls = max_calls
+        self.window_seconds = float(window_seconds)
+        self._events: dict[str, deque[float]] = defaultdict(deque)
+        self._lock = threading.Lock()
+
+    def _prune(self, key: str, now: float) -> None:
+        q = self._events[key]
+        cutoff = now - self.window_seconds
+        while q and q[0] < cutoff:
+            q.popleft()
+        if not q and key in self._events:
+            # Keep empty deques small by deleting idle keys occasionally
+            pass
+
+    def allow(self, key: str) -> bool:
+        """Return True and record a call if under the limit."""
+        now = time.monotonic()
+        with self._lock:
+            self._prune(key, now)
+            q = self._events[key]
+            if len(q) >= self.max_calls:
+                return False
+            q.append(now)
+            return True
+
+    def remaining(self, key: str) -> int:
+        """How many calls remain in the current window for this key."""
+        now = time.monotonic()
+        with self._lock:
+            self._prune(key, now)
+            return max(0, self.max_calls - len(self._events[key]))
+
+    def retry_after_seconds(self, key: str) -> float:
+        """Seconds until the oldest event exits the window (0 if allowed)."""
+        now = time.monotonic()
+        with self._lock:
+            self._prune(key, now)
+            q = self._events[key]
+            if len(q) < self.max_calls:
+                return 0.0
+            return max(0.0, (q[0] + self.window_seconds) - now)

gls/report.py

@@ -0,0 +1,150 @@
+"""
+Markdown report export for scan results.
+
+Used by the web UI (download / copy) and the CLI (`scan --markdown`).
+"""
+
+from __future__ import annotations
+
+from .models import ScanResult
+
+
+def render_markdown_report(result: ScanResult) -> str:
+    """Build a full Markdown compliance-style report from a ScanResult."""
+    lines: list[str] = []
+    title = f"{result.owner}/{result.repo}" if result.owner else result.url
+    lines.append(f"# License scan: {title}")
+    lines.append("")
+    lines.append(f"- **URL:** {result.url or 'n/a'}")
+    lines.append(f"- **Scanned at:** {result.scanned_at or 'n/a'}")
+    lines.append(f"- **Repo license:** {result.repo_license or 'Unknown'}")
+    lines.append(f"- **Primary language:** {result.primary_language or 'n/a'}")
+    lines.append(
+        f"- **Risk score:** {result.risk_score}/100 ({result.risk_score_label})"
+    )
+    lines.append(
+        f"- **Scan complete:** {'Yes' if result.scan_complete else 'No (incomplete)'}"
+    )
+    lines.append(
+        f"- **Can sell closed-source (heuristic):** "
+        f"{'Possibly (with caveats)' if result.can_sell_closed and result.scan_complete else 'No / undetermined'}"
+    )
+    lines.append(
+        f"- **Forces open source (heuristic):** {'Yes' if result.forces_open_source else 'No'}"
+    )
+    if result.has_network_copyleft:
+        lines.append(
+            "- **Network/SaaS copyleft signal (AGPL/SSPL):** Yes — review carefully"
+        )
+    if result.strong_copyleft_dev_only:
+        lines.append(
+            "- **Note:** Strong copyleft found only in dev/test dependencies"
+        )
+    lines.append(
+        f"- **Packages:** {len(result.packages)} "
+        f"(prod={result.prod_package_count}, dev={result.dev_package_count})"
+    )
+    lines.append("")
+
+    lines.append("## Verdict")
+    lines.append("")
+    lines.append(result.verdict_summary or "_No verdict._")
+    lines.append("")
+
+    counts = result.risk_counts()
+    prod_counts = result.risk_counts(prod_only=True)
+    lines.append("## Risk summary")
+    lines.append("")
+    lines.append("| Category | All | Production only |")
+    lines.append("|----------|-----|-----------------|")
+    for key in ("permissive", "weak_copyleft", "strong_copyleft", "unknown"):
+        lines.append(f"| {key} | {counts[key]} | {prod_counts[key]} |")
+    lines.append("")
+
+    if result.errors:
+        lines.append("## Notes / errors")
+        lines.append("")
+        for err in result.errors:
+            lines.append(f"- {err}")
+        lines.append("")
+
+    if result.deploy_advice:
+        lines.append("## Deploy recommendations")
+        lines.append("")
+        for adv in result.deploy_advice:
+            lines.append(f"### {adv.platform} (score {adv.score})")
+            for reason in adv.reasons:
+                lines.append(f"- {reason}")
+            lines.append(f"- Docs: {adv.docs_url}")
+            lines.append("")
+
+    if result.replacements:
+        lines.append("## Replacement suggestions")
+        lines.append("")
+        for rep in result.replacements:
+            lines.append(
+                f"- **{rep.package}** (`{rep.ecosystem}`, {rep.license_id or '?'})"
+            )
+            for alt in rep.alternatives:
+                lines.append(f"  - → {alt}")
+            if rep.note:
+                lines.append(f"  - _{rep.note}_")
+        lines.append("")
+
+    lines.append("## Packages by license")
+    lines.append("")
+    if not result.packages:
+        lines.append("_No packages resolved._")
+        lines.append("")
+    else:
+        for lic, pkgs in result.grouped.items():
+            lines.append(f"### {lic} ({len(pkgs)})")
+            lines.append("")
+            lines.append("| Package | Ecosystem | Scope | Risk | Source |")
+            lines.append("|---------|-----------|-------|------|--------|")
+            for p in sorted(pkgs, key=lambda x: (x.is_dev, x.name.lower())):
+                scope = "dev" if p.is_dev else "prod"
+                lines.append(
+                    f"| {p.name} | {p.ecosystem} | {scope} | {p.risk} | "
+                    f"`{p.source_file}` |"
+                )
+            lines.append("")
+
+    if result.dependency_files:
+        lines.append("## Dependency files analyzed")
+        lines.append("")
+        for path in result.dependency_files:
+            lines.append(f"- `{path}`")
+        lines.append("")
+
+    lines.append("## Copyright notice")
+    lines.append("")
+    lines.append("```")
+    lines.append((result.copyright_notice or "").rstrip())
+    lines.append("```")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    lines.append("## Legal disclaimer")
+    lines.append("")
+    lines.append(
+        "This report is generated by **automated heuristics** for developer "
+        "guidance only. It is **not legal advice**, not a license-compatibility "
+        "opinion, and not a warranty of non-infringement or fitness for a "
+        "particular purpose. Dual-licensing, linking models, SaaS/network use "
+        "(AGPL/SSPL), additional permissions, CLA/DCO overlays, and contractual "
+        "terms can change obligations. **Consult a qualified attorney** before "
+        "commercial closed-source distribution or reliance on any verdict."
+    )
+    lines.append("")
+    lines.append(
+        "Copyright notice templates in this report are **not claims of ownership**. "
+        "GitHub account names are not proof of copyright ownership."
+    )
+    lines.append("")
+    lines.append(
+        "_Generated by GitHub License Scanner. See docs/LEGAL_DISCLAIMER.md, "
+        "docs/PRIVACY.md, and docs/TERMS.md._"
+    )
+    lines.append("")
+    return "\n".join(lines)

gls/sbom_export.py

@@ -0,0 +1,312 @@
+"""
+SBOM export for scan results.
+
+Formats:
+  - CycloneDX 1.5 JSON (application + library components)
+  - SPDX 2.3 JSON document (packages + relationships)
+
+These documents are generated from *declared* dependencies and registry
+license metadata. They are not a full binary SBOM from a build graph.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import quote
+
+from .models import PackageLicense, ScanResult
+from .spdx_engine import expression_to_spdx_ids
+
+
+TOOL_NAME = "github-license-scanner"
+TOOL_VERSION = "1.2.0"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _purl(pkg: PackageLicense) -> str | None:
+    """Best-effort package URL (purl)."""
+    name = pkg.name
+    ver = (pkg.version_spec or "").lstrip("=^~><! ")
+    # Strip complex version ranges for purl version field
+    if any(c in ver for c in " ,|"):
+        ver = ""
+    eco = pkg.ecosystem
+    if eco == "npm":
+        # scoped: @scope/name
+        if name.startswith("@") and "/" in name:
+            scope, n = name[1:].split("/", 1)
+            base = f"pkg:npm/{quote(scope)}/{quote(n)}"
+        else:
+            base = f"pkg:npm/{quote(name)}"
+        return f"{base}@{quote(ver)}" if ver else base
+    if eco == "pypi":
+        base = f"pkg:pypi/{quote(name)}"
+        return f"{base}@{quote(ver)}" if ver else base
+    if eco == "cargo":
+        base = f"pkg:cargo/{quote(name)}"
+        return f"{base}@{quote(ver)}" if ver else base
+    if eco == "go":
+        base = f"pkg:golang/{name}"  # path may contain /
+        return f"{base}@{quote(ver)}" if ver else base
+    if eco == "rubygems":
+        base = f"pkg:gem/{quote(name)}"
+        return f"{base}@{quote(ver)}" if ver else base
+    if eco == "composer":
+        base = f"pkg:composer/{name}"
+        return f"{base}@{quote(ver)}" if ver else base
+    if eco in {"maven", "gradle"} and ":" in name:
+        group, artifact = name.split(":", 1)
+        base = f"pkg:maven/{quote(group)}/{quote(artifact)}"
+        return f"{base}@{quote(ver)}" if ver else base
+    return None
+
+
+def _bom_ref(pkg: PackageLicense, idx: int) -> str:
+    purl = _purl(pkg)
+    if purl:
+        return purl
+    return f"{pkg.ecosystem}:{pkg.name}#{idx}"
+
+
+def render_cyclonedx_json(result: ScanResult) -> str:
+    """Serialize a ScanResult as CycloneDX 1.5 JSON."""
+    serial = f"urn:uuid:{uuid.uuid4()}"
+    components: list[dict[str, Any]] = []
+    for i, pkg in enumerate(result.packages):
+        licenses = []
+        if pkg.license_id:
+            ids = expression_to_spdx_ids(pkg.license_id)
+            if ids:
+                for lid in ids:
+                    licenses.append({"license": {"id": lid}})
+            else:
+                licenses.append({"license": {"name": pkg.license_id}})
+
+        comp: dict[str, Any] = {
+            "type": "library",
+            "bom-ref": _bom_ref(pkg, i),
+            "name": pkg.name,
+            "purl": _purl(pkg),
+            "scope": "optional" if pkg.is_dev else "required",
+            "properties": [
+                {"name": "gls:ecosystem", "value": pkg.ecosystem},
+                {"name": "gls:risk", "value": pkg.risk},
+                {"name": "gls:source_file", "value": pkg.source_file},
+            ],
+        }
+        if pkg.version_spec:
+            # CycloneDX version is a single version; store range as property
+            if re_is_single_version(pkg.version_spec):
+                comp["version"] = pkg.version_spec.lstrip("=v")
+            else:
+                comp["properties"].append(
+                    {"name": "gls:version_spec", "value": pkg.version_spec}
+                )
+        if licenses:
+            comp["licenses"] = licenses
+        if pkg.license_url:
+            comp["externalReferences"] = [
+                {"type": "website", "url": pkg.license_url}
+            ]
+        # Drop null purl
+        if not comp.get("purl"):
+            comp.pop("purl", None)
+        components.append(comp)
+
+    metadata_licenses = []
+    if result.repo_license:
+        for lid in expression_to_spdx_ids(result.repo_license) or [result.repo_license]:
+            metadata_licenses.append({"license": {"id": lid if _looks_spdx(lid) else None, "name": lid}})
+            if metadata_licenses[-1]["license"].get("id") is None:
+                metadata_licenses[-1] = {"license": {"name": lid}}
+
+    doc: dict[str, Any] = {
+        "bomFormat": "CycloneDX",
+        "specVersion": "1.5",
+        "serialNumber": serial,
+        "version": 1,
+        "metadata": {
+            "timestamp": _now_iso(),
+            "tools": {
+                "components": [
+                    {
+                        "type": "application",
+                        "name": TOOL_NAME,
+                        "version": TOOL_VERSION,
+                    }
+                ]
+            },
+            "component": {
+                "type": "application",
+                "name": f"{result.owner}/{result.repo}" if result.owner else (result.url or "unknown"),
+                "bom-ref": f"app:{result.owner}/{result.repo}" if result.owner else "app:unknown",
+                "purl": (
+                    f"pkg:github/{result.owner}/{result.repo}"
+                    if result.owner and result.repo
+                    else None
+                ),
+                "licenses": metadata_licenses or None,
+                "externalReferences": (
+                    [{"type": "vcs", "url": result.url}] if result.url else []
+                ),
+                "properties": [
+                    {"name": "gls:risk_score", "value": str(result.risk_score)},
+                    {
+                        "name": "gls:forces_open_source",
+                        "value": str(result.forces_open_source).lower(),
+                    },
+                    {
+                        "name": "gls:scan_complete",
+                        "value": str(result.scan_complete).lower(),
+                    },
+                    {
+                        "name": "gls:disclaimer",
+                        "value": "Automated heuristic SBOM — not legal advice",
+                    },
+                ],
+            },
+        },
+        "components": components,
+    }
+    # Clean nulls in component
+    meta_comp = doc["metadata"]["component"]
+    if not meta_comp.get("purl"):
+        meta_comp.pop("purl", None)
+    if not meta_comp.get("licenses"):
+        meta_comp.pop("licenses", None)
+
+    return json.dumps(doc, indent=2, ensure_ascii=False)
+
+
+def re_is_single_version(spec: str) -> bool:
+    s = (spec or "").strip().lstrip("=")
+    return bool(re.fullmatch(r"v?\d+(?:\.\d+)*(?:[-+][A-Za-z0-9.]+)?", s))
+
+
+def _looks_spdx(lid: str) -> bool:
+    return bool(re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9.+_-]*", lid or ""))
+
+
+def render_spdx_json(result: ScanResult) -> str:
+    """Serialize a ScanResult as SPDX 2.3 JSON."""
+    doc_name = (
+        f"SPDXRef-DOCUMENT-{result.owner}-{result.repo}"
+        if result.owner
+        else "SPDXRef-DOCUMENT"
+    )
+    created = _now_iso()
+    packages: list[dict[str, Any]] = []
+
+    # Root package = repository
+    root_spdx_id = "SPDXRef-Package-Root"
+    root_lic = result.repo_license or "NOASSERTION"
+    packages.append(
+        {
+            "SPDXID": root_spdx_id,
+            "name": f"{result.owner}/{result.repo}" if result.owner else "root",
+            "downloadLocation": result.url or "NOASSERTION",
+            "filesAnalyzed": False,
+            "licenseConcluded": root_lic if result.repo_license else "NOASSERTION",
+            "licenseDeclared": root_lic if result.repo_license else "NOASSERTION",
+            "copyrightText": "NOASSERTION",
+            "externalRefs": (
+                [
+                    {
+                        "referenceCategory": "PACKAGE-MANAGER",
+                        "referenceType": "purl",
+                        "referenceLocator": f"pkg:github/{result.owner}/{result.repo}",
+                    }
+                ]
+                if result.owner
+                else []
+            ),
+            "comment": (
+                f"risk_score={result.risk_score}; forces_open={result.forces_open_source}; "
+                "generated by github-license-scanner (heuristic, not legal advice)"
+            ),
+        }
+    )
+
+    relationships = [
+        {
+            "spdxElementId": "SPDXRef-DOCUMENT",
+            "relationshipType": "DESCRIBES",
+            "relatedSpdxElement": root_spdx_id,
+        }
+    ]
+
+    for i, pkg in enumerate(result.packages):
+        spdx_id = f"SPDXRef-Package-{i}"
+        lic = pkg.license_id or "NOASSERTION"
+        purl = _purl(pkg)
+        ext = []
+        if purl:
+            ext.append(
+                {
+                    "referenceCategory": "PACKAGE-MANAGER",
+                    "referenceType": "purl",
+                    "referenceLocator": purl,
+                }
+            )
+        packages.append(
+            {
+                "SPDXID": spdx_id,
+                "name": pkg.name,
+                "versionInfo": pkg.version_spec or "NOASSERTION",
+                "downloadLocation": pkg.license_url or "NOASSERTION",
+                "filesAnalyzed": False,
+                "licenseConcluded": lic,
+                "licenseDeclared": lic,
+                "copyrightText": "NOASSERTION",
+                "externalRefs": ext,
+                "comment": (
+                    f"ecosystem={pkg.ecosystem}; risk={pkg.risk}; "
+                    f"scope={'dev' if pkg.is_dev else 'prod'}; source={pkg.source_file}"
+                ),
+            }
+        )
+        relationships.append(
+            {
+                "spdxElementId": root_spdx_id,
+                "relationshipType": "DEPENDS_ON",
+                "relatedSpdxElement": spdx_id,
+            }
+        )
+
+    doc: dict[str, Any] = {
+        "spdxVersion": "SPDX-2.3",
+        "dataLicense": "CC0-1.0",
+        "SPDXID": "SPDXRef-DOCUMENT",
+        "name": doc_name,
+        "documentNamespace": f"https://github.com/NezbiT/github-license-scanner/spdx/{uuid.uuid4()}",
+        "creationInfo": {
+            "created": created,
+            "creators": [f"Tool: {TOOL_NAME}-{TOOL_VERSION}", "Organization: local"],
+            "licenseListVersion": "3.22",
+            "comment": "Automated heuristic export — not legal advice",
+        },
+        "packages": packages,
+        "relationships": relationships,
+    }
+    return json.dumps(doc, indent=2, ensure_ascii=False)
+
+
+def render_sbom(result: ScanResult, fmt: str = "cyclonedx") -> str:
+    """
+    Render SBOM text for the given format.
+
+    fmt: cyclonedx | spdx | cdx | spdx-json
+    """
+    key = (fmt or "cyclonedx").lower().strip()
+    if key in {"cyclonedx", "cdx", "cyclonedx-json"}:
+        return render_cyclonedx_json(result)
+    if key in {"spdx", "spdx-json", "spdx23"}:
+        return render_spdx_json(result)
+    raise ValueError(f"Unknown SBOM format: {fmt!r} (use cyclonedx or spdx)")