SecurityChapter 05
Secrets & Credential Hygiene
A secret that enters the has been disclosed. A secret an can read is a secret the agent can leak — to the provider by default, and to an attacker if prompt injection succeeds. The entire discipline reduces to one rule with two halves: keep secrets out of the window, and keep the credentials the agent does hold small and short-lived.
The Never-In-Context Rule
The window is a disclosure boundary (Data & PII in Context). Secrets must not cross it. The violations are almost always indirect — you did not paste the key; the system did:
| Channel | How the secret gets in | The fix |
|---|---|---|
| File reads | Agent reads .env, config.yaml, a key file | Ignore-rules so secret paths are unreadable by the agent |
| Command output | A tool prints env or a verbose error with a | Wrap tools so they never echo the environment |
| Pasted logs | You paste a stack trace carrying a bearer token | Scrub before paste; assume logs contain secrets |
| History/memory | A secret persisted into memory or a transcript | Never persist live credentials; persist references |
The architectural move: the agent should never need the secret in the first place. A tool that calls an API should hold the credential in its own process and expose a capability ("send the email"), not the key ("here is the SMTP password"). The model gets the verb, never the secret. This is Scope Fence applied to credentials — the agent operates inside a boundary that does not contain the key.
Scope and Lifetime Do the Real Work
Assume a secret will leak and the only questions left are how much it grants and for how long. Both must be small:
- Scope. A read-only token for one repository is a contained incident. A broad personal access token is a breach. Provision the narrowest credential the task needs — never the one you happen to have.
- Lifetime. A short-lived token that has expired by the time it surfaces in a log is close to a non-event. Long-lived static keys are the ones that end up in postmortems.
- Isolation. The agent's credentials are not your credentials. Run agents with their own scoped identity so the blast radius is the agent's grant, not your entire access. This connects directly to Permission Architecture.
Make Leak Detection Mechanical
Hygiene that depends on remembering fails. Mechanize it, exactly as the Safety Net pattern prescribes — independent checks that do not rely on the model or the human being careful:
- Secret scanning in pre-commit and CI, so a leaked key fails the build instead of shipping.
- Hooks that block tool calls whose arguments or outputs match credential patterns — enforcement that does not trust the model's restraint.
- Rotation you can trigger fast, because the realistic plan is "detect and rotate," not "never leak."
The Tradeoff
Tight scoping and short lifetimes have a friction cost that is real and recurring: more credential plumbing, more token-minting, agents that stop mid-task because a scope was too narrow or a token expired. Teams relax scoping precisely because the friction is constant and the breach is hypothetical — right up until it is not. The defensible position is asymmetric: the friction is bounded and predictable; the breach is unbounded. Pay the bounded cost.
When Not To Over-Engineer
An agent operating only on a public repository with no credentials in reach has no secret to protect, and a credential-isolation there is ceremony guarding nothing. The rule is conditional on a secret being reachable. Where none is, spend the effort elsewhere. Where one is, the next question is what else the agent can do with the access it legitimately holds: Permission Architecture.