Docs / The attestation record

The attestation record

SafeGrd keeps an append-only record of when each snapshot was created, when it was tested, and what was restored. You can verify the chain offline with SafeGrd's public key.

How the chain works

Each Fire Drill produces a certificate, and every certificate carries the hash of the one before it. The first record has no certificate before it, so its PrevHash is the literal string genesis. SafeGrd's attestation key signs each certificate with Ed25519.

Edit an older certificate and every hash after it stops matching. Remove one and the next record links to nothing. Change a date and the signature no longer verifies.

For a database, the drill record also lists each table whose row count changed since the previous backup. The list is table_changes, and table_changes_from names the backup it was compared with (the one Threat Shield compared it with). The list also names the tables added and gone, and counts the unchanged ones.

The list stops at 200 tables, largest change first, and table_changes_omitted counts the rest. A partition rotated out for a newer one of the same name shows as one table gone and one added. The signature covers a SHA-256 digest of the list, so a changed count fails the check. A record from before 30 October 2026 has no list and verifies as it always did. To verify a record that has one, use safegrd verify history from a CLI released after that date.

Three certificates in a chain. The first has PrevHash genesis. Each later one carries the SHA-256 of the one before, and each is signed with Ed25519. certificate 1 PrevHash: genesis Ed25519 certificate 2 PrevHash: SHA-256 of 1 Ed25519 certificate 3 PrevHash: SHA-256 of 2 Ed25519
Change certificate 1 and the hash in certificate 2 no longer matches. Remove one and the link breaks.

Verify it yourself

# check the full chain for a host against SafeGrd
safegrd verify history --node node-prod-db-primary
# machine-readable, for a compliance pipeline
safegrd verify history --node node-prod-db-primary --json

The command checks that:

When the signing key changes

Each record names the key that signed it (signing_key_id). When SafeGrd rotates its attestation key, the old key's public half stays published at /api/v1/attestations/public-key under retired, with the time it stopped signing. The records it signed keep verifying.

safegrd verify history checks each record under its own key. It prints which keys signed the chain and how many records each signed. It refuses a record signed with a retired key if the record is dated after the key retired, or if it follows a record signed with the newer key.

A key rotation. Records 1 and 2 are signed with key A. Key A is retired at time T and its public half stays published under retired, with T. Record 3 is signed with key B and verifies. A record signed with key A and dated after T is refused. record 1 signed with key A record 2 signed with key A key A retired at T record 3 signed with key B, verifies a record after T signed with key A: refused public-key active: B retired: A stopped signing at T
Each record is checked under the key it names, so records signed before the rotation keep verifying. A record signed with a retired key, dated after it retired or following a record under the newer key, is refused.

Offline and air-gapped audit

# online, on an enrolled host: check the chain and save it, with the public key
safegrd verify history --save ./exported-chain.json
curl -s https://safegrd.dev/api/v1/attestations/public-key | jq -r .public_key > ./attestation.pub
# later, with no network at all
safegrd verify history --file ./exported-chain.json --key file:./attestation.pub

Give an auditor the exported JSON and the public key, and they can verify the chain on a machine with no network. --key also takes the hex key inline. Either way, every record is checked against that one key. For a chain that spans a key rotation, save the published key set while you are online and pass that instead:

# the active key and every retired one, as one file
curl -s https://safegrd.dev/api/v1/attestations/public-key > keys.json
safegrd verify history --file ./exported-chain.json --keys-file ./keys.json
# or without the CLI: paste both files into /tools/attestation-verifier

An offline check cannot see records the file leaves out. For a chain exported before a key rotation, also run safegrd verify history --node against the server, which walks every record the server holds, and compare the two.

You check an Evidence Pack the same way, using the file as it was downloaded. Run safegrd verify history --file evidence-pack.json, or paste it into the verifier page. The pack holds every host's records, and each host's chain is checked on its own.

A pack for one quarter starts each chain partway through. For each host, it names the record just before the quarter in chain_anchors, and that host's first record in the pack has to link to it. The pack carries the keys that signed it. The check uses those unless you pass --key or --keys-file with keys you saved yourself.

The console can also download the pack as a PDF, laid out for an auditor who reads on paper. The PDF is written from the JSON and has no signature of its own. Give the auditor both files and run the check on the JSON.

Sample records

