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

github_license_scanner-0.1.0.dist-info/METADATA

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: github-license-scanner
+Version: 0.1.0
+Summary: Analyze GitHub repo and dependency licenses, copyleft risk, and closed-source sellability.
+Project-URL: Homepage, https://github.com/NezbiT/github-license-scanner
+Project-URL: Issues, https://github.com/NezbiT/github-license-scanner/issues
+Author: Mario Alvarez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agpl,compliance,copyleft,dependencies,gpl,license,sbom
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: packaging>=24.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: ui
+Requires-Dist: nicegui>=2.0.0; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# GitHub License Scanner
+
+<p align="center">
+  <img src="docs/images/hero.jpg" alt="GitHub License Scanner hero banner" width="100%" />
+</p>
+
+<p align="center">
+  <strong>Analyze GitHub repo licenses + dependencies</strong><br/>
+  Know if you can sell closed-source — or if copyleft (GPL / AGPL) forces open source.<br/>
+  <em>NiceGUI web UI · CLI · bilingual ES/EN · light &amp; dark mode</em>
+</p>
+
+<p align="center">
+  <a href="#quick-start"><img src="https://img.shields.io/badge/Python-3.11%2B-2c3e50?style=flat-square" alt="Python" /></a>
+  <a href="#web-ui"><img src="https://img.shields.io/badge/UI-NiceGUI-8b5e3c?style=flat-square" alt="NiceGUI" /></a>
+  <a href="#cli"><img src="https://img.shields.io/badge/CLI-supported-3f6f4e?style=flat-square" alt="CLI" /></a>
+  <a href="#disclaimer"><img src="https://img.shields.io/badge/Not-legal%20advice-9b2c2c?style=flat-square" alt="Disclaimer" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2c3e50?style=flat-square" alt="MIT License" /></a>
+</p>
+
+---
+
+## Screenshots
+
+### Light workspace (full-width layout)
+
+<p align="center">
+  <img src="docs/images/ui-light.jpg" alt="Light mode UI — scan workspace and results" width="100%" />
+</p>
+
+### Dark mode
+
+<p align="center">
+  <img src="docs/images/ui-dark.jpg" alt="Dark mode UI — copyleft warning and package groups" width="100%" />
+</p>
+
+### How it works
+
+<p align="center">
+  <img src="docs/images/flow.jpg" alt="Flow: URL → fetch → registries → verdict → deploy" width="100%" />
+</p>
+
+| Step | What happens |
+|------|----------------|
+| 1 | Paste a GitHub URL (`owner/repo`) |
+| 2 | Read repo license + dependency manifests |
+| 3 | Look up package licenses on npm, PyPI, crates.io, … |
+| 4 | Verdict: closed sale OK vs strong copyleft |
+| 5 | Deploy tips + copyright notice to copy |
+
+---
+
+## Features
+
+- **Repo license** via GitHub REST API  
+- **Dependency scan** for `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `composer.json`, Maven/Gradle (best-effort)  
+- **Registry license lookup** (npm, PyPI, crates.io, RubyGems, Packagist)  
+- **Risk colors**: green (permissive) · orange (weak/unknown) · red (strong copyleft)  
+- **Closed-source sellability** signal + GPL/AGPL force-open flag  
+- **Permissive replacement** suggestions for problematic packages  
+- **Batch mode** (many URLs) + **scan history**  
+- **Copy copyright notice** button  
+- **Deploy advisor** (Vercel, Railway, Render, Fly.io, …)  
+- **ES / EN** UI · **light / dark** theme · **full-width** responsive layout  
+
+---
+
+## Quick start
+
+```bash
+pipx install github-license-scanner
+gls scan psf/requests
+```
+
+The web interface is an optional extra, so the CLI stays light:
+
+```bash
+pipx install 'github-license-scanner[ui]'
+gls ui
+```
+
+Optional configuration (recommended):
+
+```bash
+# PowerShell example
+$env:GITHUB_TOKEN = "ghp_..."
+$env:GLS_STORAGE_SECRET = "long-random-string"
+```
+
+Environment variables are the source of truth. A `.env` file is only a local
+convenience: one is read from the current directory or from your user config
+directory if present, and real environment variables always win.
+
+| Variable | Purpose |
+|----------|---------|
+| `GITHUB_TOKEN` | Higher GitHub API rate limits / private repos |
+| `GLS_STORAGE_SECRET` | Signs session cookies (**required** for public deploys) |
+| `GLS_HOST` / `GLS_PORT` | Bind address (default `127.0.0.1:8080`) |
+| `GLS_MAX_BATCH_URLS` | Cap batch scans (default 15) |
+| `GLS_RATE_LIMIT_SCANS` | Scans per window per client (default 20/hour) |
+| `GLS_AUTH_ENABLED` | Require web login (`1` / `true`) |
+| `GLS_USERS_FILE` | JSON users DB (default: `users.json` in the data dir) |
+| `GLS_DATA_DIR` | Override where history and users are stored |
+
+See [`.env.example`](.env.example) for the full list.
+
+History and users live in your per-user data directory, never inside the
+installed package:
+
+| OS | Path |
+|----|------|
+| Windows | `%LOCALAPPDATA%\NezbiT\github-license-scanner` |
+| macOS | `~/Library/Application Support/github-license-scanner` |
+| Linux | `~/.local/share/github-license-scanner` |
+
+### Multi-user auth + private history
+
+```bash
+gls user-add alice          # interactive password (≥8 chars)
+
+export GLS_AUTH_ENABLED=1
+export GLS_STORAGE_SECRET=long-random-string
+```
+
+Each user gets `history/<username>.json` in that data directory. Without auth,
+history stays in a single `history.json`.
+
+---
+
+## Web UI
+
+```bash
+pipx install 'github-license-scanner[ui]'
+gls ui                       # or: gls ui --host 0.0.0.0 --port 9000
+```
+
+Open **[http://127.0.0.1:8080](http://127.0.0.1:8080)** (binds to localhost by default)
+
+- Switch **ES | EN** in the top bar  
+- Toggle **light / dark** with the sun/moon button  
+- Try example chips (`psf/requests`, `encode/httpx`, …)  
+
+---
+
+## CLI
+
+```bash
+# Single repository
+gls scan https://github.com/psf/requests
+
+# Shorthand
+gls scan psf/requests
+
+# Batch (one URL per line)
+gls batch urls.example.txt
+
+# History
+gls history
+
+# Markdown + SBOM export
+gls scan psf/requests --markdown report.md --sbom bom.cdx.json
+gls scan psf/requests --sbom bom.spdx.json --sbom-format spdx
+```
+
+`github-license-scanner` is available as a longer alias for `gls`.
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | No strong copyleft force-open signal |
+| `1` | Strong copyleft detected |
+| `2` | Hard failure (bad URL, API error, …) |
+
+---
+
+## Project layout
+
+```text
+github-license-scanner/
+├── pyproject.toml          # Packaging (hatchling)
+├── gls/
+│   ├── __init__.py         # __version__
+│   ├── cli.py              # Command-line mode + entry point
+│   ├── webui.py            # NiceGUI interface (optional [ui] extra)
+│   ├── config.py           # Env-based configuration + data paths
+│   ├── rate_limit.py       # Scan rate limiter
+│   ├── auth.py             # Optional multi-user auth (PBKDF2)
+│   ├── spdx_engine.py      # SPDX expression parser + risk
+│   ├── sbom_export.py      # CycloneDX 1.5 + SPDX 2.3 JSON
+│   ├── github_api.py       # URL parse + GitHub REST
+│   ├── dependency_scanner.py  # Manifest parsers
+│   ├── license_analyzer.py    # Registry licenses + verdict
+│   ├── deploy_advisor.py   # Deploy recommendations
+│   ├── history_store.py    # JSON history (shared or per-user)
+│   ├── models.py           # Dataclasses
+│   ├── i18n.py             # ES/EN strings
+│   ├── report.py           # Markdown export
+│   └── docs/               # Legal pages served by the web UI
+│       ├── LEGAL_DISCLAIMER.md
+│       ├── PRIVACY.md
+│       └── TERMS.md
+├── scripts/                # Dev smoke tests / audit tooling
+├── .env.example
+├── urls.example.txt
+└── docs/
+    ├── AUDIT_REPORT.pdf
+    └── images/             # README screenshots
+```
+
+---
+
+## License risk legend
+
+| Color | Risk | Examples |
+|-------|------|----------|
+| Green | Permissive | MIT, Apache-2.0, BSD, ISC |
+| Orange | Weak copyleft / unknown | LGPL, MPL, EUPL, missing metadata |
+| Red | Strong copyleft | GPL, AGPL, SSPL |
+
+---
+
+## Security & privacy notes
+
+- Default bind is **localhost only** (`GLS_HOST=127.0.0.1`).
+- Set a strong **`GLS_STORAGE_SECRET`** before exposing the UI.
+- Scan history is **instance-local** and shared if multi-user — use **Clear history** or prune via config.
+- Rate limits and batch caps reduce GitHub API abuse.
+- Docs: [Privacy](gls/docs/PRIVACY.md) · [Terms](gls/docs/TERMS.md) · [Legal disclaimer](gls/docs/LEGAL_DISCLAIMER.md)
+
+---
+
+## Disclaimer
+
+This tool provides **automated heuristics only**. It is **not legal advice** and not a  
+license-compatibility opinion. Dual-licensing, linking models, SaaS (AGPL/SSPL),  
+attribution duties, and contracts can change obligations.  
+Always review with a qualified attorney before commercial closed-source distribution.  
+See [gls/docs/LEGAL_DISCLAIMER.md](gls/docs/LEGAL_DISCLAIMER.md).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/NezbiT/github-license-scanner.git
+cd github-license-scanner
+
+python -m venv .venv
+.venv\Scripts\activate          # macOS / Linux: source .venv/bin/activate
+
+pip install -e '.[ui]'
+python -m gls.cli scan psf/requests
+```
+
+Build and check a release locally before tagging:
+
+```bash
+pip install build twine
+python -m build
+twine check dist/*
+```
+
+Releases are published to PyPI by [`.github/workflows/publish.yml`](.github/workflows/publish.yml)
+using Trusted Publishing (OIDC) — no API tokens are stored anywhere.
+
+---
+
+## License
+
+Released under the **[MIT License](LICENSE)**.
+
+You may use, modify, and redistribute this project commercially or privately,  
+as long as you keep the copyright and license notice. See `LICENSE` for full text.
+
+> The MIT license applies to **this tool’s source code**.  
+> It does **not** change the licenses of the GitHub repositories or packages you scan.
+
+---
+
+<p align="center">
+  Made with NiceGUI · httpx · packaging
+</p>

