feat(ci): add reproducible builds for TEE attestation #388
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
kariy
force-pushed
the
tee/reproducible-builds
branch
2 times, most recently
from
73bd52a to
96ab475
Compare
kariy
force-pushed
the
tee/reproducible-builds
branch
from
96ab475 to
7f6d8e2
Compare
Enhancements to TEE VM image build scripts: - Fix init script bugs that caused kernel panic - Mount /proc before reading /proc/cmdline - Fix dbg() function to work with set -eu - Add error handling to mknod commands - Add network configuration to initrd - Include ip command in busybox symlinks - Configure eth0 with static IP (10.0.2.15) for QEMU user networking - Enable RPC access via QEMU port forwarding - Enhance measurement calculation script - Support both UEFI and direct kernel boot modes - Automatic fallback when SNP_KERNEL_HASHES not supported - Generate JSON manifest with measurement metadata - Add VM boot test script (test-vm-boot.sh) - Automated QEMU testing with timeout - Serial console monitoring for boot progress - Validates kernel boot, init, and Katana launch Tested: VM boots successfully, Katana RPC responds to requests 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Integrate VM image building into the CI/CD pipeline: - Add vm-image-build job after reproducible-build - Builds complete VM image using vm-image.Dockerfile - Extracts all components (disk, kernel, initrd, OVMF) - Calculates SEV-SNP measurement using sev-snp-measure - Generates structured manifest with all component hashes - Compresses disk image for distribution - Creates GitHub attestation for provenance - Outputs: - Bootable VM disk image (compressed) - Expected SEV-SNP measurement for attestation - Component manifest with SHA hashes - Individual components (kernel, initrd, OVMF) - Validates YAML syntax - Tested with local measurement calculation This enables automated, reproducible VM image builds for AMD SEV-SNP TEE deployment. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Technical documentation for the TEE VM image build pipeline: - Complete architecture overview - Detailed explanation of all build stages - Initrd structure and init script flow - Reproducibility measures and guarantees - CI/CD integration guide - Local build instructions - Testing procedures with QEMU - Security considerations - Troubleshooting guide - Performance metrics This provides developers and operators with complete understanding of the VM image build process for reproducible TEE deployments. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Security Fix: The previous disk-based boot only measured OVMF firmware, leaving the kernel, initrd, and Katana binary unmeasured. This allowed post-attestation binary replacement attacks. Direct kernel boot solves this by having the hypervisor pass kernel, initrd, and cmdline directly to the AMD secure processor for measurement before boot, creating a complete chain of trust. Changes: - Remove disk image building from Dockerfile (stages 4-5) - Export only kernel, initrd, OVMF from final stage - Update CI workflow to build boot components instead of disk - Create boot components archive instead of disk image - Update manifest with direct kernel boot deployment info - Comprehensive documentation updates explaining security model - Add detailed troubleshooting for measurement tool limitations Security guarantee: All components (OVMF + kernel + initrd with Katana + cmdline) are measured by SEV-SNP at launch when using direct kernel boot on real hardware, preventing binary replacement attacks. Note: The sev-snp-measure tool cannot pre-calculate measurements without OVMF SNP_KERNEL_HASHES support, but real SEV-SNP hardware will perform full measurement via hypervisor interface. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Enable full attestation testing on SEV-SNP hardware by adding tools to verify the launch measurement matches the expected value. New Tools: - verify-attestation.sh: Calls tee_generateQuote RPC, extracts the launch measurement from the SEV-SNP attestation report (offset 0x90), and compares it with the expected measurement from the build - E2E_TESTING.md: Comprehensive guide for running attestation tests on actual SEV-SNP hardware, including QEMU launch parameters, attestation report structure documentation, and troubleshooting Test Flow: 1. Build boot components with reproducible build 2. Calculate expected measurement with sev-snp-measure 3. Launch VM with QEMU on SEV-SNP hardware (direct kernel boot) 4. Call tee_generateQuote to get attestation report 5. Extract measurement from report (AMD spec offset 0x90, 48 bytes) 6. Compare with expected measurement - must match exactly Security Guarantee: When measurements match, it cryptographically proves the running Katana instance was launched with the exact boot components from the reproducible build, preventing binary replacement attacks. The attestation report is signed by the AMD secure processor and includes both the launch measurement and blockchain state commitment (Poseidon hash of state_root and block_hash). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Related #378
Overview
This PR implements a complete reproducible build pipeline for TEE deployments, enabling cryptographic verification of Katana binaries and bootable VM images for AMD SEV-SNP environments.
When running Katana inside a Trusted Execution Environment like AMD SEV-SNP, the hardware generates a launch measurement that third parties must independently verify. This PR moves from a "trust the developer" model to a "verify the build" model by providing hermetic builds with GitHub attestations and automated SEV-SNP measurement calculation.
Reproducible Binary Builds
The build achieves byte-for-byte reproducibility through cargo vendor for hermetic dependencies, pinned Docker images by SHA256 digest, SOURCE_DATE_EPOCH for deterministic timestamps, and static musl linking to eliminate runtime dependencies. The cairo-native feature is excluded as LLVM code generation introduces non-determinism incompatible with strict TEE measurement requirements.
VM Image Pipeline
The pipeline extends beyond binaries to create complete bootable VM images containing Katana. A multi-stage Docker build assembles pinned Ubuntu packages (kernel 6.8.0-90, OVMF 2024.02-1), creates a minimal initrd embedding the Katana binary with network configuration, and produces a 2GB disk image with GPT partitioning and systemd-boot. The initrd init script configures networking and launches Katana directly as PID 1.
SEV-SNP Measurement
The build automatically calculates expected SEV-SNP measurements using the sev-snp-measure tool, generating structured manifests with SHA hashes of all components (OVMF, kernel, initrd, disk image). These measurements enable third-party attestation verification when Katana launches in a confidential VM.
Testing & Validation
Automated QEMU boot testing validates the VM image boots correctly with Katana responding to RPC requests. The test script monitors serial console output and verifies the JSON-RPC health endpoint. Local reproducibility testing confirms identical builds produce identical hashes across different machines.
CI Integration
The release-tee.yml workflow orchestrates the complete pipeline: building the reproducible binary, assembling the VM image, calculating measurements, generating GitHub attestations for provenance, and publishing all artifacts with structured manifests.
Verify build integrity with
gh attestation verify ./katana-reproducible --repo dojoengine/katana.