spec: clarify attestation scopes in §4.5.2 and add scan-attestation example (#65)

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
+```

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"
+          }
+        ]
+      }
+    }
+  ]
+}

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"
+          }
+        }
+      ]
+    }
+  ]
+}

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

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"],