github_license_scanner-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+gls/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+gls/auth.py,sha256=vExnbGUgXacZC2aTwRx6kWkQIydsWKug7jGZGwRUaxg,6729
+gls/cli.py,sha256=N7ZDBEHE7rbh8uPbkGR97xMuiDampspIpIKwLQZ0q2A,12125
+gls/config.py,sha256=mrM0cGaMW_Jzk6Bgy8EFHiY7u4vOa-Oi8OGmJSl47y0,6071
+gls/dependency_scanner.py,sha256=lDZURfxbUKPU1t38JEbcYEHKEiK6DahQRtwL8fUnSGg,21243
+gls/deploy_advisor.py,sha256=RWDzCX0QrpauHdJ9X3KwFShM6K4ip12hXc-AarKTXww,10938
+gls/github_api.py,sha256=BScDkBrLg6KaGCnCTiZiVGCp0GCSxD-OWX7o6y_nWrg,15951
+gls/history_store.py,sha256=B-9RTpiQKRJ8kKkOB19-MwZvim06AA4A5Cq_ns5CVbs,5451
+gls/i18n.py,sha256=lggZk-TL-PHV7xVP5RiCfZKH-MdW_57N8qJ1TW8Era8,18860
+gls/license_analyzer.py,sha256=4tgpMsGIzyoLwmVqpXPguoSw_leNkElBa7QuX6x_R0g,31270
+gls/models.py,sha256=6Vj8QdCnfn7J0F3sM6B79PpcNIRRQjQU_6M28g8E5Dg,4839
+gls/rate_limit.py,sha256=QSzAP2Gk096dkPIlYTjz-y1JLtTGoBTQIEXjEnmysMg,2221
+gls/report.py,sha256=vsmF9B_6GUXGcNT6ZCqJOIhd16m-DTTxGRlXaGu4cOY,5659
+gls/sbom_export.py,sha256=EKltiV20i9Ne5ZZbLW6GMZ_xKOH_Uw0jZIQLbl5bqGQ,11009
+gls/spdx_engine.py,sha256=qcuHe0dYY0P9U71Nt_SuuLfPyDZ0DjpDXQMvCdqPwwA,12487
+gls/webui.py,sha256=vgjht82pJ2wqpgxFkwoGF8T0Q_3z_jQppHK8cQkxrkQ,70298
+gls/docs/LEGAL_DISCLAIMER.md,sha256=zS1pWfTntaS_nwyBEd_y1JTbNAqj2Z8nEZeZSyztwIc,2870
+gls/docs/PRIVACY.md,sha256=0tl39MuXUNnOLKvP9jdIVsU96nLDLZxutPSBBSy-JOk,3561
+gls/docs/TERMS.md,sha256=siSl-uZ7lgQ_HvIY7a99UoJyPvOWxXCUKeB7GkjtGmg,2486
+github_license_scanner-0.1.0.dist-info/METADATA,sha256=6FZ_c_bKPLGshOlHVGxbeSzMoapPMnnfpCjw4rIiIBs,10143
+github_license_scanner-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+github_license_scanner-0.1.0.dist-info/entry_points.txt,sha256=NPdnZXh3qeBtU4vB5rdxZIiDHwMP4kEuZX0llI8uxpA,75
+github_license_scanner-0.1.0.dist-info/licenses/LICENSE,sha256=iiCqcmQF6PZDr5vfURi3xqOG4b2K0ydcAvlGD2qaXAU,1063
+github_license_scanner-0.1.0.dist-info/RECORD,,

