diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ca03c14..12998ad 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -67,7 +67,7 @@ jobs: # host. exclude_docs drops the three that are served from the apex. if [ -d schema ]; then cp -r schema $BUILD/schema; fi - for fname in README.md CHANGELOG.md CONTRIBUTING.md GOVERNANCE.md ROADMAP.md LIMITATIONS.md PRIVACY.md CNAME robots.txt; do + for fname in index.md CHANGELOG.md CONTRIBUTING.md GOVERNANCE.md CHARTER.md CODE_OF_CONDUCT.md MAINTAINERS.md ROADMAP.md LIMITATIONS.md PRIVACY.md CNAME robots.txt; do if [ -f "$fname" ]; then cp "$fname" "$BUILD/$fname"; fi done diff --git a/README.md b/README.md index 7fb82d4..6adb783 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ [![Specification: Community Specification License 1.0](https://img.shields.io/badge/Specification-Community_Specification_License_1.0-blue.svg)](Governance/COMMUNITY-SPECIFICATION-LICENSE.md) [![Code: Apache 2.0](https://img.shields.io/badge/Code-Apache_2.0-lightgrey.svg)](LICENSE) -[![Spec](https://img.shields.io/badge/Spec-v0.1-0ea5e9)](spec/trace-v0.2.md) +[![Spec](https://img.shields.io/badge/Spec-v0.2-0ea5e9)](spec/trace-v0.2.md) [![PyPI](https://img.shields.io/pypi/v/agentrust-trace)](https://pypi.org/project/agentrust-trace/) [![CI](https://github.com/agentrust-io/trace-spec/actions/workflows/ci.yml/badge.svg)](https://github.com/agentrust-io/trace-spec/actions/workflows/ci.yml) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat)](https://discord.gg/grgzFEHgkj) @@ -29,7 +29,7 @@ TRACE Specification is an LF Project, hosted at the Linux Foundation as its own series, "TRACE Specification, a Series of LF Projects, LLC".