You can download and check these files. They come from a demo organization, where the daemon backed up a PostgreSQL database and a directory into a bucket under S3 Object Lock in compliance mode. It then restored the database into an empty one and compared it with the backup.

FileWhat it is
certificate.jsonOne drill’s signed record: what was restored, every check and its result, and the hash of the record before it.
drill-chain.jsonEvery drill record for that database, oldest first, as the chain the command below checks.
attestation-key.txtThe Ed25519 public key of the demo server, which signed them, hex-encoded. It is not safegrd.dev’s key, so check these files against this one.
evidence-pack.jsonThe Evidence Pack a Scale organization downloads: drill records, snapshot retention and the controls they are evidence for. It is not a certification or an audit opinion.
evidence-pack.pdfThe same pack as the PDF the console downloads, for an auditor who reads on paper. The signatures are over the JSON records, so a check runs on the JSON file.
# check the sample chain offline
safegrd verify history --file drill-chain.json --key file:attestation-key.txt
# and the sample Evidence Pack, two hosts' chains
safegrd verify history --file evidence-pack.json --key file:attestation-key.txt

Change any field in drill-chain.json and the same command reports the record whose signature no longer matches.

Public certificates

An owner or admin can publish a passed drill as a page that anyone with the link can open. In the console, open the Fire Drills tab, choose History, then Certificate on the drill, and Publish certificate.

The link looks like https://safegrd.dev/c/sgc_…. The address is random, so nobody finds a certificate unless you give them the link, and search engines are told not to list it. Withdraw turns the link off within a minute. If you retire the surface, every certificate published from it is turned off.

The page shows:

By default it shows nothing else: no table or file names, row or file counts, sizes, restore times, surface names, host names, snapshot ids or storage.

An owner or admin can add the surface’s name, the restore time and what was restored (tables and rows, files and directories, or emails and folders). Click Change under Badge and public page on the Fire Drills tab. The choice applies to every public certificate the organization publishes. Host names, snapshot ids and storage are never shown. Members of the organization see the whole record in the console.

A surface’s page, for a README badge

A drill’s certificate covers one point in time. For a link that stays current, publish the surface’s page from Badge and public page on the Fire Drills tab. Its address, https://safegrd.dev/c/sgs_…, shows the surface’s newest passed drill. While the page is published, every drill that passes is published with it. The badge markdown the console gives you links to this page.

If a newer drill did not pass, the page says so and shows no seal. When you withdraw the page, the drill certificates it published are withdrawn too. Drills you published one by one stay published.

A project’s page

To show every surface in a project on one page, publish it from Project pages on the same card. Its address is https://safegrd.dev/c/sgp_…. For each surface it lists the kind, the last backup and the newest drill, read when the page is opened and signed the same way. Where a surface has its own page, the project page links to it. The seal shows when every surface’s newest drill passed.

Unlike a surface’s page, the project page says how many surfaces the project has and what kind they are. Surface names appear only if you chose to show them under What certificates show. Withdrawing the project page leaves surface pages and drill certificates as they were.

The page checks the certificate’s Ed25519 signature in the browser before it shows the seal. To check it yourself, without the page, use OpenSSL 3:

# the signed statement, and its signature
curl -s https://safegrd.dev/api/v1/certificates/sgc_… > cert.json  # or sgs_…, sgp_…
jq -j .statement cert.json > statement.json
jq -r .signature cert.json | xxd -r -p > statement.sig
# the attestation public key, as PEM
curl -s https://safegrd.dev/api/v1/attestations/public-key | jq -r .public_key \
  | sed 's/^/302a300506032b6570032100/' | xxd -r -p | openssl pkey -pubin -inform DER -out safegrd.pem
# prints "Signature Verified Successfully"
openssl pkeyutl -verify -pubin -inkey safegrd.pem -rawin -in statement.json -sigfile statement.sig

The statement’s record field ties it to the full drill record without showing the record. It is the SHA-256 of a random salt, a |, and the record’s signed fields. The console shows the salt and the command that recomputes the hash, so you can show an auditor which record a certificate stands for.

When a report does not reach us

A backup still completes if its report does not reach SafeGrd. The CLI prints a warning to stderr, and the backup counts as done on the host. The run is marked attested only after SafeGrd acknowledges its report, so the host and the attestation record agree on which runs were recorded.