vulnctl 0.2.2__tar.gz → 0.3.0__tar.gz

{vulnctl-0.2.2 → vulnctl-0.3.0}/.github/workflows/release.yml

@@ -196,7 +196,7 @@ jobs:
         # Uploads only dist/*.whl and dist/*.tar.gz (signatures/SBOM live in
         # separate artifacts). Generates PEP 740 attestations via the same OIDC
         # identity by default.
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
 
   release:
     name: GitHub Release

{vulnctl-0.2.2 → vulnctl-0.3.0}/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-09
+
+Makes large runs practical: save a free NVD API key once and NVD lookups,
+the bulk of a big SBOM's runtime, get about 10x faster. Also patches a
+critical TLS advisory in a transitive dependency and trims unused files.
+The JSON output shape and its `schema_version` (`"1"`) are unchanged.
+
+### Added
+
+- **Save your NVD API key once.** `vulnctl auth nvd` prompts for the key with
+  hidden input, verifies it with one NVD request, and stores it in the OS
+  keychain (macOS Keychain, Linux Secret Service, Windows Credential Locker).
+  `vulnctl auth status` shows where the active key comes from (masked), and
+  `vulnctl auth remove nvd` deletes it. A key makes NVD lookups — the
+  slowest part of enriching a large input — about 10x faster.
+- **First-run key prompt**: the first interactive online `enrich` or `explain`
+  with no key configured offers to save one. Skipping is remembered and the
+  prompt never repeats; it never appears in scripts, pipes, CI, `--offline`
+  runs, or with `--grype -`.
+- **Sample SBOMs** `examples/medium-app.cdx.json` (~230 CVEs) and
+  `examples/large-app.cdx.json` (~1,700 CVEs): real npm, PyPI, Maven, and Go
+  packages pinned to old, vulnerable versions, for trying vulnctl on
+  realistic volume and timing enrichment.
+- **CLI reference additions**: a command index and an environment-variables
+  table in `docs/cli.md`; a commands table in the README.
+
+### Changed
+
+- **NVD key resolution**: `VULNCTL_NVD_API_KEY` still works and takes
+  precedence; the OS keychain is consulted when it is unset. Adds the
+  `keyring` dependency.
+- **Security: `anyio` 4.15.1** in the lockfile (transitive, via httpx) for
+  GHSA-82r6-8w77-94w6 (Critical: TLS host name encoding enabling potential
+  certificate spoofing) and two subprocess advisories vulnctl never
+  triggers. Fresh installs already resolved a fixed version.
+- **Pre-release cleanup**: removed unused project files (the unfinished
+  case-study and announcement drafts with their stats script, the unrecorded
+  demo tape, the completed v0.1 `ROADMAP.md`, and the superseded TestPyPI
+  workflow), the uninstalled `pre-commit` dev tooling, and the unused
+  `vulnctl.adapters.base.get_adapter()` helper. Local sdist builds now
+  exclude the maintainer's local-only notes.
+- **A rejected NVD key is named as such**: NVD answers an invalid key with
+  HTTP 404; findings now report `NVD rejected the API key (Invalid apiKey)`
+  instead of a bare `HTTP 404`.
+
 ## [0.2.2] - 2026-08-01
 
 ### Fixed
@@ -142,7 +187,8 @@ that produced it.
   sign with keyless cosign (OIDC), and publish to PyPI via trusted publishing
   (no stored token).
 
-[Unreleased]: https://github.com/NokiGuard/vulnctl/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/NokiGuard/vulnctl/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/NokiGuard/vulnctl/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/NokiGuard/vulnctl/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/NokiGuard/vulnctl/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/NokiGuard/vulnctl/compare/v0.1.0...v0.2.0

{vulnctl-0.2.2 → vulnctl-0.3.0}/CLAUDE.md

@@ -40,8 +40,10 @@ src/vulnctl/
 ├── cli.py               # Typer app wiring + cache commands; thin — no business logic here
 ├── cli_help.py          # root --help extras: generated flag summary + examples panels
 ├── commands.py          # enrich/explain command signatures; dispatch only
