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

gls/cli.py

@@ -0,0 +1,358 @@
+"""
+Command-line interface for the GitHub License Scanner.
+
+Usage examples:
+  gls scan https://github.com/psf/requests
+  gls batch urls.txt
+  gls history
+  gls ui                      # web interface (requires the [ui] extra)
+
+Exit codes for `scan` / `batch`:
+  0 — no strong copyleft force-open signal
+  1 — forces_open_source is True (useful in CI gates)
+  2 — hard failure (bad URL, network, usage error)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from . import __version__
+from .history_store import append_scan, load_history
+from .license_analyzer import analyze_repository
+from .models import ScanResult
+from .report import render_markdown_report
+from .sbom_export import render_sbom
+
+
+def _print_result(result: ScanResult, verbose: bool = True) -> None:
+    """Pretty-print a scan result to stdout."""
+    title = f"{result.owner}/{result.repo}" if result.owner else result.url
+    print("=" * 72)
+    print(f"Repository : {title}")
+    print(f"URL        : {result.url}")
+    print(f"Scanned at : {result.scanned_at}")
+    print(f"Repo license: {result.repo_license or 'Unknown'}")
+    print(f"Language   : {result.primary_language or 'n/a'}")
+    print("-" * 72)
+
+    if result.errors and not result.packages and not result.repo_license:
+        print("ERRORS:")
+        for err in result.errors:
+            print(f"  - {err}")
+        print("=" * 72)
+        return
+
+    if not result.scan_complete:
+        print("Scan complete      : NO (incomplete — do not treat verdict as reliable)")
+    flag = "YES — strong copyleft may force opening source" if result.forces_open_source else "NO"
+    if result.scan_complete and result.can_sell_closed:
+        sell = "POSSIBLY (heuristic; attribution & counsel still required)"
+    else:
+        sell = "NO / UNDETERMINED"
+    print(f"Risk score         : {result.risk_score}/100 ({result.risk_score_label})")
+    print(f"Forces open source : {flag}")
+    print(f"Can sell closed    : {sell}")
+    if result.has_network_copyleft:
+        print("Network copyleft   : YES (AGPL/SSPL-class — SaaS obligations possible)")
+    if result.strong_copyleft_dev_only:
+        print("Dev-only copyleft  : YES (strong copyleft only in dev deps)")
+    print()
+    print("Verdict:")
+    print(f"  {result.verdict_summary}")
+    print()
+
+    counts = result.risk_counts()
+    prod_counts = result.risk_counts(prod_only=True)
+    print(
+        f"Packages analyzed: {len(result.packages)}  "
+        f"(prod={result.prod_package_count}, dev={result.dev_package_count})"
+    )
+    print(
+        f"  all  [permissive={counts['permissive']}, "
+        f"weak_copyleft={counts['weak_copyleft']}, "
+        f"strong_copyleft={counts['strong_copyleft']}, "
+        f"unknown={counts['unknown']}]"
+    )
+    print(
+        f"  prod [permissive={prod_counts['permissive']}, "
+        f"weak_copyleft={prod_counts['weak_copyleft']}, "
+        f"strong_copyleft={prod_counts['strong_copyleft']}, "
+        f"unknown={prod_counts['unknown']}]"
+    )
+
+    if verbose and result.grouped:
+        print()
+        print("Packages by license:")
+        for lic, pkgs in result.grouped.items():
+            risks = {p.risk for p in pkgs}
+            risk_label = ",".join(sorted(risks))
+            print(f"  [{risk_label}] {lic} ({len(pkgs)})")
+            for p in sorted(pkgs, key=lambda x: x.name.lower())[:15]:
+                scope = "dev" if p.is_dev else "prod"
+                print(f"      - {p.name} ({p.ecosystem}/{scope}) from {p.source_file}")
+            if len(pkgs) > 15:
+                print(f"      … and {len(pkgs) - 15} more")
+
+    if result.replacements:
+        print()
+        print("Replacement suggestions (heuristic):")
+        for rep in result.replacements[:20]:
+            print(f"  * {rep.package} [{rep.license_id or '?'}] ({rep.ecosystem})")
+            for alt in rep.alternatives:
+                print(f"      → {alt}")
+
+    if result.deploy_advice:
+        print()
+        print("Deploy recommendations:")
+        for adv in result.deploy_advice:
+            print(f"  • {adv.platform} (score={adv.score})")
+            for reason in adv.reasons[:3]:
+                print(f"      - {reason}")
+            print(f"      docs: {adv.docs_url}")
+
+    if result.copyright_notice:
+        print()
+        print("Copyright notice:")
+        print("-" * 40)
+        print(result.copyright_notice)
+        print("-" * 40)
+
+    if result.errors:
+        print()
+        print("Notes / soft errors:")
+        for err in result.errors:
+            print(f"  - {err}")
+
+    print("=" * 72)
+
+
+async def cmd_scan(
+    url: str,
+    save: bool = True,
+    verbose: bool = True,
+    markdown_path: str | None = None,
+    sbom_path: str | None = None,
+    sbom_format: str = "cyclonedx",
+) -> int:
+    """Scan a single repository URL. Returns process exit code."""
+    print(f"Scanning {url} …")
+    result = await analyze_repository(url)
+    _print_result(result, verbose=verbose)
+
+    if markdown_path:
+        md = render_markdown_report(result)
+        out = Path(markdown_path)
+        out.write_text(md, encoding="utf-8")
+        print(f"Markdown report written to {out}")
+
+    if sbom_path:
+        try:
+            doc = render_sbom(result, sbom_format)
+            out = Path(sbom_path)
+            out.write_text(doc, encoding="utf-8")
+            print(f"SBOM ({sbom_format}) written to {out}")
+        except ValueError as exc:
+            print(f"SBOM export failed: {exc}", file=sys.stderr)
+            return 2
+
+    if save and result.owner and result.scan_complete:
+        append_scan(result)
+        print("Saved to history.")
+
+    if result.errors and not result.owner:
+        return 2
+    if not result.scan_complete:
+        return 2
+    if result.errors and not result.packages and result.repo_license is None:
+        if any(
+            any(k in e.lower() for k in ("not found", "rate limit", "forbidden", "exceeded"))
+            for e in result.errors
+        ):
+            return 2
+    return 1 if result.forces_open_source else 0
+
+
+async def cmd_batch(file_path: str, save: bool = True) -> int:
+    """Scan multiple URLs listed in a text file (one per line)."""
+    path = Path(file_path)
+    if not path.exists():
+        print(f"File not found: {file_path}", file=sys.stderr)
+        return 2
+
+    urls = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            urls.append(line)
+
+    if not urls:
+        print("No URLs found in file.", file=sys.stderr)
+        return 2
+
+    exit_code = 0
+    for i, url in enumerate(urls, 1):
+        print(f"\n[{i}/{len(urls)}] ", end="")
+        code = await cmd_scan(url, save=save, verbose=True)
+        if code == 2:
+            exit_code = 2
+        elif code == 1 and exit_code != 2:
+            exit_code = 1
+    return exit_code
+
+
+def cmd_history() -> int:
+    """Print saved scan history."""
+    entries = load_history()
+    if not entries:
+        print("No history yet. Run a scan first.")
+        return 0
+    print(f"History ({len(entries)} entries):\n")
+    for e in entries:
+        sell = "closed-OK" if e.get("can_sell_closed") else "OPEN-FORCE"
+        print(
+            f"  {e.get('scanned_at', '?'):<22}  "
+            f"{e.get('owner', '?')}/{e.get('repo', '?'):<30}  "
+            f"lic={e.get('repo_license') or '?':<12}  "
+            f"pkgs={e.get('package_count', 0):<4}  "
+            f"{sell}"
+        )
+    return 0
+
+
+def cmd_ui(host: str | None, port: int | None) -> int:
+    """Launch the web interface. NiceGUI is an optional extra, so import late."""
+    try:
+        from .webui import run
+    except ImportError:
+        print(
+            "The web interface is not installed.\n"
+            "Install it with: pipx install 'github-license-scanner[ui]'",
+            file=sys.stderr,
+        )
+        return 2
+    run(host=host, port=port)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="gls",
+        description="GitHub License Scanner — analyze repo & dependency licenses.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan", help="Scan a single GitHub repository URL")
+    p_scan.add_argument("url", help="GitHub repository URL or owner/repo")
+    p_scan.add_argument("--no-save", action="store_true", help="Do not write history")
+    p_scan.add_argument(
+        "--markdown",
+        metavar="PATH",
+        help="Write a Markdown report to PATH (e.g. report.md)",
+    )
+    p_scan.add_argument(
+        "--sbom",
+        metavar="PATH",
+        help="Write an SBOM JSON file to PATH (CycloneDX or SPDX)",
+    )
+    p_scan.add_argument(
+        "--sbom-format",
+        choices=("cyclonedx", "spdx"),
+        default="cyclonedx",
+        help="SBOM format when using --sbom (default: cyclonedx)",
+    )
+
+    p_batch = sub.add_parser("batch", help="Scan URLs from a text file")
+    p_batch.add_argument("file", help="Path to text file with one URL per line")
+    p_batch.add_argument("--no-save", action="store_true", help="Do not write history")
+
+    sub.add_parser("history", help="Show previous scan history")
+
+    p_ui = sub.add_parser("ui", help="Launch the web interface (needs the [ui] extra)")
+    p_ui.add_argument("--host", default=None, help="Bind address (default: GLS_HOST)")
+    p_ui.add_argument("--port", type=int, default=None, help="Port (default: GLS_PORT)")
+
+    p_user = sub.add_parser("user-add", help="Add a web UI user (multi-user auth)")
+    p_user.add_argument("username", help="Username (letters, digits, _ . -)")
+    sub.add_parser("user-list", help="List web UI users")
+
+    return parser
+
+
+def _force_utf8_output() -> None:
+    """
+    Windows consoles and redirected pipes default to a legacy codepage (cp1252)
+    that cannot encode the arrows and dashes used in reports, which crashed the
+    scan halfway through with UnicodeEncodeError. Degrade instead of dying.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError):  # detached or already-closed stream
+            pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entrypoint."""
+    _force_utf8_output()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "scan":
+        return asyncio.run(
+            cmd_scan(
+                args.url,
+                save=not args.no_save,
+                markdown_path=args.markdown,
+                sbom_path=args.sbom,
+                sbom_format=args.sbom_format,
+            )
+        )
+    if args.command == "batch":
+        return asyncio.run(cmd_batch(args.file, save=not args.no_save))
+    if args.command == "history":
+        return cmd_history()
+    if args.command == "ui":
+        return cmd_ui(args.host, args.port)
+    if args.command == "user-add":
+        from .auth import add_user
+
+        import getpass
+
+        pw = getpass.getpass("Password: ")
+        pw2 = getpass.getpass("Confirm: ")
+        if pw != pw2:
+            print("Passwords do not match", file=sys.stderr)
+            return 2
+        try:
+            add_user(args.username, pw)
+        except ValueError as exc:
+            print(exc, file=sys.stderr)
+            return 2
+        print(f"User {args.username!r} created. Set GLS_AUTH_ENABLED=1 to require login.")
+        return 0
+    if args.command == "user-list":
+        from .auth import list_usernames
+
+        names = list_usernames()
+        if not names:
+            print("No users yet. Run: gls user-add <name>")
+        else:
+            for n in names:
+                print(n)
+        return 0
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gls/config.py

@@ -0,0 +1,161 @@
+"""
+Runtime configuration for GitHub License Scanner.
+
+Environment variables are the source of truth. A .env file is a convenience
+for local development only: one is looked for in the current directory and in
+the user config directory, and neither is required. Values already present in
+the environment always win.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+import warnings
+from pathlib import Path
+
+from platformdirs import user_config_dir, user_data_dir
+
+APP_NAME = "github-license-scanner"
+APP_AUTHOR = "NezbiT"
+
+# ---------------------------------------------------------------------------
+# Writable locations (must never be inside the installed package)
+# ---------------------------------------------------------------------------
+
+DATA_DIR: Path = Path(
+    os.environ.get("GLS_DATA_DIR") or user_data_dir(APP_NAME, APP_AUTHOR)
+)
+CONFIG_DIR: Path = Path(
+    os.environ.get("GLS_CONFIG_DIR") or user_config_dir(APP_NAME, APP_AUTHOR)
+)
+
+# Optional .env loading. Never assume a file is present: installed globally,
+# the current directory has nothing to do with the package.
+try:
+    from dotenv import load_dotenv
+except ImportError:  # python-dotenv is an optional convenience
+    pass
+else:
+    for _candidate in (Path.cwd() / ".env", CONFIG_DIR / ".env"):
+        if _candidate.is_file():
+            # override=False: real environment variables take precedence.
+            load_dotenv(_candidate, override=False)
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+
+HOST: str = os.environ.get("GLS_HOST", "127.0.0.1")
+PORT: int = int(os.environ.get("GLS_PORT", "8080"))
+# When True, open browser on start (local UX). Disable in containers/CI.
+SHOW_BROWSER: bool = os.environ.get("GLS_SHOW_BROWSER", "1").strip().lower() not in {
+    "0",
+    "false",
+    "no",
+}
+
+# ---------------------------------------------------------------------------
+# Session signing secret (CRITICAL for multi-user / public deploys)
+# ---------------------------------------------------------------------------
+
+_DEFAULT_DEV_SECRET = "github-license-scanner-dev-only-not-for-production"
+
+
+def _resolve_storage_secret() -> str:
+    """
+    Resolve NiceGUI storage_secret.
+
+    Prefer GLS_STORAGE_SECRET / NICEGUI_STORAGE_SECRET.
+    In production-like hosts (0.0.0.0), refuse the insecure default.
+    """
+    secret = (
+        os.environ.get("GLS_STORAGE_SECRET")
+        or os.environ.get("NICEGUI_STORAGE_SECRET")
+        or ""
+    ).strip()
+    if secret:
+        return secret
+
+    host = os.environ.get("GLS_HOST", "127.0.0.1").strip()
+    if host in {"0.0.0.0", "::", "[::]"}:
+        # Generate an ephemeral secret so the process still starts, but warn:
+        # sessions will not survive restarts and operators must set a fixed secret.
+        generated = secrets.token_urlsafe(48)
+        warnings.warn(
+            "GLS_STORAGE_SECRET is not set while binding a public interface. "
+            "Using an ephemeral secret (sessions reset on restart). "
+            "Set GLS_STORAGE_SECRET to a long random value in production.",
+            stacklevel=2,
+        )
+        return generated
+
+    warnings.warn(
+        "Using development storage_secret. Set GLS_STORAGE_SECRET before "
+        "any multi-user or public deployment.",
+        stacklevel=2,
+    )
+    return _DEFAULT_DEV_SECRET
+
+
+def __getattr__(name: str) -> str:
+    """
+    Resolve STORAGE_SECRET lazily (PEP 562).
+
+    Computing it at import time made every CLI invocation emit the
+    development-secret warning, even though only the web UI signs sessions.
+    """
+    if name == "STORAGE_SECRET":
+        value = _resolve_storage_secret()
+        globals()["STORAGE_SECRET"] = value  # cache: warn at most once
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+# ---------------------------------------------------------------------------
+# Abuse / resource limits
+# ---------------------------------------------------------------------------
+
+# Max concurrent registry lookups (also in analyzer; kept here for docs)
+MAX_CONCURRENT_LOOKUPS: int = int(os.environ.get("GLS_MAX_CONCURRENT_LOOKUPS", "12"))
+MAX_PACKAGES_LOOKUP: int = int(os.environ.get("GLS_MAX_PACKAGES_LOOKUP", "80"))
+MAX_DEPENDENCY_FILES: int = int(os.environ.get("GLS_MAX_DEPENDENCY_FILES", "30"))
+MAX_BATCH_URLS: int = int(os.environ.get("GLS_MAX_BATCH_URLS", "15"))
+
+# Scan rate limit per client key (IP / session): N scans per window
+RATE_LIMIT_SCANS: int = int(os.environ.get("GLS_RATE_LIMIT_SCANS", "20"))
+RATE_LIMIT_WINDOW_SECONDS: int = int(os.environ.get("GLS_RATE_LIMIT_WINDOW", "3600"))
+
+# In-process registry license cache
+LICENSE_CACHE_TTL_SECONDS: int = int(os.environ.get("GLS_LICENSE_CACHE_TTL", "3600"))
+LICENSE_CACHE_MAX_ENTRIES: int = int(os.environ.get("GLS_LICENSE_CACHE_MAX", "2000"))
+
+# History retention
+HISTORY_MAX_ENTRIES: int = int(os.environ.get("GLS_HISTORY_MAX", "100"))
+# Auto-prune history entries older than this many days (0 = disabled)
+HISTORY_MAX_AGE_DAYS: int = int(os.environ.get("GLS_HISTORY_MAX_AGE_DAYS", "90"))
+
+# ---------------------------------------------------------------------------
+# GitHub
+# ---------------------------------------------------------------------------
+
+GITHUB_TOKEN: str | None = (
+    os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN") or None
+)
+
+USER_AGENT: str = os.environ.get(
+    "GLS_USER_AGENT",
+    "github-license-scanner/1.2 (+https://github.com/NezbiT/github-license-scanner; educational)",
+)
+
+# ---------------------------------------------------------------------------
+# Multi-user authentication (web UI)
+# ---------------------------------------------------------------------------
+
+AUTH_ENABLED: bool = os.environ.get("GLS_AUTH_ENABLED", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+    "on",
+}
+# JSON file of {username: {salt, hash, iterations}} — see auth.py
+USERS_FILE: str = os.environ.get("GLS_USERS_FILE", str(DATA_DIR / "users.json"))