ecdat 0.2.0__tar.gz

ecdat-0.2.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-21
+
+
+### Added
+
+- **New `ecdat` command-line interface.** A pip-installable, terminal-native
+  front end for the scanner, with subcommands:
+  - `ecdat scan <path-or-url>` — scan a local directory or an `https://` Git
+    repository, with `--format pretty|json|cbom|summary`, `--output DIR`,
+    `--fail-on critical|high|medium|low`, `--limit N`, `--no-progress`,
+    `--quiet`, and `--git-url`.
+  - `ecdat demo` — scan the bundled, deliberately-insecure sample project with
+    zero setup (and `--path` to materialise a persistent copy).
+  - `ecdat doctor` — environment self-check (Python, platform, install
+    location, git, terminal, signatures, `ECDAT_HOME`) with a one-line fix per
+    failing check.
+  - `ecdat about` — credits, project links, and an animated 3D globe.
+  - `ecdat help [command]` — command overview and per-command help.
+  - `ecdat version` — version, engine, signature count, Python, and OS.
+  - Global flags `--version`, `--no-color`, and `--debug`.
+- **Gradient ASCII banner** shown on interactive runs.
+- **Animated 3D globe** in `ecdat about` (opt-out with `--no-anim`, duration
+  controlled by `--spin`).
+- **Padlock verdict emblem** in the pretty scan report.
+- **Bundled demo project** (`ecdat/demo_project/`) shipped inside the wheel, so
+  `ecdat demo` works with no repository checkout.
+- **Crash-safe error handling.** Expected errors print a friendly message and a
+  documented exit code; unexpected errors are written to a local crash log
+  under `ECDAT_HOME/logs` with a pointer for bug reports, instead of a raw
+  traceback.
+- **Documented exit codes** for scripting and CI: `0` success, `1` findings at
+  or above `--fail-on`, `2` usage/validation error, `3` scan/runtime/unexpected
+  error, `130` interrupted (`Ctrl-C`).
+- `CHANGELOG.md` and `PYPI_README.md`, and a `[project.scripts]` console entry
+  point (`ecdat = "ecdat.cli:main"`).
+
+### Changed
+
+- **Distribution renamed to `ecdat`** (previously `ecdat-cbom`). A single wheel
+  now ships both import packages: the new app layer (`ecdat`) and the scanner
+  engine (`ecdat_core`). `python -m ecdat` behaves identically to the console
+  script; the legacy `python -m ecdat_core.cli` entry point is unchanged.
+- **Engine: `run_scan()` gained a `sandboxed=` parameter.** Callers can opt a
+  trusted local scan out of the workspace sandbox (the CLI and TUI do this — the
+  user is the trust boundary), while the HTTP API keeps the sandbox enabled.
+- Runtime dependency on `rich` added for the CLI/TUI renderers.
+
+### Security
+
+- CLI renderers treat scanned repository content (file paths, snippets,
+  algorithm names) as untrusted and render it as plain text, so it cannot
+  inject terminal escapes or Rich/HTML/Markdown markup.

ecdat-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Errorists Team
+
+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.

ecdat-0.2.0/MANIFEST.in

@@ -0,0 +1,29 @@
+# MANIFEST.in — controls the SOURCE DISTRIBUTION (sdist) file list.
+# The WHEEL is governed by [tool.setuptools.packages.find] and
+# [tool.setuptools.package-data] in pyproject.toml.
+#
+# This repo is a monorepo (ecdat_core + backend + frontend), but only
+# `ecdat_core` is published on PyPI. Everything else is pruned so
+# `pip download ecdat-cbom` never pulls in the FastAPI backend or the
+# React frontend. LICENSE is handled by [project] license-files and is
+# not re-listed here.
+
+include README.md
+include pyproject.toml
+include PYPI_README.md
+include CHANGELOG.md
+
+# Ship tests + fixtures in the sdist only (standard practice; tests are not
+# part of the wheel).
+recursive-include ecdat_core/tests *
+recursive-include ecdat/tests *
+
+# Never ship the monorepo's non-published areas.
+prune backend
+prune frontend
+
+# Housekeeping.
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store

