Issue and share a certificate

A certificate reports what a finished check found and what it did not cover, signed so that others can see whether anyone changed it. This guide takes you from a finished check to a folder you can hand to a reviewer, and to an evidence export for auditors.

Before you start

A certificate is made from a finished check that tried your agent’s tasks. If you have not run one, start with Check your agent. The certificate is about the code and settings as they were when the check ran.

A certificate you issue is signed with a key made on your own computer. That shows nobody changed it. It does not show who issued it, and it is not an independent assessment. See Prove and certificates.

Create and read it

Run geo assessment create. Geometer builds the report from the newest finished check of the project and signs it with your computer’s key. Nothing is signed until you run it. Creating it again for the same check returns the same report.

geo assessment show <id> reads the report in plain words: What the check found, then “Is it unchanged since it was signed?” and “Does it still apply to the current code and settings?”, then Rule by rule and what was not reached. geo assessment show <id> --html shows the page a recipient would open, before anything leaves your computer.

To also sign with the newer post-quantum method, add --profile hybrid. It is off by default, makes a larger file, and the person checking needs both of your computer’s public keys.

geo assessment create
geo assessment list
geo assessment show <id>

Share it

Run geo assessment export. Geometer writes a folder in its own records folder, never in your project. It holds a page you can read without Geometer or a network (index.html, with the three gauges as separate sections and no script), the evidence that may leave your computer, and a file for checking the report. Private evidence stays on your computer. Anything that looks like a password or key is withheld.

To share publicly, add --public. It makes a separate copy, with its own name, with all private evidence left out. The original report is not changed.

geo assessment export <id> --out ./share
geo assessment export <id> --out ./share-public --public

Add --include-private to the first command only if the recipient may see private evidence.

Give the recipient the folder and your public key by a route they trust, for example geo assessment key --out <where to save the key>. They check the report with the open verifier or with geo assessment verify. See Verify records yourself.

Share a link

A link lets someone open your certificate in a browser without installing anything. It is opt in, one certificate at a time. Nothing is uploaded unless you run geo certificate publish for that certificate. Certificate links are built but not switched on yet: until Geometer sets up the service, publishing shows you the preview and then says there is nowhere to publish to. If you run your own service you can publish to it with --to.

geo certificate publish <id>
geo certificate publish <id> --preview
geo certificate unpublish <id>
geo certificate published

Before anything is sent, you see exactly what will be uploaded: every file and its size, the report’s title, the rules it names and the code version (these can reveal what your project is), the issuer key’s four-word fingerprint, and three sentences: anyone with the link can read it; it stays until you remove it; Geometer stores it and did not check it. Then you confirm. In a script, --yes confirms and the preview is still printed. The upload is the same bytes the preview was built from; if the certificate changed in between, it is refused.

What is public. The separate public copy of the certificate (private evidence left out, anything that looks like a password or key withheld), the evidence allowed to leave your computer, the signed status, your public key and key log, and a random id of this computer inside the signed status entries. What is not. Private evidence, your project folder, file paths on your computer, the Prove record, call details and your secret key. There is no name, email or account.

Who it is published by. You, the builder. The page says “Stored by Geometer. Geometer did not check this certificate.” It never claims that Geometer checked or vouched for it. The link ends in #k= and your key’s id: the part after # is never sent to the server, and it lets the reader’s browser confirm the key is the one you meant. Give the reader the issuer’s key by another route, as for a shared pack.

What the page checks. In the reader’s browser it checks that the stored bytes match the link, that the key you published with sent them, and that the key is the one in the link. It does not yet check the certificate’s own signature or its rules; for that, download the file and run geo-verify assessment with your key (see Verify records yourself).

Remove it. geo certificate unpublish <id> sends a delete signed with the certificate’s key. No account or password is involved; only that key can remove it. The page then says the publisher removed it, and only the id and the time of removal are kept. Copies someone already saved cannot be recalled, and a cached copy can show for a few minutes. If you have lost the key, write to hello@geometer.dev.

Track whether it still applies

When your code changes after you issue a certificate, the answer to “Does it still apply to the current code and settings?” changes. Run geo check again, then create a new report from the new check with geo assessment create. The old certificate’s results are never rewritten.

A few commands keep a report’s status honest:

• geo assessment status <id> shows the signed status: issued, replaced, marked as no longer applying or withdrawn.
• geo assessment withdraw <id> --reason "..." records that you no longer stand behind the report. Its results are kept as they were.
• geo assessment invalidate <id> --because subject_changed --reason "..." marks it as no longer applying because something changed. The reasons are subject_changed, rule_changed, config_changed, environment_changed, dependency_changed, model_changed, policy_changed and exception_changed.
• geo assessment renew <id> keeps today’s check of the report with a fresh signed status and an anchor of the record.

To have the recheck run on every change, use geo ci in your pipeline. See Run kept checks in CI.

Evidence for auditors

geo prove export --out <folder> collects the evidence record and an anchor in one folder on your computer. Nothing is sent anywhere. The folder holds the evidence as JSON, CSV and an OpenTelemetry trace file. Add the exported certificate folder from geo assessment export for the report itself. The export cannot answer anything outside Guard, or whether the agent behaved correctly in production.

• Run kept checks in CI (Make the check run on every change.)
• Verify records yourself (What a recipient can check.)