feat: add signed global OSV bootstrap

CHANGELOG.md

@@ -13,11 +13,14 @@ All notable changes to `coderisktools-scanner` are documented here.
 - added bounded public feed adapters and explicit provenance/quality reports without claiming full-feed coverage;
 - added a real partial `seed` snapshot with 187 advisories, 378 affected-package rows and seven represented OSV ecosystems;
 - added signed, pinned seed bootstrap and a separate explicit `--profile seed --apply` activation command.
+- added a streamed, signed global OSV SQLite ZIP bootstrap that installs and activates the pinned database on first default vulnerability scan;
+- added `vuln-db bootstrap-global` and `vuln scan --no-bootstrap` controls.
 
 ### Fixed
 
 - directory self-scan now skips SQLite database artifacts, preventing the real seed from tripping the scanner byte cap in CI;
 - bootstrap now verifies the detached Ed25519 manifest envelope, exact database SHA-256, SQLite integrity, foreign keys, snapshot identity and manifest counts before atomic installation.
+- global ZIP bootstrap verifies the compressed asset digest, one-member extraction contract, expanded database digest, compact provenance manifest and staged snapshot before local activation.
 
 ### Seed boundary
 

README.md

@@ -1,8 +1,8 @@
 # CodeRiskTools Secret Scanner Engine
 
-**Local-first, offline-by-default scanner for secret-like values, risky configuration changes and opt-in local vulnerability analysis.**
+**Local-first scanner for secret-like values, risky configuration changes and opt-in local vulnerability analysis.**
 
-CodeRiskTools Secret Scanner Engine is MIT licensed and has no runtime dependencies. It scans diffs, staged changes, local directories and bounded Git history without executing target-project code. Vulnerability analysis is a separate, explicitly selected local SQLite/SBOM path.
+CodeRiskTools Secret Scanner Engine is MIT licensed and has no runtime dependencies. It scans diffs, staged changes, local directories and bounded Git history without executing target-project code. Vulnerability analysis uses a local SQLite/SBOM path; the pinned signed global database can be installed automatically on its first use.
 
 > Evidence, not guarantees. A clean result is not proof that code is secure. Findings can contain false positives and false negatives. This tool is not a security audit, certification, legal opinion or compliance guarantee.
 
@@ -22,7 +22,7 @@ CodeRiskTools Secret Scanner Engine is MIT licensed and has no runtime dependenc
 - local SQLite vulnerability snapshot scanning and reports;
 - snapshot reconciliation, verification, status, update, rollback, retention pruning and provenance fetch commands;
 - OpenVEX/CycloneDX VEX annotations, suppression and vulnerability baselines;
-- no telemetry, no target-project execution and no network during ordinary scans.
+- no telemetry or target-project execution; secret/config scans and vulnerability scans after database bootstrap perform no network I/O.
 
 The stable detector count excludes provisional candidates. See the detector backlog and source records in [`docs/STAGE6_SECRET_DETECTOR_BACKLOG.md`](docs/STAGE6_SECRET_DETECTOR_BACKLOG.md) and [`docs/STAGE8_CI_CD_BATCH1_SOURCES.md`](docs/STAGE8_CI_CD_BATCH1_SOURCES.md).
 
@@ -34,7 +34,7 @@ This repository contains only the public Scanner flagship. It does not contain o
 
 - Python 3.10–3.13;
 - Git is required for `--staged` and `--git-history` modes;
-- ordinary scanning does not require network access or third-party runtime packages.
+- secret/config scanning does not require network access or third-party runtime packages; first-use default vulnerability scanning downloads a pinned signed database ZIP.
 
 From a checkout:
 
@@ -247,12 +247,11 @@ The sidecar schema is `coderisktools.vulnerability.external-evidence-provenance`
 
 ## 4. Local vulnerability scanning
 
-The vulnerability path requires an explicitly supplied local SQLite database with an active snapshot:
+The vulnerability path uses a local SQLite database with an active snapshot. If `--database` is omitted and the default database is absent, the first run downloads, verifies, extracts and activates the pinned signed global OSV snapshot:
 
 ```bash
 secret-scanner vuln scan \
   --root . \
-  --database vulnerability.sqlite \
   --format json
 ```
 
