Linux Open Trusted Attestation

Linux Open Trusted Attestation, or LOTA, is a Linux attestation and runtime-integrity framework.

It lets a remote verifier or game server decide whether a host was enrolled through a manufacturer-backed TPM, booted into an approved firmware and Secure Boot state, runs the expected LOTA agent image, and enforces the configured runtime gates through BPF LSM.

LOTA is not a behavioral anti-cheat engine. It does not scan gameplay state, input, memory signatures, or network behavior. It provides a hardware-backed trust substrate that game, anti-cheat, fleet, or relying-party policy can build on top of.

Trust chain overview

The production trust chain is:

TPM 2.0 EK certificate -> Attestation CA (1) -> LOTA agent (2) -> Verifier / SDK consumer (3)

(1) Attestation CA
  - verifies EK roots
  - runs TPM2 credential activation
  - issues an AIK certificate

(2) LOTA agent
  - owns TPM interaction
  - measures boot and runtime state
  - loads signed BPF LSM policy

(3) Verifier or SDK consumer
  - checks AIK certificate trust
  - verifies TPM quote freshness
  - enforces PCR, boot, runtime, and token policy

The verifier trusts a CA-issued AIK certificate, not an agent-asserted public key. Firmware and Secure Boot state are pinned through PCR 0, PCR 1, and PCR 7. LOTA's own boot commitment is bound through PCR14. Runtime protection is enforced by the agent and BPF LSM hooks, with fs-verity, SELinux, lockdown, module signing, and signed BPF objects forming the production floor.

For the complete security boundary, read Documentation/security/threat-model.rst.

Quick start

• Build the tree: env GOCACHE=/tmp/lota-gocache make BUILD_DIR=/tmp/lota-build all
• Run unit tests: env GOCACHE=/tmp/lota-gocache make BUILD_DIR=/tmp/lota-build test-unit
• Build optional examples: make examples
• Bring up a production host: see Documentation/operator/production-bringup/index.rst
• Run the end-to-end demo material: see examples/README.rst
• Report a vulnerability: see SECURITY.md
• Contribute a patch: see CONTRIBUTING.rst

Build inputs include a C toolchain, clang/LLVM for BPF, libbpf, TPM2-TSS, OpenSSL, systemd, libseccomp, D-Bus headers, and Go for the verifier and attestation CA.

The authoritative build and test policy is in Documentation/contributor/development/index.rst.

Essential documentation

All users should know where these documents live:

• Threat model: Documentation/security/threat-model.rst
• Production bring-up: Documentation/operator/production-bringup/index.rst
• Development and testing policy: Documentation/contributor/development/index.rst
• Branch and release flow: Documentation/contributor/branching.rst
• Reproducible builds: Documentation/security/reproducible-builds.rst
• Performance evaluation: Documentation/performance/evaluation.rst
• PCR policies: policies/README.rst
• SELinux policy: selinux/README.rst
• EK root bundle material: configs/ek-roots/README.rst
• Security reporting: SECURITY.md
• Code of Conduct: CODE_OF_CONDUCT.rst

The full documentation tree, organised by reader role, lives under Documentation/.

Repository map

• src/agent/ - privileged host agent, TPM interaction, BPF loading, IPC, reporting, enrollment, and runtime measurement.
• src/bpf/ - BPF LSM enforcement programs.
• src/initramfs/ - PCR14 initramfs lock helper and dracut integration.
• src/attestca/ - attestation CA and TPM credential-activation service.
• src/verifier/ - verifier, policy engine, stores, API server, nonce handling, revocation, and report validation.
• src/sdk/ and include/ - C SDK, server SDK, token formats, and public integration headers.
• policies/, configs/, systemd/, selinux/, and dbus/ - production deployment policy and service material.
• examples/ - enrollment, demo server, anti-cheat heartbeat, game UI, sealed-key, mTLS, runtime remeasurement, and blocking scenarios.
• benchmarks/ and syzkaller/ - performance and kernel-surface validation material.

Who are you?

• Operator - deploying the agent and verifier on real hosts.
• Game or anti-cheat integrator - consuming trust verdicts and SDK tokens.
• Security reviewer - auditing the trust model and reporting vulnerabilities.
• TPM or attestation engineer - reviewing enrollment, EK roots, AIKs, and PCRs.
• Kernel or BPF engineer - reviewing runtime gates and LSM portability.
• Distribution maintainer - packaging, signing, and reproducing releases.
• New contributor - preparing patches against lota-next.
• Academic reviewer - evaluating design, threat model, and measurements.
• Automated coding assistant - following project contribution rules.

The role-specific documentation index lives at Documentation/index.rst.

For specific users

Operator

Production operation starts with the bring-up document. The agent intentionally fails closed when required gates are missing.

