Implementing AttestationVerifier with ReferenceValues for Hardware Identity

Use the AttestationVerifier abstract interface to validate hardware attestation evidence against declarative ReferenceValues policies, enabling provider-neutral verification of confidential computing identities such as SEV-SNP and TDX.

The microsoft/agent-governance-toolkit provides a provider-neutral attestation verification stack that converts raw hardware evidence into trusted identity claims. By implementing AttestationVerifier with ReferenceValues, you can enforce hardware-bound security policies that verify platform configuration, measurements, and TCB status without coupling to specific attestation providers like Azure MAA or Google Confidential Computing.

Core Architecture: Evidence, Policy, and Verifier

The attestation stack decouples evidence collection from policy enforcement through three primary abstractions defined in agentmesh/identity/attestation.py and agentmesh/identity/attestation_verifier.py.

AttestationEvidence Model

AttestationEvidence is an immutable data structure that packages cryptographic proof generated by hardware attestation services. It binds the attestation report to the agent's identity through fields like agent_did, challenge_id, nonce, and public_key_hash, preventing replay attacks according to ADR 0010.

Key fields include:

• platform: Hardware platform identifier (e.g., "azure-caci")
• runtime_measurements: Dictionary of verified measurements (e.g., {"cce_policy_hash": "policy-v1"})
• report_data_hash: Computed hash binding the evidence to the specific challenge
• key_origin: Origin of the attestation key (e.g., KeyOrigin.SKR)

ReferenceValues Policy

ReferenceValues declares the expected hardware configuration as implemented in agentmesh/identity/attestation.py. This policy object encodes the exact platform state you trust, allowing declarative specification of acceptable TEE configurations.

Critical policy fields include:

• required_platform: Platform identifier that must match the evidence
• expected_measurements: Dictionary of required runtime measurements
• required_claims: Key-value pairs that must appear in the attestation (e.g., compliance status)
• allowed_tcb_statuses: List of acceptable Trusted Computing Base states (e.g., ["up_to_date"])
• require_debug_disabled: Boolean enforcing that debug mode is disabled
• image_match_policy: Strategy for verifying container images (e.g., ImageMatchPolicy.SIGNING_IDENTITY)
• allowed_image_signers: List of trusted signing identities when using signing-based policies

AttestationVerifier Interface

The abstract AttestationVerifier class defines the contract for verification implementations. The interface requires a single asynchronous method:

async def verify(
    self, 
    evidence: AttestationEvidence, 
    reference_values: ReferenceValues
) -> AttestationClaims:

Concrete implementations execute checks against the reference values and return normalized AttestationClaims on success, or raise AttestationVerificationError on policy violation.

Step-by-Step Implementation Guide

Follow these steps to implement hardware identity verification using the toolkit's Python SDK.

Step 1: Construct AttestationEvidence

Build the evidence object using the cryptographic helpers provided in agentmesh/identity/attestation.py. In production, this data originates from your attestation provider (e.g., Azure Confidential Computing), but for testing you can construct it manually:

from agentmesh.identity.attestation import (
    AttestationEvidence,
    KeyOrigin,
    compute_report_data_hash_hex,
    public_key_hash_hex,
)

public_key_hash = public_key_hash_hex(b"\x01" * 32)

evidence = AttestationEvidence(
    platform="azure-caci",
    evidence="base64-attestation-report",
    agent_did="did:mesh:agent-1",
    challenge_id="challenge_123",
    nonce="nonce-abc",
    public_key_hash=public_key_hash,
    report_data_hash=compute_report_data_hash_hex(
        "did:mesh:agent-1", "challenge_123", "nonce-abc", public_key_hash
    ),
    key_origin=KeyOrigin.SKR,
    runtime_measurements={"cce_policy_hash": "policy-v1"},
    secure_boot_verified=True,
)

The compute_report_data_hash_hex function ensures the evidence cryptographically binds to the specific agent DID and challenge, preventing replay attacks.

Step 2: Define ReferenceValues Policy

Declare your security policy by instantiating ReferenceValues with the exact hardware configuration you require:

from agentmesh.identity.attestation import ReferenceValues, ImageMatchPolicy

reference = ReferenceValues(
    required_platform="azure-caci",
    expected_measurements={"cce_policy_hash": "policy-v1"},
    required_claims={"x-ms-compliance-status": "compliant"},
    allowed_tcb_statuses=["up_to_date"],
    require_debug_disabled=True,
    image_match_policy=ImageMatchPolicy.SIGNING_IDENTITY,
    allowed_image_signers=["trusted-ci"],
)

