nanny

Watches the local agent harnesses — claude-code, opencode, pi — for credentials that have leaked into the places they write, and records where and when, so the leak can be rotated before somebody else finds it.

Agents spill secrets as a matter of routine. systemctl cat prints every Environment= line, env | grep -i token prints the value it matched on, journalctl -u echoes authorization headers, and all of it lands in a session transcript that is then stored on disk, sent to a model provider, and kept indefinitely. The architecture repo's agent-credentials.md §6 is the rule ("treat stdout as publication"); nanny is the thing that notices when the rule was broken.

It runs locally, on the machine whose harnesses it watches. It is not a service, has no network access, and needs no credentials of its own.

What it watches

Taken from an actual workstation rather than from each project's documentation, because the interesting surfaces are the ones nobody advertises.

harness	surfaces
claude-code (~/.claude)	session transcripts (projects/**/*.jsonl), prompt history, agent memories, file-history/ (a copy of every file an agent edited), paste-cache/, shell-snapshots/ and session-env/ (the environment a tool call ran with), persisted tool output, todos and tasks, the harness's own logs
opencode (~/.local/share/opencode)	opencode.db — the part, message and session_input tables, read read-only — plus logs, session diffs and cached tool output
pi (~/.pi)	agent/sessions/**/*.jsonl, settings, the ACP session map
shell	.bash_history, .zsh_history, fish, python, psql, node histories
working trees	everything textual under ~/git, because the file most likely to hold a credential is the one with no extension and no name you would think to glob for

What it will not read

Detection is by shape alone. nanny never reads a credential store, and the paths below are refused rather than merely deprioritised:

~/.agents, ~/.gnupg, ~/.password-store, ~/.ssh, ~/.step, each harness's own auth file, ~/.aws/credentials, ~/.netrc, ~/.npmrc, ~/.docker/config.json, ~/.kube/config, and nanny's own state directory.

Two reasons. A credential in one of those is not a spill — it is the credential living where it belongs, and reporting it would bury the real findings. And a monitor that reads every secret on the machine is a process worth compromising, which defeats the point of having it.

The cost of that choice is false positives, since nanny cannot recognise a house credential that has no distinctive format. confidence, min_entropy and per-rule allow patterns are how that is managed; nanny ignore is how the survivors are dealt with.

The redaction invariant

A matched secret never leaves the scanner. A tool that finds leaked credentials and writes them into its own database has not fixed the problem, it has added another copy.

What is recorded is a salted keyed hash (so the same secret in five places is recognisably one secret, and a stolen findings database reveals nothing), the length of the match, and a masked preview:

…"Authorization: Bearer ••••[51]", "url": "https://…

This is enforced by the type system rather than by discipline. nanny_entities::Secret borrows the matched span, cannot be cloned into an owned form, cannot be serialised, and its Debug prints Secret(<redacted, 51 bytes>) — so a stray {:?} in a log statement is harmless rather than a rotation. Nothing downstream of the scanner is able to disclose a value, because nothing downstream is given one.

Using it

nanny                       # the triage screen
nanny status                # what is watched, what has been found
nanny scan                  # scan now; exits non-zero if anything is new
nanny findings --json       # for scripts
nanny show 42               # one finding in full, including how to rotate it
nanny ack 42                # seen and triaged; the credential is still live
nanny rotated 42            # the leaked value is now worthless
nanny ignore 42             # not a secret
nanny rules                 # the active ruleset
nanny doctor                # is nanny itself configured safely

The triage screen is the default because the usual question is "do I have to rotate something right now", and that is a list to walk rather than a query to compose:

nanny  3 unresolved  1 critical  ·  showing unresolved
┌ findings ───────────────────────────────────────────────────────────────────┐
│ WHEN      SEVERITY  HARNESS  WHAT                    WHERE            STATUS │
│▸12:04:31  critical  claude   Anthropic API key       …/a1f2.jsonl:8814  open │
│ 09:51:02  high      opencode Gitea or Forgejo token  …/opencode.db     open  │
│ Aug 31    critical  pi       PEM private key         …/msg-14.jsonl:22 ack   │
└─────────────────────────────────────────────────────────────────────────────┘
┌ finding 1 ──────────────────────────────────────────────────────────────────┐
│ what      Anthropic API key (anthropic-api-key)                             │
│ where     ~/.claude/projects/-home-…/a1f2.jsonl:8814                        │
│ seen      first 12:04:31 · last 12:04:31 · 1 time                           │
│ match     104 bytes · certain confidence · fingerprint 3f9a2c1de4b70852      │
│ context   …"content":"the key is ••••[104] — use it"…                       │
│                                                                             │
│ rotate    Revoke the key in the Anthropic console and issue a replacement.  │
└─────────────────────────────────────────────────────────────────────────────┘
 j/k move · a ack · R rotated · i ignore · o reopen · f filter · y show path · q quit

