residoo 0.8.0 → 0.8.1

package/README.md

@@ -43,16 +43,16 @@ scanned here left your machine; residoo makes no network calls.
 
 That's one snapshot. `residoo watch` runs the same engine continuously and
 alerts the moment a new secret lands, instead of waiting for you to
-remember to scan again; no other tool in the field has anything like it
-(see [Watch: continuous scanning](#watch-continuous-scanning)):
-
-```
-$ residoo watch
-watching 43 sources, 118 files · polling every 5s
-
-2026-09-03 14:02:11  [high]  AWS Access Key ID  AKIA****ABCD
-  claude-code · session-9f2c.jsonl:214 · rf1-8a3e91  Rotate: https://.../access_keys
-```
+remember to scan again. `residoo mcp` lets Claude Code query findings
+conversationally. `residoo cred` removes the reason a credential gets
+pasted into chat in the first place: store it once in your OS keychain,
+run a command with it injected as an environment variable, never typed
+into the conversation at all — which also means a long session compacting
+away the exact value you pasted days ago can't force you to paste it
+again, since there's nothing to lose. `residoo guard` blocks an obviously
+sensitive file read before it happens (100% recall, 0% false positives on
+its own [scored 81-case corpus](bench/guard/RESULTS.md)). All four are
+covered in [docs/features.md](docs/features.md).
 
 > [!NOTE]
 > gitleaks and trufflehog scan **commits**. residoo scans the **conversation
@@ -61,45 +61,21 @@ watching 43 sources, 118 files · polling every 5s
 > trufflehog/betterleaks' verification postures, in
 > [docs/comparison.md](docs/comparison.md).
 
-Scan and watch tell you what already leaked. The most common way a NEW
-leak happens is pasting a key into the chat so Claude can use it, which
-then sits in that conversation's transcript forever, the exact thing scan
-exists to catch in the first place. `residoo cred` closes that loop: store
-a credential once in your OS keychain, then let Claude run a command with
-it injected as an environment variable, never pasted into the chat, never
-written into a script (see
-[Cred: run commands with injected credentials](#cred-run-commands-with-injected-credentials)):
-
-```
-$ residoo cred set aws-prod --env AWS_ACCESS_KEY_ID --env AWS_SECRET_ACCESS_KEY
-Value for AWS_ACCESS_KEY_ID (input hidden):
-Value for AWS_SECRET_ACCESS_KEY (input hidden):
-Stored credential "aws-prod" (2 env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
-
-$ residoo cred run aws-prod -- aws s3 ls
-exit 0 (succeeded). stdout: 3 line(s), stderr: 0 line(s).
-Command output is never shown by design, only exit status and line counts.
-```
-
 ## Benchmark: measured, not claimed
 
-A reproducible benchmark against 8 real competing tools, on a synthetic-but-
-pattern-true corpus (72 Claude Code sessions, 45 planted credentials, zero
-real secrets), with live egress monitoring so "no network calls" is
-observed, not just documented. Re-run against every meaningful release,
-most recently v0.8.0:
+Scored #1 of 8 real competing tools on a reproducible, synthetic-but-
+pattern-true corpus, with live egress monitoring so "no network calls" is
+observed, not just documented:
 
 | | residoo | best of the rest |
 |---|---|---|
 | Distinct credentials found (all claimed classes) | **45/45 (100%)** | agentsweep 33/42 (79%) |
 | Precision (false positives) | **100%** (0 of 55 flags wrong) | gitleaks, whatileaked, trufflehog also 100% |
-| Network egress during the scan | **none-observed** | 3 of 8 tools attempt real outbound calls in their *default* mode (trufflehog: 50 connection attempts to github.com, slack.com, api.anthropic.com, gitlab.com, npmjs.org) |
+| Network egress during the scan | **none-observed** | 3 of 8 tools attempt real outbound calls in their *default* mode |
 
-No single blended score, on purpose: a blend would hide exactly the class-
-level differences (base64-wrapped, split-across-lines, JSON-nested) the
-benchmark exists to measure. Full per-class breakdown, fairness rules, and
-reproduction steps: [bench/](bench/). Self-run, pending independent
-reproduction; everything needed to rerun it ships in this repo.
+Published while losing rows, then fixed in public against the classes it
+was losing — full methodology, every dated rerun, and how to reproduce it
+yourself: [docs/benchmark.md](docs/benchmark.md).
 
 ## What it does
 
@@ -109,245 +85,34 @@ reproduction; everything needed to rerun it ships in this repo.
   [`src/patterns.js`](src/patterns.js).
 - Sees through two transcript-specific disguises: a credential dumped only
   as base64 on a line, or split across two adjacent streaming records, is
-  decoded/rejoined and rescanned, then reported as `base64-wrapped` or
-  `split across lines` so you know it was hidden. See
-  [`src/decode.js`](src/decode.js).
-- Pairs an AWS secret access key (no vendor prefix of its own) with a
-  nearby confirmed access key id and reports both at high confidence: the
-  *pairing* is the signal, not the shape alone. Ambiguous pairings are
-  reported as nothing rather than a guess. Same mechanism now also covers
-  PlanetScale and MongoDB Atlas Service Account credentials. See
-  [`src/pairing.js`](src/pairing.js).
-- Decodes a JWT's own `exp` claim locally (no network call, since the
-  claim is inside the signed payload) and reports "valid until" or
-  "expired" instead of just "last seen." See
-  [`src/jwtExpiry.js`](src/jwtExpiry.js).
+  decoded/rejoined and rescanned. See [`src/decode.js`](src/decode.js).
+- Pairs an AWS secret access key with a nearby confirmed access key id
+  (also PlanetScale and MongoDB Atlas Service Account credentials) and
+  reports both at high confidence; ambiguous pairings are reported as
+  nothing rather than a guess. See [`src/pairing.js`](src/pairing.js).
+- Decodes a JWT's own `exp` claim locally and reports "valid until" or
+  "expired" instead of just "last seen."
 - **`--verify`** (opt-in, makes a real network call): asks a credential's
-  own vendor whether it still authenticates, using the exact value found in
-  your transcript. 35 vendors today, off by default. See
-  [Verifying credentials are still live](#verifying-credentials-are-still-live)
-  below.
-- With `--include-noisy`, filters broad generic-secret rules by how
-  machine-random the matched value looks; never applied to the default
-  rules. See [`src/rarity.js`](src/rarity.js).
+  own vendor whether it still authenticates. 35 vendors today, off by
+  default. See [docs/architecture.md](docs/architecture.md#verifying-credentials-are-still-live).
 - Redacts everything in its own output, including `--json`: you get a
   shape and a first/last-4 preview, never the real value.
-- `--sarif` emits SARIF 2.1.0 for GitHub code scanning; `--json` carries
-  the full picture (findings, integrity, rotation) together.
-- `--seal --keychain` stores the vault key in the OS's own credential store
-  instead of a typed passphrase. See [Sealing](#sealing-what-it-finds).
+- `--sarif` emits SARIF 2.1.0 for GitHub code scanning.
+- `--seal --keychain` encrypts every transcript with a finding into a
+  local vault. See [docs/architecture.md](docs/architecture.md#sealing-what-it-finds).
 - Tells you how many **distinct** secrets it found versus how many times
   one got echoed back across tool calls, so the headline number reflects
   real exposure, not repetition.
-- Flags likely placeholder/example matches separately from real findings,
-  rather than hiding them or inflating the count.
 - Also scans agent **config files** and checks for **planted persistence**
-  (hooks, droppers, invisible Unicode); see the next section.
+  (hooks, droppers, invisible Unicode) — a different, better-documented
+  leak surface. See [docs/architecture.md](docs/architecture.md#beyond-transcripts-configs-and-planted-persistence).
 - Attaches a **rotation runbook** to every finding, plus a local
-  acknowledgement ledger. See [Rotation](#rotation-from-found-to-closed).
-- `--project <dir>` scans a repository checkout instead of the machine, for
-  CI and pre-commit. See [CI and pre-commit](#ci-and-pre-commit).
-- **`residoo watch`**: continuous scanning instead of one snapshot, alerting
-  the moment a new secret lands in a transcript. See
-  [Watch: continuous scanning](#watch-continuous-scanning) below.
-- **`residoo mcp`**: query findings and manage rotation from inside Claude
-  Code itself, over a hand-rolled MCP server. See
-  [MCP: query findings from inside Claude Code](#mcp-query-findings-from-inside-claude-code)
-  below.
-- **`residoo cred`**: store a live credential in the OS keychain and run
-  one allow-listed command with it injected as an environment variable,
-  never seen by the caller. See
-  [Cred: run commands with injected credentials](#cred-run-commands-with-injected-credentials)
-  below.
-
-## Beyond transcripts: configs and planted persistence
-
-Transcripts leak what your agent *saw*. Config files leak what it was
-*configured with*, and that's the better-measured problem: GitGuardian
-counted 24,008 secrets inside MCP config files on public GitHub (2,117
-still valid), and Lakera found live credentials inside
-`.claude/settings.local.json` shipped in ~30 published npm packages. So
-`residoo scan` also covers the home-level config files of Claude Code,
-Claude Desktop, Cursor, Gemini CLI, Codex, and Kiro, plus project-level
-Claude Code configs (`.mcp.json`, `.claude/settings*.json`) resolved from
-project roots the agent itself recorded, never by guessing directories.
-
-Those same files are where 2026's supply-chain campaigns (Mini Shai-Hulud,
-Miasma, the keyv/ChainDrop wave, TrapDoor) planted hooks, dropper scripts,
-and zero-width-Unicode prompt injection. Every scan now also runs
-**integrity checks** over those exact locations:
-
-- Every auto-executing hook is listed; only a published campaign IOC or
-  campaign-shaped behavior (piping a download into a shell, base64-decode-
-  then-execute) escalates to a warning.
-- Loose scripts in `.claude/` and known planted filenames are flagged by
-  name.
-- `CLAUDE.md`, `.cursorrules`, and `.cursor/rules/*` are checked for
-  zero-width Unicode.
-- `.vscode/tasks.json` is parsed for folder-open auto-run tasks.
-
-Read-only like everything else. `--no-integrity` skips it entirely. A
-config that can't be read is reported as unverified, never silently
-counted clean.
-
-## How it works
-
-```
-                    YOUR MACHINE · no network calls
-  ┌───────────────────────────────────────────────────────────────┐
-  │                                                               │
-  │   42 transcript sources           agent config files          │
-  │   ~/.claude, Cursor, Codex…       settings · MCP · memory     │
-  │   (--project <dir>: a repo checkout instead of the machine)   │
-  │            │                              │                   │
-  │            ├──────────────┬───────────────┤                   │
-  │            ▼              │               ▼                   │
-  │   stream + match          │        integrity checks           │
-  │   50 verified rules       │        hooks · droppers ·         │
-  │            │              │        zero-width unicode         │
-  │            ▼              ▼               │                   │
-  │        redacted report (first/last 4 chars only) ◀────────────┤
-  │            │                                                  │
-  │            ├─▶ rotation hints per finding · explain / ack     │
-  │            │   ledger: ~/.residoo/rotations.json              │
-  │            │                                                  │
-  │            ▼  --seal (only if you ask)                        │
-  │        AES-256-GCM vault · scrypt key · encrypted manifest    │
-  │            │                              │                   │
-  │            ▼  unseal --restore            ▼  --upload-cloudroam
-  │        SHA-256 verified copy          ciphertext only ┄┄┄┄┄┄┄┄┄▶
-  │                                                               │
-  └───────────────────────────────────────────────────────────────┘
-```
-
-The `--seal` and `--upload-cloudroam` legs never run unless you pass their
-flag. Nothing in the diagram ever modifies or deletes an existing file. The
-one exception, stated in the open: `residoo ack` writes residoo's own
-rotation ledger at `~/.residoo/rotations.json` (atomic, redacted, never a
-user file).
-
-## Sealing what it finds
-
-Finding a leaked key raises the obvious next question: *now what?*
-
-```bash
-residoo scan --seal
-```
-
-Every transcript that carried a finding is encrypted into a local vault
-directory: AES-256-GCM, key derived from your passphrase with scrypt,
-streamed so an 800MB transcript never touches memory whole. The vault's own
-manifest is encrypted too, so it doesn't advertise what's inside even by
-name. **Originals are never touched.** Once you've verified a restore works
-(`residoo unseal <vault> --restore 0001.sealed --out /tmp/check`, checked
-byte-identical via a recorded SHA-256), deleting the plaintext is your
-decision, made by you.
-
-Optionally, `--upload-cloudroam` (with `CLOUDROAM_API_KEY`, `--connector`,
-`--bucket`) copies the sealed vault to [CloudRoam](https://cloudroam.io) for
-durable, cross-cloud storage.
-
-> [!IMPORTANT]
-> `--upload-cloudroam` is the *only* feature in residoo that touches the
-> network to send your data anywhere. It never runs unless you pass the
-> flag, and only ciphertext is transmitted: the vault is sealed before any
-> upload code executes.
-
-## Verifying credentials are still live
-
-`--verify` asks a credential's own vendor whether it still authenticates,
-using the exact value found in your transcript. Off by default, one real
-network call per distinct credential.
-
-Three vendors need a paired id+secret: **AWS** (via `sts:get-caller-identity`,
-shelling out to your own `aws` CLI rather than reimplementing request
-signing), **PlanetScale**, and **MongoDB Atlas** (Service Account
-credentials only, the legacy Public/Private Key pair has no distinguishing
-prefix and isn't detected at all). The other 32 are a single credential
-each, one direct API call:
-
-Slack · OpenAI · Anthropic · GitHub · Hugging Face · Replicate ·
-DigitalOcean · Pinecone · SendGrid · Groq · xAI · OpenRouter · Stripe · npm ·
-Notion · GitLab · Supabase · ElevenLabs · CircleCI · Airtable · Cloudflare ·
-Heroku · Netlify · Linear · Telegram · Discord webhooks · Vercel · Cerebras ·
-Render · Neon · PostHog · Fly.io
-
-Every vendor clears the same two-stage bar before being wired up:
-independent research against that vendor's own current docs, then a
-separate, adversarial pass that tries to refute the first before it's
-trusted. A real, sourced reason (no free endpoint, needs context the
-credential doesn't carry, or a format not confirmed specifically enough to
-detect safely) is why some detected credential types aren't wired to
-`--verify` at all, not an oversight (Fly.io's `fm1a_`/`fm1r_`/`fm2_`
-"macaroon" tokens are the clearest example: real-machine testing produced a
-measured false-positive rate, so that family is detected nowhere in
-residoo). A verified-active credential is escalated to "rotate
-immediately"; a verified-invalid one is reported already dead, no action
-needed. See [`src/verify.js`](src/verify.js).
-
-## Rotation: from found to closed
-
-Detection without rotation is theater: 64% of secrets leaked publicly in
-2022 were still valid years later, 88% of re-verified leaked AWS keys still
-authenticated, and the median time to remediate a GitHub-leaked secret is
-94 days. Every finding in a residoo report comes with the way out:
-
-- **A rotation hint per finding**, from a guidance map covering all 50
-  detection rules. Where shown, a rotation URL was fetched and confirmed to
-  document revoking that exact credential type.
-- **`residoo explain <rule-id>`** prints the full runbook: where to revoke,
-  the steps, what revocation does. `residoo explain --list` shows the whole
-  catalogue.
-- **`residoo ack <fingerprint>`** records that you rotated a finding.
-  **`residoo dismiss <fingerprint>`** records that it was never a real
-  secret. Both live in `~/.residoo/rotations.json`, residoo's own ledger,
-  written atomically, redacted through the same pipeline as previews.
-- **"Recommended actions" leads the report**: how many *distinct* values
-  still need a decision, versus how many are already resolved (acked,
-  dismissed, or `--verify`-confirmed dead).
-- **The rotation list groups by credential type**, so the URL prints once
-  per type. Each value's own line shows its redacted preview, file, and
-  when it was last seen.
-- **Order matters, and the report says so.** The ChainDrop campaign (Aug
-  2026) shipped a token monitor that fires an attacker payload the moment a
-  stolen GitHub token is revoked. When a scan finds both integrity warnings
-  and leaked credentials, the report tells you to remove the planted
-  persistence first, rotate second.
-
-Acks and dismissals change what the report *says*, never what CI *does*:
-`--fail-on-find` fails on every finding, resolved or not, unless you pass
-`--allow-acked` (integrity warnings always fail either way).
-
-## CI and pre-commit
-
-`residoo scan --project <dir>` scans a repository checkout instead of the
-machine it runs on: committed transcripts, agent configs, root `.env`
-files, plus integrity checks anchored at that directory. It never touches
-the machine's home-level sources, so a clean CI run means the checkout is
-clean and claims nothing about anyone's laptop.
-
-As a GitHub Action (this repo doubles as a composite action):
-
-```yaml
-steps:
-  - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.8.0
-```
-
-As a pre-commit hook:
-
-```yaml
-repos:
-  - repo: https://github.com/dandovdub/residoo
-    rev: v0.8.0
-    hooks:
-      - id: residoo
-```
-
-Or with no integration at all:
-`npm install -g residoo && residoo scan --project . --fail-on-find`.
-Exit codes and exactly what project mode does and doesn't see are in
-[docs/ci.md](docs/ci.md).
+  acknowledgement ledger. See [docs/architecture.md](docs/architecture.md#rotation-from-found-to-closed).
+- `--project <dir>` scans a repository checkout instead of the machine,
+  for CI and pre-commit. See [docs/ci.md](docs/ci.md).
+- `residoo watch` / `residoo mcp` / `residoo cred` / `residoo guard`:
+  continuous scanning, conversational queries, credential injection
+  without pasting, and pre-read blocking. See [docs/features.md](docs/features.md).
 
 ## What it does not do
 
@@ -364,6 +129,13 @@ Exit codes and exactly what project mode does and doesn't see are in
   just encrypted a copy of.
 - **No telemetry, no analytics, no update-check ping.**
 
+Shape-based detection also can't tell a real secret from a realistic-
+looking example in a fetched web page. Three suppression layers narrow the
+gap, none catches every case, and all are re-includable with
+`--include-suppressed`. Treat every finding as a lead to check, not a
+certainty — true of every tool in this category, including the well-
+established ones.
+
 ## Install
 
 ```bash
@@ -385,9 +157,10 @@ brew install residoo
 The Homebrew formula installs the exact tarball published to npm (sha256
 verified): same bits, not a second build.
 
-Requires Node.js 18+ (22.5+ for the SQLite-backed sources listed below;
-residoo still runs fine without it). Zero runtime dependencies: check
-`package.json` rather than take that on faith.
+Requires Node.js 18+ (22.5+ for the SQLite-backed sources listed in
+[docs/sources.md](docs/sources.md); residoo still runs fine without it).
+Zero runtime dependencies: check `package.json` rather than take that on
+faith.
 
 ## Usage
 
@@ -406,7 +179,7 @@ residoo scan [options]
   --no-integrity          skip the integrity checks
   --no-color              disable ANSI colour
   --verify                ask each credential's own vendor if it still authenticates
-                          (real network call; see "Verifying credentials are still live")
+                          (real network call; see docs/architecture.md)
 
   --seal                  encrypt every transcript with findings into a local vault
   --vault-dir <dir>       vault location (default ./residoo-vault-<stamp>)
@@ -420,267 +193,18 @@ residoo ack <fingerprint> [--note <text>]           mark one finding rotated
 residoo unseal <vault-dir>                          list a vault's contents
 residoo unseal <vault-dir> --restore <n> --out <p>  restore one file, hash-verified
 
-residoo watch [options]
-
-  --interval <seconds>    how often to check for new content (default 5, minimum 1)
-  --json                  NDJSON events on stdout, one line per finding/re-exposure
-  --verify                same opt-in vendor check as scan --verify, applied to
-                          each newly found credential once
-  --include-noisy, --include-suppressed, --no-color   same meaning as scan
+residoo watch / mcp / cred / guard                  see docs/features.md
 ```
 
 The vault passphrase comes from `RESIDOO_PASSPHRASE` or a hidden interactive
 prompt. There is no recovery if you lose it, so pick one you keep.
 
-## Watch: continuous scanning
-
-`residoo scan` is a snapshot. `residoo watch` is the same engine run
-continuously: it polls every source `scan` already covers, and the moment a
-new secret lands in a transcript, prints an alert with the redacted value,
-the rule, the file, and the same rotation runbook a scan finding carries,
-instead of waiting for you to remember to run `scan` again.
-
-```
-$ residoo watch
-watching 43 sources, 118 files (61 tailed, 57 rescanned on change)
-polling every 5s; fs.watch is not used, every alert comes from polling
-
-2026-09-03 14:02:11  [high]  AWS Access Key ID  AKIA****ABCD
-  claude-code · session-9f2c.jsonl:214 · rf1-8a3e91  Rotate: https://.../access_keys
-```
-
-It is watch-from-**now**: run `residoo scan` first for anything already on
-disk, since a fresh `residoo watch` baselines whatever it finds on its first
-sweep silently and only alerts on content written after it starts. A finding
-already acknowledged or dismissed (`residoo ack` / `residoo dismiss`) stays
-suppressed, checked against the same `~/.residoo/rotations.json` ledger, and
-a ledger change made mid-watch takes effect within one poll interval, no
-restart needed. A findings-free sweep prints nothing at all, including to
-its own watched Claude Code session, by design: no other tool in this
-project's own benchmark ([`bench/`](bench/)) has a continuous mode at all,
-verified directly against each one's own `--help` output rather than
-assumed; see [docs/comparison.md](docs/comparison.md) for how the one
-adjacent thing, GitGuardian's `ggshield` AI hook, works differently.
-
-## MCP: query findings from inside Claude Code
-
-`residoo mcp` runs residoo as an MCP server over stdio, so Claude Code can
-query findings and manage the rotation ledger conversationally instead of
-you running the CLI in a terminal:
-
-```bash
-claude mcp add residoo -- residoo mcp
-```
-
-or run `scripts/install-mcp.sh` (also in this repo), which installs residoo
-itself first if it isn't already, then registers it and verifies the
-connection.
-
-or add it directly to `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "residoo": { "type": "stdio", "command": "residoo", "args": ["mcp"] }
-  }
-}
-```
-
-Five read-only tools, mirroring the CLI exactly: `residoo_scan` (a fresh
-scan, merged with rotation status), `residoo_check` (only what's new
-since the last check in this conversation, backed by the same engine as
-`watch`), `residoo_explain` (a rule's rotation runbook), and
-`residoo_ack` / `residoo_dismiss` (append to the local ledger). Every
-value returned is redacted the same way the CLI's own output is; nothing
-here makes a network call or touches the transcript files themselves.
-Like the rest of residoo, this is hand-rolled against the MCP spec
-directly, not built on `@modelcontextprotocol/sdk`: zero runtime
-dependencies stays true here too. A sixth, opt-in tool exists for
-injected-credential execution, covered below.
-
-A seventh tool, `residoo_verify_finding`, is genuinely different from the
-other six: it asks a credential's own vendor, live, whether it's still
-active (the same mechanism as `scan --verify`, scoped to exactly one
-credential per call). This is the one MCP tool that makes a real network
-call, so it does not exist at all unless you set
-`RESIDOO_MCP_ALLOW_VERIFY=1` in the environment `residoo mcp` runs in — a
-default install stays true to "zero network calls" without a caveat.
-Once enabled, pass a `fingerprint` from a prior `residoo_scan`; you get
-back `active`, `invalid`, or `unknown`, never the raw value. Paired
-credentials (AWS access key + secret, PlanetScale, MongoDB Atlas) aren't
-supported yet — use `residoo scan --verify` from a terminal for those.
-
-## Cred: run commands with injected credentials
-
-The usual way an AI coding agent ends up able to use a real credential is
-you pasting it into the chat, which puts it in that conversation's
-transcript forever, indistinguishable from any other leak `residoo scan`
-finds. `residoo cred` is the alternative: store the credential once in
-your OS keychain, then let Claude run one allow-listed command with it
-injected as environment variables. Claude never sees the raw value,
-before, during, or after, and it's never written into a script either.
-
-```bash
-residoo cred set aws-prod --env AWS_ACCESS_KEY_ID --env AWS_SECRET_ACCESS_KEY
-# hidden-typed input, once per --env flag; interactive TTY only, no
-# scripted entry, since a live credential is more sensitive than a vault
-# passphrase and should never be typeable into a script or env var.
-
-RESIDOO_CRED_ALLOWED_COMMANDS="aws=/usr/local/bin/aws" residoo mcp
-# now residoo_run_with_cred exists as an MCP tool; it does not exist at
-# all (won't appear in the tool list) until this is set.
-
-residoo cred run aws-prod -- aws s3 ls
-# same operation from a terminal, for testing without an MCP client.
-```
-
-**Why this is safer than it looks, stated precisely, not just asserted:**
-
-- `RESIDOO_CRED_ALLOWED_COMMANDS` (`name=/absolute/path,...`) is an
-  environment variable the operator sets outside any conversation, read
-  fresh on every single invocation. Empty or unset means **nothing may
-  run, by design**: this is the actual, sole security boundary.
-- The `command` a caller (human or model) supplies is used **only as a
-  lookup key** into that map, never as a path, never resolved via
-  `PATH`. This was not always true: a first draft matched by binary
-  *name* alone (checked fresh every call, but only verifying the name the
-  caller claimed, not the binary that actually ran), and an adversarial
-  review found two concrete ways around that: a caller-supplied path
-  smuggled straight past the check, and a same-named malicious binary
-  planted earlier on the server process's own inherited `PATH`. Both are
-  closed structurally now: `command` cannot cause any file other than the
-  operator-pinned absolute path to execute, full stop.
-- Arguments are always a structured list, never a shell string, so no
-  shell metacharacter ever gets interpreted.
-- The executed command's own stdout/stderr content is **never returned**,
-  only exit status and line counts, because that output is itself a
-  channel the injected secret could leak through in ways no redaction
-  pass can guarantee to catch (an echoed variable, a stack trace).
-- A hung command is killed after 30 seconds, not configurable by the
-  caller (letting a model choose its own timeout has no legitimate use
-  and only helps an attacker keep a process alive longer).
-- One line goes to `residoo mcp`'s own **stderr** per credential use
-  (timestamp, credential name, command, exit code, never the value or
-  the arguments). This is **not durable by default**: redirect the MCP
-  server's stderr at launch (`residoo mcp 2>> ~/.residoo-cred-audit.log`,
-  or your MCP client's equivalent) if you want a persistent trail.
-
-**Only ever allow-list narrow, single-purpose CLIs**, never a tool that
-can itself run arbitrary third-party code as part of normal operation
-(`npm`, `npx`, `pip`, `make`, `cargo`, any build tool). Watch out even for
-a seemingly narrow tool with its own plugin system: an allow-listed `gh`
-still receives the injected credential as an inherited environment
-variable in whatever `gh extension exec` or `gh alias` runs, which is
-untrusted the moment it's a third-party extension. This is a residual
-risk allow-listing alone doesn't remove, so narrow the tools you allow-list
-accordingly, and prefer credentials scoped as tightly as the vendor
-allows.
-
-Storage is macOS (`security`) or Linux (`secret-tool`) only, matching
-`--seal --keychain`'s own existing platform support; Windows is refused
-with a clear message rather than half-built. There is no `residoo cred
-list` in v1: you need to already know the name you set.
-
-## Guard: block a sensitive read before it happens
-
-Everything above finds a leak after it's already written to disk. `residoo
-guard` is the one piece of residoo that tries to stop one from happening in
-the first place — a Claude Code `PreToolUse` hook that blocks an obviously-
-sensitive file read (`.env`, `id_rsa`, `.aws/credentials`, and similar)
-before the command runs at all.
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Bash|Read", "hooks": [{ "type": "command", "command": "residoo guard" }] }
-    ]
-  }
-}
-```
-in `.claude/settings.json`. It reads one hook payload from stdin and writes
-a deny decision to stdout only when the proposed command or file path
-matches; anything it doesn't recognize falls through untouched, with zero
-output, exit 0.
-
-This is narrower than it might sound, and the gap is worth stating
-plainly rather than implying more than it does: Claude Code's hooks API
-lets a `PreToolUse` hook see the proposed tool INPUT (a Bash command
-string, a Read file path) before it runs, but there is no documented
-mechanism for a hook to see or redact a tool's OUTPUT — by the time a
-`PostToolUse` hook fires, that output is already committed to the
-transcript. So this can only block on the shape of the request, never
-clean up what a command already printed. It will not catch a secret typed
-directly into a prompt, or one arriving in the output of an otherwise
-unremarkable command (`curl`, a build log). `residoo scan` / `watch` /
-`mcp` remain the actual safety net; this is a best-effort tripwire on top
-of them, not a replacement.
-
 ## Sources supported today
 
-43 sources: 42 transcript stores plus the agent-config source above, in two
-honestly-distinct tiers. `--project` adds one more, opt-in source that
-scans a checkout instead of the machine.
-
-**Real-install-verified**: run against an actual, populated installation
-and confirmed to find real content: **Claude Code**
-(`~/.claude/projects/**/*.jsonl`) and **agent config files** for its
-Claude-family paths.
-
-**Multi-source-corroborated-but-unverified**: backed by 2+ independent,
-credible sources but not checked against a real install on any machine this
-project was built on. Still built to fail loudly rather than silently
-report "all clear":
-
-Cursor, Codex CLI, OpenCode, Aider, Cline, Roo Code, Kilo Code, Windsurf,
-PearAI, Trae, Void, Gemini CLI, Qwen Code, Continue, Open Interpreter,
-Goose, GitHub Copilot Chat/CLI, `llm`, Codebuff, Mentat, Hermes, OpenClaw,
-Warp, Crush, Grok Build, Kiro CLI/IDE, Zed, JetBrains Junie/AI Assistant,
-Sourcegraph Cody, Amazon Q Developer, Qodo Gen, OpenHands, Factory Droid
-CLI, Devin CLI, Pi, Google Antigravity, Kimi Code, and `fx`.
-
-A few are SQLite-backed (Cursor, Crush, Cody, Devin CLI, Hermes, Kiro CLI,
-`llm`, Trae, Void, Warp, Zed) and need Node.js 22.5+ for the built-in
-`node:sqlite` module. On an older Node, each reports as detected-but-not-
-scanned rather than silently dropping.
-
-**Investigated and deliberately not included:** Plandex (client-server,
-nothing local to scan), CodeGPT and Augment Code (account/cloud-based, no
-local transcript file), Replit Agent (cloud-only). Tabby, Tabnine,
-Zencoder, Tongyi Lingma, and Berd didn't clear the 2-independent-source bar
-in the time available. A verified adapter for any of these is a welcome PR.
-
-See [`src/sources/index.js`](src/sources/index.js) for the full list, and
-each source file's own header for exactly what was and wasn't checked.
-
-## Adding a source
-
-A source is a small object with four methods: `id()`, `label()`,
-`available()`, `files()`, `readLines(file)`.
-[`src/sources/claude-code.js`](src/sources/claude-code.js) is the reference
-implementation: copy it, point it at your tool's real local storage path,
-open a PR. Two contracts worth getting right:
-
-- **`files()`** yields `{ file, mtimeMs, sizeBytes, broken }`. Set
-  `broken: true` for an entry that looked scannable but wasn't (a dangling
-  symlink); don't just skip past it silently.
-- **`readLines(file)`** is `async`, returning `{ lines, status, bytesRead }`
-  with `status` one of `"complete"`, `"partial"`, `"too-large"`, `"failed"`.
-  Whatever's in `lines` for a non-`"complete"` status still gets scanned.
-
-Please verify the path actually exists and holds real content before
-submitting.
-
-## A known limitation, stated plainly
-
-Shape-based detection can't tell a real secret from a realistic-looking
-example in a fetched web page or documentation your agent read back to
-you. Three suppression layers narrow the gap (known vendor-documented
-example values, placeholder bodies built from one repeated character, and
-placeholder-looking surrounding context), but none catches every case, and
-all are re-includable with `--include-suppressed`. Treat every finding as a
-lead to check, not a certainty. The same is true of every tool in this
-category, including the well-established ones.
+43 sources, real-install-verified for Claude Code and its config family,
+multi-source-corroborated for the rest (Cursor, Codex CLI, Cline, Windsurf,
+Gemini CLI, Copilot, and 30+ more). Full list, what "corroborated" means,
+and how to add one: [docs/sources.md](docs/sources.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
   "license": "MIT",
   "author": "CloudRoam (https://cloudroam.io)",

package/src/guard.js

@@ -39,18 +39,45 @@ const BOUNDARY = "(?:$|[\\s'\"`;|&)<>])";
 // Left boundary: start of string, a path separator (mid-path, e.g.
 // "/foo/.env"), OR whitespace/a shell metacharacter (the path is one
 // argument in a longer command, e.g. "cat .env && echo done" -- ".env" is
-// preceded by a space, not a separator).
+// preceded by a space, not a separator). Deliberately NOT a hyphen: an
+// earlier version added one (to catch "gcp-service-account-prod.json",
+// see the dedicated pattern below instead) and it broke the public.pem/
+// public.key exclusions below -- a negative lookahead only guards its own
+// anchor position, and a hyphen boundary let the regex engine start
+// matching again from a LATER position inside the same filename (e.g.
+// right after "public-" in "public-key.pem"), silently walking around the
+// exclusion. Kept narrow and per-pattern instead of widening this shared
+// primitive for one case.
 const SEP = "(?:^|[\\s'\"`;|&(<>\\\\/])";
 const pat = (body) => new RegExp(SEP + body + BOUNDARY, "i");
 
+// Suffixes that make a .env-shaped path a committed, secret-free template
+// rather than the real thing: never planted with live credentials by
+// convention, and reading one is completely routine (checking which vars
+// a project needs). Found by testing this guard against realistic dev
+// commands, not assumed: cat .env.example was blocked before this existed.
+const ENV_SAFE_SUFFIX = "example|sample|template|dist|default|schema";
+
 const SENSITIVE_PATH_PATTERNS = [
-  // dotenv files, including staged/numbered variants (.env.local, .env.1)
-  { re: pat("\\.env(?:\\.[\\w.-]+)?"), label: "a .env file" },
-  // SSH private keys: the conventional default names, and any *.pem/*.key
-  { re: pat("id_(?:rsa|dsa|ecdsa|ed25519)(?:\\.pub)?"), label: "an SSH private key" },
-  { re: new RegExp(SEP + "\\.ssh[\\\\/]", "i"), label: "the SSH directory" },
-  { re: pat("[\\w.-]+\\.pem"), label: "a .pem key file" },
-  { re: pat("[\\w.-]+\\.key"), label: "a .key file" },
+  // dotenv files, including staged/numbered variants (.env.local, .env.1),
+  // but not a known-safe template suffix (see ENV_SAFE_SUFFIX above).
+  { re: pat(`\\.env(?:\\.(?!(?:${ENV_SAFE_SUFFIX})(?:$|[\\s'"\`;|&)<>.]))[\\w.-]+)?`), label: "a .env file" },
+  // SSH private keys: the conventional default names. Deliberately NOT
+  // *.pub -- a public key is, by definition, meant to be shared (it's
+  // what you paste into GitHub's own SSH keys page); blocking its read
+  // protects nothing and was a real false positive found the same way.
+  { re: pat("id_(?:rsa|dsa|ecdsa|ed25519)"), label: "an SSH private key" },
+  // The whole .ssh directory, EXCEPT its own *.pub files and known_hosts
+  // (host key fingerprints, not credentials -- reading it can't expose
+  // anything) -- same public-key/not-actually-sensitive principle as the
+  // id_/*.pem/*.key exclusions above, applied to a directory match.
+  { re: new RegExp(SEP + "\\.ssh[\\\\/](?!(?:[\\w.-]+\\.pub|known_hosts(?:\\.old)?)(?:$|[\\s'\"`;|&)<>]))", "i"), label: "the SSH directory" },
+  // *.pem/*.key, except a filename that itself says "public": a real
+  // private key is never conventionally named that way, and "public.pem"/
+  // "public-key.pem" naming a non-sensitive cert is common enough that
+  // blocking it is pure noise, not protection.
+  { re: pat("(?!public[-_.])[\\w.-]+\\.pem"), label: "a .pem key file" },
+  { re: pat("(?!public[-_.])[\\w.-]+\\.key"), label: "a .key file" },
   // cloud / vendor credential files with a fixed, well-known name
   { re: pat("\\.aws[\\\\/](?:credentials|config)"), label: "the AWS credentials file" },
   { re: pat("\\.netrc"), label: "the .netrc file" },
@@ -60,7 +87,14 @@ const SENSITIVE_PATH_PATTERNS = [
   { re: pat("\\.kube[\\\\/]config"), label: "the kubeconfig file" },
   { re: pat("application_default_credentials\\.json"), label: "gcloud application-default credentials" },
   { re: pat("credentials\\.json"), label: "a credentials.json file" },
-  { re: pat("service[_-]?account[\\w.-]*\\.json"), label: "a GCP service-account key file" },
+  // No SEP prefix here, on purpose: a real, common naming convention
+  // prefixes this with a project/company name and a hyphen (e.g.
+  // "gcp-service-account-prod.json"), which the standard SEP boundary
+  // (start/whitespace/separator, deliberately not a hyphen -- see SEP's
+  // own comment) would miss entirely. "service[_-]?account" is specific
+  // enough as a token that not requiring a left boundary here is a safe,
+  // narrow exception rather than a reason to widen SEP itself.
+  { re: new RegExp("service[_-]?account[\\w.-]*\\.json" + BOUNDARY, "i"), label: "a GCP service-account key file" },
   { re: pat("secrets?\\.(?:json|ya?ml)"), label: "a secrets file" },
 ];