This policy enforces that only SEV-SNP VMs running the specified CCE policy, with up-to-date TCB and debug mode disabled, from your trusted CI pipeline are accepted.

Step 3: Execute Verification

Instantiate a verifier and call the verify method. For local testing, use MockAttestationVerifier from agentmesh/identity/attestation_verifier.py:

import asyncio
from agentmesh.identity.attestation_verifier import MockAttestationVerifier

verifier = MockAttestationVerifier(
    claims={"x-ms-compliance-status": "compliant", "image_signer": "trusted-ci"}
)

async def verify():
    claims = await verifier.verify(evidence, reference)
    print(f"Platform: {claims.platform}")
    print(f"Confidential level: {claims.confidential_level}")

asyncio.run(verify())

In production, replace MockAttestationVerifier with a concrete implementation that communicates with Azure MAA, Google Confidential Computing, or your chosen attestation service while maintaining the same interface.

Verification Logic Deep Dive

When verify() is invoked, the implementation (typically in _verify_reference_values) performs the following validation sequence:

1. Platform Verification: Confirms evidence.platform matches reference_values.required_platform
2. Freshness Check: Validates the evidence has not expired using is_expired
3. TCB Validation: Verifies the evidence's TCB status exists within allowed_tcb_statuses
4. Debug Policy Enforcement: Ensures debug mode is disabled when require_debug_disabled is True
5. Measurement Comparison: Validates that runtime_measurements contains all key-value pairs specified in expected_measurements
6. Claims Validation: Confirms all required_claims exist in the attestation with matching values
7. Image Signer Verification: When image_match_policy is SIGNING_IDENTITY, validates the signer against allowed_image_signers

Only if all checks pass does the method return an AttestationClaims object containing normalized trust information like confidential_level and key_origin.

Testing Locally with MockAttestationVerifier

The MockAttestationVerifier class provides a CI-safe implementation for testing your policies without access to real hardware. Located in agentmesh/identity/attestation_verifier.py, it accepts a dictionary of claims to return and performs all reference value validation logic against your policy.

For comprehensive test examples, examine agent-governance-python/agent-mesh/tests/test_attestation_verifier.py, which demonstrates both success paths and failure modes (expired evidence, mismatched measurements, invalid TCB status).

For end-to-end integration tests using concrete provider implementations, see agent-governance-python/agent-os/modules/iatp/iatp/tests/test_attestation.py.

Summary

Implementing hardware identity verification with AttestationVerifier and ReferenceValues provides:

• Provider Neutrality: The same verification logic works across SEV-SNP, TDX, and future TEEs without code changes
• Declarative Policies: Hardware requirements are expressed as data in ReferenceValues rather than imperative code
• Cryptographic Binding: Evidence is cryptographically tied to agent identity through challenge-response mechanisms and report data hashing
• Testable Security: MockAttestationVerifier enables validation of security policies in CI/CD pipelines before production deployment

Frequently Asked Questions

How do I implement a custom AttestationVerifier for a new hardware platform?

Create a concrete class inheriting from AttestationVerifier and implement the abstract verify method. Your implementation should parse the hardware-specific attestation format, extract claims, and invoke _verify_reference_values (or equivalent logic) to validate against ReferenceValues. Keep the public interface unchanged so existing code using await verifier.verify(evidence, reference) continues to work without modification.

What ReferenceValues fields are required for SEV-SNP attestation on Azure?

For Azure Container Instances with SEV-SNP, set required_platform="azure-caci", specify the expected_measurements including the cce_policy_hash, and include "x-ms-compliance-status": "compliant" in required_claims. Always set require_debug_disabled=True for production workloads and verify the TCB status is "up_to_date" through allowed_tcb_statuses.

How does the toolkit prevent replay attacks during attestation?

The AttestationEvidence structure includes challenge_id, nonce, and report_data_hash fields that cryptographically bind the attestation to a specific verification request. The compute_report_data_hash_hex function incorporates the agent DID, challenge, nonce, and public key hash, ensuring evidence cannot be reused across different contexts or time windows.

Can I store ReferenceValues in external policy stores rather than hardcoding them?

Yes. ReferenceValues is a standard Python dataclass (as defined in agentmesh/identity/attestation.py), making it compatible with JSON/YAML serialization. You can load policies from configuration files, environment variables, or remote policy servers at runtime, enabling per-tenant or environment-specific hardware requirements without code changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}