ecdat-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: ecdat
+Version: 0.2.0
+Summary: Cryptographic discovery and post-quantum readiness scanner — CLI with a gradient ASCII banner and an animated 3D globe (CBOM, CycloneDX 1.6)
+Author: ECDAT Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/profm0r14rty/ecdat
+Project-URL: Repository, https://github.com/profm0r14rty/ecdat
+Project-URL: Issues, https://github.com/profm0r14rty/ecdat/issues
+Project-URL: Changelog, https://github.com/profm0r14rty/ecdat/blob/main/CHANGELOG.md
+Keywords: cbom,cli,cryptography,cyclonedx,post-quantum,pqc,quantum,sbom,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: jsonschema; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# ecdat
+
+**ECDAT** is a [CycloneDX](https://cyclonedx.org/) **Cryptography Bill of
+Materials (CBOM) scanner for post-quantum readiness**. One command finds the
+cryptographic artefacts in a codebase — RSA, ECC, DH, DSA, MD5, SHA-1, DES,
+3DES, RC4, AES, and others — scores each one's post-quantum risk with Mosca's
+inequality, recommends NIST post-quantum replacements, and emits a real
+CycloneDX 1.6 CBOM next to a dashboard-friendly risk summary.
+
+It is a small, self-contained Python package (runtime dependencies: `pydantic`
+and `rich`) — no FastAPI, Postgres, Redis, or Docker required. It runs fully
+offline: the only network access is `git clone` for an explicit URL scan.
+
+Why it is more than a lookalike scanner:
+
+- **Real CBOM output.** The report is genuine CycloneDX 1.6, validated against
+  the official JSON Schema on every scan in the test suite, so Dependency-Track,
+  Syft, Grype, and other CycloneDX tooling parse it unchanged.
+- **"Classically broken" is not "quantum vulnerable".** MD5, SHA-1, DES, 3DES,
+  and RC4 are reported as broken *today*; RSA, ECC, DH, and DSA as broken *by
+  Shor's algorithm*. An actively exploitable hash is never mislabeled
+  "quantum-safe".
+- **Offline and private.** No telemetry, no update checks.
+- **Crash-safe.** Expected errors print a clear message and exit code;
+  unexpected errors are written to a local crash log instead of a raw
+  traceback.
+
+## Install
+
+```bash
+pipx install ecdat        # recommended: isolated and on PATH
+uv tool install ecdat     # recommended if you use uv
+pip install ecdat         # into the active Python environment
+```
+
+If plain `pip` reports `externally-managed-environment`, that is
+[PEP 668](https://peps.python.org/pep-0668/) protecting your OS Python — use
+`pipx` or `uv tool` (or a virtualenv) instead of forcing the install. On
+Windows, install with `py -m pip install ecdat`; if `ecdat` is not on `PATH`,
+run the CLI as `py -m ecdat …`.
+
+## 60-second tour
+
+```bash
+ecdat demo                                   # scan the bundled sample project
+ecdat scan .                                 # scan the current directory
+ecdat scan https://github.com/<user>/<repo>  # scan a public https:// repo
+ecdat about                                  # credits and an animated 3D globe
+ecdat doctor                                 # check your environment
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ecdat scan <path-or-url>` | Scan a local directory, or an `https://` Git repository |
+| `ecdat demo` | Scan the bundled, deliberately-insecure sample project (zero setup) |
+| `ecdat doctor` | Environment self-check with a one-line fix per problem |
+| `ecdat about` | Credits, project links, and a spinning 3D globe |
+| `ecdat help [command]` | Command overview, or full help for one command |
+| `ecdat version` | Version, engine, signature count, Python, and OS |
+
+Global flags: `--version`, `--no-color`, and `--debug`.
+
+## Formats
+
+`ecdat scan --format <pretty|json|cbom|summary>`:
+
+| Format | Contents |
+|--------|----------|
+| `pretty` | Colourised terminal report (default) |
+| `json` | The full `ScanResult` |
+| `cbom` | A CycloneDX 1.6 CBOM |
+| `summary` | The risk rollup used by dashboards |
+
+Payload formats write **only** the payload to stdout; progress, warnings, and
+errors go to stderr — so `ecdat scan . -f cbom > cbom.json` is safe to pipe.
+`ecdat demo` supports `pretty`, `json`, and `summary`.
+
+For CI, `ecdat scan . --fail-on high` exits `1` when a finding is at or above
+that level (`quantum-safe` findings never count) and `0` when clean. The other
+exit codes are `2` (usage/validation error), `3` (scan/runtime/unexpected
+error), and `130` (interrupted with `Ctrl-C`).
+
+## Guarantees
+
+- **Offline by default.** Only `git clone` for an explicit `https://` URL scan
+  touches the network; local scans never do.
+- **No telemetry and no update checks.**
+- **Injection-safe rendering.** File paths, matched snippets, and algorithm
+  names from scanned (untrusted) code are rendered as plain text and cannot
+  inject terminal escapes or Rich/HTML/Markdown markup.
+- **Validated Git-URL scanning.** Only `https://` URLs are cloned, and the host
+  is resolved and checked against private/reserved address ranges before any
+  clone runs.
+
+## Links
+
+- Source, issues, and documentation: <https://github.com/profm0r14rty/ecdat>
+- Security policy: <https://github.com/profm0r14rty/ecdat/blob/main/SECURITY.md>
+- Changelog: <https://github.com/profm0r14rty/ecdat/blob/main/CHANGELOG.md>
+- Live demo dashboard: <https://ecdat-web.onrender.com>
+- Live demo API: <https://ecdat-api.onrender.com>
+- License (MIT): <https://github.com/profm0r14rty/ecdat/blob/main/LICENSE>

ecdat-0.2.0/PYPI_README.md

@@ -0,0 +1,104 @@
+# ecdat
+
+**ECDAT** is a [CycloneDX](https://cyclonedx.org/) **Cryptography Bill of
+Materials (CBOM) scanner for post-quantum readiness**. One command finds the
+cryptographic artefacts in a codebase — RSA, ECC, DH, DSA, MD5, SHA-1, DES,
+3DES, RC4, AES, and others — scores each one's post-quantum risk with Mosca's
+inequality, recommends NIST post-quantum replacements, and emits a real
+CycloneDX 1.6 CBOM next to a dashboard-friendly risk summary.
+
+It is a small, self-contained Python package (runtime dependencies: `pydantic`
+and `rich`) — no FastAPI, Postgres, Redis, or Docker required. It runs fully
+offline: the only network access is `git clone` for an explicit URL scan.
+
+Why it is more than a lookalike scanner:
+
+- **Real CBOM output.** The report is genuine CycloneDX 1.6, validated against
+  the official JSON Schema on every scan in the test suite, so Dependency-Track,
+  Syft, Grype, and other CycloneDX tooling parse it unchanged.
+- **"Classically broken" is not "quantum vulnerable".** MD5, SHA-1, DES, 3DES,
+  and RC4 are reported as broken *today*; RSA, ECC, DH, and DSA as broken *by
+  Shor's algorithm*. An actively exploitable hash is never mislabeled
+  "quantum-safe".
+- **Offline and private.** No telemetry, no update checks.
+- **Crash-safe.** Expected errors print a clear message and exit code;
+  unexpected errors are written to a local crash log instead of a raw
+  traceback.
+
+## Install
+
+```bash
+pipx install ecdat        # recommended: isolated and on PATH
+uv tool install ecdat     # recommended if you use uv
+pip install ecdat         # into the active Python environment
+```
+
+If plain `pip` reports `externally-managed-environment`, that is
+[PEP 668](https://peps.python.org/pep-0668/) protecting your OS Python — use
+`pipx` or `uv tool` (or a virtualenv) instead of forcing the install. On
+Windows, install with `py -m pip install ecdat`; if `ecdat` is not on `PATH`,
+run the CLI as `py -m ecdat …`.
+
+## 60-second tour
+
+```bash
+ecdat demo                                   # scan the bundled sample project
+ecdat scan .                                 # scan the current directory
+ecdat scan https://github.com/<user>/<repo>  # scan a public https:// repo
+ecdat about                                  # credits and an animated 3D globe
+ecdat doctor                                 # check your environment
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ecdat scan <path-or-url>` | Scan a local directory, or an `https://` Git repository |
+| `ecdat demo` | Scan the bundled, deliberately-insecure sample project (zero setup) |
+| `ecdat doctor` | Environment self-check with a one-line fix per problem |
+| `ecdat about` | Credits, project links, and a spinning 3D globe |
+| `ecdat help [command]` | Command overview, or full help for one command |
+| `ecdat version` | Version, engine, signature count, Python, and OS |
+
+Global flags: `--version`, `--no-color`, and `--debug`.
+
+## Formats
+
+`ecdat scan --format <pretty|json|cbom|summary>`:
+
+| Format | Contents |
+|--------|----------|
+| `pretty` | Colourised terminal report (default) |
+| `json` | The full `ScanResult` |
+| `cbom` | A CycloneDX 1.6 CBOM |
+| `summary` | The risk rollup used by dashboards |
+
+Payload formats write **only** the payload to stdout; progress, warnings, and
+errors go to stderr — so `ecdat scan . -f cbom > cbom.json` is safe to pipe.
+`ecdat demo` supports `pretty`, `json`, and `summary`.
+
+For CI, `ecdat scan . --fail-on high` exits `1` when a finding is at or above
+that level (`quantum-safe` findings never count) and `0` when clean. The other
+exit codes are `2` (usage/validation error), `3` (scan/runtime/unexpected
+error), and `130` (interrupted with `Ctrl-C`).
+
+## Guarantees
+
+- **Offline by default.** Only `git clone` for an explicit `https://` URL scan
+  touches the network; local scans never do.
+- **No telemetry and no update checks.**
+- **Injection-safe rendering.** File paths, matched snippets, and algorithm
+  names from scanned (untrusted) code are rendered as plain text and cannot
+  inject terminal escapes or Rich/HTML/Markdown markup.
+- **Validated Git-URL scanning.** Only `https://` URLs are cloned, and the host
+  is resolved and checked against private/reserved address ranges before any
+  clone runs.
+
+## Links
+
+- Source, issues, and documentation: <https://github.com/profm0r14rty/ecdat>
+- Security policy: <https://github.com/profm0r14rty/ecdat/blob/main/SECURITY.md>
+- Changelog: <https://github.com/profm0r14rty/ecdat/blob/main/CHANGELOG.md>
+- Live demo dashboard: <https://ecdat-web.onrender.com>
+- Live demo API: <https://ecdat-api.onrender.com>
+- License (MIT): <https://github.com/profm0r14rty/ecdat/blob/main/LICENSE>

ecdat-0.2.0/README.md

@@ -0,0 +1,200 @@
+# ECDAT - Enterprise Cryptographic Discovery & Analysis Tool
+
+ECDAT is a Cryptography Bill of Materials (CBOM) scanner for post-quantum readiness assessment. It discovers cryptographic artefacts in source code, assesses their quantum-computing risk using Mosca's algorithm, and recommends NIST post-quantum replacements, outputting a CycloneDX 1.6 CBOM report.
+
+## Install the CLI
+
+The `ecdat` command is a standalone, pip-installable scanner — no Docker,
+Postgres, Redis, or API required. It runs fully offline; see
+[Privacy and trust](#privacy-and-trust).
+
+```bash
+pipx install ecdat        # recommended: isolated and on PATH
+uv tool install ecdat     # recommended if you use uv
+pip install ecdat         # into the active Python environment
+```
+
+If `pip install` stops with `error: externally-managed-environment`, that is
+[PEP 668](https://peps.python.org/pep-0668/) protecting your OS Python — use
+`pipx` or `uv tool` (or a virtualenv) rather than forcing the install. On
+Windows, install with `py -m pip install ecdat`; if `ecdat` is not on `PATH`,
+run the CLI as `py -m ecdat …`.
+
+Upgrade or remove it later:
+
+```bash
+pipx upgrade ecdat           # or: uv tool upgrade ecdat
+pip install --upgrade ecdat
+pipx uninstall ecdat         # or: uv tool uninstall ecdat
+```
+
+### 60-second tour
+
+```bash
+ecdat demo                                   # scan the bundled sample project
+ecdat about                                  # credits and an animated 3D globe
+ecdat scan .                                 # scan the current directory
+ecdat scan https://github.com/<user>/<repo>  # scan a public https:// repo
+ecdat help                                   # list every command
+ecdat doctor                                 # check your environment
+```
+
+<!-- screenshots: docs/img/*.png -->
+
+### Commands
+
+| Command | What it does |
+|---------|--------------|
+| `ecdat scan <path-or-url>` | Scan a local directory, or an `https://` Git repository |
+| `ecdat demo` | Scan the bundled, deliberately-insecure sample project (zero setup) |
+| `ecdat doctor` | Environment self-check (Python, git, signatures, `ECDAT_HOME`) |
+| `ecdat about` | Credits, project links, and a spinning 3D globe |
+| `ecdat help [command]` | Command overview, or full help for one command |
+| `ecdat version` | Version, engine, signature count, Python, and OS |
+
+Global flags: `--version`, `--no-color`, `--debug`.
+
+### Output formats
+
+`ecdat scan --format <pretty|json|cbom|summary>`:
+
+- `pretty` (default) — the colourised terminal report.
+- `json` — the full `ScanResult`.
+- `cbom` — a CycloneDX 1.6 CBOM.
+- `summary` — the risk rollup used by dashboards.
+
+Payload formats write **only** the payload to stdout; progress, warnings, and
+errors go to stderr. That keeps `ecdat scan . -f cbom > cbom.json` safe to
+pipe. `ecdat demo` supports `pretty`, `json`, and `summary`.
+
+### Use in CI
+
+```bash
+ecdat scan . --fail-on high
+```
+
+`--fail-on <critical|high|medium|low>` returns exit code `1` when any finding
+is at or above that level (`quantum-safe` findings never count). Exit codes:
+`0` success · `1` findings at or above `--fail-on` · `2` usage/validation
+error · `3` scan/runtime/unexpected error · `130` interrupted (`Ctrl-C`).
+
+### Privacy and trust
+
+- **Runs fully offline.** The only network access is `git clone` for an
+  explicit `https://` URL scan; local scans never touch the network.
+- **No telemetry, no update checks.**
+- **Hostile repo content cannot inject escapes or markup.** File paths,
+  snippets, and algorithm names from scanned repositories are attacker-
+  controlled; the CLI renders them as plain text, never as Rich/HTML/Markdown
+  markup. Covered by `ecdat/tests/test_app_render.py`.
+
+## Running locally
+
+### Prerequisites
+
+- Docker with Docker Compose (Compose v2+).
+
+### Infrastructure + API + Dashboard
+
+From the repo root, build and start the whole stack:
+
+```bash
+docker compose up --build
+```
+
+This brings up four services:
+
+| Service  | Image / source       | Purpose                                            |
+|----------|----------------------|----------------------------------------------------|
+| postgres | `postgres:16-alpine` | Persistent scan database (named volume `postgres_data`) |
+| redis    | `redis:7-alpine`     | Scan job status keys (`scan:{id}:status`)          |
+| api      | `backend/Dockerfile` | FastAPI app on `http://localhost:8000`, uvicorn with hot reload |
+| web      | `frontend/Dockerfile`| React dashboard at `http://localhost:5173`, nginx serves the build and reverse-proxies `/api` + `/health` to `api` |
+
+Database credentials are read from `.env` (copy `.env.example` to `.env` and
+adjust as needed). The compose file falls back to the same dev defaults, so a
+plain `docker compose up --build` works with no `.env` file at all.
+
+Smoke test — the API should answer immediately once the containers are up
+(either directly, or through the web container's proxy):
+
+```bash
+curl http://localhost:8000/health
+# {"status":"ok"}
+curl http://localhost:5173/health
+# {"status":"ok"}
+```
+
+The dashboard lives at `http://localhost:5173`. The `web` container keeps the
+frontend bundle's default same-origin `VITE_API_BASE_URL`: nginx serves the
+compiled static files and forwards `/api` + `/health` to the `api` service, so
+no runtime env substitution or CORS config is needed in the containerized flow.
+
+Details:
+
+- On container start, the API entrypoint (`backend/docker-entrypoint.sh`)
+  runs `alembic upgrade head` against Postgres before launching uvicorn.
+- `./backend` is bind-mounted into the container and uvicorn runs with
+  `--reload`, so backend code edits take effect without rebuilding.
+- The `api` service waits for both `postgres` and `redis` to report healthy
+  (`depends_on.condition: service_healthy`); `web` waits for `api` to start.
+
+Tear down with `docker compose down` (add `-v` to also delete the Postgres
+named volume).
+
+## Live Deployment
+
+The project is deployed on Render's free tier.
+
+- **API**: [https://ecdat-api.onrender.com](https://ecdat-api.onrender.com)
+- **Dashboard**: [https://ecdat-web.onrender.com](https://ecdat-web.onrender.com)
+
+**Note on cold starts**: The API sleeps after 15 minutes of inactivity. The first request after sleep will take about a minute to respond while the service warms up. Please hit the `/health` endpoint once before starting the demo to ensure the app is responsive.
+
+## Securing a non-demo deployment (optional API-key auth)
+
+By default ECDAT's API is fully open — anyone with the URL can submit scans and
+read everyone's scan history. That's intentional for the public hackathon demo.
+For anything resembling a real deployment, the API ships with a minimal
+single-tier gate: when enabled, every `/api/scans*` endpoint (writes *and*
+reads) requires an `Authorization: Bearer <key>` header. Full multi-tenant
+auth (users, orgs, roles) is deliberately not part of this mechanism.
+
+1. **Generate one or more keys** out-of-band — never reuse committed values:
+
+   ```bash
+   python -c "import secrets; print(secrets.token_urlsafe(32))"
+   ```
+
+2. **Enable the gate** by setting two environment variables on the API:
+
+   - `REQUIRE_API_KEY=true`
+   - `API_KEYS=<comma-separated keys>` (whitespace around keys is fine)
+
+   Where to set them depends on the deployment:
+
+   - **Docker Compose** — add both to your `.env` (copied from
+     `.env.example`); the `api` service passes them through.
+   - **Render** — set both in the Web Service's **Environment** panel
+     (note: Render's env vars are separate from a local `.env` file) and
+     redeploy. Render's env changes apply on the next deploy — the gate reads
+     them per request, so no restart is needed once the new env is live.
+
+   The gate is **off by default**; with `REQUIRE_API_KEY` unset or `false`,
+   behavior is unchanged. If you enable it without setting `API_KEYS`, the API
+   fails closed (HTTP 500) rather than silently opening up.
+
+3. **Clients** must send the key on every (non-`/health`) request:
+
+   ```bash
+   curl -H "Authorization: Bearer <key>" https://your-api/api/scans
+   ```
+
+   `GET /health` stays public so uptime monitors and warm-keeping pings keep
+   working.
+
+**Dashboard caveat**: the bundled dashboard is a public-demo artifact — its API
+client sends no auth header, so once you flip the gate on, the dashboard's
+`/api/scans` calls will be rejected (401). A non-demo deployment either uses
+API-keyed clients / CI pipelines, or terminates the key at a same-origin proxy.
+Key entry in the UI is intentionally out of scope for this gate.

ecdat-0.2.0/ecdat/__init__.py

@@ -0,0 +1,10 @@
+"""ECDAT — Enterprise Cryptographic Discovery & Analysis Tool."""
+
+import importlib.metadata
+
+DIST_NAME = "ecdat"
+
+try:
+    __version__ = importlib.metadata.version(DIST_NAME)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0+unknown"

ecdat-0.2.0/ecdat/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m ecdat` to run the CLI."""
+
+from ecdat.cli import main
+
+raise SystemExit(main())