show
Both lines were written but the edits never landed, so a demoted finding displayed as plain `medium (certain)` with no account of why it was not the `critical` its rule says. That is precisely the failure the design set out to avoid: a silently downgraded finding is one nobody can trust, and it is worse than no demotion at all. Verified on the live database — nanny's own test fixture now reads "medium (certain) — critical for this rule, lowered because this is a test fixture" — and the suppression round trip works against real data: remember the value once, and a later sweep credits the suppression with the copies it caught instead of reopening them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XAqHWfdMAsYu1o36tgeima
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
ack, rotated, ignore and reopen take ids or a selector — --rule,
--harness, --under <path>, --fingerprint — with --dry-run to see what
would change first. That matters more than it sounds: a first sweep of a real
machine reports over a thousand findings, most of them the same few test
fixtures repeated through vendored dependencies, and dismissing those one id at
a time is data entry rather than triage.
nanny ignore --under ~/git/some-upstream-checkout --note "not my credentials"
nanny rotated --fingerprint c7c0c9894025e096 # every copy of one secret, at once
Severity depends on where, not only on what
A rule's severity answers "what kind of credential is this" — an Anthropic key is
critical because Anthropic keys are critical. That is half the question. The
other half is what a leak at this location costs you, and without it a fake key
in a #[cfg(test)] block scores the same as a live one in a transcript.
So in a working tree, severity is the rule's severity demoted by context —
tests, benchmarks, fixtures, examples, documentation, .example/.tmpl configs
— and the finding says so:
severity medium (certain) — critical for this rule, lowered because this is test fixture
Demoted, not dropped. crates/nanny-core/src/scan.rs:271 should read
medium — test fixture, not vanish; a tool that hides things is one you cannot
reason about, and nanny's silence is only worth something if it means something.
Demotion drops a finding below alert.min_severity, so it stops interrupting
without disappearing.
Only in working trees. A .md in a repo is documentation; a .md in
~/.claude/projects/*/memory/ is an agent memory, which is exactly where a real
credential ends up. In a harness store there is no way to tell "the transcript
quotes a test file" from "the transcript printed a live key", so nothing there is
demoted.
Remembering that a value is not a credential
Marking a finding ignored settles one row. But "that is an invented token"
is true of the value, wherever it turns up next — including in the transcript
of the session where an agent read the file it lives in. So a judgement can be
remembered:
nanny ignore 849 --everywhere # this value is not a credential, anywhere
nanny ignore --under ~/git/upstream --everywhere --note "their fixtures, not my keys" # ...or just not here
nanny suppressions # what has been remembered, and what it caught
nanny unsuppress 3 # forget it; the value is reported again
In the triage screen, i ignores the row and I ignores the value everywhere.
Suppressions are keyed by fingerprint, which is what makes the feature safe to
have at all: the table holds the same one-way salted hashes as the findings
table and no values, so remembering a judgement risks nothing the database did
not already. Suppressed findings are still recorded — the inventory stays
honest — they simply land ignored and never alert. nanny suppressions shows
how many each has caught, so one that has stopped earning its place is visible
rather than accumulating silently.
The two mechanisms compose. Demotion handles the fixture where it lives; suppression handles every copy of that same fake token wherever an agent quoted it, transcripts included.
Tuning the noise
~/git is watched by default because a spilled value there is a spill whether
or not it was ever committed. On a machine with third-party checkouts it is also
where most of the false positives are: someone else's test keys, committed on
purpose. Build output, vendored dependencies, tool caches and minified assets
are excluded already; beyond that, exclude in the config takes globs, and
nanny ignore --under ... --everywhere handles a checkout you would rather keep
but not hear about.
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
On a real workstation — 286 MB of claude transcripts, a 52 MB opencode
database, 25 pi sessions and fifty repositories under ~/git:
| cold sweep, everything read | 38 s, 112 MB resident |
| warm sweep, nothing changed | 3.3 s |
| daemon at rest | 49 MB resident, 4 filesystem watches |
Every source carries a cursor: appended files are tailed from where they were left, rewritten files are skipped on an unchanged length and mtime, and database tables resume from the last row id. The expensive collectors — working trees, the opencode database — run only on the periodic sweep, never on a file event, because during an active agent session inotify fires every second or two and re-walking a hundred thousand files each time would leave the daemon never idle.
Four things were measured rather than assumed. Each is written up where the code lives, because each looked correct and was not:
- A combined
RegexSetcost 11.0 s for a 37 MB transcript; running the same twenty-two patterns individually cost 1.7 s. A combined automaton cannot use the per-pattern literal prefilters (sk-ant-,ghp_,-----BEGIN) that make the individual searches nearly free. The obvious optimisation was a 6× pessimisation. - 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.
- Rebuilding the preview mask for every match is quadratic in the number of matches in a chunk. Built once and binary-searched instead.
serde_jsonwill serialise ani128and then refuse to read it back inside a tagged enum. Every whole-file cursor was silently unreadable, so the fast path existed and never once fired — a warm sweep cost 25 s instead of 3.3 s, and nothing failed loudly enough to notice. Timestamps arei64nanoseconds, and a round-trip test now guards it.- A recursive inotify watch costs one kernel watch descriptor per directory
beneath the root. Handing the watcher
$HOMEand~/git— which the shell and working-tree collectors did, because those are their roots — cost 342 MB resident and a stream of permission denials from container storage, for events that were either ignored or already covered. Periodic collectors now register no watch at all, and the shell collector watches$HOMEshallowly. 342 MB → 49 MB.
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/nannyat 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 --userunit, not a system service under a dedicated account. What it watches is the operator's home directory; a system service cannot see it withProtectHome=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, plusIPAddressDeny=anyandRestrictAddressFamilies=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.