+├── auth.py              # `vulnctl auth` commands + first-run NVD key prompt
+├── credentials.py       # NVD key resolution (env var > OS keychain), save/remove
 ├── models.py            # Pydantic: Finding, Enrichment, Verdict, DecisionPath
-├── ingest/              # cve_list.py, cyclonedx.py, spdx.py, grype.py, trivy.py
+├── ingest/              # cve_list.py, cyclonedx.py, grype.py (spdx/trivy: FR-4, not yet built)
 ├── adapters/            # one module per intel source; all implement SourceAdapter ABC
 │   ├── base.py          # SourceAdapter ABC + registry
 │   ├── epss.py, kev.py, nvd.py, osv.py, ghsa.py, exploits.py
@@ -62,7 +64,7 @@ tests/
 3. **Fail open on enrichment, fail loud on input.** A source being down degrades the enrichment (mark the field `unavailable`, note it in the decision path) — it never crashes a run. Malformed SBOMs/scanner files are hard errors with actionable messages.
 4. **Every verdict is explainable.** `DecisionPath` records each tree node visited, the input value used, and which source supplied it. If you add a scoring signal, you must thread it through `DecisionPath`.
 5. **Offline mode is first-class.** `--offline` must work using only cached/bundled data (EPSS CSV snapshot, KEV JSON snapshot). Adapters declare whether they support offline.
-6. **No secrets in code or fixtures.** NVD API key comes from `VULNCTL_NVD_API_KEY` env var only. Scrub any recorded fixtures of keys before committing.
+6. **No secrets in code or fixtures.** The NVD API key comes from the `VULNCTL_NVD_API_KEY` env var, else the OS keychain (`keyring`, service `vulnctl`) — never a config file, the cache, or a CLI flag. Only the CLI layer (`credentials.py`/`auth.py`) touches the keychain; the pipeline hands adapters the resolved key as their `credential`. Tests run against an in-memory keychain (`tests/conftest.py`). Scrub any recorded fixtures of keys before committing.
 
 ## Security posture (this is a security tool — hold the bar)
 

{vulnctl-0.2.2 → vulnctl-0.3.0}/FRAMEWORK.md

