Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 19 of 30

Secrets isolation

0 of 30 complete

Why it matters

An agent reads environment variables, runs commands, writes files and calls the network, which is every path a credential can travel. A developer's shell history is one copy; an agent trace is another, often with wider access and longer retention. Prompt instructions do not enforce anything, so the engineering problem is to remove the secret from the agent's reach and leave only a narrow capability behind.

Mental model

It is a valet key that opens the door but not the trunk. The metaphor breaks because a shell can copy the key, so the key must never be inside the shell at all; the capability has to sit behind a proxy the agent calls by name.

How it works

Secret reach: store, agent surfaces, proxyInteractive
credential inlet
Step 1/6 · where the key lives
  1. trusted · secret store
    the secrettrusted
    Long-lived API key
    pasted into the promptcredential inlet · open
  2. untrusted · agent reach
    leak surfaceuntrusted
    Context window
  3. Long-lived API key· env var, readablecredential inlet · open
    leak surfaceuntrusted
    Shell env + child processes
  4. Long-lived API key· written to configcredential inlet · open
    leak surfaceuntrusted
    Diff, commit, stored trace
  5. neutral · proxy + egress
    Shell env + child processes· call by namecredential inlet · open
    holds the keyneutral
    Credential proxy
    auth added
  6. allowlistedneutral
    Upstream API
  7. Diff, commit, stored trace· push, paste, trace
    off-listneutral
    Any other host
trusted pathtainted pathcontrol openboundary holdspassespending approvaltrusted zoneuntrusted zoneneutral zone3 zones · 7 nodes · illustrative geometry

where the key lives. One long-lived key is configured in the store. The proxy can read it; the agent should not. The design question is how many copies exist after this point.

Figure. The boundary is the credential inlet: strip secret-bearing environment variables and let the agent call a proxy instead of holding the key. It stops the key entering the context, the shell and written files; it does not make the proxy's upstream scope safe, and it cannot un-expose a trace that was already stored. Blocked, no copy is made: the edges beyond the three surfaces show what a copy would reach. Shown with environment injection open; use Blocked to apply the inlet.

What to notice. Residual risk: the proxy still holds a credential, so an over-scoped token is the same breach with a shorter life. A scan before a commit or a stored trace is the second control and is not drawn as a gate. Every copy is a rotation event.

Text version

Three zones: TRUSTED · SECRET STORE holds the long-lived API key; UNTRUSTED · AGENT REACH holds the context window, the shell environment with child processes, and the diff, commit and stored trace; NEUTRAL · PROXY + EGRESS holds the credential proxy, an allowlisted upstream API and any other host. Three dashed red paths carry the key from the store into the context, the shell and written files. The shell calls the proxy by name on a solid path, the proxy adds auth upstream on another solid path, and the written files feed a dashed red path to any other host. The four store and proxy-call edges carry the credential inlet control: open, the key is copied into all three surfaces; blocked, those three paths are cut at teal bars and the proxy call passes with a teal tick. Downstream edges show what the copies would reach.

  1. Inventory the credentials the task needs and replace long-lived keys with short-lived, scoped tokens.
  2. Inject them through an egress proxy or a credential helper the agent calls by name.
  3. Strip secret-bearing environment variables from the shell the agent controls.
  4. Scan the diff, command log and trace for secret patterns before any of them is stored.
  5. Deny reads of env files, key material and cloud credential directories at the sandbox layer.
  6. Rotate and revoke automatically when a scan hits, and treat the run as compromised.

Trade-offs

ChoiceGood forCostFails when
Environment variable injectionSimple, works with existing toolsVisible to every child processAgent runs arbitrary shell
Proxy with injected authAgent never sees the secretExtra hop, per-service configTraffic must be inspectable
Short-lived scoped tokenLimited blast radiusIssuance complexityTask outlives the token
Developer's own credentialsNo setupFull account accessAny unattended run
Trade-off mapInteractive

Good for

Simple, works with existing tools

Cost

Visible to every child process

Fails when

Agent runs arbitrary shell

  1. Agent runs arbitrary shell
  2. Traffic must be inspectable
  3. Task outlives the token
  4. Any unattended run

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Environment variable injection is good for Simple, works with existing tools, costs Visible to every child process, and fails when Agent runs arbitrary shell. Proxy with injected auth is good for Agent never sees the secret, costs Extra hop, per-service config, and fails when Traffic must be inspectable. Short-lived scoped token is good for Limited blast radius, costs Issuance complexity, and fails when Task outlives the token. Developer's own credentials is good for No setup, costs Full account access, and fails when Any unattended run

Failure modes

  • Secret in the transcript. A debug command prints the environment and the trace stores it. Debug: scan stored traces with the same pattern set used on the repository.
  • Commit leak. The agent writes a config file with a token and commits it. Debug: run a secret scan on the agent's branch before merge, not only on the main branch.
  • Over-scoped token. The token can delete production resources because it was copied from a human session. Debug: list the token's permissions and compare them with the task's needs.

In production

Alert on secret-scanner hits in agent branches and on egress to unknown hosts. Keep token lifetimes shorter than a task and revoke at completion.

Common misconceptions

People think: A private repository keeps secrets safe.

Actually: Agent traces, CI logs and local clones are separate copies with weaker controls.

People think: Prompt instructions can prevent secret leakage.

Actually: The model is not an enforcement point, so the secret has to be out of reach.

Interview angle

Follow the secret through context, files, process environment and network, then remove it from each. A strong answer describes a capability-based design and a scan at the boundary. Telling the model not to reveal secrets, with no mention of traces or child processes, is the weak response.

Sources