a and R are deliberately different actions. Acknowledged means seen and decided; rotated means the leaked value is now worthless. Only the second one closes the exposure, and conflating them turns a triaged backlog into one that looks clean.

The daemon raises a desktop notification for anything at or above alert.min_severity (default high). It says what leaked and where; it has no access to the value, so there is nothing for it to put on a shared screen.

Rotation

nanny records and alerts. It does not rotate anything, and it never edits a harness's files — mutating a live session transcript to redact it is a good way to break the harness that is writing it.

Optional rotation is planned. The seam is already in place rather than being retrofitted later: every rule may carry a RotationHint naming the issuing service, what to do about a leak, and whether rotation is even sufficient (for a private key it is not — that is incident response). nanny show prints it, and a future executor dispatches on the service name. See doc/rotation.md.

Building and running

cargo build --release
install -Dm755 target/release/nanny-daemon ~/.local/bin/nanny-daemon
install -Dm755 target/release/nanny        ~/.local/bin/nanny

install -Dm644 asset/systemd/nanny.service ~/.config/systemd/user/nanny.service
systemctl --user daemon-reload
systemctl --user enable --now nanny.service
loginctl enable-linger "$USER"    # so it watches when you are not logged in

Configuration is optional; asset/config/config.toml.tmpl documents every setting and its default. Local rule overrides go in ~/.config/nanny/rules.d/.

Performance

A cold sweep of a real workstation — 286 MB of claude transcripts, a 52 MB opencode database, 25 pi sessions and fifty repositories under ~/git — takes about 2m10s and holds 112 MB resident. Subsequent sweeps read almost nothing: every source carries a cursor, appended files are tailed from where they were left, and rewritten files are skipped on an unchanged length and mtime.

Two things were measured rather than assumed, and both are written up where the code lives:

• Matching with a combined RegexSet cost 11.0s for a 37 MB transcript; running the same twenty-two patterns individually cost 1.7s, because a combined automaton cannot use the per-pattern literal prefilters (sk-ant-, ghp_, -----BEGIN) that make the individual searches nearly free.
• Cutting chunks at the last newline in each window stalls to one byte per iteration on a file with a short first line and one enormous second one — a minified bundle, a base64 payload. It consumed five gigabytes of heap before it was caught. A newline is now only accepted as a cut point in the second half of a window.

Deviations from house convention

Everything else follows ~/git/architecture/generic.md. These do not, and each is deliberate:

• §5 Postgres. State is SQLite, in ~/.local/state/nanny at 0600. nanny watches one operator's home directory on one machine: there is no second consumer and nothing to replicate. More to the point, the data is a map of where credentials have leaked on this host, which should not travel the mesh to a shared cluster or sit in a backup somebody else can restore.
• §8 service accounts. nanny runs as a systemd --user unit, not a system service under a dedicated account. What it watches is the operator's home directory; a system service cannot see it with ProtectHome=true, and relaxing that so a daemon can read a human's home is a worse posture than running as that human. The unit still carries the hardening that means anything in user scope, plus IPAddressDeny=any and RestrictAddressFamilies=AF_UNIX — nanny has no business on the network.
• §9 firewalld, §10 SELinux ports. Not applicable: nanny listens on nothing.
• §3 config path. ~/.config/nanny/config.toml, not /etc/nanny/, for the same reason as the unit scope.
• §7 CI deployment. There is no deploy workflow. nanny is installed on the workstation it watches, by the operator, from a local build.

Layout

crates/
├── nanny-entities/   types, and the redaction invariant that makes the rest safe
├── nanny-core/       rules, scanner, exclusions, the ports the data layer implements
├── nanny-data/       SQLite store, harness collectors, desktop alerting
├── nanny-daemon/     the watcher: inotify plus a periodic sweep
└── nanny-cli/        `nanny` — the triage screen and the scriptable subcommands
asset/systemd/        the systemd --user unit
asset/config/         config and rule-override templates
doc/                  design notes

Detection lives in nanny-core and knows nothing about the filesystem; the collectors live in nanny-data and know nothing about what a secret looks like. That split is what lets the rules be tested without a disk and the readers be tested without a ruleset.