Nokku is a security tool, so this page is written for the people who review it. It explains what protects what, and it’s honest about the limits. The SECURITY.md of each part goes deeper, see the last section.
The short version
- The core can be down and your servers stay reachable. Servers check logins on their own, without calling the core.
- Nothing that matters sits in plain text. CA private keys, SSO secrets and recordings are encrypted in the core. Tokens are stored only as hashes.
- Stolen tokens don’t travel.
nkandnokkudbind their sessions to a key on the machine, ideally inside a TPM chip. - A sign-in certifies one key. Malware that rides on your
nksession can’t get a certificate for a key of its own and carry it off. - Workspaces can’t see each other. The database itself filters every request down to one workspace, so a bug in the application can’t mix them up.
- Your own
sshdstays yours. The daemon never touches port22or/etc/ssh, so you always have a way back in.
Keys and encryption
- Certificate authority. The workspace CA’s private keys are encrypted at rest in the core and decrypted only to sign. Only the public parts leave it.
- Encryption at rest. Secrets in the database are encrypted with a keyset that is itself wrapped, by a key derived from the instance secret or by a KMS (HashiCorp Vault or Scaleway). Every secret is tied to the row it is stored in, so a copy pasted into another row or workspace does not open.
- Recordings are encrypted with a key of their own each, which is one more secret in the database. A deleted recording can’t be read from the moment its row goes.
- No passwords. People sign in with a passkey, a link mailed to them, or their identity provider. There is nothing to leak, stuff or reuse.
- Tokens (sessions, sign-in links, service account keys, invites, enroll tokens) are stored as SHA-256 hashes. The plain token exists only at the moment it’s issued. Sign-in links work once and expire quickly.
- In transit,
nkandnokkudrequire TLS 1.3 to the core and always check its certificate. A core with a certificate from a private CA is trusted through that CA, handed to them as a file, never by skipping the check. SSH sessions are end-to-end encrypted between the laptop and the server, also when they pass through the relay.
Machine identity and DPoP
nk and nokkud each hold a signing key tied to the machine:
- With a TPM 2.0, the key is created inside the chip and can’t be exported.
- Without one, it’s a software key wrapped with a key derived from the machine’s identity. Copying the file to another machine doesn’t work. It is only as safe as the file’s permissions, so
--require-tpmlets you refuse this fallback.
Every request they send to the core carries a fresh DPoP proof (RFC 9449) signed with that key. A proof also carries a short-lived nonce from the core, and the core accepts each proof once. A captured proof can’t be replayed. A leaked session token alone is useless.
A person’s nk sign-in also registers their SSH public key, and the session gets certificates for that key only. A new key needs a new sign-in. Your SSH key can live in the TPM or on a FIDO2 security key that wants a touch for every login. The nk SECURITY.md shows what each option protects against.
A CI job signs in with its platform’s own signed token, and its session is bound with DPoP too. Service account keys for scripts are the exception: they are plain bearer tokens, so treat them like passwords. Their certificates are short-lived and never outlive the key. See Automation and CI.
Tenant isolation
A workspace is the hard boundary. Accounts, sessions, credentials, servers and audit events all belong to exactly one, and nothing in a request names a workspace. The core picks it from the address the request came in on, before it looks at who is calling. A self-hosted core serves one workspace. The hosted service gives each workspace its own address, so cookies, passkeys and sign-in links of one workspace never reach another.
All data lives in PostgreSQL. Every workspace table uses row-level security with one identical rule: each request runs with its workspace set, and the database only returns that workspace’s rows. If the workspace isn’t set, the database returns nothing. Requests run as a database role that is bound by these rules.
This is a safety net against bugs, not a wall against a compromised core. Work that spans workspaces, like background jobs, runs as a second role that skips the rules, and the core holds the password of both.
A session is pinned to the workspace it was created in and carries the account’s role. Every API call declares the minimum role it needs. Calls nobody classified are denied by default. Adding a way in, like a passkey or a CI rule, or changing the CA needs a recent sign-in in the browser.
The daemon on your servers
- Certificates only. Its SSH server refuses passwords and plain keys.
- Local decisions. Logins are checked against the local access list. No call to the core happens during a login.
- Least privilege for sessions. The daemon runs as root only so it can start each session as the right Linux user.
- No shared secret. It authenticates to the core with its DPoP-bound machine key. Deleting the daemon in the web app revokes it.
- Break-glass by design. Your system
sshdon port22is never touched. If Nokku misbehaves, your usual way in still works. Secure and monitor it by your own rules.
Web and API hardening
- Passkeys (WebAuthn) with user verification, bound to the workspace address.
- Accounts are created by invitation, by the identity provider or by SCIM, never by a public form. An invite is the admin’s proof that the person belongs here.
- Requesting a sign-in link always answers the same, so the form can’t be used to find out who has an account.
- Stricter rate limits on sign-in routes than on the rest of the API.
- Strict content security policy, HSTS, frame denial, SameSite cookies and CSRF protection.
- An email for every new way into an account, like a sign-in from a new device or a new passkey.
- Outbound requests to SSO providers and audit streams never reach the addresses where clouds serve instance metadata. On the hosted service they only reach public addresses. A self-hosted core also reaches private ones, so an identity provider on your own network works.
Limits to know about
- Certificates can’t be recalled. Nokku revokes access by changing what servers allow, not with a revocation list. On servers with
nokkudthat’s immediate. On servers set up withnk sync, and on a daemon server that was offline, new logins stop when the certificate expires. No new certificate is signed without the grant, and certificates for servers without the daemon are kept short. - The relay carries encrypted traffic. It can’t read sessions, but it can see that a connection happened and how much data flowed.
- The browser terminal is different. There the core is the SSH client, so what is on the screen passes through it in the clear.
- Port 22 is out of scope. Logins through your own
sshdbypass Nokku’s checks, audit and recording by design. - Recordings capture what’s on screen. Nothing is redacted. See Audit log and recordings.
Go deeper
Each part has its own SECURITY.md with the details and how to report a vulnerability:
- Core and web app: the secret, KMS, the owner account, network and database
- nokkud: the machine key, how its SSH server behaves, recordings
- nk: where your key lives and what a compromised machine can do
- Shared packages: TPM, DPoP and trust code
To report a vulnerability, see SECURITY.md.