Collector-Attested Receipts

What it is

A collector-attested receipt is a proof receipt whose number was measured by a collector running inside your own network, and signed there with a key that never leaves your boundary. It answers a fair question from a relying party: did this number come from the supplier's network, or did the platform make it up?

How it works:

The collector (cmdash-collector) generates an Ed25519 key on its own host. CMDash only ever sees the public half.
For each measurement, the collector signs a statement of the counts (numerator, denominator, unknown), the metric, the time it measured, and the deployment and tenant it belongs to.
CMDash builds an ordinary receipt from that measurement. The receipt names the collector key as its source, and uses the collector's own measured-at time as its observation time, so it can never claim to be fresher than the collector signed.
The collector's signature travels next to the receipt as a companion document (GET /proof/receipts/<receiptId>/collector-attestation). A verifier that knows the companion reports ATTESTED. A verifier that does not still sees an ordinary, valid measured receipt.

Two metrics can be attested today: endpoint-detection coverage (hosts) and MFA enrolment (users). They issue as the claims collector-attested.si.malicious-code-protection and collector-attested.ia.mfa-enrolled, each fresh for 14 days.

When to use it

When a relying party wants more than "CMDash says so": for example an insurer or a prime that asks whether a coverage number was measured inside your network. Skip it when the number you already issue from connected integrations is enough.

Before you start

Tier: collectors run custom connectors, so enrolling one needs the custom connectors entitlement (Command and above).
Role: enrolling a collector, issuing a key registration token and revoking a collector are OWNER or ADMIN. There is no screen for this yet: enrolment is by API (POST /collectors, POST /collectors/<id>/key-token) and the collector is the cmdash-collector command. See the developer reference and the install runbook (docs/runbooks/collector-install.md).
The collector binary must be one you can obtain. Check that your delivery channel serves it before relying on this.

How to

Enrol an attesting collector

Enrol with attested: true, or issue a key registration token for an existing enrolment. The token is one-time, lives 24 hours, and CMDash stores only its hash. Issuing one moves the enrolment to signature version 2 for good: from then on it refuses every push until a key is registered, so there is no window in which an older, weaker push is accepted.
On the collector host run cmdash-collector enroll --enrollment-id <id> --registration-token <token> --identity-file ./collector-identity.json. It generates the key (file mode 0600, never overwritten, refused if other users can read it, never sent or printed) and registers it with a proof that it holds the private key.
Run the collector as before. Each push now carries an Ed25519 signature over its body, which includes every attested measurement.
A new receipt is issued from the newest attested measurement the next time receipts are refreshed at /proof.

To replace a key, run cmdash-collector rotate-key --identity-file ./collector-identity.json (signed by both the old and new key), or issue a new registration token. The old key is retired, and both routes are audited.

Check one (relying party)

Get the receipt and its companion document, then:

code

cmdash-verify receipt.json --fetch --deployment <the issuing origin> \
  --collector-attestation attestation.json \
  --collector-key <deployment>#<tenantRef>=<supplier-collector-key.pem> \
  --require-collector-attestation

Pinning the collector key (--collector-key) with a key you obtained from the supplier is what makes the result independent of the issuing deployment. Without it, the key is only "issuer-named": the receipt's own signed sources name it, and the check says in plain words that a deployment that fabricated both the receipt and a collector key would look consistent. --require-collector-attestation makes a receipt whose attestation is not ATTESTED exit non-zero.

What it proves and what it does not

Proves: the holder of the collector key signed exactly this statement, and the statement names this receipt's issuer, metric, counts and observation time, and the receipt names that key. With a pinned key, also that the key is one you got from the supplier.
Does not prove: that the supplier's own system reported the truth to its collector; that the key is the supplier's rather than one the issuing deployment chose (unless pinned); or that the key had not been revoked, when no revocation time is known to an offline check.

Common questions

What if the collector is revoked? Revoking a collector revokes its keys from that instant. Receipts issued before it stay verifiable and are shown as attested with the revocation time; a receipt issued at or after it fails as a mismatch, and CMDash signs nothing new from it.

Does a collector-attested receipt replace the normal one? No. It is an additional claim. The ordinary receipt for the same control is unchanged.

Is a receipt without the companion any weaker? It is an ordinary valid measured receipt. It just carries no evidence about where the measurement was taken.

Is the list of items in the measurement signed by the collector for the relying party? The per-item states are covered by the push signature to CMDash, not the portable statement. An auditor who samples an item sees what the push carried, attested to CMDash, not to the relying party.

Proof receipts
Verifying a proof receipt
The specification: docs/specs/collector-attestation-v0.md

This page is the product manual, published from the repository at docs/user/feature-guides/collector-attested-receipts.md. Customers read the same text inside CMDash under Help. Last updated October 4, 2026.