Add Proxy-Based Attestation and aTLS Overview

docs/attestation.md

@@ -1,73 +1,83 @@
----
-id: attestation
-title: Attestation
-sidebar_position: 4
----
+# Attestation Overview
+
+Attestation is a security mechanism that allows a client to **verify the identity and integrity of a remote system before sending sensitive data**.
 
-## Attestation
+In the context of confidential computing, attestation provides cryptographic proof that an application is running:
 
-Attestation is a security process used to verify that a system is running trusted software inside a trusted environment.  
-In Cube AI, attestation ensures that the confidential computing environment (CVM) has not been tampered with before Cube AI services start running.
+* Inside a **Trusted Execution Environment (TEE)**
+* With **expected software and configuration**
+* Without interference from the host operating system, hypervisor, or cloud provider
 
-Cube AI performs attestation both **internally** during the boot sequence of the confidential virtual machine (CVM) and via a **user-facing endpoint** that allows clients to verify trust guarantees.
+Attestation is a foundational building block for **zero-trust architectures**, where trust is never assumed and must always be verified.
+
+For Cube AI, attestation ensures that sensitive prompts, embeddings, and responses are processed only by trusted and verified AI services.
 
 ---
 
-## How Cube AI Uses Attestation Today
+## Attestation and Attested TLS (aTLS)
+
+To allow clients to send confidential data to Cube AI securely, a secure channel based on **Attested TLS (aTLS)** is established.
+
+aTLS is a standard TLS connection augmented with a **hardware-backed attestation report** proving that the remote service is running inside a **Trusted Execution Environment (TEE)**.
 
-Cube AI runs inside **hardware-backed Confidential Virtual Machines (CVMs)** based on **AMD SEV-SNP and Intel TDX**.
+In Cube AI, the agent service running inside the TEE acts as the TLS server and extends its X.509 certificate with an attestation report generated by the underlying TEE (e.g. AMD SEV-SNP).
 
-These confidential computing technologies provide:
+When generating the attestation report, the service embeds the **hash of its ephemeral public key** into the `report_data` field of the attestation report.
 
-- Full memory encryption  
-- Protection from a malicious hypervisor or cloud provider  
-- Integrity verification of the VM state  
-- Hardware-enforced measurement of what software boots inside the VM  
+A new TLS certificate and a fresh attestation report are generated for every connection, ensuring cryptographic freshness and preventing replay attacks.
 
-During startup:
+This provides cryptographic proof that the client is communicating directly with the Cube AI service running inside a TEE, and not with the host system or any intermediary.
 
-1. The CVM performs **hardware attestation** using platform-specific attestation mechanisms (**AMD SEV-SNP or Intel TDX**).
-2. Measurements are validated internally before Cube AI components start.
-3. If the environment does not match expected measurements, the system refuses to start.
+---
+
+## Proxy-Based Attestation
+
+Unlike systems where users must manually perform attestation using a CLI tool, Cube AI automates the attestation process through a **proxy component deployed in the Cube AI infrastructure**.
 
-Because this attestation happens before any workloads run, Cube AI ensures that:
+The Cube AI Proxy:
 
-- The AI backend (Ollama or vLLM) is running on trusted code  
-- The proxy and API services are verified  
-- Sensitive data and model prompts are protected from host-level access  
+* Forwards client connections to Cube AI services secured with **aTLS**
+* Fetches and exposes attestation evidence associated with the aTLS-secured service endpoint
+* Ensures that the TLS key is cryptographically bound to the attested TEE
+* Provides auditability through structured logs and attestation records
+* Transparently forwards client requests and responses
+
+From the user's perspective, the client application communicates with Cube AI services over **standard HTTPS**.  
+Attestation evidence can be retrieved directly through the proxy, while aTLS verification results are recorded in structured audit logs, without requiring any client-side deployment or manual verification steps.
 
 ---
 
-## Why Attestation Matters
+## Attestation Policy Verification
+
+The Local Proxy enforces an **attestation policy** that defines the expected properties of the TEE.
 
-Confidential Computing provides strong isolation, but attestation ensures:
+This policy includes:
 
-- The VM truly has confidential computing protections enabled  
-- The system hasn’t been modified by the cloud provider  
-- No unauthorized code is executed inside the confidential environment  
-- All model prompts and responses remain protected even from the host  
+* Reference values for fields in the attestation report
+* Expected measurements identifying the Cube AI service running inside the TEE
+* Verification that the TLS key is bound to the attested enclave
 
-This is essential for:
+![Event details](img/eventdetails.png)
 
-- Enterprise deployments  
-- Regulated industries (healthcare, finance, defense, R&D)  
-- Zero-trust security architectures  
-- Protecting sensitive AI inputs and outputs  
+Only if the attestation report satisfies the policy will the Proxy establish and maintain the aTLS connection.
 
 ---
 
-## User-Facing Attestation
+## aTLS Verification and Audit Logs
+
+Each successful aTLS handshake is recorded by the Cube AI Proxy in structured audit logs.  
+These audit log entries provide verifiable evidence that the connection was established with a TEE-backed Cube AI service and that attestation policy verification succeeded.
 
-Cube AI exposes a user-facing attestation endpoint that allows applications
-to verify that they are interacting with a trusted Cube AI instance.
+![aTLS handshake audit log](img/atls-audit-log.png)
 
-### 🔹 Attestation Endpoint
+Through these logs, users can audit completed aTLS handshakes and verify that no connections were established without successful attestation.
 
-Applications can request an attestation report using:
+## Security Guarantees
 
-```bash
-POST /attestation
-```
+This design ensures that:
 
-The returned attestation data can be validated by the client to ensure that the
-Cube AI instance is running inside a trusted confidential computing environment.
+* Plaintext input is visible only inside the TEE
+* Sensitive data and AI workloads are processed exclusively within the enclave
+* The host OS, hypervisor, and cloud provider cannot access user data
+* No manual attestation steps are required from users
+* The client can trust the identity and integrity of the remote service