sev_pytools

A Python library and CLI tool for AMD SEV-SNP (Secure Encrypted Virtualization - Secure Nested Paging) attestation report verification. This project provides comprehensive functionality for parsing, validating, and verifying SEV-SNP attestation reports, including cryptographic signature verification, certificate chain validation, and policy-based security enforcement.

Overview

AMD SEV-SNP (Secure Encrypted Virtualization - Secure Nested Paging) is a confidential computing technology that provides hardware-assisted isolation and memory encryption for virtual machines. SEV-SNP attestation reports are cryptographic evidence that prove the integrity, authenticity, and security posture of a SEV-SNP enabled system.

Key Features

• Complete Report Parsing: Parse SEV-SNP attestation reports with detailed structure extraction
• Cryptographic Verification: ECDSA signature verification for attestation report authentication
• Certificate Chain Validation: Full X.509 certificate chain verification with CRL checking
• Policy Validation Framework: Flexible JSON-based policy engine for security requirement enforcement
• AMD KDS Integration: Automatic fetching of certificates from AMD Key Distribution Service
• Guest Policy Management: Comprehensive guest policy flag interpretation and validation
• Platform Information: Platform capability and feature analysis
• Comprehensive Logging: Detailed verification steps with configurable logging levels
• CLI Tools: Ready-to-use command-line utilities for report inspection and verification

Architecture

The library is organized as follows:

Core Components

• attestation_report.py: AMD SEV-SNP attestation report parsing and data structure definitions

  • AttestationReport: Complete report structure parsing and representation
  • TcbVersion: Trusted Computing Base version handling
  • Cpuid: CPU identification and feature parsing

• verify.py: Complete attestation verification pipeline

  • Report signature verification using certificate chain
  • Certificate chain validation to AMD root CA
  • Policy-based validation with configurable rules
  • Comprehensive security posture assessment

Supporting Modules

• certs.py: Certificate management and verification utilities for AMD SEV-SNP attestation
• guest_policy.py: Guest policy management and validation for AMD SEV-SNP attestation
• platform_info.py: Platform information parsing and management for AMD SEV-SNP attestation
• policy.py: Policy validation framework for AMD SEV-SNP attestation reports
• signature.py: Digital signature handling for AMD SEV-SNP attestation reports
• fetch.py: Certificate fetching utilities for AMD SEV-SNP attestation reports
• print_report.py: Command-line utility for displaying AMD SEV-SNP attestation report details
• sev_logging.py: Centralized logging configuration for sev_pytools package

Project Structure

Installation

Requirements

• Python 3.6+
• Dependencies (automatically installed):
  • cryptography >= 39.0.0
  • requests >= 2.25.0

Install from Source

git clone https://github.com/TEE-Attestation/sev_pytools.git
cd sev_pytools
pip install .

Uninstallation

pip uninstall sev_pytools

Usage

Command Line Tools

Print Attestation Report Details

Display the contents of an AMD SEV-SNP attestation report in human-readable format:

# Using the installed command
sev-print -f report.bin

# With debug output for detailed parsing information
sev-print -f report.bin -d

# Using Python module directly
python -m sev_pytools.print_report -f report.bin

Options:

• -f, --file: Path to the attestation report file (default: report.bin)
• -d, --debug: Enable debug mode for additional output

Verify Attestation Report Authenticity

Perform complete cryptographic verification of an AMD SEV-SNP attestation report:

# Basic verification
sev-verify -f report.bin -c ./certs/

# Verbose verification with detailed steps
sev-verify -f report.bin -c ./certs/ -v

# Show report data after successful verification
sev-verify -f report.bin -c ./certs/ -r

# With policy validation
sev-verify -f report.bin -c ./certs/ -q policy.json

Options:

• -f, --file: Path to the attestation report file (default: report.bin)
• -c, --certs: Path to the directory containing certificates (default: ca)
• -d, --debug: Enable debug mode for additional output (automatically enables verbose mode)
• -v, --verbose: Enable verbose mode for detailed information
• -r, --reportdata: Print report data at the end of successful verification
• -p, --processor: Processor model (e.g., milan, genoa) used only if no certificates found (default: genoa)
• -q, --policy: Path to the policy file for validating the report against security policies (optional)

Fetch Certificates from AMD KDS

Retrieve certificates from the AMD Key Distribution Service:

# Fetch ARK and ASK certificates
sev-fetch ca -p genoa -e PEM -d ./certs/

# Fetch VCEK certificate for a specific report
sev-fetch vcek -p genoa -e PEM -d ./certs/ -r report.bin

Options:

• ca: Fetch ARK and ASK certificates
• vcek: Fetch VCEK certificate
• -p, --processor: Processor model (e.g., milan, genoa) (default: genoa)
• -e, --encoding: Certificate encoding format (PEM or DER)
• -d, --directory: Directory to save the fetched certificates
• --endorser: Endorser type (vcek or vlek) for fetching VCEK or VLEK certificates
• -r, --report: Path to the attestation report file (required for fetching VCEK)

Python API

Basic Report Parsing

from sev_pytools import AttestationReport

# Load and parse an attestation report
with open('report.bin', 'rb') as f:
    report_data = f.read()

report = AttestationReport.unpack(report_data)

# Access report components
print(f"Report version: {report.version}")
print(f"Guest SVN: {report.guest_svn}")
print(f"Policy: {report.policy}")

# Display report details
report.log_details()

Complete Report Verification

from sev_pytools.verify import verify_report
from sev_pytools import AttestationReport

# Load report
with open('report.bin', 'rb') as f:
    report_data = f.read()

report = AttestationReport.unpack(report_data)

