Checking a native evidence package on your own systems

Implementation status — verify against src/. Checker version 1 is stella evidence check-package (src/Cli/StellaOps.Cli/Commands/EvidenceCheckPackageCommand.cs, src/Cli/StellaOps.Cli/Services/EvidencePackageChecker.cs), specified by RFC-0003. It reaches operators with the next CLI release. It supports ED25519 and ES256 package signatures and no time or log evidence profile.

This guide is for the operator who wants a per-check report on a native evidence package (bundle.tgz) that the organisation’s own Installation produced.

How the checker works

You run the command on your own systems. It reads only the files you name, makes no network request, and writes the report where you say. It sends nothing to Stella Ops, and Stella Ops receives no package, material, report or result.
Stella Ops signs nothing about the package or the report. You may sign the report with your Installation’s own key (see Sign the report).
You decide which keys are trusted. Key trust (check C6) comes only from the trust list you pass with --trusted-key. The Stella Ops entitlement record is not an input: it serves licence administration only, and the checker does not read it. See the vendor operating rules in eidas-qtsp-posture.md§6.
The report describes local execution: its operatingModel reads “Checked locally with Stella Ops checker version <version> under customer control”. It never states that Stella Ops verified a package.
Each check has its own result. There is no overall verdict.

Before you start

The package. Download the sealed bundle’s native package with GET /api/evidence/v1/evidence/{bundleId}/download (scope evidence:read); see bundle packaging. Record its SHA-256 before you move it.
Your trust list. Collect the public keys you trust for evidence of this Installation, as SubjectPublicKeyInfo PEM files or a JSON Web Key Set. The Evidence service publishes its bundle signing public keys at /api/evidence/v1/evidence/capsules/signing-keys/jwks (anonymous read, no private material). A key set fetched from the Installation proves nothing by itself: keep only keys whose thumbprints your organisation declared through an independent channel.
- The thumbprint is sha256: followed by the lowercase hexadecimal SHA-256 of the key’s DER SubjectPublicKeyInfo. The report prints it for every key it reads. For a PEM key you can compute it with openssl pkey -pubin -in key.pem -outform DER | sha256sum.
- The checker computes thumbprints from the key bytes. A key identifier (kid, the package’s keyId, a file name) is never trusted.
- Private key material is refused, never loaded.
Material bytes (optional). To check material bytes (C5), place each original file below one directory at the material’s canonicalPath.

Run the check

stella evidence check-package bundle.tgz --trusted-key evidence-keys.jwks.json --materials ./materials --output report.json

Option	Meaning
`<package>`	The native evidence package (`bundle.tgz`).
`--trusted-key <file>`	A public key you trust for evidence of this Installation: SPKI PEM or JSON Web Key Set. Repeatable. These keys form the trust list for C6 and are also tried for the package signature (C3).
`--package-key <file>`	A further public key to try for C3 without declaring it trusted. Repeatable. If it verifies the signature and is not in the trust list, C3 passes and C6 fails.
`--materials <dir>`	Directory with original material bytes for C5.
`--output`, `-o <file>`	Write the JSON report to this file and print a summary. Without it the report goes to standard output.
`--sign`	Sign the report with this Installation’s enrolled DSSE key; requires `--output`.

Exit codes: 0 the package was admitted and the report written, whatever the check results; 5 the package was refused at admission (the report records the reason); 1 the package file was not found; 2 --sign without --output; 4 the report was written but signing failed.

Read the report

The report is one JSON document with schema stella.ops/evidencePackageCheckReport@v1, written deterministically. Its members are schemaVersion, checker, operatingModel, checkedAt, inputs, admission, checks, statements, trust and limits.

Admission. The checker reads at most 16 archive entries, only regular files with the five package file names at the archive root, within fixed size limits. A path with a directory part or .., a link, a device entry, a repeated name or an oversize entry refuses admission, and no check runs. Package content is data: nothing in it is executed, fetched or printed as an instruction.

Checks. Each entry has a result (pass, fail, not-checked or unsupported), reasons, prerequisites and whether it rests on an authenticated payload.

Check	`pass` means
C1 checksum-list consistency	`checksums.txt` lists exactly the materials of the signed payload.
C2 signed payload equality	`manifest.json` equals the signed payload.
C3 package signature	The signature verifies over the signed payload bytes under one key you supplied; the report names the key by thumbprint and input.
C4 material root recomputation	The material root recomputed from the signed entries equals every stated root.
C5 supplied material bytes	Every listed material was supplied and matches its size and SHA-256. Materials without bytes are `not-checked`, never counted as checked.
C6 key trust	C3 passed, and the key that verified C3 is in your trust list.
C7 version-field extraction	At least one version field was extracted from the signed payload. These are package statements, not versions observed running.
C8 time and log evidence	No profile is implemented in checker version 1; each item found is `unsupported`.

C6 results in detail:

Result	Reason	Meaning
`pass`	—	The key that verified C3 is in your trust list.
`fail`	`key-not-in-customer-trust-list`	C3 passed under a key you supplied with `--package-key` that is not in your trust list.
`not-checked`	`no-customer-trust-configured`	You passed no `--trusted-key`.
`not-checked`	`no-usable-trusted-key`	None of the trust-list files held a readable public key.
`not-checked`	`prerequisite-not-passed:C3`	C3 did not pass, so there is no key to compare.

Statements. Each value read from the package carries its source (for example signed-payload or unsigned-file:bundle.json), its authentication status with the checks it rests on, and the operation (extracted, recomputed, compared). A payload value counts as authenticated only when C3 passed.

Trust. For the package signature the report separates the mathematical verification (C3), the key authorisation under your trust list (C6, with each trust-list file’s name and SHA-256) and the revocation information, which is unavailable offline: the trust list states which keys you trust at the time of the check, not when a key was withdrawn or compromised. Keeping it current is your responsibility.

Sign the report (optional)

With --sign, the command signs the exact report bytes as a DSSE envelope (payload type application/vnd.stellaops.evidence-package-check-report.v1+json) with this Installation’s enrolled generic-dsse purpose key, the signing path stella attest sign uses, and writes <output>.dsse.json. A reader verifies the envelope over the report file as written, with the Installation’s public key obtained independently; the envelope keyid is only a hint. The signature is your organisation’s statement about its own document. It adds no time evidence.

What a report establishes, and what it does not

Every report carries these limits:

Results state what the package says and whether its signature binds its statements to the keys named in the report. They do not establish that the represented events happened, that Stella Ops software produced the package, or that any scan, gate or decision it describes ran or ran correctly. A correctly bound key can still sign invented content.
A key is trusted for the Installation’s evidence only as far as C6 states, and only because you configured it. The checker does not establish who holds a key. Package version 1 states no installation identifier, so C6 does not establish which Installation produced the package.
No vendor record, the Stella Ops entitlement record included, authenticates, certifies or authorises any key named in a report.
Checking a package is not executing the scans it describes. The artifacts a package names are not the whole estate. Nothing in a report establishes the absence of vulnerabilities, or compliance with any law, regulation or contract.
checkedAt is the operator’s system clock, not an assured time.

RFC-0003: the full check definitions, dependency model and report contract.
Native package verification: the manual verification steps.
Offline verification of portable bundles: stella evidence verify-offline, for the portable evidence bundle format.