Skip to content
Ambry

Security

The model, and its edges

What Ambry protects, how, and the places it deliberately does not reach. The server enforces every rule here, and the ones that matter most are in the database schema too.

What it is for

Ambry replaces a spread of per-project encrypted files and the passwords that open them. That arrangement had four problems: agents decrypting values in a shell leaked them into transcripts, key material lived on a workstation, one password opened many projects, and nothing recorded who read what.

The first problem is the one the design is built around. Redacting output is not a control: the next clever pipe prints the value. The only thing that holds is an agent credential that cannot return plaintext at all.

Who can do what

Three kinds of principal, and the server decides each request from the credential alone. An agent's reveal or inject is refused without consulting grants, so no grant, however broad, can give an agent a value.

What people, agents and deploy runners can each do in Ambry
Action People The dashboard and ambry, logging in each time Agents An MCP server and an agent token Runners A deploy runner and a token scoped to one namespace
List secrets, read their metadata, query the audit log Yes Yes Yes
Create a secret whose value the server generates Yes Yes gets back a fingerprint, never the value No
Rotate a secret to a new generated version Yes Yes same: a fingerprint comes back No
Enter a value only a person has Yes No files a request; a person fulfils it No
Reveal a value Yes an explicit, audited action No refused by the server, whatever the client No
Inject values into a deploy step No No refused by the server Yes only for the namespace it is granted
Administer principals, tokens and grants Yes No No
  • Secret routes authorize before they look anything up, so a missing secret and a forbidden one are the same 403.
  • Values travel only in request and response bodies, never in URLs, and no log line carries a value or a request body.
  • A bearer token appears in exactly one response, the one that issues it. Tokens are stored as hashes, with a TTL and an optional address range.

How values are sealed

libsodium primitives only, with no custom constructions. Each version of each secret gets its own random data key, and the value is sealed with XChaCha20-Poly1305. The additional data binds the namespace, path and version, so a ciphertext copied into another row fails to open.

Each data key is wrapped by a subkey derived from the KEK. Fingerprints are HMAC-SHA-256 under a separate subkey, then truncated: two references can be compared, and a short password cannot be brute-forced from its fingerprint.

The one key

The key-encryption key is a 32-byte file on the host, readable only by the service user. It is generated there and never leaves it, is never stored in the database, and never travels in a backup stream with it.

  • Without it the server fails closed. It refuses a key file that other users can read, one that is a symlink, or one of the wrong length.
  • It refuses a store sealed under a different KEK, both at start and on every reconnection, so a restore onto the wrong key cannot quietly write under a second one.
  • A recovery kit, the KEK sealed under a passphrase with Argon2id, is how the key survives losing the host. Its format and tools exist; making the kit is still to do, and the kit and its passphrase are never kept together.

The audit chain

Every write and every open is recorded in the same transaction as the change. If the audit row cannot be written, the value does not move. The log never contains values.

The rows form a chain, each MACed under a KEK subkey over the one before it, so a deleted or edited row breaks every row after it. A chain accepts appends under one key only. A verifier walks it end to end.

Backups

Backups are proved before they are sealed. The nightly job restores its own dump into a throwaway database, verifies the audit chain against the live head, opens every sealed value, and checks that each one re-derives its stored fingerprint. Only the bytes that passed are sealed, to a public key whose private half is kept offline.

A sealed backup is anonymous: anyone with the public key could make one. So a restore checks the recovered chain against a record of each backup's audit head kept outside the backup storage, and refuses a file that record does not name.

This machinery is built and deployed, with its timers off until the offline keypair exists. See Status.

Where it runs

The service is internal. It runs on one host on a private network, listens on loopback, and is reached through nginx with TLS on the LAN. There is no public endpoint, and there will not be one. This website is a separate static site and never fronts it.

Nothing running depends on Ambry being up. Deploys read from it and render configuration onto hosts, so an outage stops deploys, not services.

What it does not defend

Stated rather than implied:

  • A logged-in person can reveal. Reveal is explicit, masked again after 30 seconds, and audited, but there are no per-namespace reveal permissions yet.
  • Root on the host has the KEK. The design keeps the key off the database and out of backups; it cannot keep it from the machine it runs on.
  • A playbook can still print what it was given. No Ansible lookup can force no_log on the task that calls it, which was measured rather than assumed. The lookup refuses runs it can see would print, and the real control is that agents never hold a runner token.
  • A value in flight is in ordinary memory. Values are locked and zeroed inside the store, not at the HTTP boundary.
  • KEK rotation does not exist yet. Nor does authentication of a backup's origin beyond the audit-head record.

What is built, and what is not

Each component and each named gap, in its own words.