-> **Developer Preview.** Launching at Confidential Computing Summit, June 23 2026. +> **Developer Preview.** Launched at Confidential Computing Summit, 23 June 2026. Spec v0.2 is current. See [LIMITATIONS.md](LIMITATIONS.md) before relying on it in production. An open specification for hardware-attested AI agent governance records. TRACE defines the format, anchoring protocol, and verification rules for cryptographically provable evidence that an AI agent ran under a specific policy, in a verified hardware environment, on classified data, invoking identified tools, all bound into a single signed artifact rooted in silicon attestation. diff --git a/docs/crosswalks/acta-decision-receipts.md b/docs/crosswalks/acta-decision-receipts.md index 3d4f9f5..8f280c0 100644 --- a/docs/crosswalks/acta-decision-receipts.md +++ b/docs/crosswalks/acta-decision-receipts.md @@ -98,7 +98,7 @@ An Acta decision receipt proves that a specific policy decision, over a specific ## Conformance fixtures -Six real fixtures in [`examples/action-receipts/acta/`](../../examples/action-receipts/acta/), generated by an actual Ed25519 signer (generator committed alongside), covering the negative cases raised in [trace-spec#97](https://github.com/agentrust-io/trace-spec/issues/97) and [trace-spec#95](https://github.com/agentrust-io/trace-spec/issues/95): valid accepted, valid denied (negative controller-equivalent outcome), signature/key mismatch (mismatched key committed), broken chain (validly signed, wrong predecessor hash), stale policy digest, and mismatched session binding. Expected outcomes are machine-readable in `expected.json`, and [`tests/test_acta_fixtures.py`](../../tests/test_acta_fixtures.py) re-verifies every fixture in CI against the draft-02 envelope and the declared positive/negative results, using this repository's existing `rfc8785` and `cryptography` dependencies, so fixture or envelope drift fails the build. +Six real fixtures in [`examples/action-receipts/acta/`](../../examples/action-receipts/acta/), generated by an actual Ed25519 signer (generator committed alongside), covering the negative cases raised in [trace-spec#97](https://github.com/agentrust-io/trace-spec/issues/97) and [trace-spec#95](https://github.com/agentrust-io/trace-spec/issues/95): valid accepted, valid denied (negative controller-equivalent outcome), signature/key mismatch (mismatched key committed), broken chain (validly signed, wrong predecessor hash), stale policy digest, and mismatched session binding. Expected outcomes are machine-readable in `expected.json`, and [`tests/test_acta_fixtures.py`](https://github.com/agentrust-io/trace-spec/blob/main/tests/test_acta_fixtures.py) re-verifies every fixture in CI against the draft-02 envelope and the declared positive/negative results, using this repository's existing `rfc8785` and `cryptography` dependencies, so fixture or envelope drift fails the build. ## References diff --git a/index.md b/index.md new file mode 100644 index 0000000..2a90ae6 --- /dev/null +++ b/index.md @@ -0,0 +1,93 @@ +--- +title: Hardware-attested receipts for AI agent actions +description: TRACE is an open specification for hardware-attested AI agent governance records. A Trust Record states what ran, where, under which policy, touching which data, calling which tools, in a form any third party can verify without trusting the operator. +--- + +# TRACE + +TRACE (Trust, Runtime Attestation, and Compliance Evidence) is an open specification for hardware-attested AI agent governance records. It defines the record format, the anchoring protocol, and the verification rules for cryptographic evidence that an AI agent ran under a specific policy, in a verified hardware environment, on a given data class, invoking identified tools, all bound into a single signed artifact rooted in silicon attestation. + +**A Trust Record answers what ran, where, under which policy, touching which data, and calling which tools, in a form any third party can verify without trusting the operator.** + +!!! tip "TL;DR" + - An audit log is written by the system being audited. A Trust Record is signed inside a TEE and checked against a hardware root, so the operator cannot author it after the fact. + - The current specification is **v0.2**, with a [conformance test suite](https://tests.agentrust-io.com) that scores a record by level. + - Install with `pip install agentrust-trace` and sign your first record in a few minutes. + - TRACE Specification is hosted at the Linux Foundation as its own series, [TRACE Specification, a Series of LF Projects, LLC](https://www.linuxfoundation.org/). + +```bash +pip install agentrust-trace +``` + +```python +from agentrust_trace import TrustRecord, sign_record + +record = TrustRecord( + subject="spiffe://trust.example.org/agent/payments-processor", + model_id="claude-sonnet-4-6", + platform="amd-sev-snp", + policy_hash="sha256:b2c3d4...", +) +signed = sign_record(record, key=signing_key) +``` + +## What a Trust Record proves + +Each question maps to a claim a third party can check without asking you. + +| Question | TRACE claim | +|---|---| +| What model ran? | `model.model_id` + `model.weights_digest` | +| Where did it run? | `runtime.platform` + `runtime.measurement` | +| Under which policy? | `policy.bundle_hash` + `policy.enforcement_mode` | +| What data did it touch? | `data_class` | +| Which tools were called? | `tool_transcript.hash` + `tool_transcript.call_count` | +| Is the record independently anchored? | `anchoring.receipt_uri` (SCITT) | + +## Where to start + +
+ +- __Run it__ + + --- + + Sign a record, verify it, and see what a failed check looks like. + + [Quickstart](docs/quickstart.md) + +- __Read it__ + + --- + + The normative specification, with the claim set, the anchoring protocol, and the verification rules. + + [TRACE v0.2](spec/trace-v0.2.md) + +- __Test it__ + + --- + + Score an implementation against the spec by conformance level before claiming compliance. + + [Conformance suite](https://tests.agentrust-io.com) + +- __Integrate it__ + + --- + + Emit and consume Trust Records from AGT, cMCP, and sandboxed agent runtimes. + + [Integration guides](docs/integration/agt.md) + +
+ +## What it is built on + +TRACE profiles existing IETF and IRTF work rather than replacing it: [RFC 9711 (EAT)](https://www.rfc-editor.org/rfc/rfc9711) for the claim envelope, [RFC 9334 (RATS)](https://www.rfc-editor.org/rfc/rfc9334) for the attester, verifier, and relying-party roles, and the SCITT draft for transparency-ledger anchoring. A related standardization track runs in [CoSAI WS4](https://github.com/oasis-open-projects/coalition-for-secure-ai). + +## Status and governance + +The specification is a **Developer Preview**. v0.2 is current and published with a conformance test suite. Read [Limitations](LIMITATIONS.md) for the scope boundaries before relying on it in production. + +TRACE Specification is an [LF Project](https://www.linuxfoundation.org/), hosted at the Linux Foundation as its own series, "TRACE Specification, a Series of LF Projects, LLC", under [LF Projects policies](https://lfprojects.org/policies/). See [Governance](GOVERNANCE.md) for how decisions are made and [Contributing](CONTRIBUTING.md) for how to propose a change. diff --git a/mkdocs.yml b/mkdocs.yml index 3d393bb..902e1f0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,12 +21,10 @@ exclude_docs: | schema/trace-revocation-bundle.json LICENSE NOTICE + README.md ANTITRUST.md ADOPTERS.md - MAINTAINERS.md SECURITY.md - CHARTER.md - CODE_OF_CONDUCT.md pyproject.toml theme: @@ -88,7 +86,7 @@ plugins: conformance suite. sections: Getting started: - - README.md + - index.md - docs/quickstart.md - docs/trust-levels.md - docs/verification.md @@ -184,7 +182,7 @@ extra_css: - https://agentrust-io.com/design-system.css nav: - - Home: README.md + - Home: index.md - Getting Started: - Quickstart: docs/quickstart.md - Trust Levels: docs/trust-levels.md @@ -221,6 +219,8 @@ nav: - OWASP Agentic Top 10: docs/crosswalks/owasp-agentic-top-10.md - Acta Decision Receipts: docs/crosswalks/acta-decision-receipts.md - Test Suite: https://tests.agentrust-io.com + - Method: + - How the conformance vectors are built: docs/conformance-method.md - RFCs: - Composable zero-knowledge proofs: docs/rfcs/composable-zk-assurance.md - Project: @@ -228,6 +228,9 @@ nav: - Changelog: CHANGELOG.md - Contributing: CONTRIBUTING.md - Governance: GOVERNANCE.md + - Technical Charter: CHARTER.md + - Code of Conduct: CODE_OF_CONDUCT.md + - Maintainers: MAINTAINERS.md - Roadmap: ROADMAP.md - Privacy: PRIVACY.md - Scope: Governance/Scope.md diff --git a/overrides/main.html b/overrides/main.html index fc0d908..7cd12af 100644 --- a/overrides/main.html +++ b/overrides/main.html @@ -9,24 +9,10 @@ is not repeated here. #} -{# - The homepage is built from README.md, which mkdocs treats as the site index. - Material falls back to site_name when a page has no front-matter title, so the - homepage was titled with the bare string "TRACE". Front matter is not an option - here: README.md is also the GitHub landing page and YAML would render as noise - there. Inner pages keep their own titles through super(). -#} -{% block htmltitle %} - {% if page and page.is_homepage %} - Hardware-attested receipts for AI agent actions - {{ config.site_name }} - {% else %} - {{ super() }} - {% endif %} -{% endblock %} {% block extrahead %} {{ super() }} - {% set page_title = page.title ~ " - " ~ config.site_name if page and page.title and not page.is_homepage else config.site_name %} + {% set page_title = page.title ~ " - " ~ config.site_name if page and page.title else config.site_name %} {% set page_desc = page.meta.description if page and page.meta and page.meta.description else config.site_description %} {% set page_url = page.canonical_url if page and page.canonical_url else config.site_url %}