Vulnerability-Intelligence Manifest Contract v1

Contract: stella.ops/vulnIntelligenceManifest@v1 (CONTRACT-VULN-INTELLIGENCE-MANIFEST-V1-074). Schema: vuln-intelligence-manifest.v1.schema.json (JSON Schema 2020-12, the payload). DSSE payload type: application/vnd.stellaops.vuln-intelligence-manifest.v1+json. Files in an export: intelligence-manifest.json (the canonical payload) and, when the export is signed, intelligence-manifest.dsse.json (the envelope). Examples: valid payload, invalid payload. Sprint: SPRINT_20261027_006 SIM-1. Vendor signing: SIM-2. Consumer verification: SIM-3. Snapshot display: SIM-4.

Purpose

The compact vulnerability database (stella vuln-db export) is the intelligence that stella sbom check --vuln-db and the offline mirror decide with. The intelligence manifest identifies one export exactly: every file in it with its SHA-256 and size, the export’s version label, and the vulnerability hub publication (the advisory snapshot) it was built from, with that snapshot’s version and time. Signed by the vendor, it lets an installation verify offline that the files it holds are the ones Stella Ops published, and show how old the intelligence it decides with is.

The existing manifests stay as they are and stay readable: manifest.json, vuln-db.manifest.json and vuln-db-sharealike.manifest.json keep every field (docs/OFFLINE_KIT.md §2.3.1). The intelligence manifest lists them as files of the export; it does not replace their content.

What a verified manifest establishes

A manifest whose envelope verifies against a pinned vendor root of purpose vendor-intelligence (see the vendor trust-root set) establishes, and only establishes:

that Stella Ops published an export whose files have exactly the listed paths, sizes and SHA-256 digests;
that the export was built from the hub publication snapshot.artifactRef, at source generation snapshot.sourceGeneration, published at snapshot.publishedAt.

It does not establish:

that the advisories are complete, correct or current: upstream sources lag, disagree and are amended, and the snapshot is as old as snapshot.publishedAt;
that a verdict computed from the database is correct for any image or SBOM;
anything about files that are not listed, or about the export after its files change.

Payload fields

All fields are required, and no other field is allowed.

Field	Type	Meaning
`schemaVersion`	string	`stella.ops/vulnIntelligenceManifest@v1`.
`dbVersion`	string	The export’s version label: `dbVersion` in `manifest.json` and in the database’s `db_manifest` table.
`generatedAt`	string	When the export ran, UTC. This is not the advisory snapshot time.
`snapshot.artifactRef`	string	The hub publication the export was built from: `corpusArtifactRef` in `manifest.json`.
`snapshot.sourceGeneration`	integer	The advisory snapshot version: the hub’s source generation of that publication.
`snapshot.publishedAt`	string	The advisory snapshot time: when the hub published the corpus, UTC.
`snapshot.publicationManifestDigest`	string	`sha256:` of the hub publication manifest the export downloaded.
`files[]`	array	Every file of the export except signature envelopes and public key files, sorted by `path` (ordinal), each path once.
`files[].path`	string	Relative to the export directory, forward slashes, no `..` segment.
`files[].role`	string	`core-db`, `companion-db`, `combined-manifest`, `core-manifest` or `companion-manifest`.
`files[].sha256`	string	`sha256:` and the lowercase hex SHA-256 of the file’s bytes.
`files[].sizeBytes`	integer	The file’s size in bytes.

An export lists exactly one core-db and one core-manifest, and a companion-db with its companion-manifest only when the share-alike companion was written. intelligence-manifest.json itself is not listed: it is the payload.

Envelope

{
  "payloadType": "application/vnd.stellaops.vuln-intelligence-manifest.v1+json",
  "payload": "<base64 of the canonical payload bytes>",
  "signatures": [
    { "keyid": "<key id>", "sig": "<base64 signature>" }
  ]
}

payload is the RFC 8785 canonical JSON of the manifest; intelligence-manifest.json holds the same bytes. A payload that is not byte-identical to its canonical form is refused.
Each signature covers the DSSE pre-authentication encoding of the payload type and the payload bytes.
A vendor export is signed with the vendor intelligence key; its keyid is the key’s vendor root-set identifier (sha256: and the SHA-256 of its SubjectPublicKeyInfo). An operator who re-exports may sign with a tenant key instead; that signature verifies only against a root the operator configures explicitly, never against the vendor set.

Verification rules

A consumer refuses the export, with a stated reason, when:

the envelope is not valid JSON, has another payload type, has no signature, or no signature verifies under a trusted root;
the payload is not canonical, does not match the schema, lists a path twice, or lacks the core-db or core-manifest entry;
a listed file is missing, or its size or SHA-256 differs;
a database file (*.sqlite) is present in the export directory but not listed.

An export without intelligence-manifest.dsse.json is unsigned. A consumer refuses it unless the operator passes the explicit unsigned override, and then reports the database as unsigned in its output. Verification needs no network. It does not refuse an old snapshot: consumers show the snapshot version and time so the operator sees how current the intelligence is.

Examples

examples/vuln-intelligence-manifest.v1.valid.json lists the five files of an export with a share-alike companion. Its digests are illustrative.
examples/vuln-intelligence-manifest.v1.invalid.json is refused: snapshot.publishedAt is missing, the publication digest is uppercase, the only file path climbs out of the export with .., and the core manifest is not listed.

The examples are payloads only. Vendor signing keys never enter the product or this repository; tests sign with keys they generate.