A scope says what a credential may read. It says nothing about how much, or how fast, and it leaves no trace by itself. enveil adds two things: every disclosure is recorded against whoever asked, and tokens carry a read budget.
Every read is recorded
A write is something someone did on purpose. A read is how a credential actually leaves the system, and it is the question an incident starts with: who has seen this key? So enveil records reads, not just writes.
Each event holds:
- who: the person or the machine identity, kept apart, so an agent's read is not mistaken for its creator's;
- what: the action, the project, the environment, the key and the version read or written;
- when;
- from where: the source IP address.
An event never holds a value.
The audit write for a disclosure lives inside the same function that decrypts. The value is returned only after its event is stored, and if the write fails the read is refused. A new endpoint therefore cannot hand out a secret without recording it. Events for other actions, such as writes, are recorded on a best-effort basis: a failed audit write is logged, and the write itself stands.
In the dashboard, Audit trail shows recent activity with disclosures highlighted and agents marked. From a secret, Who has read this secret lists every read of that key and every export of an environment that included it.
Actions
| Action | Recorded when |
|---|---|
secret_read |
One value was disclosed: enveil get, the get_secret MCP tool, a historical version, Reveal in the dashboard |
environment_exported |
A whole environment was disclosed at once: enveil run, pull, export_environment. One event per export, naming every key it carried |
secret_proxied |
A value was injected by proxy mode on its way to an allowed host, not disclosed to the caller |
secret_created, secret_updated, secret_deleted |
A value was written, replaced (including by rollback) or removed |
secret_proxy_hosts_changed |
A secret's allowed hosts changed, which widens or narrows where it can be sent |
secret_expiry_changed |
A secret's expiry was set or cleared |
project_created, project_renamed, project_deleted |
A project was created, renamed or deleted in the dashboard |
identity_created, identity_revoked |
A machine identity was minted or revoked |
trust_policy_created, trust_policy_deleted |
A trust policy was registered or deleted, in the dashboard or over MCP |
identity_throttled |
A read was refused because the credential was over its budget |
Listing keys, history, whoami and example disclose nothing and are not recorded.
Read budgets
Each credential that reads through the API has a budget of secrets disclosed per minute and per hour:
- A machine identity uses its own limits, set with
--budget 60/600or in the dashboard. Without them it gets the defaults: 600 a minute, 5,000 an hour. - A person's token (the CLI login, an MCP connector, an API key) is metered against the same defaults. Your login can reach everything you can, and an agent running on it should not be able to drain that at full speed.
- A person clicking Reveal in the dashboard is not metered.
The budget is charged per secret, not per request. get costs one. An export costs as many units as the environment holds, otherwise the cheapest way to drain a project would be the one the budget barely notices. Each injection in proxy mode costs one.
The minute window stops a runaway loop; the hour window bounds a sustained drain. Counters are shared across server replicas.
When a budget runs out
The request is refused before the value is decrypted. The CLI exits with code 4; the API answers 429 with reason: "read_budget_exceeded" and retryable: true; over MCP the tool result has isError: true with the same fields. The message says which window ran out and what the limit is.
Refused reads still count, so a caller hammering the endpoint stays refused instead of earning a fresh allowance per attempt. Each refusal is recorded as identity_throttled.
The organization's owners and admins are emailed when a machine identity is throttled, at most once per identity every 24 hours. The email names the identity, what it was refused and where, never a value, and links to the dashboard to revoke it. A person's throttled token sends no email.
retryable: true means the same call can succeed after the window resets. An agent should stop and tell the person, not retry in a loop.
The budget check fails closed: if the counter cannot be updated, the read is refused. A refused read can be repeated later; an unbounded drain cannot be undone.
What this bounds, and what it does not
It bounds repeated mass reads and slow enumeration, and it makes a runaway or compromised agent visible: there is an event for every read, a refusal when it goes too fast, and an email to someone who can revoke it.
It does not prevent one authorized export of everything already in scope. An identity scoped to prod with a budget large enough for that environment can read all of it, once. That is what the scope list is for: give agents the narrowest scope, and prefer proxy-only access, which never hands the value to the caller at all.