Skip to content

docs: expand levels page with concrete record examples per level #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
imran-siddique merged 2 commits into from
Jun 21, 2026
Merged

docs: expand levels page with concrete record examples per level #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e8a482
docs: expand levels page with concrete record examples per level
imran-siddique Jun 21, 2026
ee1cf8c
docs: add How to fix column to all error code tables
imran-siddique Jun 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 33 additions & 33 deletions docs/error-codes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,54 +4,54 @@ All TRACE test failures emit a structured error code of the form `TR-<MODULE>-<N

## TR-ENV — Envelope

| Code | Description |
|------|-------------|
| TR-ENV-001 | Missing or invalid `eat_profile` URI |
| TR-ENV-002 | `iat` is missing, not an integer, or out of range |
| TR-ENV-003 | `subject` does not match SPIFFE URI or DID pattern |
| TR-ENV-004 | One or more required fields are absent |
| Code | Description | How to fix |
|------|-------------|------------|
| TR-ENV-001 | Missing or invalid `eat_profile` URI | Set `eat_profile` to `"tag:agentrust.io,2026:trace-v0.1"` |
| TR-ENV-002 | `iat` is missing, not an integer, or out of range | Set `iat` to a Unix timestamp integer (e.g. `int(time.time())`) |
| TR-ENV-003 | `subject` does not match SPIFFE URI or DID pattern | Use `spiffe://<trust-domain>/<path>` or a `did:` URI |
| TR-ENV-004 | One or more required fields are absent | Add the missing field(s); check the [Schema Reference](https://trace.agentrust-io.com/schema) for the full required set |

## TR-SIG — Signature

| Code | Description |
|------|-------------|
| TR-SIG-001 | Signature algorithm is not Ed25519 |
| TR-SIG-002 | `cnf.jwk` missing or malformed |
| TR-SIG-003 | Signature verification failed |
| TR-SIG-004 | Private key material (`d` member) found in `cnf.jwk` |
| Code | Description | How to fix |
|------|-------------|------------|
| TR-SIG-001 | Signature algorithm is not Ed25519 | Generate an Ed25519 key (`generate_key()`) and re-sign; ES256 and RS256 are not accepted |
| TR-SIG-002 | `cnf.jwk` missing or malformed | Populate `cnf.jwk` with the OKP public key `{"kty":"OKP","crv":"Ed25519","x":"..."}` — `sign_record()` does this automatically |
| TR-SIG-003 | Signature verification failed | Re-sign the record with `sign_record(record, key)`; the record fields must not have changed after signing |
| TR-SIG-004 | Private key material (`d` member) found in `cnf.jwk` | Remove the `d` field before embedding the JWK; `key_to_jwk()` returns the public-only form |

## TR-RTE — Runtime

| Code | Description |
|------|-------------|
| TR-RTE-001 | `runtime.platform` is not a recognised TEE enum value |
| TR-RTE-002 | `runtime.measurement` is not a valid `sha256:` digest |
| TR-RTE-003 | RIM URI present but does not resolve to a valid reference image |
| Code | Description | How to fix |
|------|-------------|------------|
| TR-RTE-001 | `runtime.platform` is not a recognised TEE enum value | Use one of: `software-only`, `tpm2`, `sev-snp`, `tdx`, `opaque` |
| TR-RTE-002 | `runtime.measurement` is not a valid `sha256:` digest | Provide a 64-character hex digest prefixed with `sha256:`; for Level 0 all-zeros is conventional |
| TR-RTE-003 | RIM URI present but does not resolve to a valid reference image | Remove `runtime.rim_uri` if not using a RIM, or ensure the URI returns a valid reference manifest over HTTPS |

## TR-POL — Policy

| Code | Description |
|------|-------------|
| TR-POL-001 | `policy.bundle_hash` is not a valid `sha256:` digest |
| TR-POL-002 | `policy.enforcement_mode` is not `enforce`, `advisory`, or `silent` |
| Code | Description | How to fix |
|------|-------------|------------|
| TR-POL-001 | `policy.bundle_hash` is not a valid `sha256:` digest | Compute `sha256:` + hex digest of your Cedar policy bundle bytes |
| TR-POL-002 | `policy.enforcement_mode` is not `enforce`, `advisory`, or `silent` | Replace `"strict"` or `"monitor"` with `"enforce"`, `"advisory"`, or `"silent"` |

## TR-TXN — Transcript

| Code | Description |
|------|-------------|
| TR-TXN-001 | `tool_transcript.hash` is not a valid `sha256:` digest |
| TR-TXN-002 | `tool_transcript.call_count` is negative or not an integer |
| Code | Description | How to fix |
|------|-------------|------------|
| TR-TXN-001 | `tool_transcript.hash` is not a valid `sha256:` digest | Set `tool_transcript.hash` to `sha256:` + 64 hex chars of the Merkle root of the tool call log |
| TR-TXN-002 | `tool_transcript.call_count` is negative or not an integer | Set `tool_transcript.call_count` to a non-negative integer (0 is valid for sessions with no tool calls) |

## TR-ANC — Transparency

| Code | Description |
|------|-------------|
| TR-ANC-001 | `transparency` field missing or empty |
| TR-ANC-002 | `transparency` URI does not use `https://` scheme |
| Code | Description | How to fix |
|------|-------------|------------|
| TR-ANC-001 | `transparency` field missing or empty | Submit the record to a SCITT transparency log and set `transparency` to the returned receipt URI |
| TR-ANC-002 | `transparency` URI does not use `https://` scheme | Only `https://` URIs are accepted; update the URI or use the agentrust registry at `https://registry.agentrust.io` |

## TR-SCA — Provenance

| Code | Description |
|------|-------------|
| TR-SCA-001 | `build_provenance.slsa_level` is not 0–4 |
| TR-SCA-002 | `build_provenance.digest` is not a valid `sha256:` digest |
| Code | Description | How to fix |
|------|-------------|------------|
| TR-SCA-001 | `build_provenance.slsa_level` is not 0–4 | Set `build_provenance.slsa_level` to an integer 0–4 matching your SLSA build level |
| TR-SCA-002 | `build_provenance.digest` is not a valid `sha256:` digest | Set `build_provenance.digest` to `sha256:` + 64 hex chars of the container image or artifact digest |
150 changes: 150 additions & 0 deletions docs/levels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,160 @@ TRACE defines three conformance levels. Higher levels require all lower-level mo
| **1** | Level 0 + TR-RTE, TR-SCA | Production TEE-attested records |
| **2** | Level 1 + TR-TXN, TR-ANC | Full records with transparency anchoring |

## Level 0 — Software-only

Level 0 records are signed with a software key. The `runtime.platform` must be `"software-only"`. All-zero measurement is conventional for development use.

**Minimum conformant Level 0 record:**

```json
{
"eat_profile": "tag:agentrust.io,2026:trace-v0.1",
"iat": 1750000000,
"subject": "spiffe://trust.example.org/agent/my-agent",
"model": {
"provider": "anthropic",
"model_id": "claude-sonnet-4-6",
"version": "20251001"
},
"runtime": {
"platform": "software-only",
"measurement": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
},
"policy": {
"bundle_hash": "sha256:b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
"enforcement_mode": "enforce"
},
"data_class": "internal",
"build_provenance": {
"slsa_level": 1,
"digest": "sha256:e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6"
},
"appraisal": {
"status": "none",
"verifier": "https://verifier.example.org"
},
"transparency": "https://registry.agentrust.io/claim/placeholder",
"cnf": {
"jwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
}
},
"signature": "eyJhbGciOiJFZERTQSJ9..."
}
```

**Modules tested:** TR-ENV, TR-SIG, TR-POL

**What causes a Level 0 failure:**

- `eat_profile` missing or wrong value — TR-ENV-001
- `runtime.platform` is a TEE value (e.g. `sev-snp`) but Level 0 is requested — TR-RTE-001 does not apply, but TR-ENV still checks the envelope
- `policy.enforcement_mode` is `"strict"` or `"monitor"` — TR-POL-002
- `cnf.jwk` missing or contains private key material (`d` field) — TR-SIG-002, TR-SIG-004
- Signature does not verify against `cnf.jwk` — TR-SIG-003

---

## Level 1 — TEE Attestation

Level 1 adds hardware attestation. `runtime.platform` must be one of: `tpm2`, `sev-snp`, `tdx`, `opaque`. The measurement must be non-zero. `appraisal.status` must be `"affirming"`.

**Minimum conformant Level 1 record** (changes from Level 0 in bold context):

```json
{
"eat_profile": "tag:agentrust.io,2026:trace-v0.1",
"iat": 1750000000,
"subject": "spiffe://trust.example.org/agent/my-agent",
"model": {
"provider": "anthropic",
"model_id": "claude-sonnet-4-6",
"version": "20251001"
},
"runtime": {
"platform": "sev-snp",
"measurement": "sha256:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
},
"policy": {
"bundle_hash": "sha256:b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
"enforcement_mode": "enforce"
},
"data_class": "confidential",
"build_provenance": {
"slsa_level": 2,
"digest": "sha256:e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6"
},
"appraisal": {
"status": "affirming",
"verifier": "https://verifier.agentrust.io"
},
"transparency": "https://registry.agentrust.io/claim/placeholder",
"cnf": {
"jwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
}
},
"signature": "eyJhbGciOiJFZERTQSJ9..."
}
```

**Modules tested:** TR-ENV, TR-SIG, TR-POL, TR-RTE, TR-SCA

**What causes a Level 1 failure over Level 0:**

- `runtime.platform` is `"software-only"` — TR-RTE-001
- `runtime.measurement` is all zeros — TR-RTE-002 (all-zero is invalid at Level 1)
- `build_provenance` missing entirely — TR-SCA-001, TR-SCA-002
- `appraisal.status` is `"none"` — while not a hard schema violation, a conformant Level 1 record should carry `"affirming"`

---

## Level 2 — Transparency Anchoring

Level 2 adds tool transcript and transparency anchor requirements. The `transparency` field must be a resolvable HTTPS URI pointing to a SCITT receipt, not the placeholder value.

**Minimum conformant Level 2 record** (additional fields over Level 1):

```json
{
"tool_transcript": {
"hash": "sha256:c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
"call_count": 4
},
"transparency": "https://registry.agentrust.io/claim/01J3XKWP4NQZ8R5HT6YD7VMBCE",
"anchor": {
"log_id": "https://registry.agentrust.io",
"leaf_hash": "sha256:f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5"
}
}
```

**Modules tested:** TR-ENV, TR-SIG, TR-POL, TR-RTE, TR-SCA, TR-TXN, TR-ANC

**What causes a Level 2 failure over Level 1:**

- `tool_transcript.hash` missing or not a valid `sha256:` digest — TR-TXN-001
- `tool_transcript.call_count` negative or not an integer — TR-TXN-002
- `transparency` is the placeholder URI, missing, or not HTTPS — TR-ANC-001
- `anchor.leaf_hash` missing or not a valid `sha256:` digest — TR-ANC-002

---

## Choosing a level

- Use **Level 0** during development. Records can use `runtime.platform: "software-only"` and `build_provenance.slsa_level: 0`.
- Use **Level 1** for production deployments in a TEE (AMD SEV-SNP, Intel TDX, NVIDIA H100).
- Use **Level 2** when you need an auditable, tamper-evident log with a SCITT transparency service.

The certification program (launching 2027) will require Level 1 at minimum.

## Related

- [Error Codes](error-codes.md) — every TR-* error with description and fix
- [Test Modules](modules/index.md) — per-module test lists with positive and negative cases
- [TRACE Trust Levels](https://trace.agentrust-io.com/trust-levels) — full specification of what each level proves
Loading