@@ -79,6 +79,7 @@ class SourceAdapter(ABC):
 - Registered in a simple registry (same pluggable pattern as composeguard's rule engine)
 - Each adapter: check cache → batch-fetch misses (bounded concurrency, per-source rate limits) → validate against strict Pydantic schema → write cache → return
 - Isolation rule: adapters import only `base`, `cache`, `models`. Adding a source touches exactly one new module + fixtures + registry line
+- `credential` constructor argument: the source's optional API key, resolved by the CLI layer (env var, then OS keychain — `credentials.py`) and passed per adapter name by the pipeline. Adapters never read the keychain themselves
 - `progress` attribute (display plumbing, assigned by the pipeline, no-op by default): adapters call `self.progress(n)` as work for `n` IDs completes; total advances per `fetch` must sum to `len(cve_ids)`. Never awaited, never load-bearing
 
 ### 3.3 Enrichment pipeline

{vulnctl-0.2.2 → vulnctl-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: vulnctl
-Version: 0.2.2
+Version: 0.3.0
 Summary: CLI-first vulnerability prioritization: auditable SSVC verdicts from fused threat intelligence
 Project-URL: Homepage, https://github.com/NokiGuard/vulnctl
 Author: Brian Truong
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.28
+Requires-Dist: keyring>=25
 Requires-Dist: pydantic>=2.9
 Requires-Dist: rich>=13.9
 Requires-Dist: ruamel-yaml>=0.18
@@ -63,13 +64,26 @@ pipx install vulnctl
 vulnctl --version
 ```
 
-Requires Python 3.11+ on Linux or macOS. No credentials are required; an NVD
-API key (optional, for higher rate limits) is read from the
-`VULNCTL_NVD_API_KEY` environment variable only.
+Requires Python 3.11+ on Linux or macOS. No credentials are required, but a
+free NVD API key makes enrichment about 10x faster on large inputs: the first
+online run offers to save one to your OS keychain, or run `vulnctl auth nvd`
+any time. The `VULNCTL_NVD_API_KEY` environment variable overrides the saved
+key (use it in CI). See [docs/cli.md](docs/cli.md#vulnctl-auth).
 
 Enable tab completion for commands, flags, and values with
 `vulnctl --install-completion` (see [docs/cli.md](docs/cli.md)).
 
+## Commands
+
+| Command | What it does |
+|---|---|
+| `vulnctl enrich` | Enrich CVE/GHSA IDs, an SBOM (`--sbom`), or a Grype scan (`--grype`) and rank with SSVC verdicts |
+| `vulnctl explain <ID>` | One finding in depth: every source's answer, the decision path, and what would flip it |
+| `vulnctl auth nvd` · `status` · `remove nvd` | Save, inspect, or delete your NVD API key (OS keychain) |
+| `vulnctl cache stats` · `purge` | Inspect or clear the local response cache |
+
+Every flag and example: `vulnctl --help`, or [docs/cli.md](docs/cli.md).
+
 ## Quickstart (60 seconds)
 
 **1. See a verdict and the decision path behind it.** This runs entirely from
@@ -123,6 +137,10 @@ vulnctl enrich --sbom app.cdx.json --context context.yaml
 grype my-image:latest -o json | vulnctl enrich --grype - --context context.yaml
 ```
 
+No SBOM handy? [`examples/medium-app.cdx.json`](examples/medium-app.cdx.json)
+(~230 CVEs) and [`examples/large-app.cdx.json`](examples/large-app.cdx.json)
+(~1,700 CVEs) are real packages pinned to old, vulnerable versions.
+
 **4. Gate CI on risk, not raw CVSS.** Emit SARIF for code scanning, then fail
 the build only when something crosses your threshold:
 
@@ -168,7 +186,6 @@ uv run ruff check .           # lint
 uv run ruff format --check .  # format check
 uv run mypy src/              # type check
 uv run vulnctl --help         # smoke-test the CLI
-uv run pre-commit install     # wire the git hook
 ```
 
 All four checks (pytest, ruff check, ruff format, mypy) must pass before any

{vulnctl-0.2.2 → vulnctl-0.3.0}/README.md

@@ -37,13 +37,26 @@ pipx install vulnctl
 vulnctl --version
 ```
 
-Requires Python 3.11+ on Linux or macOS. No credentials are required; an NVD
-API key (optional, for higher rate limits) is read from the
-`VULNCTL_NVD_API_KEY` environment variable only.
+Requires Python 3.11+ on Linux or macOS. No credentials are required, but a
+free NVD API key makes enrichment about 10x faster on large inputs: the first
+online run offers to save one to your OS keychain, or run `vulnctl auth nvd`
+any time. The `VULNCTL_NVD_API_KEY` environment variable overrides the saved
+key (use it in CI). See [docs/cli.md](docs/cli.md#vulnctl-auth).
 
 Enable tab completion for commands, flags, and values with
 `vulnctl --install-completion` (see [docs/cli.md](docs/cli.md)).
 
+## Commands
+
+| Command | What it does |
+|---|---|
+| `vulnctl enrich` | Enrich CVE/GHSA IDs, an SBOM (`--sbom`), or a Grype scan (`--grype`) and rank with SSVC verdicts |
+| `vulnctl explain <ID>` | One finding in depth: every source's answer, the decision path, and what would flip it |
+| `vulnctl auth nvd` · `status` · `remove nvd` | Save, inspect, or delete your NVD API key (OS keychain) |
+| `vulnctl cache stats` · `purge` | Inspect or clear the local response cache |
+
+Every flag and example: `vulnctl --help`, or [docs/cli.md](docs/cli.md).
+
 ## Quickstart (60 seconds)
 
 **1. See a verdict and the decision path behind it.** This runs entirely from
@@ -97,6 +110,10 @@ vulnctl enrich --sbom app.cdx.json --context context.yaml
 grype my-image:latest -o json | vulnctl enrich --grype - --context context.yaml
 ```
 
+No SBOM handy? [`examples/medium-app.cdx.json`](examples/medium-app.cdx.json)
+(~230 CVEs) and [`examples/large-app.cdx.json`](examples/large-app.cdx.json)
+(~1,700 CVEs) are real packages pinned to old, vulnerable versions.
+
 **4. Gate CI on risk, not raw CVSS.** Emit SARIF for code scanning, then fail
 the build only when something crosses your threshold:
 
@@ -142,7 +159,6 @@ uv run ruff check .           # lint
 uv run ruff format --check .  # format check
 uv run mypy src/              # type check
 uv run vulnctl --help         # smoke-test the CLI
-uv run pre-commit install     # wire the git hook
 ```
 
 All four checks (pytest, ruff check, ruff format, mypy) must pass before any

{vulnctl-0.2.2 → vulnctl-0.3.0}/SPEC.md

@@ -62,7 +62,7 @@ A CLI-first vulnerability prioritization engine that turns raw findings into **a
 ## 5. Non-functional requirements
 
 - **NFR-1:** Enrich 500 CVEs in < 60s warm-cache, < 5min cold (API rate limits permitting)
-- **NFR-2:** Zero required credentials; NVD API key optional (higher rate limits) via env var
+- **NFR-2:** Zero required credentials; NVD API key optional (higher rate limits) via env var or the OS keychain (`vulnctl auth nvd`, offered once on the first interactive online run)
 - **NFR-3:** Runs on Linux and macOS; Python 3.11+; installable via `pipx install vulnctl`
 - **NFR-4:** Test coverage ≥ 85% on `ssvc/` and `adapters/`; SSVC engine at 100% branch coverage
 - **NFR-5:** All third-party API schemas validated defensively; malformed upstream data degrades, never crashes

{vulnctl-0.2.2 → vulnctl-0.3.0}/docs/cli.md

@@ -11,6 +11,18 @@ from the real signatures.
 vulnctl [OPTIONS] COMMAND [ARGS]...
 ```
 
+## Commands
+
+| Command | What it does |
+|---|---|
+| [`enrich`](#vulnctl-enrich) | Enrich CVE/GHSA IDs, an SBOM, or a Grype scan and rank the findings with SSVC verdicts. |
+| [`explain`](#vulnctl-explain) | One finding in depth: every source's answer, the decision path, and what would change the verdict. |
+| [`auth nvd`](#vulnctl-auth) | Save or replace your NVD API key in the OS keychain (verified first). |
+| [`auth status`](#vulnctl-auth) | Show which NVD key vulnctl will use and where it comes from (masked). |
+| [`auth remove nvd`](#vulnctl-auth) | Delete the saved NVD key from the keychain. |
+| [`cache stats`](#vulnctl-cache) | Show cache location, size, and entries per source. |
+| [`cache purge`](#vulnctl-cache) | Delete cached entries, all or one source's. |
+
 ## Global options
 
 | Option | What it does |
@@ -54,6 +66,10 @@ piped stdout — `-f json | jq` — stays byte-clean. It appears only when
 stderr is a real terminal, clears itself when the run completes, and is
 skipped entirely for `--offline` runs (they finish instantly).
 
+Online runs read the NVD API key from `VULNCTL_NVD_API_KEY` or the OS
+keychain; with neither, the first interactive run offers to save one — see
+[`vulnctl auth`](#vulnctl-auth).
+
 Exit codes: `0` success, `1` input/config error, `2` `--fail-on` threshold
 met — full semantics in [exit-codes.md](exit-codes.md).
 
@@ -68,8 +84,18 @@ vulnctl enrich --sbom app.cdx.json --context context.yaml --format json
 
 # Grype scan from stdin, gate CI on Attend or worse
 grype my-image:latest -o json | vulnctl enrich --grype - --fail-on attend
+
+# Bundled sample SBOMs of old, vulnerable packages (npm, PyPI, Maven, Go)
+vulnctl enrich --sbom examples/medium-app.cdx.json --limit 25   # ~230 CVEs
+vulnctl enrich --sbom examples/large-app.cdx.json -f json > large.json  # ~1,700 CVEs
 ```
 
+The two sample SBOMs in `examples/` are sized for trying vulnctl on realistic
+volume and for timing runs: with an NVD key, NVD lookups for the medium file
+take about 3 minutes cold and the large one about 22 (roughly 10x longer
+without a key). Repeat runs answer from the cache in seconds. CVE counts drift
+as new advisories are published against these old versions.
+
 ## `vulnctl explain`
 
 ```
@@ -106,6 +132,68 @@ vulnctl cache COMMAND [ARGS]...
 | `cache stats` | Show cache location, size, and entry counts per source. |
 | `cache purge` | Delete all cached entries, or one source's with `--source <name>` (e.g. `--source epss`). |
 
+## `vulnctl auth`
+
+Manage the optional NVD API key. No credentials are ever required, but
+without a key NVD allows about 7 lookups a minute — on a large SBOM that is
+most of the run. A free key ([request one here](https://nvd.nist.gov/developers/request-an-api-key))
+makes NVD lookups roughly 10x faster.
+
+```
+vulnctl auth COMMAND [ARGS]...
+```
+
+| Command | What it does |
+|---|---|
+| `auth nvd` | Prompt for your key (hidden input), verify it with one NVD request, and save it to your OS keychain. Re-run to replace it. |
+| `auth status` | Show whether a key is configured and where it comes from; the key itself is masked to its last four characters. |
+| `auth remove nvd` | Delete the saved key from the keychain. |
+
+**Where the key lives.** In the OS keychain only — macOS Keychain, Linux
+Secret Service (GNOME Keyring / KWallet), or Windows Credential Locker — never
+a config file, the cache, or a command-line flag. The
+`VULNCTL_NVD_API_KEY` environment variable, when set, takes precedence over
+the saved key; use it in CI and anywhere without a keychain.
+
+**First-run prompt.** The first time `enrich` or `explain` runs online with no
+key configured, vulnctl offers to save one:
+
+```
+No NVD API key found. Without one NVD allows about 7 lookups a minute;
+a free key makes enrichment ~10x faster: https://nvd.nist.gov/developers/request-an-api-key
+NVD API key (input hidden; Enter to skip):
+```
+
+A key NVD rejects is asked for again (up to three tries); a key that can't be
+verified because NVD is unreachable is saved anyway with a warning. Pressing
+Enter skips, and vulnctl remembers that and never asks again
+(`vulnctl auth nvd` still works any time). The marker is
+`~/.config/vulnctl/nvd-key-prompt-dismissed` — delete it to see the prompt
+again.
+
+The prompt never appears where it could get in the way: when stdin or stderr
+isn't a terminal (scripts, pipes, CI — or when `CI` is set), with `--offline`,
+or with `--grype -` (stdin is the scan). It writes to stderr and reads from
+the terminal, so `-f json > out.json` stays clean.
+
+### Examples
+
+```bash
+vulnctl auth nvd              # paste your key (hidden); verified, then saved
+vulnctl auth status           # NVD API key: …a1b2 from macOS Keyring
+vulnctl auth remove nvd       # forget the saved key
+```
+
+## Environment variables
+
+| Variable | What it does |
+|---|---|
+| `VULNCTL_NVD_API_KEY` | NVD API key; takes precedence over a key saved with `vulnctl auth nvd`. Use in CI. |
+| `VULNCTL_GITHUB_TOKEN` | Optional GitHub token for advisory lookups (5,000 req/h instead of 60). |
+| `XDG_CACHE_HOME` | Cache location: `$XDG_CACHE_HOME/vulnctl/cache.db` (default `~/.cache`). |
+| `XDG_CONFIG_HOME` | Config location for the prompt-dismissed marker (default `~/.config`). |
+| `CI` | When set, vulnctl never prompts. |
+
 ## Shell completion
 
 Typer ships tab completion for commands, flags, and enum values