diff --git a/conformance/examples/scan-attestation/README.md b/conformance/examples/scan-attestation/README.md new file mode 100644 index 0000000..79e0340 --- /dev/null +++ b/conformance/examples/scan-attestation/README.md @@ -0,0 +1,44 @@ +# Scan Attestation vs. Compliance Attestation + +A worked example for `trustManifest.attestations` in `spec/ard.md` (§4.5). The entry carries both an organizational compliance attestation and an artifact security scan attestation side by side to illustrate their distinct scopes. + +## Files + +| File | What it is | +| :--- | :--- | +| `ard.json` | The ARD manifest. One entry with two attestations. | +| `invoice-reader.scan.sarif` | The scan attestation document referenced by the entry. | + +The scanned artifact itself is not vendored here — in a deployment it is served by the publisher at the entry's `url`, and the attestation refers to it by digest rather than by copy. + +## What each attestation claims + +`SOC2-Type2` is an **organizational compliance attestation**. It attests that the publisher operates an audited control environment. It does not make a claim about the `invoice-reader` artifact itself — the same certificate could appear unchanged across every entry the publisher lists. + +The `agent-threat-scan` entry is an **artifact scan attestation** (one of several artifact-scoped attestation categories alongside build provenance such as SLSA/in-toto, transparency-log receipts, and runtime evaluations). It attests that the artifact at the entry's `url` was analyzed for tool-poisoning and hidden-capability content, bounded by the ruleset named in the referenced SARIF document. + +## Following the binding + +The entry's `digest` covers the **attestation document**, per `spec/schemas/ard-entry.schema.json`: + +```sh +shasum -a 256 invoice-reader.scan.sarif +# cdbd706458d30031292cb80c697357257e2fcb739917dc68d67c7b8925d3bee3 +``` + +That hash is recomputable from `invoice-reader.scan.sarif`. + +The binding to the **scanned artifact** lives inside the SARIF document under `runs[].artifacts[].hashes`. If the artifact changes, that hash no longer matches, preventing a scan result from being silently reattached to a modified artifact. + +The SARIF document also records `tool.driver.name`, `version`, `rules[]`, and `invocations[].properties` (`rulesetName`, `rulesetVersion`) so a consumer can evaluate the scope of the scan rather than treating the presence of an attestation as a blanket safety verdict. + +## Notes + +- **The `type` token is illustrative.** `trustManifest.attestations[].type` is an open string in ARD (§4.5); `agent-threat-scan` is an example value, not a closed spec enum. +- **A scan attestation is bounded by its ruleset and scanner.** Verifying `digest` confirms the integrity of the attestation document; verifying who ran the scan relies on the cryptographic signature over the trust manifest (`§4.5.2`) or an envelope such as an in-toto DSSE statement. + +## Validate + +```sh +./conformance/bin/conformance-test manifest conformance/examples/scan-attestation/ard.json +``` diff --git a/conformance/examples/scan-attestation/ard.json b/conformance/examples/scan-attestation/ard.json new file mode 100644 index 0000000..b0f5061 --- /dev/null +++ b/conformance/examples/scan-attestation/ard.json @@ -0,0 +1,32 @@ +{ + "entries": [ + { + "identifier": "urn:air:tools.example.com:server:invoice-reader", + "displayName": "Invoice Reader", + "type": "application/mcp-server-card+json", + "url": "https://tools.example.com/mcp/invoice-reader.json", + "description": "Reads uploaded invoices and returns structured line items.", + "representativeQueries": [ + "extract the line items from this invoice", + "what is the total on the attached invoice" + ], + "trustManifest": { + "identity": "spiffe://tools.example.com/mcp/invoice-reader", + "identityType": "spiffe", + "attestations": [ + { + "type": "SOC2-Type2", + "uri": "https://tools.example.com/trust/soc2-2026.pdf", + "mediaType": "application/pdf" + }, + { + "type": "agent-threat-scan", + "uri": "https://tools.example.com/trust/invoice-reader.scan.sarif", + "mediaType": "application/sarif+json", + "digest": "sha256:cdbd706458d30031292cb80c697357257e2fcb739917dc68d67c7b8925d3bee3" + } + ] + } + } + ] +} diff --git a/conformance/examples/scan-attestation/invoice-reader.scan.sarif b/conformance/examples/scan-attestation/invoice-reader.scan.sarif new file mode 100644 index 0000000..c718ff9 --- /dev/null +++ b/conformance/examples/scan-attestation/invoice-reader.scan.sarif @@ -0,0 +1,51 @@ +{ + "$schema": "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json", + "version": "2.1.0", + "runs": [ + { + "tool": { + "driver": { + "name": "example-agent-scanner", + "version": "2.3.0", + "informationUri": "https://scanner.example.com/", + "rules": [ + { + "id": "EX-TOOL-POISONING-001", + "name": "ToolDescriptionInstructionInjection", + "shortDescription": { + "text": "Tool description contains instructions directed at the model." + } + }, + { + "id": "EX-HIDDEN-CAPABILITY-002", + "name": "UndeclaredNetworkEgress", + "shortDescription": { + "text": "Tool performs network egress not declared in its schema." + } + } + ] + } + }, + "artifacts": [ + { + "location": { + "uri": "invoice-reader.json" + }, + "hashes": { + "sha-256": "d27f6473cd6b4a8ec3623a9ec01e8b42d0c607b0bc416237720f20a28f114a5b" + } + } + ], + "results": [], + "invocations": [ + { + "executionSuccessful": true, + "properties": { + "rulesetName": "example-agent-ruleset", + "rulesetVersion": "2026.08" + } + } + ] + } + ] +} diff --git a/spec/ard.md b/spec/ard.md index 5b878e2..d1209e7 100644 --- a/spec/ard.md +++ b/spec/ard.md @@ -192,6 +192,8 @@ The cryptographic trust domain asserted in `trustManifest.identity` MUST align w ARD does not define a signing or verification procedure of its own. The signed payload, its canonicalization, signature processing, and key resolution are defined by the trust framework the manifest declares in `trustManifest.trustSchema` (through its `governanceUri` and `verificationMethods`). ARD mandates only the publisher-authority binding of §4.5.1; two implementations verifying the same manifest defer to the same declared framework. A future ARD profile MAY pin a concrete default scheme, but this specification does not. A federated registry SHOULD run the verification its declared framework specifies and MAY use the outcome in filtering, ranking, and admission decisions; a registry that passes an unverified trust manifest through untouched forfeits the trust the federation depends on. +Entries in `trustManifest.attestations` can carry verifiable claims across distinct scopes — including **organizational compliance** (e.g., `SOC2-Type2`, `HIPAA-Audit`), **artifact security scans** (e.g., SARIF analysis of the artifact's content), **build provenance and SBOMs** (e.g., SLSA, in-toto DSSE), **transparency-log receipts** (e.g., SCITT/ANS registrations), and **runtime evaluations**. Consumers and registries should interpret each attestation according to its scope: an organizational compliance attestation applies to the publisher's control environment rather than the safety of a specific artifact, whereas artifact-scoped attestations (such as security scans or build provenance) should identify the evaluated artifact by cryptographic digest inside the referenced attestation document so the claim cannot be reattached to a modified artifact. Note that the `digest` field on the attestation item covers the referenced attestation document itself. + A relevance score returned by Search (§5.3.2) reflects semantic relevance only and MUST NOT be interpreted as a trust, compliance, or safety judgment; trust evaluation is fully decoupled. ## 5. Discovery diff --git a/spec/schemas/ard-entry.schema.json b/spec/schemas/ard-entry.schema.json index a4b8e6a..cf20f6d 100644 --- a/spec/schemas/ard-entry.schema.json +++ b/spec/schemas/ard-entry.schema.json @@ -138,7 +138,7 @@ }, "attestations": { "type": "array", - "description": "Verifiable claims (compliance audits, certifications).", + "description": "Verifiable claims (e.g., organizational compliance audits, artifact security scans, build provenance, transparency-log receipts, or runtime evaluations).", "items": { "type": "object", "required": ["type", "uri"],