github-license-scanner 0.1.1

Analyze GitHub repo and dependency licenses, copyleft risk, and closed-source sellability.

GitHub License Scanner

Analyze GitHub repo licenses + dependencies
Know if you can sell closed-source — or if copyleft (GPL / AGPL) forces open source.
NiceGUI web UI · CLI · bilingual ES/EN · light & dark mode

---

Screenshots

Light workspace (full-width layout)

Dark mode

How it works

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

pipx install github-license-scanner
gls scan psf/requests

The web interface is an optional extra, so the CLI stays light:

pipx install 'github-license-scanner[ui]'
gls ui

Optional configuration (recommended):

# 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 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

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

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 (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

# 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

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 · Terms · Legal disclaimer

---

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.

---

Development

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:

pip install build twine
python -m build
twine check dist/*

Releases are published to PyPI by .github/workflows/publish.yml using Trusted Publishing (OIDC) — no API tokens are stored anywhere.

---

License

Released under the MIT 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.

---

Made with NiceGUI · httpx · packaging