Threat model

kovra is built around one job: let your tools and AI agents use secrets without seeing the sensitive ones. This page states that plainly — the assets it guards, the adversaries it’s designed against, and the limits it does not cross. A security tool that overstates its guarantees is worse than one that’s honest about them.

Assets

• Secret values — literals, the private halves of keypairs, and TOTP seeds.
• The master key — the root of trust that encrypts the whole vault.
• The integrity of the audit trail — a faithful record of what happened.

What kovra is designed to stop

• A prompt-injected or hijacked AI agent exfiltrating secrets. An agent runs under a scope and never receives the plaintext of a high, prod, or inject-only secret. Out-of-scope coordinates are unaddressable — they don’t exist for that session, so a manipulated agent can’t reach what it was never granted.
• A program reading back a value it was given. Sending a high/prod value into a program the agent itself wrote would defeat the point, so those injections are only allowed into a reviewed, allowlisted executable. The allowlist pins the program’s content — an edit un-allowlists it — and refuses generic interpreters and launchers (sh, bash, env, python, node, make, …), which would run whatever script they are handed. Such a run also gets a sanitized environment: a fixed PATH and none of the variables that make a shell, an interpreter or the dynamic loader run extra code.
• Plaintext leaking into the places it usually leaks. Values never land in a log, on disk, in argv, in shell history, or in a model’s context window.
• A secret committed by accident. A pre-commit hook scans staged changes and blocks the commit.
• A lost or stolen laptop, or casual disk inspection. Every record is encrypted at rest under the master key (custodied in the OS keyring, or derived with Argon2id), and coordinates aren’t exposed as plaintext filenames.

In-scope guarantees

• Sensitive reveals and injections require a deliberate bioProve — they never happen on their own, and never at an agent’s request for high/prod.
• The confirmation prompt is built by kovra from the real request, so it can’t be faked by a caller. It shows the environment, the secret and who asks before the command, and every value a caller can influence is shown escaped, so none can add a line of its own or push the real fields out of view. A long command, path or reference is shown whole, over several lines that kovra marks as continuations (an indent and ↪). Whitespace that could pad a value out of view is shown visible: a run of three or more spaces as one marker with its length ([␣×120]), and every other space escaped. On a Mac every approval is read in kovra’s own window, which shows every field whole however long and scrolls, so nothing is shown cut and only a request past 1 MiB of text or 1 000 secrets, which no command that could start reaches, is refused for its length (so it cannot freeze the screen); where the prompt is a system dialog with room for a few lines (Windows Hello), a request too long to show whole is refused, with the reason.
• The audit trail records every outcome without storing a value or a full fingerprint.
• Critical values — high, inject-only and every prod value — show no fingerprint at all, so not even a truncated one can confirm a guess.
• A swapped master key is detected: the vault holds a key check, and kovra refuses to read or seal with a key that does not open it.

Out of scope — the honest limits

• The last mile. Once a value is delivered to the process that needs it, it lives in that process’s memory under that program’s rules. kovra secures custody and delivery, not what a program does with a value after it has it.
• A compromised host. kovra trusts the operating system’s keyring and biometric subsystem and the machine’s own integrity. A root-level compromise, a kernel keylogger, or malware reading another process’s memory is outside what a user-space tool can defend.
• A human (or program) you authorize. kovra makes a sensitive action deliberate and attributable — it does not make it impossible. If you bioProve a bad action, or allowlist a malicious program, kovra will carry it out and record it.
• Raising a sensitivity after the fact. Moving a secret to high or inject-only protects it from then on; it does not take back a value that was already shown or delivered. If it may have been exposed, rotate it.
• The vault files themselves. kovra keeps no older copy of a record, but a program running as you can still copy, delete, or put back the vault’s files with the shell. That is the file system’s limit, not something an app can stop; a backup of your vault holds whatever sensitivity each secret had when it was made.
• Cloud provider trust. A cloud reference resolves under your provider identity; the provider still sees what it always would.
• Your cloud CLI login. A reference resolves with your own provider login (az, aws). An agent running as you, with that CLI signed in, can read the provider secret directly: high on a reference governs what kovra delivers, not what your cloud session allows.
• The Keychain item. On macOS any program running as you can delete or rewrite the Keychain item that holds the master key, with no prompt. That is the operating system’s limit. kovra cannot prevent it, but it detects it: a swapped key stops kovra instead of sealing new secrets under a key the agent knows, and a deleted one leaves the vault unreadable until you restore it with kovra key import — a denial of service, not a disclosure.
• What an allowlisted program reads. The allowlist pins the file you reviewed, not the files it reads (a sourced script, a config file). A program running as you that swaps the file between kovra’s last check and the launch is, again, the file system’s limit.

Trust assumptions

kovra assumes: your machine and OS are not already compromised; the OS keyring and biometric prompt behave as the platform intends; and the vetted cryptographic libraries it builds on are sound. It rolls no cryptography of its own — see Cryptography.