Working with attestation reports¶

When a workflow is triggered with attestation reporting requested, Opaque generates cryptographic proof that the workflow executed inside a trusted, hardware-protected environment. The Opaque SDK automatically retrieves this proof—called an attestation report—and validates it to confirm that the environment, binaries, and request data all match trusted measurements.

Each attestation run generates two outputs that you can later verify or archive for audit:

• An attestation report (.jwt), the signed proof of secure execution issued by the trusted environment.
• An appraisal log (.log), the record of how the SDK verified that report.

This guide shows how to verify, re-appraise, and enforce policy on attestation artifacts created when a workflow author enables attestation in Opaque.

What you’ll work with¶

When a workflow is triggered with attestation reporting requested, the SDK saves the generated artifacts to the paths defined in the submission parameters (report_path and appraisal_path).

As a developer, you’ll typically access:

• .jwt reports: Signed files representing the environment’s security claims.
• .log files: Detailed results of how the SDK appraised those reports.
• Optional endorsement data: Such as the nonce, workflow ID, or portions of the request and response bodies.

These files form the cryptographic evidence of secure execution and can be used later for independent verification, audit, or compliance review.

Checking a saved report¶

You can verify a saved attestation report at any time using the Opaque SDK. This process, known as appraisal, confirms that the report originated from a trusted execution environment and that its contents still match expected platform measurements.

You can independently verify a saved attestation report at any time using the Opaque SDK:

from opaque.attestation.authority.appraiser import AttestationAuthorityAppraiser

# Example path to a saved attestation report (generated when attestation reporting was requested)
report_file = "/path/to/report/2025-10-07_20-31-04-UTC-report.jwt"

# Read the report into memory
with open(report_file, "rb") as f:
    report_bytes = f.read()

# Create an appraiser with default validation policies for supported runtimes
appraiser = AttestationAuthorityAppraiser.from_runtimes()

# Appraise the report
# If no endorsement data (nonce, workflow ID, request/response) available, pass an empty list
appraisal = appraiser.appraise(report_bytes, [])

# Print the appraisal result
print(appraisal)

This example assumes no endorsement data (nonce, workflow ID, request body, or response body) is available. If you have some of these items, you can pass them as a partial list to appraise() in any order to strengthen verification.

All attestation reports include an expiry timestamp. If a report has expired but you still need to verify its contents, you can disable expiry checks while keeping all other validations intact:

# Create an appraiser that skips expiry checks but performs all other checks
appraiser = AttestationAuthorityAppraiser.from_runtimes(verify_exp=False)

A successful appraisal confirms that the report originated from a valid trusted execution environment and that its claims still match expected platform measurements.

Configuring a specific appraiser¶

If your appraisal requirements are stricter than the defaults, you can configure a specific appraiser to enforce tighter policies. For example, you might require that a workflow be verified as having run on an Opaque trusted computing base (O-TCB) node with a confidential GPU (cGPU) attached.

from opaque.attestation.authority.appraiser import AttestationAuthorityAppraiser
from opaque.attestation.azure.aas.otcb import OTCBAppraiser
from opaque.attestation.runtimes import Runtime
from opaque.workflow import WorkflowService

# Create an appraiser for O-TCB environments that require a confidential GPU
innerAppraiser = OTCBAppraiser(cgpu=True)

# Create an attestation authority appraiser that uses this specific inner appraiser
appraiser = AttestationAuthorityAppraiser.from_appraisers(
    {Runtime.AZURE_OAS_OPAQUE_CVM_CGPU: innerAppraiser}
)

# Create a workflow client using a given UUID and attach the configured appraiser
workflow_service = WorkflowService(
    workflow_uuid=uuid.UUID(WORKFLOW_SERVICE_UUID), appraiser=appraiser
)

With this setup, any appraisal (or workflow submission that uses this appraiser) will fail if the report doesn’t meet the defined runtime criteria. This is especially useful for regulated workloads or when your organization enforces environment-specific attestation policies.

Interpreting the report¶

The attestation report and log provide verifiable proof of execution.

You don’t need to decode the JWT to understand its meaning—use the following summary to interpret results.

AKS clusters with confidential node pools¶

For workflows running on Azure Kubernetes Service (AKS) with confidential node pools, the appraisal log (.log) provides evidence that the workflow executed on trusted AMD SEV-SNP hardware using verified, unmodified Azure images. These logs record the claims that Azure Attestation Service (AAS) verified as part of the confidential VM’s trust chain.

When you review an AKS appraisal log, look for claims that confirm the following:

• The workflow ran on AMD SEV-SNP–backed confidential nodes verified by Azure Attestation.
• The OS and Kubernetes distribution were unmodified Azure builds.
• Memory encryption and isolation were enforced throughout execution.
• The request and response were both processed within this trusted environment, and the proof was generated for this specific request

The following table shows some examples of the claims you’ll see in the appraisal log and what they represent.

If any claim fails verification, the SDK raises a SecurityError and marks the report as unverified.

Opaque trusted computing base (O-TCB)¶

For workflows running on the Opaque trusted computing base (O-TCB), the appraisal log shows evidence that the workflow executed inside an Opaque-provisioned confidential virtual machine (O-CVM) built on Azure SEV-SNP hardware. These reports include additional Opaque-specific verification steps that confirm the integrity of both the environment and the software stack.

When you review an O-TCB appraisal log, look for claims that confirm the following:

• The environment used a verified Opaque image and an immutable, Opaque-provided OS and Kubernetes distribution.
• Memory encryption was enforced, and isolation was maintained during execution.
• All binaries matched Opaque-signed builds.
• If a confidential GPU (cGPU) was attached, it passed attestation through NVIDIA’s Remote Attestation Service (NRAS).
• The request and response were verified as bound to the same secure execution instance inside the trusted environment

The following table shows examples of the claims you’ll see in the appraisal log and what they represent.

If any of these claims fail appraisal or don’t match expected measurements, the SDK marks the report as unverified and raises a SecurityError.

Next steps¶

Attestation artifacts are your proof of secure workflow execution. Archive both the attestation report (.jwt) and appraisal log (.log) as part of your audit trail so they can be independently re-appraised during future reviews or compliance checks.