47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
---
|
|
summary: How to keep secret values out of AI agent session transcripts — use shell command substitution for consumption, and never echo secrets in agent-driven CLI success output.
|
|
tags:
|
|
- type/convention
|
|
- convention/agent-secret-hygiene
|
|
- domain/agent-security
|
|
- tool/credvault
|
|
scope: global
|
|
type: convention
|
|
source: credvault envelope-leak incident, 2026-07-12
|
|
date: 2026-07-12
|
|
last_updated: 2026-07-12
|
|
---
|
|
|
|
# Secrets out of agent transcripts
|
|
|
|
## The rule
|
|
|
|
In AI-agent sessions, **the transcript is the leak surface, not git**. Anything printed to
|
|
stdout becomes durable text: session logs, memory summaries, handoff documents, cached
|
|
context. A gitignored file does not protect a secret the agent `cat`s; a vault does not
|
|
protect a secret the CLI echoes back.
|
|
|
|
Two patterns that generalize to any credential tooling an agent drives:
|
|
|
|
1. **Consume via shell command substitution.** `ENV_VAR=$(secret-fetch-cmd) target-cmd`
|
|
never exposes the value — the transcript records the command *text*, not the substituted
|
|
output. This is the default way an agent should use a credential in any command.
|
|
2. **Agent-driven CLIs must not echo secrets in success envelopes.** Return `null`/omit the
|
|
secret by default (the caller supplied it or will fetch it deliberately); offer an
|
|
explicit opt-in flag (e.g. `--show-secret`) for the rare case a human wants to see it.
|
|
|
|
Corollary: a fancier `exec`-style env-injection wrapper or local cache is usually
|
|
overengineering — command substitution gets ~90% of the value with zero new surface area.
|
|
|
|
## Why
|
|
|
|
Discovered when credvault's `ensure` success envelope echoed a caller-supplied bot password
|
|
back into a session transcript. Fixed 2026-07-12: envelope nulling + `--show-secret`
|
|
(credvault eb51e4c), consumption pattern tracked in credvault issue #11.
|
|
|
|
## How to apply
|
|
|
|
- When an agent needs a credential in a command: inline it via `$( … )`, never fetch-then-paste.
|
|
- When building or reviewing any CLI agents will drive: audit every success path for secret
|
|
echo; default to redaction with an opt-in display flag.
|