Guide 20 of 61 · Protecting secrets and data
Keep secrets and card numbers out of prompts
See which credentials your agent sends its model provider, have the proxy replace them with cache-safe placeholders, and deny tool calls that carry one.
Steps marked preview rely on a package that has not passed its release gate.
See which credentials and payment card numbers your agent sends to its model provider, have the proxy replace them with placeholders that keep the provider's prompt cache working, deny hooked commands and tool calls that carry one, and know what to do when a finding is wrong.
1. See what the proxy finds
Start the agent with agentgarm run, so its model calls go through agentgarm-session's proxy. By default the proxy runs DLP in inspect mode: it scans a copy of each request off the forwarding path and never changes a byte, and it scans responses as they stream. It looks for credentials in known formats (Anthropic, OpenAI, AWS access key ids, GitHub, GitLab, Slack, Google API keys, Stripe live keys, npm tokens and PEM private key blocks) and for payment card numbers with a valid Luhn digit; names, addresses and other personal data are not detected.
Each finding is recorded with the rule ids, a count and the action taken, never the secret. The dashboard's Alerts screen lists it as “Secret detected” (the Overview shows the newest alerts), with the count and the rule ids (for example anthropic_api_key).
agentgarm run -- claudeagentgarm ui --openChecked by the walk: this command ran as written on a no-root Linux install.
2. Turn on redaction
Redaction is a setting of agentgarm-session, not of the policy: start it with --dlp redact (--dlp off turns DLP off). No install option sets it. A no-root install runs agentgarm-session as a user service, so add the two arguments to its command line, the ExecStart line of ~/.config/systemd/user/agentgarm-session.service on Linux or the ProgramArguments of ~/Library/LaunchAgents/com.agentgarm.session.plist on macOS, and restart it. The overview then says “Secret redacted” for each request it changed.
Running agentgarm install --user again rewrites that file without the arguments, which returns the proxy to inspect mode with no alert, so add them again afterwards and check the overview for “Secret redacted”. A root install keeps the unit for every user in /etc/systemd/user/agentgarm-session.service or /Library/LaunchAgents/com.agentgarm.session.plist, which only root can edit, and sudo agentgarmd install --session rewrites it the same way.
Redaction replaces secrets in JSON request bodies sent without compression; a compressed body is forwarded as it is and only reported. It fails closed: a request it cannot redact is refused in the provider's error format and never forwarded unredacted. That is a 500 if the scan does not complete, a 400 for JSON nested more than 1,024 levels deep or holding more than 65,536 secrets, a 503 with retry-after while the proxy's request memory is full, and a 413 when the body and its redacted copy can never fit in it. Except for the 500, a refused request's secrets are still reported, as denied.
systemctl --user daemon-reload
systemctl --user restart agentgarm-sessionlaunchctl bootout gui/$(id -u)/com.agentgarm.session
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agentgarm.session.plistChecked by the walk: this command ran as written on a no-root Linux install.
3. Know why the prompt cache keeps working
A secret becomes <AGENTGARM_SECRET_, twelve hex digits of an HMAC-SHA256 of the secret under the session's key, and >. While agentgarm-session runs, the same secret always gets the same placeholder, and only the secret's bytes change: the body is not re-serialised, so key order, whitespace and cache_control positions stay as the agent sent them. A conversation redacted from the first appearance of a secret is byte-identical turn after turn, which keeps the provider's cached prefix. Signed content (thinking, signature and redacted_thinking) is never rewritten, since changing it breaks the provider's signature check; a secret there is still reported.
The key is random and never stored, and neither is the mapping. After agentgarm-session restarts, a secret maps to a new placeholder, so the first redacted request of each conversation costs one prompt-cache miss. Turning redaction on in the middle of a conversation changes its earlier turns once; Claude Code recovers from the resulting thinking-signature mismatch.
4. Apply the same rules to hooked calls
agentgarmd runs the same detection on what a hook asks about: commands and their arguments, and tool and MCP arguments. Every pack ships with on_secret: alert, which records the finding and lets the call proceed. With on_secret: deny in an enforce-mode policy, a call carrying a secret is denied by the rule builtin.dlp, and Claude Code is told “AgentGarm: the call contains a secret”; in audit mode it only alerts. on_secret: redact denies a hooked call the same way, since no hook can hand the agent its arguments back with placeholders. The hook layer is advisory, since agents let a call through when their hook times out.
Whatever the setting, the requests stored with each decision, and tool and MCP call arguments, are redacted before they reach agentgarmd's store. Lint the edited policy and restart agentgarmd, as in the first guide.
dlp:
on_secret: alertsecurity_boundaries:
dlp:
# A secret in a hooked command or tool call denies the call (builtin.dlp), in enforce mode only.
on_secret: denyagentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yamlChecked by the walk: this command ran as written on a no-root Linux install.
See also
Watch your agent for a week, then enforceStart a policy in audit mode, see what enforcing it would have blocked in your own history, fix the rules that get in the way, then switch it to enforce.
5. Check uploads to paste sites and webhooks
previewThe same detection runs on another surface, WEB, when a policy lists sites for outbound inspection (security_boundaries.network.inspect): agentgarm-session reads what a launched agent's tools send to those sites, the request's path, query and body, and never the response. There a finding is recorded in Audit mode as what Block would have stopped, alerted in Alert mode, or denied in Block mode, where the request is never sent; a key sent to the service that issued it (a GitHub token to api.github.com) is recorded as expected and raises no alert. Each finding keeps the site, the rule ids, a count and where in the request it was, never the secret. Its own guide covers turning it on and reading its findings.
See also
Check what agents upload to paste sites and webhooksHave AgentGarm read what launched agents send to paste sites, file sharing and webhooks, record or stop secrets, and fix tools that refuse its certificate.
6. Deal with a false positive
The detection favours precision over recall, because a wrong finding denies or rewrites real work. A rule fires only on the right prefix, character set and length, with a token boundary on both sides and enough entropy, so a prefix inside a word, a low-entropy placeholder such as sk-ant-xxxx, a timestamp, a public key or a number that fails the Luhn check is not a finding. The alert names the rule that fired, and under deny the decision's audit reason reads secrets found: followed by the rule ids. For prompts and hooked calls the policy has no per-rule exception: if a finding blocks work, set on_secret back to alert, or run agentgarm-session without --dlp redact. For a site under outbound inspection, per_host's ignore_rules records one rule's findings on that site as expected.