@@ -272,14 +271,15 @@ secret-scanner vuln scan \
 Options:
 
 - `--root DIR` — local repository root;
-- `--database FILE` — local regular SQLite database;
+- `--database FILE` — local regular SQLite database; defaults to `~/.local/share/coderisktools/vuln-db/global-osv.sqlite`;
+- `--no-bootstrap` — reject a missing default database instead of downloading it;
 - `--format {json,sarif,markdown,html,csv}`;
 - `--output FILE` — write the report atomically;
 - `--baseline FILE` — JSON format emits new/existing/resolved delta;
 - `--vex FILE` — local OpenVEX or CycloneDX VEX;
 - `--suppressions FILE` — strict local suppression document.
 
-Matching is offline, active-snapshot-only and read-only. The database path cannot be a symlink, URL or non-regular file.
+After first-use bootstrap, matching is offline, active-snapshot-only and read-only. The database path cannot be a symlink, URL or non-regular file. Manual installation is available as `secret-scanner vuln-db bootstrap-global`.
 
 ## 5. OSV feed import
 
@@ -396,7 +396,7 @@ secret-scanner vuln-db prune \
 
 ### Explicit allowlisted HTTPS fetch
 
-This is the only `vuln-db` operation that performs network I/O, and it requires an explicit allowlist:
+This explicit generic fetch operation requires an explicit allowlist. The separate `bootstrap-global` operation performs only its built-in, pinned, signature-verified GitHub Release download:
 
 ```bash
 secret-scanner vuln-db fetch \

data/vulnerability-seed/release-keyring.json

@@ -1,6 +1,7 @@
 {
   "keys": {
-    "coderisktools-seed-2026": "64d79d903860fc16b2adb99d9a8ebe6a05540b9a9a2437d0062ba1c552a380a1"
+    "coderisktools-seed-2026": "64d79d903860fc16b2adb99d9a8ebe6a05540b9a9a2437d0062ba1c552a380a1",
+    "coderisktools-vulndb-2026": "5fd70b01c5ef2b0317765fe188f5ef136527d8bceefcff37b0adfc40c4fbf235"
   },
   "schema": "coderisktools.rule-keyring",
   "version": 1

docs/GLOBAL-OSV-SNAPSHOT.md

@@ -0,0 +1,81 @@
+# Global OSV SQLite snapshot
+
+The global OSV builder imports the pinned OSV `all.zip` directly into a temporary SQLite database without extracting the archive to disk.
+
+## Scope and naming
+
+A successful artifact is labeled:
+
+- `profile: global-osv`
+- `completeness: full-osv-source`
+- `production_full_database: false`
+
+`full-osv-source` means that every accepted JSON member from the pinned global OSV archive was processed. It does **not** mean complete Core coverage, complete vulnerability coverage, or proof that an unmatched component is safe. GHSA, KEV, EPSS, NVD, distro feeds, and other enrichments have separate provenance and completeness requirements.
+
+## Space-efficient evidence mode
+
+The large snapshot uses `source_record_mode: digest-only`:
+
+- normalized advisory, alias, package, range, version, reference, and matching data remain in SQLite;
+- valid GIT/CVE records without an OSV `package` object remain as advisories and digest-backed source evidence; their affected entries are counted as `unmapped_affected_entries` and are not package-matchable;
+- every source record keeps its source/native ID, SHA-256 content digest, record fingerprint, and advisory mapping;
+- the duplicate full source JSON payload is omitted from SQLite;
+- the exact pinned ZIP digest and source URL are retained in the manifest.
+
+This avoids storing the same multi-gigabyte JSON payload twice while preserving verifiable provenance. The pinned ZIP remains the raw source artifact.
+
+## Build
+
+```bash
+python scripts/build_global_osv_vulndb.py \
+  --archive /path/to/all.zip \
+  --source-manifest /path/to/manifest.json \
+  --output /path/to/coderisktools-vulndb-global-osv.sqlite \
+  --manifest-output /path/to/coderisktools-vulndb-global-osv.manifest.json \
+  --sha256-output /path/to/coderisktools-vulndb-global-osv.sqlite.sha256 \
+  --snapshot-id global-osv-YYYY-MM-DD
+```
+
+The builder:
+
+1. rejects symlinks, unsafe paths, duplicate members, encrypted files, non-JSON payloads, oversized members, and oversized expanded archives;
+2. verifies the pinned archive SHA-256 before import;
+3. imports bounded batches with no archive extraction;
+4. rejects the build if the configured import-error threshold is exceeded;
+5. checks SQLite integrity and foreign keys;
+6. generates a bounded-memory `compact-v1` content digest;
+7. publishes manifest and checksum first and the SQLite readiness artifact last with no-overwrite hard links;
+8. leaves the embedded snapshot **staged**, never active.
+
+## GitHub Release ZIP and first-run installation
+
+The repository never stores the multi-gigabyte database in Git history. Release `v3.1.0` publishes:
+
+- `coderisktools-vulndb-global-osv-2026-07-23.sqlite.zip`;
+- `coderisktools-vulndb-global-osv-2026-07-23.manifest.json`;
+- `coderisktools-vulndb-global-osv-2026-07-23.manifest.sig.json`.
+
+The ZIP contains exactly one SQLite member. On the first `vuln scan` invocation, when the default database path does not exist, the scanner:
+
+1. downloads the pinned manifest and Ed25519 signature;
+2. validates the embedded public key and profile contract;
+3. streams the ZIP to disk with a 2 GiB compressed limit;
+4. verifies the ZIP SHA-256;
+5. validates the single-member ZIP contract and declared expanded size;
+6. streams extraction with a 9 GiB database limit and SHA-256 verification;
+7. runs SQLite integrity, foreign-key, compact-manifest, and snapshot quality gates;
+8. atomically installs and locally activates the verified snapshot.
+
+Default location:
+
+```text
+~/.local/share/coderisktools/vuln-db/global-osv.sqlite
+```
+
+Manual bootstrap:
+
+```bash
+secret-scanner vuln-db bootstrap-global
+```
+
+Automatic network bootstrap can be disabled with `vuln scan --no-bootstrap`.

docs/RELEASE-NOTES-3.1.0.md

@@ -1,6 +1,6 @@
 # CodeRiskTools Scanner 3.1.0 — release notes
 
-CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability database workflow and publishes a real, verified **partial seed** snapshot for bootstrap and integration testing.
+CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability database workflow, a small verified **partial seed**, and a pinned signed global OSV SQLite ZIP for first-use installation.
 
 ## What is included
 
@@ -12,6 +12,9 @@ CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability databas
 - signed pinned bootstrap that installs seed as staged only;
 - explicit `vuln-db activate --profile seed --apply` activation;
 - real lodash `4.17.15` end-to-end matching evidence with stable fingerprints.
+- streamed first-use global database bootstrap with ZIP/database SHA-256, Ed25519, SQLite integrity, foreign-key and compact-manifest verification;
+- automatic installation to `~/.local/share/coderisktools/vuln-db/global-osv.sqlite` when the default database is missing;
+- `vuln-db bootstrap-global` for an explicit installation and `vuln scan --no-bootstrap` to disable automatic network bootstrap.
 
 ## Release assets
 
@@ -21,6 +24,7 @@ CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability databas
 - SHA-256 sidecar;
 - Ed25519 signed manifest envelope (`.sig` JSON);
 - public release keyring.
+- global OSV single-SQLite ZIP, detached manifest and Ed25519 signed manifest envelope.
 
 ## Verified seed facts
 
@@ -37,6 +41,6 @@ CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability databas
 
 ## Important limitations
 
-This seed is not Core, Full, Production or Complete. It retains 129 exact-alias conflicts rather than heuristically merging advisories. A zero-finding seed scan is not proof that a project has no vulnerabilities. Updates remain user-triggered; ordinary scanner runs do not download feeds.
+The seed is not Core, Full, Production or Complete. The global snapshot is labeled `full-osv-source`, not complete Core coverage or proof that an unmatched component is safe. It retains exact-alias conflicts rather than heuristically merging advisories. A zero-finding scan is not proof that a project has no vulnerabilities. Secret/config scans remain offline; the first default vulnerability scan downloads only the pinned signed release asset, and subsequent matching is local.
 
 A clean scanner result is not proof that code is secure. This release is not a security audit, certification, compliance guarantee or legal opinion.