Catch boot-config drift with cohort prevalence
Every attestation already proves the hard things: real hardware, Secure Boot state, dbx revocation, EAR status. Cohort prevalence adds one optional signal on top. How common is this device's boot configuration among devices like it? Use it to flag the one laptop whose bootloader nobody else in your fleet runs, without false-positiving the 999 that are fine.
Prevalence is an AND-constraint evaluated after every explicit check passes. It can add a reason to reject; it can never remove one. A device that fails Secure Boot or presents an emulated TPM is rejected no matter how common its profile is, so you can turn this on without weakening anything you already enforce.
Where it sits
You don't compute anything: the cohort claims ride on every attestation for free. You decide two things: (1) whether to gate on a prevalence floor in your policy, and (2) which population to compare against. global is every device of the same make/model/firmware on the network (advisory); tenant-fleet is only your own managed devices, an empirical golden image you can safely hard-gate.
1 · Client — nothing to change
The cohort claims are emitted on every appraisal, so your existing flow is all you need. The dumb client just collects an opaque evidence blob (over a nonce your server minted) and posts it to your backend, with no keys and no Root Herald contact:
import { attest } from "@rootherald/browser";
// The same collection you already do. Cohort claims come back automatically
// in the server's verdict — no flags, no extra round-trips.
const evidence = await attest(nonce); // nonce relayed from your server
await fetch("/api/session", {
method: "POST",
body: JSON.stringify({ challengeId, evidence }),
});2 · Server — read the claim, act on it
Appraise with rh.verify(); the verdict carries the cohort claims whether or not your policy gates on them. Read them, log them, alert on them; gating is opt-in.
import { RootHerald } from "@rootherald/node";
const rh = new RootHerald({ secretKey: process.env.RH_SECRET_KEY! }); // rh_sk_…
// Earlier: rh.issueChallenge() -> relay nonce to the client.
const v = await rh.verify(body.evidence, {
challengeId: body.challengeId,
policy: "rootherald:builtin:strict-hardware",
});
if (v.device.verdict !== "pass") return forbid("device_check_failed");
// The explicit checks already decided pass/fail. These are the cohort signals,
// carried on verdict.device alongside the rest of the device attestation result:
// v.device.cohortPrevalence number | null weakest-link prevalence, 0–1 (null = cold start)
// v.device.novelProfile boolean too rare, or cohort too small to judge yet
// v.device.cohortScope "global" | "tenant-fleet"
// v.device.cohortSampleSize number distinct real devices in the denominator
// v.device.cohortPrevalencePerPcr { "0":…, "4":…, "7":… } firmware / bootloader / Secure-Boot
if (v.device.novelProfile) {
// A new-but-legitimate firmware build is novel until adoption grows. Don't hard-block —
// log it, or require a step-up, depending on how strict this action is.
await audit.log("novel_device_profile", { deviceId: v.device.ueid, sample: v.device.cohortSampleSize });
}
if (v.device.cohortPrevalence !== null && v.device.cohortPrevalence < 0.01) {
// Bottom 1% of its cohort — worth a second look for a sensitive action.
await reviewQueue.add(v.device.ueid, { prevalence: v.device.cohortPrevalence });
}cohortPrevalence is the minimum across the three tracked low-variance PCRs: firmware (PCR[0]), bootloader (PCR[4]), Secure Boot policy (PCR[7]). If your firmware is common but your bootloader is one-in-a-million, you score one-in-a-million. A nullvalue means the cohort is still too small to estimate; handle it as "unknown," never as a silent reject.3 · Gate it in the dashboard (the 0–1 policy)
To enforce a floor instead of just reading the signal, set it on the policy your project uses. Open Dashboard → Policies, edit the policy (or create one), and find the Cohort prevalence (optional) section.
Policies → (your policy) → Cohort prevalence (optional). Toggle Enforce a minimum cohort prevalence on. The slider is the 0–1 floor, shown as a percentage: drag it to, say, 5% (0.05).
Then pick the two behaviours that make this safe to turn on:
- Cohort scope. Start with
global(advisory: you're comparing against the whole network and the default behaviour iswarn). Switch totenant-fleetonce you have enough of your own devices enrolled; that compares against your golden image and is the one you can safely hard-gate. - On novel profile. What happens below the floor (or when the cohort is too small):
warnannotates the verdict and degrades the configuration trust vector (default, recommended while you tune the number),step-updemands a fresh re-attestation,rejectcontraindicates.
Cohort scope set to tenant-fleet and On novel profile set to step-up, the recommended pairing once your fleet data is warm: rare-for-your-fleet devices get a re-attestation challenge rather than a hard block.
A brand-new firmware build is legitimately rare until adoption grows, and a freshtenant-fleethas too few devices to judge anything. That's why the default is warn and why prevalence reads null below the sample floor. Run in warn first, watch the cohortSampleSize climb in your logs, then tighten to step-up / reject once the denominator is meaningful.
4 · Allowlist the legitimate-but-rare ones
Some of your own devices will legitimately be rare: a new hardware refresh, a pre-release firmware. Those land in Dashboard → Cohort allowlistas a review queue; one click approves a profile so it satisfies the constraint for your tenant's policies, without loosening anything for anyone else.
Cohort allowlist → review queue. A novel profile your devices presented, with its cohortKey and per-PCR values, plus a one-click Approve.