TPM 2.0 · Zero-touch provisioning · FastAPI · Talos Linux

Hardware Trust
for Kubernetes Nodes

The ITL Attestation Service anchors every cluster node to its physical TPM Endorsement Key. No hardware identity, no cluster access — ever.

View on GitHub Documentation Architecture API Reference
Status: Alpha Development: In Progress
TPM 2.0 Ready FastAPI 0.115+ Python 3.12+ SQLite (upgradeable) Talos Linux AMD & Intel fTPM
Trust flow

From bare metal to cluster node

Every node must prove its hardware identity before it ever receives a cluster credential. The TPM EK fingerprint is the immutable anchor.

TPM Chip
EK fingerprint
SHA-256 of EK bytes
→
Registration
USB agent or
Talos extension
POST /register
or /self-register
→
Attestation
Service
EK verified,
machine stored
→
Operator
Approves + assigns
role & hostname
POST /approve
→
Attestation
EK re-verified
on every boot
POST /attest
→
MachineConfig
delivered
GET /config/{token}
→
Node joins
cluster
talosctl apply-config
Registration

Two paths, one identity model

Both paths anchor machine identity to the TPM EK fingerprint. Choose based on whether you have physical USB access before first boot.

USB Registration Agent
Pre-boot — operator has physical access
  • Boot machine from ITL HardenedOS USB (Alpine Linux)
  • Agent reads EK cert from /sys/class/tpm/tpm0/
  • Posts EK fingerprint + hardware metadata to /api/v1/register
  • Service returns a signed Talos ISO URL with config token baked in
  • Operator boots machine from that ISO — Talos auto-fetches its config
Talos Extension (itl-tpm-register)
Zero-touch — machine boots generic Talos ISO
  • Machine boots generic Talos ISO with talos.config=<service-url>
  • Extension reads EK from TPM on first boot
  • Posts to /api/v1/self-register → machine appears as pending_approval
  • Polls /api/v1/attest every 60 s until operator approves
  • On approval: extension fetches full MachineConfig, applies it, node reboots into cluster
Machine lifecycle

Full lifecycle control

Every state transition is logged. Operators can lock, unlock, revoke, and remotely wipe nodes at any time.

State 1
registered / pending_approval
Machine is known to the service. Operator has not yet assigned a role or approved it. No cluster credentials are delivered.
POST /register · /self-register
State 2
Operator Approval
Operator assigns role (controlplane / worker-infra / worker-app), hostname, and optional static IP. A fresh config token is generated.
POST /machines/{id}/approve
State 3
attested
TPM EK fingerprint verified on boot. Full MachineConfig is delivered via one-time config token. Node joins the cluster.
POST /attest · GET /config/{token}
State 4
locked
Reversible suspension. Attestation and cert issuance are blocked. No data is destroyed. Unlockable without hardware intervention.
POST /machines/{id}/lock · /unlock
State 5
revoked
Permanent removal from the cluster. When wipe=true, the next attestation poll returns action=wipe and the Talos extension triggers a full disk reset.
POST /machines/{id}/revoke
Offline
Offline Bundle
Generate a self-contained ZIP containing a signed enrollment cert, role MachineConfig, and USB deployment script — for air-gapped environments with no network access to the service.
GET /machines/{id}/offline-bundle
Features

Security by design

Every control exists to prevent a specific class of attack. Nothing is security theatre.

EK Fingerprint Verification
Server always re-derives the SHA-256 fingerprint from raw EK bytes — never trusts the client-supplied value. Compared with hmac.compare_digest (constant-time).
Enrollment CA
On-disk RSA-4096 CA issues 30-day mTLS enrollment certs for offline USB bundles. Cert + nonce challenge proves key possession, not just cert ownership.
One-time Config Tokens
secrets.token_urlsafe(32) (256 bits). Scoped to a single machine. Regenerated on every registration and approval, invalidating any prior token.
Status-gated Config Delivery
Only attested machines receive their full MachineConfig. All other states get a safe pending config containing zero cluster secrets.
Remote Wipe
Revoking with wipe=true causes the Talos extension to execute talosctl reset --graceful=false, wiping STATE + EPHEMERAL partitions and rebooting into maintenance mode.
No-TPM Fallback
Supports ek_source=pub for machines where the EK cert is not published (e.g. AMD fTPM). Fingerprint is computed from the raw public key bytes instead.
Talos Image Factory
Dynamically builds ISO schematics with talos.config=<url> baked into kernel args. Falls back to pre-built ITL HardenedOS ISO when ITL_ISO_URL is set.
TPM Key Wrapping
Enrollment private keys can be RSA-OAEP-SHA256 wrapped to a TPM resident decrypt key supplied by the client — the plaintext key never leaves the TPM.
AK Activation & PCR Quotes
Nodes register a hardware-resident Attestation Key via POST /machines/{id}/ak-activate. The service verifies the TPM2_Quote signature and PCR digest — proving the machine booted exactly the expected firmware.
Nonce Anti-Replay
Server issues single-use 256-bit nonces (60-second TTL) via GET /attest/challenge. Enable enforcement with ITL_REQUIRE_NONCE=true to prevent recording-and-replaying attestation requests.
Secret Vault Extension
AES-256-GCM encrypted secret storage. Machine-specific secrets (TPM-bound via EK fingerprint) and shared secrets (multi-machine access with ACL). Ideal for disk keys, join tokens, and API keys.
Webhooks Extension
HTTP webhook delivery for attestation events (machine.registered, machine.approved, secret.accessed). HMAC-SHA256 signatures, delivery history, automatic retry, test endpoints.
Metrics Extension
Prometheus-compatible metrics at /metrics endpoint. Tracks machine registrations, attestations, secret operations, webhook deliveries, and audit log activity. Ready for Grafana dashboards.
Pulumi Provider
Manage machine registration and approval as Pulumi resources. Drift detection, one-time secret bundles, enrollment token generation — full IaC lifecycle for bare-metal cluster nodes.
Documentation

Everything you need

From first deployment to production operations — all in one place.

Architecture
System context, component layout, module structure, dependency flow
API Endpoints
Complete REST reference — request/response schemas, auth, status codes
Deployment
Docker Compose, env vars, volume layout, Kubernetes manifests
Operations
Machine lifecycle workflows, operator runbooks, monitoring
Security
Threat model, implemented controls, open issues, hardening guide
UI Walkthrough
Annotated screenshots of all demo pages — dashboard, machines, audit log, machine detail
How a TPM Works
EK, PCRs, AK credential activation, TPM quotes — concepts explained from first principles
Extension System
Secret Vault, Webhooks, Metrics — modular extensions with REST APIs and database models
Event System
NodeEvent enum, EventBus, typed context objects, hook decorators — complete reference
Extension Development
Build your own extension — REST routes, database models, event hook subscriptions
Use Cases
ZTP, hardware replacement, dual-control, SPIFFE, CMDB sync, Vault, Kubernetes label sync
Pulumi Provider
IaC automation — RegisteredMachine, MachineApproval, secret bundles, drift detection
Source Code
GitHub repository — issues, PRs, Dockerfile, CI workflow
Technology

Built on solid foundations

Chosen for production reliability, not novelty.

Python 3.12+ FastAPI 0.115+ SQLModel 0.0.21+ SQLite (Alembic) cryptography 43+ httpx 0.28+ PyYAML 6.0+ Uvicorn Talos Linux TPM 2.0 RSA-4096 / RSA-2048 OAEP-SHA256 Docker GitHub Actions Pulumi 3.x pulumi-itl-attestation