github_license_scanner-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

github_license_scanner-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+github-license-scanner = gls.cli:main
+gls = gls.cli:main

github_license_scanner-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NezbiT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gls/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gls/auth.py

@@ -0,0 +1,229 @@
+"""
+Optional multi-user authentication for the web UI.
+
+When GLS_AUTH_ENABLED is true, the NiceGUI app requires a login.
+Each user gets an isolated history file under <data_dir>/history/<user>.json.
+
+Password storage uses PBKDF2-HMAC-SHA256 (stdlib only).
+Users file format (JSON):
+  {
+    "alice": {"salt": "hex", "hash": "hex", "iterations": 200000},
+    ...
+  }
+
+CLI:
+  gls user-add alice
+  gls user-list
+"""
+
+from __future__ import annotations
+
+import getpass
+import hashlib
+import json
+import os
+import re
+import secrets
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+try:
+    from .config import DATA_DIR  # type: ignore
+except Exception:  # noqa: BLE001
+    from platformdirs import user_data_dir
+
+    DATA_DIR = Path(user_data_dir("github-license-scanner", "NezbiT"))
+
+USERS_PATH = Path(os.environ.get("GLS_USERS_FILE") or (DATA_DIR / "users.json"))
+
+DEFAULT_ITERATIONS = 200_000
+USERNAME_RE = re.compile(r"^[A-Za-z0-9_.-]{1,64}$")
+
+
+def auth_enabled() -> bool:
+    """Return True when multi-user auth is required for the web UI."""
+    return os.environ.get("GLS_AUTH_ENABLED", "").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+        "on",
+    }
+
+
+def _atomic_write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".users_", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+            fh.flush()
+            os.fsync(fh.fileno())
+        Path(tmp).replace(path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def load_users() -> dict[str, dict[str, Any]]:
+    """Load users database (empty dict if missing)."""
+    if not USERS_PATH.exists():
+        return {}
+    try:
+        data = json.loads(USERS_PATH.read_text(encoding="utf-8") or "{}")
+        return data if isinstance(data, dict) else {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_users(users: dict[str, dict[str, Any]]) -> None:
+    _atomic_write(USERS_PATH, json.dumps(users, indent=2, ensure_ascii=False))
+
+
+def hash_password(password: str, *, salt: bytes | None = None, iterations: int = DEFAULT_ITERATIONS) -> dict[str, Any]:
+    """Create a password record."""
+    if not password or len(password) < 8:
+        raise ValueError("Password must be at least 8 characters")
+    salt = salt or secrets.token_bytes(16)
+    dk = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), salt, iterations)
+    return {
+        "salt": salt.hex(),
+        "hash": dk.hex(),
+        "iterations": iterations,
+    }
+
+
+def verify_password(password: str, record: dict[str, Any]) -> bool:
+    """Constant-time-ish verify of password against stored record."""
+    try:
+        salt = bytes.fromhex(record["salt"])
+        expected = bytes.fromhex(record["hash"])
+        iterations = int(record.get("iterations") or DEFAULT_ITERATIONS)
+    except (KeyError, ValueError, TypeError):
+        return False
+    got = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), salt, iterations)
+    return secrets.compare_digest(got, expected)
+
+
+def authenticate(username: str, password: str) -> bool:
+    """Return True if credentials are valid."""
+    user = (username or "").strip()
+    if not user or not password:
+        return False
+    users = load_users()
+    rec = users.get(user)
+    if not rec:
+        # Also try case-insensitive match
+        for k, v in users.items():
+            if k.lower() == user.lower():
+                rec = v
+                user = k
+                break
+    if not rec:
+        # Dummy work to reduce timing oracle on missing users
+        hash_password("dummy-password-xx", salt=b"\x00" * 16)
+        return False
+    return verify_password(password, rec)
+
+
+def add_user(username: str, password: str) -> None:
+    """Create or update a user password."""
+    user = (username or "").strip()
+    if not USERNAME_RE.match(user):
+        raise ValueError(
+            "Username must be 1–64 chars: letters, digits, _ . -"
+        )
+    users = load_users()
+    users[user] = hash_password(password)
+    save_users(users)
+
+
+def delete_user(username: str) -> bool:
+    users = load_users()
+    if username in users:
+        del users[username]
+        save_users(users)
+        return True
+    return False
+
+
+def list_usernames() -> list[str]:
+    return sorted(load_users().keys())
+
+
+def normalize_username(username: str) -> str:
+    return (username or "").strip()
+
+
+def history_user_key(username: str | None) -> str | None:
+    """
+    Return a filesystem-safe history key.
+
+    None means shared/local anonymous history (auth disabled).
+    """
+    if not username:
+        return None
+    u = normalize_username(username)
+    if not USERNAME_RE.match(u):
+        return None
+    return u.lower()
+
+
+# ---------------------------------------------------------------------------
+# CLI helpers
+# ---------------------------------------------------------------------------
+
+def _cli(argv: list[str]) -> int:
+    if len(argv) < 2 or argv[1] in {"-h", "--help"}:
+        print(__doc__)
+        return 0
+    cmd = argv[1]
+    if cmd == "list-users":
+        names = list_usernames()
+        if not names:
+            print("No users. Create one with: python -m gls.auth add-user <name>")
+            print(f"Users file: {USERS_PATH}")
+            return 0
+        for n in names:
+            print(n)
+        return 0
+    if cmd == "add-user":
+        if len(argv) < 3:
+            print("Usage: python -m gls.auth add-user <username>", file=sys.stderr)
+            return 2
+        username = argv[2]
+        pw = getpass.getpass("Password: ")
+        pw2 = getpass.getpass("Confirm: ")
+        if pw != pw2:
+            print("Passwords do not match", file=sys.stderr)
+            return 2
+        try:
+            add_user(username, pw)
+        except ValueError as exc:
+            print(exc, file=sys.stderr)
+            return 2
+        print(f"User {username!r} saved to {USERS_PATH}")
+        print("Enable auth with GLS_AUTH_ENABLED=1")
+        return 0
+    if cmd == "hash-password":
+        pw = getpass.getpass("Password: ")
+        rec = hash_password(pw)
+        print(json.dumps(rec, indent=2))
+        return 0
+    if cmd == "delete-user":
+        if len(argv) < 3:
+            print("Usage: python -m gls.auth delete-user <username>", file=sys.stderr)
+            return 2
+        ok = delete_user(argv[2])
+        print("Deleted" if ok else "Not found")
+        return 0 if ok else 1
+    print(f"Unknown command: {cmd}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(_cli(sys.argv))