How itlusions/itl.controlplane.attestation works
1. This repository is a Python control plane for TPM-backed machine attestation and enrollment. The core job is to register machines by TPM EK fingerprint, verify their identity at boot, and deliver the correct Talos MachineConfig only after an approval step.
2. The runtime is split into a few clear surfaces: the attestation service, the operator dashboard, the operator CLI, and a provisioning agent used for physical/USB-based registration. The attestation service is the system of record; the other components are clients or views over it.
3. The main backend lives under src/attestation. It is organized as a layered API app: routes expose HTTP endpoints, handlers implement business logic, repositories persist machines/operators, models define domain objects, and schemas define request/response contracts. core/app.py, config.py, and deps.py wire the application together.
4. Machine lifecycle is the central data flow. A machine enters through /register or /self-register, is stored as pending, then moves through approve/reject/revoke/lock/unlock states, and finally reaches attestation and config application. The readme’s two flows make this explicit: one for a USB agent that reads the TPM EK before deployment, and one for a Talos ISO boot that self-registers on first boot.
5. Trust enforcement is isolated in src/attestation/pki. This boundary handles nonce generation, TPM verification, EK certificate chain validation, OIDC-related auth support, and enrollment CA issuance. These pieces decide whether a machine’s evidence is trustworthy before the control plane releases credentials or config.
6. Persistent state is small but security-sensitive. The service stores machine and operator records in the configured database, with migrations in migrations/ showing schema evolution such as EK fingerprint hashing. It also persists CA material and generated role configs on disk under the volumes described in the readme.
7. Talos configuration and ISO delivery are another distinct subsystem. src/attestation/talos contains config generation and ISO-factory integration. The system can either return a prebuilt hardened ISO via ITL_ISO_URL or fall back to Talos Image Factory, then use cached role configs and one-time config tokens to supply the final MachineConfig.
8. The operator dashboard is a separate web application under src/web. It has its own API layer, services, repositories, templates, and static assets. It appears focused on visualization and day-2 operations such as machines, policies, config, audit, and query views rather than on the low-level attestation protocol itself.
9. Audit and query capabilities are treated as a separate concern inside the web app. audit_service.py, audit_repo.py, and kql_engine.py suggest an append-oriented audit trail plus a query layer for searching operational history. This is the main read side of the system for operators.
10. The CLI in src/cli is an operator client for interacting with the attestation API. It includes auth, token caching, Keycloak integration, and a plugin mechanism, which means the command surface can be extended without changing the core server.
11. src/extensions is a plugin-style capability layer for the control plane. Built-ins include metrics, webhook delivery, secret vault, and Pulumi state management. These extensions add automation and integrations around the core machine lifecycle, but they are not the primary trust boundary for enrollment.
12. There is also an IaC boundary in src/pulumi_provider and examples/pulumi-demo. This lets external infrastructure automation manage or consume control plane resources through a Pulumi provider, keeping provisioning concerns separate from the attestation runtime.
13. Deployment is handled with both container and cluster artifacts: docker-compose.yml for local runs, a Helm chart under deploy/helm/attestation for Kubernetes, and deploy/kind for local cluster testing. These files define service exposure, persistence, and secret wiring, but not business logic.
14. The agent/ folder is the physical provisioning companion. It reads the TPM EK from hardware and initiates the registration flow before the machine is booted, which is why the architecture supports a pre-deployment USB path in addition to the standard first-boot self-registration path.
15. The tests in tests/ validate the security-sensitive boundaries: nonce handling, TPM verification, enrollment CA behavior, dual-control logic, config encryption, and API request handling. That makes the test suite a good map of the system’s critical trust and state-transition paths.
Main entry points: routes HTTP routes · pki PKI boundary · handlers Handlers · __main__.py CLI client
Components 25
Attestation service
Core control plane API and machine lifecycle backend
- App core · Application setup, config, and dependency injection
src/attestation/core/app.py - HTTP routes · HTTP endpoints for registration, machines, attestation, config, and audit
src/attestation/routes - Handlers · Lifecycle logic for registration, approval, attestation, and config delivery
src/attestation/handlers - Repositories · Machine and operator persistence layer
src/attestation/repositories - Domain models · Machine and operator domain objects
src/attestation/models - Schemas · Request and response payload definitions
src/attestation/schemas - Registration · USB and self-registration entrypoints for new machines
src/attestation/routes/registration.py - Machine ops · Approve, reject, revoke, lock, unlock, and inspect machine state
src/attestation/routes/machines.py - Attestation · Boot-time identity verification and evidence handling
src/attestation/routes/attestation.py - Config delivery · MachineConfig selection and delivery after trust is established
src/attestation/routes/config.py
Trust & PKI
Evidence verification, nonce handling, and enrollment CA issuance
- PKI boundary · Nonce, TPM, OIDC, and enrollment CA trust logic
src/attestation/pki - Nonce store · Tracks one-time challenge material for attestation
src/attestation/pki/nonce_store.py - TPM verifier · Validates TPM-backed identity evidence and EK fingerprints
src/attestation/pki/tpm_verifier.py - Quote verifier · Checks attestation quotes and proof material
src/attestation/pki/quote_verifier.py - Enrollment CA · Issues enrollment credentials and CA material
src/attestation/pki/enrollment_ca.py
Operator surfaces
Dashboard and CLI clients for operators
- Dashboard app · Operator-facing dashboard and API surface
src/web/app.py - Web services · Dashboard-facing services for machines, audits, and queries
src/web/services - Web API · Dashboard endpoints for machines, policies, config, audit, and query
src/web/api - Audit repo · Persistent audit trail backing the operator views
src/web/repositories/audit_repo.py - CLI client · Command-line client for interacting with the attestation API
src/cli/__main__.py - CLI auth · Authentication, Keycloak integration, and token caching
src/cli/auth.py
Automation & extensions
Provisioning companion, extensions, and infrastructure integration
- Provisioning agent · USB-based companion that reads TPM EK before deployment
agent/agent.py - Extensions · Built-in automation and integration extensions
src/extensions - Pulumi provider · Infrastructure automation client for control plane resources
src/pulumi_provider/provider.py - Talos delivery · Generates Talos configs and serves or fetches hardened ISOs
src/attestation/talos
Connections 26
- App core → HTTP routes: wires · Application mounts HTTP route modules
- App core → Handlers: injects · App wiring provides services to handlers
- HTTP routes → Registration: exposes · Registration endpoints handle new machine onboarding
- HTTP routes → Machine ops: exposes · Machine lifecycle endpoints manage operator actions
- HTTP routes → Attestation: exposes · Attestation endpoints verify identity at boot
- HTTP routes → Config delivery: exposes · Config endpoints return approved machine configuration
- HTTP routes → Schemas: serializes · Routes use request and response contracts
- Handlers → Repositories: persists · Handlers store and update machine and operator state
- Handlers → Domain models: uses · Business logic operates on domain objects
- Handlers → PKI boundary: verifies · Handlers consult trust services before approval or release
- PKI boundary → Nonce store: manages · One-time challenge generation and tracking
- PKI boundary → TPM verifier: verifies · TPM evidence and EK identity validation
- PKI boundary → Quote verifier: checks · Quote and proof validation
- PKI boundary → Enrollment CA: issues · Enrollment credential issuance after trust succeeds
- Dashboard app → Web API: serves · Dashboard app exposes HTTP views and endpoints
- Dashboard app → Web services: orchestrates · UI and API pages call service layer logic
- Web services → Audit repo: reads · Services query audit history and operational records
- Web API → HTTP routes: consumes · Operator views depend on the attestation control plane API
- CLI client → CLI auth: authenticates · CLI handles operator login and token reuse
- CLI client → HTTP routes: calls · CLI talks to the attestation service API
- Provisioning agent → Registration: registers · Physical provisioning path submits TPM EK for onboarding
- Extensions → CLI client: extends · Some extensions add CLI commands and automation hooks
- Extensions → Handlers: augments · Extensions add cross-cutting behaviors around lifecycle events
- Pulumi provider → HTTP routes: manages · Infrastructure automation consumes control plane resources
- Talos delivery → Config delivery: delivers · Talos config generation feeds MachineConfig delivery
- Talos delivery → Enrollment CA: depends on · Delivery can require enrollment credentials and role config material