# itlusions/itl.controlplane.attestation architecture

> Architecture diagram of the GitHub repository itlusions/itl.controlplane.attestation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itlusions/itl.controlplane.attestation
- Repository: https://github.com/itlusions/itl.controlplane.attestation

## Overview

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: [`src/attestation/routes`](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/routes) (HTTP routes), [`src/attestation/pki`](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/pki) (PKI boundary), [`src/attestation/handlers`](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/handlers) (Handlers), [`src/cli/__main__.py`](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/cli/__main__.py) (CLI client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_attestation["Attestation service"]
  node_attestation_app["App core<br/>FastAPI wiring<br/>[app.py]"]
  node_attestation_routes["HTTP routes<br/>API surface"]
  node_attestation_handlers["Handlers<br/>business logic"]
  node_attestation_repos[("Repositories<br/>persistence")]
  node_attestation_models["Domain models<br/>entities"]
  node_attestation_schemas["Schemas<br/>contracts"]
  node_attestation_registration(("Registration<br/>onboarding flow<br/>[registration.py]"))
  node_attestation_machines(("Machine ops<br/>lifecycle API<br/>[machines.py]"))
  node_attestation_attest(("Attestation<br/>verification API<br/>[attestation.py]"))
  node_attestation_config(("Config delivery<br/>machine config<br/>[config.py]"))
end

subgraph group_trust["Trust & PKI"]
  node_trust_pki{{"PKI boundary<br/>trust services"}}
  node_trust_nonce["Nonce store<br/>replay defense<br/>[nonce_store.py]"]
  node_trust_tpm["TPM verifier<br/>evidence verifier<br/>[tpm_verifier.py]"]
  node_trust_quote["Quote verifier<br/>quote verification<br/>[quote_verifier.py]"]
  node_trust_ca["Enrollment CA<br/>credential issuance<br/>[enrollment_ca.py]"]
end

subgraph group_operator["Operator surfaces"]
  node_web_app["Dashboard app<br/>web UI<br/>[app.py]"]
  node_web_services["Web services<br/>presentation logic"]
  node_web_api["Web API<br/>routes"]
  node_web_repo[("Audit repo<br/>storage<br/>[audit_repo.py]")]
  node_cli_app["CLI client<br/>operator CLI<br/>[__main__.py]"]
  node_cli_auth["CLI auth<br/>token management<br/>[auth.py]"]
end

subgraph group_automation["Automation & extensions"]
  node_agent["Provisioning agent<br/>physical enrollment<br/>[agent.py]"]
  node_extensions{{"Extensions<br/>plugin system"}}
  node_pulumi_provider["Pulumi provider<br/>iac provider<br/>[provider.py]"]
  node_talos{{"Talos delivery<br/>config pipeline"}}
end

node_attestation_app -->|"wires"| node_attestation_routes
node_attestation_app -->|"injects"| node_attestation_handlers
node_attestation_routes -->|"exposes"| node_attestation_registration
node_attestation_routes -->|"exposes"| node_attestation_machines
node_attestation_routes -->|"exposes"| node_attestation_attest
node_attestation_routes -->|"exposes"| node_attestation_config
node_attestation_routes -->|"serializes"| node_attestation_schemas
node_attestation_handlers -->|"persists"| node_attestation_repos
node_attestation_handlers -->|"uses"| node_attestation_models
node_attestation_handlers -->|"verifies"| node_trust_pki
node_trust_pki -->|"manages"| node_trust_nonce
node_trust_pki -->|"verifies"| node_trust_tpm
node_trust_pki -->|"checks"| node_trust_quote
node_trust_pki -->|"issues"| node_trust_ca
node_web_app -->|"serves"| node_web_api
node_web_app -->|"orchestrates"| node_web_services
node_web_services -->|"reads"| node_web_repo
node_web_api -.->|"consumes"| node_attestation_routes
node_cli_app -->|"authenticates"| node_cli_auth
node_cli_app -.->|"calls"| node_attestation_routes
node_agent -->|"registers"| node_attestation_registration
node_extensions -.->|"extends"| node_cli_app
node_extensions -.->|"augments"| node_attestation_handlers
node_pulumi_provider -.->|"manages"| node_attestation_routes
node_talos -->|"delivers"| node_attestation_config
node_talos -.->|"depends on"| node_trust_ca

click node_attestation_app "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/core/app.py"
click node_attestation_routes "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/routes"
click node_attestation_handlers "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/handlers"
click node_attestation_repos "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/repositories"
click node_attestation_models "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/models"
click node_attestation_schemas "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/schemas"
click node_attestation_registration "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/routes/registration.py"
click node_attestation_machines "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/routes/machines.py"
click node_attestation_attest "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/routes/attestation.py"
click node_attestation_config "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/routes/config.py"
click node_trust_pki "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/pki"
click node_trust_nonce "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/pki/nonce_store.py"
click node_trust_tpm "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/pki/tpm_verifier.py"
click node_trust_quote "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/pki/quote_verifier.py"
click node_trust_ca "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/pki/enrollment_ca.py"
click node_web_app "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/web/app.py"
click node_web_services "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/web/services"
click node_web_api "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/web/api"
click node_web_repo "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/web/repositories/audit_repo.py"
click node_cli_app "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/cli/__main__.py"
click node_cli_auth "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/cli/auth.py"
click node_agent "https://github.com/itlusions/itl.controlplane.attestation/blob/main/agent/agent.py"
click node_extensions "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/extensions"
click node_pulumi_provider "https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/pulumi_provider/provider.py"
click node_talos "https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/talos"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_attestation_app,node_attestation_routes,node_attestation_handlers,node_attestation_repos,node_attestation_models,node_attestation_schemas,node_attestation_registration,node_attestation_machines,node_attestation_attest,node_attestation_config toneBlue
class node_trust_pki,node_trust_nonce,node_trust_tpm,node_trust_quote,node_trust_ca toneAmber
class node_web_app,node_web_services,node_web_api,node_web_repo,node_cli_app,node_cli_auth toneMint
class node_agent,node_extensions,node_pulumi_provider,node_talos toneRose
```

## Components

### Attestation service

Core control plane API and machine lifecycle backend

- [App core](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/core/app.py): FastAPI wiring · Application setup, config, and dependency injection · `src/attestation/core/app.py`
- [HTTP routes](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/routes): API surface · HTTP endpoints for registration, machines, attestation, config, and audit · `src/attestation/routes`
- [Handlers](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/handlers): business logic · Lifecycle logic for registration, approval, attestation, and config delivery · `src/attestation/handlers`
- [Repositories](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/repositories): persistence · Machine and operator persistence layer · `src/attestation/repositories`
- [Domain models](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/models): entities · Machine and operator domain objects · `src/attestation/models`
- [Schemas](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/schemas): contracts · Request and response payload definitions · `src/attestation/schemas`
- [Registration](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/routes/registration.py): onboarding flow · USB and self-registration entrypoints for new machines · `src/attestation/routes/registration.py`
- [Machine ops](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/routes/machines.py): lifecycle API · Approve, reject, revoke, lock, unlock, and inspect machine state · `src/attestation/routes/machines.py`
- [Attestation](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/routes/attestation.py): verification API · Boot-time identity verification and evidence handling · `src/attestation/routes/attestation.py`
- [Config delivery](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/routes/config.py): machine config · 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](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/pki): trust services · Nonce, TPM, OIDC, and enrollment CA trust logic · `src/attestation/pki`
- [Nonce store](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/pki/nonce_store.py): replay defense · Tracks one-time challenge material for attestation · `src/attestation/pki/nonce_store.py`
- [TPM verifier](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/pki/tpm_verifier.py): evidence verifier · Validates TPM-backed identity evidence and EK fingerprints · `src/attestation/pki/tpm_verifier.py`
- [Quote verifier](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/pki/quote_verifier.py): quote verification · Checks attestation quotes and proof material · `src/attestation/pki/quote_verifier.py`
- [Enrollment CA](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/attestation/pki/enrollment_ca.py): credential issuance · Issues enrollment credentials and CA material · `src/attestation/pki/enrollment_ca.py`

### Operator surfaces

Dashboard and CLI clients for operators

- [Dashboard app](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/web/app.py): web UI · Operator-facing dashboard and API surface · `src/web/app.py`
- [Web services](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/web/services): presentation logic · Dashboard-facing services for machines, audits, and queries · `src/web/services`
- [Web API](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/web/api): routes · Dashboard endpoints for machines, policies, config, audit, and query · `src/web/api`
- [Audit repo](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/web/repositories/audit_repo.py): storage · Persistent audit trail backing the operator views · `src/web/repositories/audit_repo.py`
- [CLI client](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/cli/__main__.py): operator CLI · Command-line client for interacting with the attestation API · `src/cli/__main__.py`
- [CLI auth](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/cli/auth.py): token management · Authentication, Keycloak integration, and token caching · `src/cli/auth.py`

### Automation & extensions

Provisioning companion, extensions, and infrastructure integration

- [Provisioning agent](https://github.com/itlusions/itl.controlplane.attestation/blob/main/agent/agent.py): physical enrollment · USB-based companion that reads TPM EK before deployment · `agent/agent.py`
- [Extensions](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/extensions): plugin system · Built-in automation and integration extensions · `src/extensions`
- [Pulumi provider](https://github.com/itlusions/itl.controlplane.attestation/blob/main/src/pulumi_provider/provider.py): iac provider · Infrastructure automation client for control plane resources · `src/pulumi_provider/provider.py`
- [Talos delivery](https://github.com/itlusions/itl.controlplane.attestation/tree/main/src/attestation/talos): config pipeline · Generates Talos configs and serves or fetches hardened ISOs · `src/attestation/talos`

## Connections

- 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
