Vulnerability mirror seeds

This page accompanies VULN-B1’s source cutover. Deployment and final acceptance are recorded in the consolidation sprint; source implementation alone is not a rollout receipt.

The CLI builds a seed from one retained corpus publication. It resolves the publication handle first, downloads its consensus-input and advisory-metadata sections with pinned byte ranges, and verifies their lengths, strong ETags and SHA-256 digests. A rotating current pointer cannot mix two publications in one seed.

stella mirror seed export --output-directory ./seed
stella mirror seed validate --seed-directory ./seed
stella mirror seed import --seed-directory ./seed

The configured CLI profile supplies the hub URL and credentials. Export requires advisory:read and vex:read; import requires advisory:ingest and vex:ingest. Local validation requires neither a database nor a network connection. The hub is tenant-free, so seed commands do not accept a database connection or tenant selector.

Each seed directory contains manifest.json, advisories.jsonl and advisory-index.jsonl. The manifest identifies the source publication and generation, scope, body digest/length/count, and the digest of the complete advisory state index. Hashes use the existing Stella Ops cryptography library. The seed records mirrored claims; it does not assert that the upstream issuer signed the copied document.

Scope and deltas

stella mirror seed export --source osv --ecosystem npm --output-directory ./npm-seed
stella mirror seed export --delta-baseline ./seed/manifest.json --output-directory ./delta
stella mirror seed import --seed-directory ./delta --delta-apply

Source and ecosystem selectors accept repeated or comma-separated values. A source selector matches the publication’s issuer/source key; an ecosystem matches the package type, such as npm, deb or rpm. Metadata aggregated from excluded sources is omitted and counted in the manifest rather than silently redistributed under a narrower scope.

A delta retains its baseline’s scope. Its full state index lets the next delta use it as a baseline without loading a corpus-sized map into memory. The delta body carries added, changed and removed advisory records in identity order. The importer verifies the base state-index digest and scope before any generation or raw-document write. Delta baselines identify the complete resulting state, independently of the delta body’s digest; two empty deltas cannot be confused merely because their bodies have identical bytes. A matching replay is safe.

Installing a different full seed over an existing mirror dataset requires explicit --replace-existing. Replacement removes only obsolete mirror claims; independently ingested provider claims remain. --overwrite on export or copy applies only to a seed directory’s three owned files and refuses unrelated content.

Import and publication

Configure Vulnerabilities:MirrorSeed:StagingRoot as storage writable by the hub web role. Vulnerabilities:MirrorSeed:MaxBundleBytes defaults to 32 GiB. Individual advisory records are bounded to 16 Mi characters. Invalid UTF-8, malformed records, digest mismatches, out-of-order identities and oversized inputs are refused. Temporary uploads are removed after the operation.

The owner validates the complete upload before writing, then uses the ordinary ingestion and normalization paths under a source fence. Reusing an older raw-document digest does not suppress an A-to-B-to-A value restoration. Fact writes remain content-guarded.

The worker services a durable publication request using the existing corpus publisher, including when online ingestion is disabled or the estate is sealed. The web role does not write the publication root. Repeating an identical seed does not repeatedly publish the same corpus. The import receipt describes data application; publication is a separate worker completion boundary.

The owner endpoint is POST /api/vulnerabilities/v1/mirror/seeds/import, with content type application/vnd.stellaops.mirror-seed+ndjson, required X-StellaOps-Content-Digest and X-StellaOps-Mirror-State-Digest, optional delta base/scope headers, and the validateOnly and replaceExisting query controls. A baseline mismatch or active source operation returns 409; malformed input returns 400; another content type returns 415; an unconfigured staging root returns 503. Export requires a current publication with the independent fixedVersion field; an older publication is refused rather than silently losing that value.