Skip to content

The Etminan handbook

Etminan is TPM 2.0 + Linux IMA host-integrity attestation that survives a full root compromise. A monitored host measures itself from inside the kernel and seals the result in tamper-resistant hardware; a separate, independently administered verifier makes every trust decision off-box. This handbook is the operator's reference for deploying and running both halves.

What Etminan is

Every classic file-integrity monitor — AIDE, Tripwire, Samhain — keeps its checksum database and raises its alarm on the very host it is watching. A root-level compromise can rewrite that database, silence that alarm, and the machine keeps reporting itself healthy. The compromised host is being asked whether it is compromised, and it answers "no."

Etminan removes the host's ability to lie. Integrity evidence comes from Linux IMA measuring files into a TPM 2.0 Platform Configuration Register — a one-way, kernel-level hardware operation that root cannot reverse or forge after the fact — and every pass/fail judgment is made by a different machine that the monitored host has no control over.

The one property the whole design defends

A fully root-compromised monitored host cannot forge a "genuine" verdict, nor silently suppress an alarm.

The threat model, in plain terms

Etminan assumes the worst realistic case: an attacker has full root on a monitored host. They can patch binaries, edit config, replace the agent, feed it lies, or kill it outright. The architecture is built so that none of that produces a false "all clear."

Three design choices make that hold:

  • Two independently administered binaries. The etminan-agent on the monitored host and the etminan-verifier on a separate device are run by different people, on different machines, with different credentials. A host compromise reaches the agent — never the verifier.
  • The host never judges itself. The agent makes no pass/fail decision, writes no audit entries, and raises no alerts. It only relays signed, verifiable evidence. Every judgment happens on the verifier.
  • Evidence root cannot forge. The signature over each quote is produced by an Attestation Key whose private half never leaves the TPM. A compromised host can refuse to answer or kill the agent — but silence is itself a detectable, alarm-worthy state — and it cannot manufacture a freshly-nonced, validly-signed clean quote for a state that isn't real.

What a vTPM proves, and what it doesn't

On a virtual machine with a vTPM, attestation proves the guest OS was not tampered with from the inside — the stated threat model. It does not by itself prove the TPM is genuine silicon rather than software emulated under a compromised hypervisor. For discrete hardware you can close that gap at enrollment with a manufacturer EK-certificate chain (see Enrolling a host).

How it works

A monitored host's kernel measures files as they are read or executed and extends each measurement into PCR 10 of the TPM. On request, the agent takes a TPM-signed quote of that PCR and ships it alongside the raw IMA measurement-log delta. The verifier replays the log, recomputes PCR 10, and confirms the value it computed equals the value the TPM signed — binding the human-readable log to the cryptographic quote — then diffs the measurements against an approved baseline and decides.

flowchart LR
    subgraph host["Monitored host — etminan-agent (a relay)"]
        direction TB
        files["Files read / executed"] -->|kernel IMA hook| ima["IMA measurement log<br/>(SHA-256 bank)"]
        ima -->|"extend (one-way)"| pcr["TPM 2.0 · PCR 10"]
        pcr -->|"TPM2_Quote, signed by AK<br/>(private key never leaves TPM)"| agent["etminan-agent"]
        ima -->|log delta since last offset| agent
    end

    subgraph verifier["Separate device — etminan-verifier (every decision)"]
        direction TB
        replay["Replay log → recompute PCR 10"] --> compare{"recomputed ==<br/>TPM-signed digest?"}
        compare -->|no| forge["Reject: forged / inconsistent"]
        compare -->|yes| diff["Diff vs. approved baseline"]
        diff --> decide["Verdict"]
    end

    agent -->|"quote + log delta<br/>mandatory mutual TLS, pinned by fingerprint"| replay
    decide -->|finding| alarm["Alarm off-box:<br/>email · SIEM · notify plugins"]

    style host fill:#0f1c18,stroke:#1e332b,color:#e9efec
    style verifier fill:#0f1c18,stroke:#1e332b,color:#e9efec
    style alarm fill:#1e332b,stroke:#7fd99a,color:#e9efec
    style forge fill:#3a1f1a,stroke:#e0846b,color:#e9efec

The verifier polls every enrolled host on a schedule (hourly by default). A fresh nonce in every request defeats replay of a captured quote; the offline signature math means the verifier itself needs no TPM.

Core concepts

Term What it is
TPM 2.0 A tamper-resistant hardware (or firmware/virtual) security chip. Holds the keys that sign attestations; its private key material never leaves the chip.
Linux IMA The kernel's Integrity Measurement Architecture. Hashes files as they are read or executed and extends each hash into a TPM PCR — a kernel-level operation userspace root cannot undo.
PCR 10 The Platform Configuration Register the IMA runtime log extends into. Etminan uses the SHA-256 bank of PCR 10, exclusively and by design.
Quote A TPM-signed statement of a PCR's current value plus a verifier-supplied nonce, signed by the host's Attestation Key. The un-forgeable core of the evidence.
AK / EK The Attestation Key signs quotes; the Endorsement Key is the TPM's stable identity, used at enrollment to prove the AK really lives in this TPM.
Measurement log The human-readable IMA record (ascii_runtime_measurements_sha256) of every measured file. Only trusted once it replays to the signed PCR value.
Baseline The set of measurements an operator has explicitly, signably approved as known-good for a host. Drift is proposed, never auto-accepted.
Agent etminan-agent — the relay on each monitored host. Needs a TPM. Makes no decisions.
Verifier etminan-verifier — makes every trust decision on a separate device. Needs no TPM.

Full definitions are in the Glossary.

Editions

Etminan ships in two editions from a single codebase, selected at compile time:

  • Standard — free of charge, self-hosted. The complete attestation engine: enrollment, the baseline/approval workflow, mandatory mutual TLS, the hash-chained audit log, the etminan-verifierd trust daemon with its peer-UID op interface, RBAC (admin/operator/viewer roles) and optional per-role TOTP, key rotation/revocation, and the notify/change-source plugins.
  • Enterprise — everything in Standard plus SIEM output (CEF/LEEF over syslog) and dual control (four-eyes approval).

Enterprise edition

Throughout this handbook, capabilities that require the Enterprise build are called out in a box like this one. The Standard build and the feature-off path are byte-for-byte the legacy behaviour.

Standard is free of charge and self-hosted, but it is not open source. See Editions for the full capability matrix.

How to read this handbook

Conventions

Commands are shown for the machine they run on — etminan-agent … on a monitored host, etminan-verifier … on the verifier device. Placeholders like web-01 (a host id) and 10.0.0.5:7620 (an agent address) are examples; substitute your own. Both binaries hand-roll their argument parsing, so every subcommand also accepts -h/--help for a focused, in-terminal summary.