# Verify report (will auto-fetch certificates if needed)
try:
    verify_report(report, certs_dir='./certs/', verbose=True)
    print("Report verification successful!")
except Exception as e:
    print(f"Verification failed: {e}")

Policy Validation

The toolkit supports validating attestation reports against security policies defined in JSON format. This allows you to enforce specific security requirements and check measurements are known good values.

Policy File Format

Policies are defined in JSON format with the following structure:

{
  "metadata": {
    "name": "AMD SEV-SNP Security Policy",
    "version": "1.0",
    "description": "Example security policy for validating AMD SEV-SNP attestation reports"
  },
  "validation_rules": {
    "measurement": {
      "exact_match": "123456789abcdef..."
    },
    "version": {
      "min_value": 3
    },
    "policy": {
      "migrate_ma_allowed": false,
      "debug_allowed": false
    },
    "platform_info": {
      "tsme_enabled": true,
      "alias_check_complete": true
    },
    "current_tcb": {
      "bootloader": {
        "min_value": 9
      },
      "tee": {
        "min_value": 0
      },
      "snp": {
        "min_value": 15
      },
      "microcode": {
        "min_value": 72
      }
    }
  }
}

Policy Validation Rules

The following validation rule types are supported:

• exact_match: Field must exactly match the specified value
• min_value: Field must be greater than or equal to the specified minimum
• max_value: Field must be less than or equal to the specified maximum
• allow_list: Field value must be in the list of allowed values
• deny_list: Field value must not be in the list of denied values
• boolean: Field must match the specified boolean value (true/false). This can be specified using the boolean value as the attribute value directly.

Using Policy Validation

Policy validation can be used programmatically:

from sev_pytools import AttestationPolicy, AttestationReport

# Load policy from file
policy = AttestationPolicy(policy_file="policy.json")

# Load attestation report
report = AttestationReport.from_file("report.bin")

# Validate report against policy
try:
    policy.validate_report(report, verbose=True)
    print("Report passed all policy checks!")
except PolicyValidationError as e:
    print(f"Policy validation failed: {e}")

The verify.py script also supports policy validation when the -q or --policy flag is used with a policy file path:

python verify.py -f path/to/report.bin -c path/to/certs/directory -q path/to/policy.json [-v]

This will perform both cryptographic verification of the attestation report and validate it against the specified policy file.

Certificate Management

Automatic Certificate Fetching

By default, the library automatically fetches certificates from AMD's Key Distribution Service (KDS):

• AMD Root Key (ARK) Certificate
• AMD SEV Signing Key (ASK) Certificate
• Versioned Chip Endorsement Key (VCEK) Certificate
• Certificate Revocation List (CRL)

Local Certificate Storage

For offline verification or to avoid network requests, certificates are stored locally:

certs/
├── ark.pem          # AMD Root Key
├── ask.pem          # AMD SEV Signing Key
├── crl.pem          # AMD CRL
└── vcek.pem         # Versioned Chip Endorsement Key

Fetching Certificates

To fetch certificates from the AMD Key Distribution Service:

python fetch.py ca -p PROCESSOR -e ENCODING -d DIRECTORY [--endorser {vcek,vlek}]
python fetch.py vcek -p PROCESSOR -e ENCODING -d DIRECTORY -r REPORT_PATH

or if installed with pip use sev-fetch ....

• ca: Fetch ARK and ASK certificates
• vcek: Fetch VCEK certificate
• -p or --processor: Processor model (e.g., milan, genoa) (default: genoa)
• -e or --encoding: Certificate encoding format (PEM or DER)
• -d or --directory: Directory to save the fetched certificates
• --endorser: Endorser type (vcek or vlek) for fetching VCEK or VLEK certificates
• -r or --report: Path to the attestation report file (required for fetching VCEK)

Logging

SNP PyTools includes comprehensive logging support for both library usage and command-line tools. This helps with debugging, monitoring, and auditing.

Command Line Logging

All command-line tools support logging flags. Available logging options:

• -v, --verbose: Enable verbose logging (shows DEBUG level messages)
• -q, --quiet: Enable quiet mode (only WARNING and ERROR messages)
• --log-file PATH: Write logs to specified file in addition to console output

# Enable verbose logging (DEBUG level)
sev-verify -f report.bin --verbose

# Enable quiet mode (WARNING level and above)
sev-fetch ca --quiet

# Save logs to file
sev-print -f report.bin --log-file verification.log

Library Logging

When using sev_pytools as a library, you can configure logging to suit your application:

from sev_pytools import setup_library_logging, get_logger, AttestationReport

# Setup logging for library usage
logger = setup_library_logging(level="INFO", log_file="sev_operations.log")

# Use the logger
logger.info("Starting attestation report processing")

# Load and process a report - the library will automatically log key operations
with open("report.bin", "rb") as f:
    data = f.read()

report = AttestationReport.unpack(data)  # This will log parsing progress
logger.info("Successfully parsed attestation report")

Requirements

Installation

Requirements

• Python 3.6+
• Dependencies (automatically installed):
  • cryptography >= 39.0.0
  • requests >= 2.25.0

Install from Source

git clone https://github.com/TEE-Attestation/sev_pytools.git
cd sev_pytools
pip install .

Uninstallation

pip uninstall sev_pytools

Contributing

Contributions are welcome! Please follow the contribution guidelines in the TAS repository.

Acknowledgments

This project is based on the AMD SEV-SNP specification and related documentation. All the specifications used can be found here: https://www.amd.com/en/developer/sev.html

The snpguest rust tool that can be used to generate the attestation report, and that models the verification process, can be found here: https://github.com/virtee/snpguest/tree/main

License

MIT License - Copyright 2025 Hewlett Packard Enterprise Development LP.

See LICENSE file for details.