Hardware attestation¶

Attestation is a signed report from the processor itself about what is running on it. This page is for teams running agents on confidential computing hardware (machines that keep a workload sealed off, even from the cloud operator) who want that report to name a specific manifest. You start with a local software example, then pick the hardware path that fits your machine.

A matching digest (the manifest's fingerprint) in a report does not by itself prove the report came from real hardware, or that the agent's current inputs were measured correctly. Checking hardware evidence properly needs the vendor's trusted root certificates, a list of approved measurements, and a rule for how old a report may be. The local example below does not touch real hardware.

Run the API locally¶

Complete the first-manifest tutorial, append this block to first_manifest.py, and run it again. Using software only, it ties the manifest's digest into a report, and ties a report to a nonce (a random one-time challenge from the checker, which shows the report is fresh).

import hashlib
import json
import secrets
from agent_manifest._auto_provider import SoftwareProvider

provider = SoftwareProvider()
provider.extend_manifest_hash(record)
report = provider.get_attestation_report()
assert report.platform == "software"
assert provider.verify_manifest_in_report(report, record)
modified = copy.deepcopy(record)
modified["artifacts"]["model_identity"]["version"] = "different"
assert not provider.verify_manifest_in_report(report, modified)
print("PASS: software binding matches the record and rejects an edited record")

# These observations belong to the demo's trusted configuration collector.
runtime_inputs = {
    "system_prompt_hash": prompt_hash,
    "policy_hash": context.policy_bundle_hash,
    "model_version": context.model_version,
}
context_bytes = json.dumps(runtime_inputs, sort_keys=True, separators=(",", ":")).encode()
context_hash = "sha256:" + hashlib.sha256(context_bytes).hexdigest()
nonce = secrets.token_bytes(32)  # In a service, the verifier issues this challenge.
runtime_report = provider.attest_runtime_state(nonce, context_hash)
assert runtime_report.platform == "software"
assert runtime_report.nonce_hex == nonce.hex()
assert runtime_report.context_hash == context_hash
second = provider.attest_runtime_state(secrets.token_bytes(32), context_hash)
assert second.report_data_hash != runtime_report.report_data_hash
print("PASS: a new nonce changes the software binding; no hardware proof was produced")

from agent_manifest import parse_platform_info, appraise_platform_info, SnpVerificationError

# On real SEV-SNP hardware: parse_platform_info(parse_snp_report(report.quote).platform_info).
# PLATFORM_INFO (offset 0x40) sits inside the signed report body, so a mutated byte
# invalidates the signature just like a mutated measurement would - the field is
# authenticated. What verify_attestation_chain() does not do is interpret it: it has
# no opinion on whether SMT-on or an unconfirmed alias check is acceptable. That
# policy judgment is appraise_platform_info()'s job, as its own explicit step (see
# limitations.md).
good_platform_info = parse_platform_info(0b0010_0000)  # alias_check_complete set, SMT off
appraise_platform_info(good_platform_info, require={"alias_check_complete"}, forbid={"smt_enabled"})
print("PASS: platform policy satisfied (alias_check_complete set, SMT off)")

bad_platform_info = parse_platform_info(0b0000_0001)  # SMT on, alias_check_complete unset
try:
    appraise_platform_info(bad_platform_info, require={"alias_check_complete"}, forbid={"smt_enabled"})
    raise AssertionError("expected the platform policy to reject this report")
except SnpVerificationError:
    print("PASS: platform policy rejects an SMT-enabled report with no alias check")

Expect four PASS lines in total from this page (two from the software-binding example above, two from the platform-policy calls just added). Copying the returned nonce or context into a response would not prove freshness or hardware authenticity. The two platform-policy checks test the policy logic on hand-written bits, not a captured hardware report; that end-to-end path is tested separately (linked below).

Appraise platform state before trusting hardware evidence¶

An AMD SEV-SNP report also says how the processor itself is configured, for example whether SMT (two threads sharing one core) is switched on. Whether that configuration is acceptable is your decision, and you check it in a separate step after the report's signature checks out.

hw_result = verify_attestation_chain(
    report, expected_manifest_hash=expected_hash, snp_report_bytes=report.quote,
    vcek_cert_der=vcek_der, cert_chain_pem=cert_chain_pem,
)

# Only attempt platform appraisal once hardware appraisal has already passed.
# A tampered or malformed report can fail hw_result.passed on its own; there
# is no reason to also risk parse_snp_report() raising on the same bad bytes
# before the caller ever reaches its decision, and no reason to trust
# PLATFORM_INFO from a report whose signature has not verified in the first
# place.
platform_ok = False
if hw_result.passed:
    platform_info = parse_platform_info(parse_snp_report(report.quote).platform_info)
    try:
        appraise_platform_info(platform_info, require={"alias_check_complete"}, forbid={"smt_enabled"})
        platform_ok = True
    except SnpVerificationError:
        platform_ok = False

if hw_result.passed and platform_ok:
    context.verified_attestation_manifest_hashes.add(expected_hash)
    context.attestation_evidence_manifest_id = record["manifest_id"]

Select the hardware path¶

A provider is the SDK component that asks the hardware for a report. Pick it by the attestation interface your guest (the virtual machine your agent runs in) actually exposes. A CPU model name or a "confidential VM" product label is not enough to go on.

In short: verify_manifest_in_report() checks that the report names this manifest. Treat it as one check in the appraisal, not a complete signature, certificate, freshness, and workload-policy verdict. The recipient must examine authenticated quote bytes and compare the measurements with its own allowlist.

Runtime state attestation (freshness proofs)¶

A freshness proof answers "is this agent still in the approved state right now?" The checker sends a new nonce, and the agent's machine returns a report that includes it, so an old report cannot be replayed. The proof is only as good as whatever measured the agent's state, and it says nothing about what happens after it was taken.

Choose challenge frequency according to the operation and stale-evidence policy. Periodic calls alone do not bound drift detection unless measurement collection, verification, and rejection are all enforced. A report also does not prove what happens after it was collected.

Auto-detection¶

select_provider(level=N) picks a provider for you based on what the machine offers. It is a convenience, and it does not check conformance. The current order is Azure CVM, direct SNP, direct TDX, TPM, then software.

Without a hardware candidate, requesting level >= 1 raises AttestationUnavailableError. Do not silently retry with level=0 in a path that requires hardware. For reproducible local tests, choose SoftwareProvider() directly rather than depending on the host's devices or environment variables.

Apply an acceptance policy¶

Hardware evidence is one input to your decision, never the whole decision. A provider name does not establish a conformance level or regulatory compliance. Apply the specification's conformance requirements, including artifact coverage, signature profile, required evidence, and recipient policy. Hardware appraisal and application authorization remain separate checks.

Pass independently appraised evidence into the verifier's context, bound to the exact manifest. Then require the full manifest result to be VALID; a successful hardware check cannot override a bad signature, expired record, revocation, or artifact mismatch. Continue with server-side verification.