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
- trusted · secret storethe secrettrustedLong-lived API keypasted into the promptcredential inlet · open
- untrusted · agent reachleak surfaceuntrustedContext window
- Long-lived API key· env var, readablecredential inlet · openleak surfaceuntrustedShell env + child processes
- Long-lived API key· written to configcredential inlet · openleak surfaceuntrustedDiff, commit, stored trace
- neutral · proxy + egressShell env + child processes· call by namecredential inlet · openholds the keyneutralCredential proxyauth added
- allowlistedneutralUpstream API
- Diff, commit, stored trace· push, paste, traceoff-listneutralAny other host
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.
- Inventory the credentials the task needs and replace long-lived keys with short-lived, scoped tokens.
- Inject them through an egress proxy or a credential helper the agent calls by name.
- Strip secret-bearing environment variables from the shell the agent controls.
- Scan the diff, command log and trace for secret patterns before any of them is stored.
- Deny reads of env files, key material and cloud credential directories at the sandbox layer.
- Rotate and revoke automatically when a scan hits, and treat the run as compromised.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Environment variable injection | Simple, works with existing tools | Visible to every child process | Agent runs arbitrary shell |
| Proxy with injected auth | Agent never sees the secret | Extra hop, per-service config | Traffic must be inspectable |
| Short-lived scoped token | Limited blast radius | Issuance complexity | Task outlives the token |
| Developer's own credentials | No setup | Full account access | Any unattended run |
Good for
Simple, works with existing tools
Cost
Visible to every child process
Fails when
Agent runs arbitrary shell
- Agent runs arbitrary shell
- Traffic must be inspectable
- Task outlives the token
- 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
- OWASP, Top 10 for LLM Applications — sensitive information disclosure and excessive agency.
- HumanLayer, 12-Factor Agents — keeping credentials and control outside the model.
- GitHub, Removing sensitive data from a repository — why a committed secret is already exposed.