Threat model
This page is for people deciding whether to use device-passport: device owners, the teams that run a CA, and buyers who need to know what a "passing" device really means. It restates section 4 of the design in plain language and describes what the Phase 1 code actually does.
Status: Phase 1 (v0). Every answer is agent-reported. Device keys are software keys until the hardware backends land (milestone M6). Read Residual risks in Phase 1 before you rely on this for anything.
The short version
device-passport lets an SSH server admit only devices that say they meet a posture bar: disk encrypted, OS patched, firewall on, and so on. The device signs its answers with its own key. A team-run CA checks the answers and, if they pass, issues an SSH certificate that lasts 10 minutes.
It catches honest mistakes. It does not catch a liar with root.
- It defends against a careless owner (encryption off, updates ignored, firewall off), commodity malware that has not got root, and someone reusing a person's credentials from a machine that was never enrolled.
- It does not defend against a dishonest device owner, or malware with root, lying about the device's state. On a general-purpose computer where the user is root, software cannot prove its own integrity to someone far away.
This is the same model that compliance agents such as Vanta or 1Password Device Trust work under. Auditors accept it for SOC 2. We say it plainly so nobody mistakes it for more.
What "agent-reported" means
Every answer the device gives carries an assurance level. Phase 1 has one level in use: agent-reported.
An agent-reported answer means: the device-passport agent on this specific device says so.
It proves:
- The answer came from the agent holding this device's key. The key was registered to a named person through your SSO.
- The answer is fresh. It answers a one-time challenge from the CA that is valid for 60 seconds. The CA accepts each challenge once.
- The answer is for this CA. It names the CA's audience key, so it cannot be replayed to another organisation.
- The facts behind it were collected recently. The agent declines rather than answer with facts older than the grant allows (60 seconds). One exception: the OS update check runs every few hours and may be up to a day old.
It does not prove:
- That the agent is unmodified. Root can replace or patch it.
- That the facts are true. The agent reads them from the operating system. Root can make the operating system say anything.
- That the device stays compliant after the answer. A device can turn its firewall off one second after a certificate is issued.
- In Phase 1, that the key is in hardware. See below.
The CA does not trust the assurance label the device writes. It works the
label out itself. Until evidence from a trusted issuer is checked (Phase 2),
the CA counts every result as agent-reported, whatever the device claims.
The CA refuses to start with min_assurance = "hardware-backed" for the same
reason.
Hardware-backed answers come later (Phase 2). They are signed by Apple or a TPM and checked by an evidence issuer. They narrow the gap: an attacker cannot forge Apple's or a TPM's signature over the boot state. Runtime state above the boot chain stays self-reported even then.
What device-passport will never do
These are design rules (the anti-goals in section 3 of the design). If any of them becomes true, the design has failed, even if it works.
- No organisation can change, isolate or wipe your device. The agent has
no command that changes device state. The CA cannot send it anything; the
agent only answers challenges that its own SSH agent fetched. Its
signing method for SSH (
sign_ssh) signs SSH login requests for the device key and nothing else. - The vendor cannot take over your machine. There is no vendor service in Phase 1 at all. The CA is open source and run by the team that wants the check.
- An organisation cannot rebuild your device's raw state by probing.
Answers are yes / no / unknown for named, coarse predicates such as
os_patched_within:14d. They are not raw data. An organisation can only ask the exact predicates you granted it, at mostrate_per_hourtimes an hour (120 by default). Every question and answer is written to a local, hash-chained log you can read withdp logand check withdp log verify. - Claims are never presented as stronger than they are. See above.
- One organisation's access never depends on another organisation's infrastructure. Each team runs its own CA. Grants name one CA's key.
What the CA learns, and what it does not
At enrollment (dp enroll), the CA learns:
- your identity from your SSO: the OIDC subject and your email (or whatever claim the CA maps to SSH principals);
- the device's public key and the device id (a hash of that key);
- where the device says the key lives (
key_kind: software, Secure Enclave or TPM); - the agent's grant-root public key, and the grant you chose to give it.
At each certificate request, the CA learns:
- the outcome (
true,falseorunknown) of each predicate it asked about, under your grant; - the device clock's time when the answer was made and when the facts were collected;
- the grant id.
The CA does not learn:
- raw facts: no file lists, no process lists, no version strings, no settings values;
- anything about predicates you did not grant;
- which other organisations your device talks to. Each grant names one CA.
Each CA gets only its own certificate, from its own
dp-ssh-agentsocket (see Host scoping).
One thing is shared: the device key. The same public key is registered with every CA you enroll with, and it is in every SSH certificate. Two organisations that compare notes can tell that the same device enrolled with both. Every SSH server you log in to sees the key too.
The CA's challenge endpoint gives the same refusal for "unknown device", "revoked", "bad signature" and "principal not allowed". Another organisation cannot use your CA to find out whether a device is enrolled there.
Who can do what
A compromised CA
Someone who controls a team's CA (its host, or its key files) can:
- issue SSH certificates for any principal on any key. They get into every server that trusts that CA. This is true of any SSH CA. Protect the SSH CA key like a root password.
- ask your device the predicates in its grant, up to the grant's rate limit. Each question is logged on the device.
- read the enrollment data above for every person and device.
They cannot:
- change, lock, wipe or run anything on your device;
- ask predicates you did not grant, or ask more often than the grant allows;
- use your grant with another organisation's CA, or another CA's grant;
- get into servers that trust a different CA.
To stop trusting a CA, revoke its grant on the device (dp grants revoke <grant_id>). The agent stops answering at once.
A compromised device (malware without root)
Malware running as you, but not root, can:
- use your SSH access, as with any ssh-agent. It can ask
dp-ssh-agentto sign SSH logins, and so log in where you can, while the device passes the posture check. - lie about screen lock. The root daemon cannot read screen-lock
settings, so
dp-ssh-agentcollects them in your session and pushes them todpassd. Any process running as you can push a different value. - revoke your grants or mint new ones. Both are owner-only methods on the
dpassdsocket, and your processes are the owner.
It cannot:
- make the device pass a check it fails, other than screen lock. The facts come from the root daemon.
- get the device to sign a forged posture answer.
sign_sshrefuses anything that is not an SSH login request. - copy the device key. In Phase 1 the software key file is readable by root only. With a hardware key (M6) nobody can copy it.
Other local users (not you, not root) can read the predicate outcomes with
dp status. They cannot use the key, see grants, or read the log.
A malicious root user (or a dishonest owner)
Root can make the device say anything. Root can:
- feed the agent false facts, or replace the agent;
- in Phase 1, copy the software device key and the grant-root key and answer from another machine. That machine then passes as this device.
This is the main limit of the whole approach, and it is stated in the design. Hardware keys (M6) stop the key copying. Hardware-backed evidence (Phase 2) stops lies about the boot state. Nothing in this design stops a root user lying about runtime settings.
A stolen laptop
If the thief gets the laptop unlocked and logged in, they can use your
SSH access like you can. Enrollment is already done, so no SSO login is
needed for each certificate. Revoke the device on the CA at once (dpass-ca devices revoke <device_id>). It gets no new certificates after that. A
certificate it already has stays valid until it expires (at most cert_ttl,
10 minutes by default).
If the laptop is locked or off:
- With full-disk encryption on, the thief cannot read the keys.
- With encryption off (the device would fail
disk_encrypted), a thief can boot another OS and copy the Phase 1 software key files. Then they can pose as the device from anywhere until you revoke it. - With a hardware key (M6), the key cannot leave the chip, so it cannot be used anywhere but the stolen laptop.
A network attacker
The device only talks to a CA over HTTPS (plain HTTP is allowed only to
127.0.0.1 or [::1], for testing). The CA must sit behind a TLS
terminator. Beyond TLS:
- challenges are signed by the CA's audience key, and the agent only answers challenges signed by the key its grant names;
- answers are signed by the device key and bound to a one-time nonce and to the CA. A captured answer cannot be replayed;
- the challenge request itself is signed by the device, so nobody else can fetch a challenge (which carries the device's grant);
- the SSO login uses the authorization code flow with PKCE, a fresh
nonceandstate, and a redirect to a loopback port on the device.dp enrollchecks thestate.
A network observer can still see that a device talks to a CA (DNS, TLS server name) and when.
How access ends
| Action | Takes effect | What still works |
|---|---|---|
dpass-ca devices revoke <device_id> |
next challenge or certificate request | certificates already issued, until they expire |
dpass-ca people revoke <email> |
next request, for every device of that person | same as above |
dp grants revoke <grant_id> (on the device) |
next challenge from that CA | same as above |
| Device stops passing a predicate | next certificate fetch | the cached certificate, until it expires |
dpass-ca people revoke also blocks the person's email and principal key.
A recreated SSO account with the same email cannot register again.
Three things outlive revocation:
- Issued certificates. OpenSSH does not ask the CA whether a
certificate is still good. A certificate is valid until it expires. That
is why the default lifetime is 10 minutes.
dp-ssh-agentreuses a cached certificate while it has more than 60 seconds left. - Open SSH sessions. sshd checks the certificate at login only. A
session that is already open stays open after the certificate expires.
So does an SSH connection shared through
ControlMaster. - Posture changes. The device is checked when a certificate is issued, not during the session.
Operators can close the first gap with OpenSSH's own RevokedKeys. See
Operating the CA.
Host scoping
The ssh-agent protocol does not tell the agent which server ssh is
connecting to. If one agent socket served every CA's certificate, every
server would see every organisation's certificate, and connecting to one
organisation's server would contact every CA.
So dp-ssh-agent opens one socket per ssh.toml entry (one per CA and
principal), and dp ssh setup points each entry's Host patterns at that
entry's socket with IdentityAgent. A server that matches one
organisation's patterns sees only that organisation's certificate (and the
raw device key), and only that CA is contacted. The patterns are yours to
set. A pattern that is too broad shows that certificate to more servers.
Residual risks in Phase 1
- Software keys. The hardware backends (Secure Enclave, TPM) are
milestone M6 and not built yet. The device key is a file readable by
root. Root, or anyone who can read an unencrypted disk, can copy it.
ssh_key_hardware_boundisfalseon every Phase 1 device. Release builds ofdpassdrefuse the software key unless started with--allow-software-key. - Everything is agent-reported. No result is backed by hardware
evidence. The
dp_tokensslot for that is always empty. See What "agent-reported" means. - Screen lock is user-reported. It comes from your session, not the root daemon.
- Checks are point in time. Posture is checked when each certificate is
issued, at most every
cert_ttl. Nothing is re-checked during an open session. - The CA is one process on one host. It holds the SSH CA key on disk
(
0600). A PKCS#11 backend is planned, not built. - Shared device key across CAs. Organisations can link a device across enrollments by its public key.
- macOS is less tested. The end-to-end SSH test runs in CI on Linux only. The OpenSSH spike has not yet been repeated on macOS 14.
- Wire formats are v0. They may change before Phase 2.