• Production checklist: Documentation/operator/production-bringup/index.rst
• PCR policy templates: policies/README.rst
• SELinux policy: selinux/README.rst
• EK root bundles: configs/ek-roots/README.rst
• Example configuration: configs/lota.conf.example
• Re-enrollment flow: examples/enrollment/README.rst

Game or anti-cheat integrator

LOTA exposes trust decisions and token verification material. Gameplay policy remains outside this repository.

• Example index: examples/README.rst
• Reference server: examples/demo_server/README.rst
• Anti-cheat heartbeat producer: examples/demo_anticheat/README.rst
• Demo game client: examples/demo_game/README.rst
• End-to-end demo: examples/demo/README.rst
• mTLS example: examples/mtls/README.rst
• Runtime remeasurement: examples/runtime_remeasure/README.rst

Security reviewer

Start with the threat model and the security reporting policy. Do not file public issues for exploitable vulnerabilities.

• Threat model: Documentation/security/threat-model.rst
• Security reporting: SECURITY.md
• Reproducible release verification: Documentation/security/reproducible-builds.rst
• Production bring-up: Documentation/operator/production-bringup/index.rst
• Development tests and fuzzing: Documentation/contributor/development/index.rst
• Performance baseline: Documentation/performance/evaluation.rst

TPM or attestation engineer

The hardware trust contract is centered on EK root validation, credential activation, AIK certificates, TPM quotes, PCR policy, and PCR14 boot commitment.

• Threat model: Documentation/security/threat-model.rst
• Enrollment example: examples/enrollment/README.rst
• EK root bundles: configs/ek-roots/README.rst
• PCR policy documentation: policies/README.rst
• Production bring-up: Documentation/operator/production-bringup/index.rst

Kernel or BPF engineer

The kernel-facing surface lives in the BPF LSM object, loader, runtime measurement path, initramfs PCR14 lock, SELinux policy, and Syzkaller harness.

• BPF and production gates: Documentation/operator/production-bringup/index.rst
• SELinux policy: selinux/README.rst
• Kernel test policy: Documentation/contributor/development/index.rst
• Syzkaller harness: syzkaller/README.rst
• Runtime remeasurement example: examples/runtime_remeasure/README.rst

Distribution maintainer

Packaging must preserve the security contract. Release artifacts are intended to be reproducible and verified against signed manifests.

• Reproducible builds: Documentation/security/reproducible-builds.rst
• Release and branch flow: Documentation/contributor/branching.rst
• Production install gates: Documentation/operator/production-bringup/index.rst
• systemd units: systemd/
• udev rules: configs/udev/99-lota-tpm.rules
• IMA policy: configs/ima/lota-ima-policy
• SELinux policy: selinux/README.rst

New contributor

Development happens on lota-next. Open pull requests there, not against main.

• Contribution rules: CONTRIBUTING.rst
• Development and testing policy: Documentation/contributor/development/index.rst
• Branch model: Documentation/contributor/branching.rst
• Local patch checks: scripts/check-patch
• Commit-message normalizer: scripts/format-patch
• Code of Conduct: CODE_OF_CONDUCT.rst

Academic reviewer

For thesis or architecture review, read the security model first, then the production and measurement documents.

• Threat model: Documentation/security/threat-model.rst
• Production bring-up: Documentation/operator/production-bringup/index.rst
• Performance evaluation: Documentation/performance/evaluation.rst
• Reproducible builds: Documentation/security/reproducible-builds.rst
• Examples: examples/README.rst

Automated coding assistant

Automated tools must follow the same contribution rules as human contributors. They must not weaken security checks, invent threat-model claims, remove DCO trailers, or bypass documentation updates for changed behavior.

• Contribution rules: CONTRIBUTING.rst
• Development policy: Documentation/contributor/development/index.rst
• Security reporting: SECURITY.md
• Local quality gate: scripts/check-patch

Communication and support

• Security vulnerabilities: use GitHub Private Vulnerability Reporting for github.com/szymonwilczek/lota; see SECURITY.md.
• General contribution process: see CONTRIBUTING.rst.
• Conduct reports: see CODE_OF_CONDUCT.rst.
• Release status and supported versions are documented in release notes and Documentation/contributor/branching.rst.

Licensing

Copyright (C) 2026 Szymon Wilczek.

LOTA is dual-licensed:

• The userspace components are licensed under the MIT license; the full text is in LICENSE. That includes the headers the agent and the BPF program share, because those carry LOTA's own definitions rather than anything derived from kernel source.
• Kernel-facing BPF programs are licensed GPL-2.0-only, as the kernel interface they attach to requires; the full text is in LICENSE.GPL-2.0-only.

Every source file carries an SPDX-License-Identifier naming the license that applies to it, so the license of any individual file is unambiguous regardless of which component it belongs to.