residoo 0.4.3 → 0.4.4

package/README.md

@@ -117,6 +117,24 @@ won't be built into the tool that writes it.
   demonstrated usable credential and sorted to the top of its group in the
   Rotation section, ahead of the ones that are, on their own, not yet proven
   exploitable.
+- Decodes a JWT-shaped token's own `exp` claim locally (no network call: the
+  claim is inside the signed payload, so it cannot be altered without
+  breaking the signature) and reports "valid until" or "expired" next to it
+  in the Rotation section, instead of just "last seen." Only `exp` is ever
+  read; every other claim in the payload is decoded transiently and
+  discarded. See `src/jwtExpiry.js`.
+- **`--verify`** (opt-in, makes a real network call): for an AWS access key
+  id found paired with its secret, asks AWS itself whether the pair still
+  authenticates via `sts:get-caller-identity`, the same free, read-only,
+  permission-less call the AWS CLI and tools like aws-vault use for exactly
+  this. Shells out to your own `aws` CLI rather than reimplementing AWS
+  request signing (residoo ships zero runtime dependencies, and a subtly
+  wrong signing implementation would silently report real keys as invalid,
+  worse than not checking). A verified-active pair is escalated to "rotate
+  immediately"; a verified-invalid one is reported as already dead, no
+  action needed, and sorted out of the way. Off by default; every environment
+  variable the `aws` CLI reads is built from scratch, never inherited, so it
+  can never fall back to your own real AWS profile. See `src/verify.js`.
 - With `--include-noisy`, filters the broad generic-secret rules by how
   machine-random the matched value actually looks (a lightweight, offline
   approximation of BPE-tokenization rarity checks): ordinary English, a
@@ -128,10 +146,10 @@ won't be built into the tool that writes it.
   preview, never the real value, including in `--json` mode. A decoded or
   rejoined secret is redacted exactly like a plain one.
 - On an interactive terminal, prints who it is and where it lives before
-  scanning starts (`residoo v0.4.3 · find secrets your AI coding agent left
+  scanning starts (`residoo v0.4.4 · find secrets your AI coding agent left
   on disk` plus the repo URL), then a live spinner naming the current file
   as it scans. Every report also opens with the exact version and timestamp
-  it was run with (`residoo v0.4.3 · scanned 2026-01-01 12:00`; `--json`
+  it was run with (`residoo v0.4.4 · scanned 2026-01-01 12:00`; `--json`
   carries the same as `residooVersion`/`scannedAt`), so a report pasted or
   screenshotted later never leaves you guessing which build produced it.
   When there are findings, the report closes with a "Next steps" pointer to
@@ -355,7 +373,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.4.3
+  - uses: dandovdub/residoo@v0.4.4
 ```
 
 As a pre-commit hook:
@@ -363,7 +381,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.4.3
+    rev: v0.4.4
     hooks:
       - id: residoo
 ```
@@ -378,10 +396,14 @@ documented in [docs/ci.md](docs/ci.md).
 ## What it does not do
 
 - **No network calls in the default path, and none at all unless you
-  explicitly pass `--upload-cloudroam`.** A secret scanner that phones home is
-  not a tool you should trust with your secrets. Verify this yourself: the one
-  `fetch` call in the codebase is in `src/sealvault.js`, reachable only behind
-  that flag, and sends only encrypted bytes.
+  explicitly pass `--upload-cloudroam` or `--verify`.** A secret scanner that
+  phones home is not a tool you should trust with your secrets. Verify this
+  yourself: the one `fetch` call in the codebase is in `src/sealvault.js`,
+  reachable only behind `--upload-cloudroam`, and sends only encrypted bytes.
+  `--verify` is the other opt-in exception, and makes no `fetch` call at all:
+  it shells out to your own `aws` CLI with the exact AWS credential a scan
+  found, asking AWS's own `sts:get-caller-identity` whether it still
+  authenticates (see `src/verify.js`). Neither runs unless you pass the flag.
 - **Nothing destructive, ever.** Scanning is read-only. Sealing creates *new*
   files and modifies or deletes nothing, not even the plaintext it just
   encrypted a copy of. That last step is deliberately left to a human.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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/cli.js

@@ -54,9 +54,11 @@ const HELP = `residoo: find secrets leaking through your AI agent's session hist
   Both are recorded in ~/.residoo/rotations.json, the only file residoo
   ever writes outside an explicit --seal.
 
-  Scanning makes NO network calls and changes nothing on disk. Findings are
-  redacted in every output format. Sealing (--seal) writes NEW encrypted
-  files only. It never modifies or deletes anything that already exists.
+  Scanning makes NO network calls by default and changes nothing on disk.
+  Findings are redacted in every output format. The one opt-in exception is
+  --verify, which asks AWS itself whether a found AWS credential still
+  authenticates; see below. Sealing (--seal) writes NEW encrypted files
+  only. It never modifies or deletes anything that already exists.
 
 Usage:
   residoo scan [options]
@@ -96,6 +98,17 @@ Scan options:
   --no-integrity          skip the integrity checks (planted hooks, dropper
                           files, auto-run tasks, hidden Unicode)
   --no-color              disable ANSI colour
+  --verify                for every AWS access key id found paired with its
+                          secret (see Rotation below), ask AWS itself
+                          whether the pair still authenticates, via
+                          sts:get-caller-identity, using the exact
+                          credential found in your transcript. THIS MAKES A
+                          REAL NETWORK CALL TO AWS. Off by default. Needs
+                          the aws CLI on PATH; residoo shells out to it
+                          rather than reimplementing AWS request signing.
+                          Only AWS is covered today. A verified-invalid
+                          credential is reported as already dead, not as
+                          something to rotate.
 
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule
@@ -125,10 +138,11 @@ Seal options (used with scan):
                           only, unlike a passphrase, it is not portable to
                           another machine.
   --vault-dir <dir>       where to create the vault (default: ./residoo-vault-<stamp>)
-  --upload-cloudroam      ALSO upload the sealed vault to CloudRoam. This is the
-                          only residoo feature that touches the network, it is
-                          off unless you pass it, and only ciphertext is sent.
-                          Needs CLOUDROAM_API_KEY (env) plus:
+  --upload-cloudroam      ALSO upload the sealed vault to CloudRoam. One of two
+                          opt-in features that touch the network (--verify
+                          above is the other); off unless you pass it, and
+                          only ciphertext is sent. Needs CLOUDROAM_API_KEY
+                          (env) plus:
   --connector <id>        CloudRoam connector id for the destination
   --bucket <name>         destination bucket
   --prefix <p>            optional key prefix inside the bucket
@@ -434,6 +448,12 @@ async function main(argv) {
   const includeSuppressed = args.includes("--include-suppressed");
   const failOnFind = args.includes("--fail-on-find");
   const allowAcked = args.includes("--allow-acked");
+  // The one flag that makes residoo do something other than read local
+  // files: --verify shells out to the user's own `aws` CLI with any AWS
+  // access key + paired secret this scan finds, to ask AWS itself whether
+  // they still authenticate (see verify.js). Off by default; every other
+  // flag here only changes what is READ or how it is DISPLAYED.
+  const verifyAws = args.includes("--verify");
 
   // --project [dir]: the dir is optional (CI passes ".", a bare --project
   // means the current directory). null means machine mode.
@@ -543,7 +563,7 @@ async function main(argv) {
   }
 
   const progress = makeProgressReporter(noColor);
-  const result = await scan({ sources, includeNoisy, includeSuppressed, onProgress: progress.onProgress });
+  const result = await scan({ sources, includeNoisy, includeSuppressed, onProgress: progress.onProgress, verifyAws });
   progress.stop();
   const integrity = wantsIntegrity ? runIntegrity() : null;
   const rotation = renderRotation(result.findings, acks, dismissed);

package/src/jwtExpiry.js

@@ -0,0 +1,48 @@
+"use strict";
+
+/**
+ * Local, offline JWT expiry decoding.
+ *
+ * Unlike an AWS or vendor API key, a JWT's own payload can carry an `exp`
+ * claim, and that claim is inside the signed part of the token: it cannot
+ * be altered without invalidating the signature, so decoding it locally is
+ * a trustworthy answer to "is this still valid," not a guess, PROVIDED the
+ * token is actually validated (signature + expiry) by whatever service
+ * accepts it. residoo does not check the signature (it does not know the
+ * issuer's key, and would need a network call to ask), so this only ever
+ * reports the claimed expiry, never that a token is genuinely live.
+ *
+ * No network call, no dependency, no vendor to ask: this is the free,
+ * zero-risk half of "is this credential still valid" (see verify.js for
+ * the opt-in, network-calling AWS half of that same question).
+ */
+
+function base64UrlDecode(segment) {
+  const padded = segment.replace(/-/g, "+").replace(/_/g, "/");
+  return Buffer.from(padded, "base64").toString("utf-8");
+}
+
+/**
+ * Returns the token's `exp` claim as milliseconds since epoch, or null when
+ * the token is not decodable as a JWT or carries no `exp` claim. Only the
+ * `exp` field is ever read out of the payload; every other claim (sub,
+ * email, scopes, whatever an issuer put in there) is decoded transiently
+ * and discarded, never stored or reported, so a JWT's expiry can be shown
+ * without also handling the rest of its payload as sensitive data.
+ */
+function decodeJwtExpiryMs(token) {
+  if (typeof token !== "string") return null;
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  let payload;
+  try {
+    payload = JSON.parse(base64UrlDecode(parts[1]));
+  } catch {
+    return null;
+  }
+  const exp = payload && payload.exp;
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
+  return exp * 1000;
+}
+
+module.exports = { decodeJwtExpiryMs };

package/src/report.js

@@ -229,8 +229,19 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
       // the same type are shown as two separate lines on purpose, not
       // collapsed on a guess.
       const lastSeenNote = typeof e.lastSeenMs === "number" ? `last seen ~${ageDays(e.lastSeenMs)}d ago` : null;
+      // The one credential type residoo can say "still valid" about with
+      // zero network calls: a JWT's own exp claim, inside its signature
+      // (see jwtExpiry.js). Not proof it is accepted anywhere (residoo
+      // never checks the signature), only that the token's own claimed
+      // window has or has not passed.
+      const jwtExpiryNote = typeof e.jwtExpiresAtMs === "number"
+        ? (e.jwtExpiresAtMs < Date.now()
+            ? `expired ${new Date(e.jwtExpiresAtMs).toISOString().slice(0, 10)}`
+            : `valid until ${new Date(e.jwtExpiresAtMs).toISOString().slice(0, 10)}`)
+        : null;
       push(`    ${STATUS_TAG[e.status]}  ${e.preview}  ${paint(c.dim, fileNote)}` +
-        (lastSeenNote ? `  ${paint(c.dim, lastSeenNote)}` : ""));
+        (lastSeenNote ? `  ${paint(c.dim, lastSeenNote)}` : "") +
+        (jwtExpiryNote ? `  ${paint(c.dim, jwtExpiryNote)}` : ""));
       // An access key id and its AWS secret are each meaningless alone (see
       // pairing.js): the id names WHICH key, the secret authenticates it,
       // and an attacker needs both. Called out in red/bold, the same
@@ -238,11 +249,25 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
       // line under it is a demonstrated full working credential, not just a
       // shape that matched a pattern; a plain access-key-id or secret finding
       // with NO pairing note is still worth checking, but nothing here
-      // proves it is actually exploitable on its own.
-      if (e.pairedSecretPreview) {
-        push(paint(c.red + c.bold, `               ⚠ paired with secret ${e.pairedSecretPreview} · full working credential, rotate this one first`));
-      } else if (e.pairedAccessKeyPreview) {
-        push(paint(c.red + c.bold, `               ⚠ paired with access key ${e.pairedAccessKeyPreview} · full working credential`));
+      // proves it is actually exploitable on its own. --verify (see
+      // verify.js) can strengthen this to an outright confirmation, or
+      // downgrade it to "already dead": both come from a real answer from
+      // AWS, not a guess, so they get their own wording rather than folding
+      // into the generic pairing line.
+      if (e.pairedSecretPreview || e.pairedAccessKeyPreview) {
+        const otherHalf = e.pairedSecretPreview
+          ? `paired with secret ${e.pairedSecretPreview}`
+          : `paired with access key ${e.pairedAccessKeyPreview}`;
+        if (e.awsVerified === "active") {
+          push(paint(c.red + c.bold, `               ⚠ ${otherHalf} · VERIFIED ACTIVE: AWS accepted these credentials moments ago, rotate immediately`));
+        } else if (e.awsVerified === "invalid") {
+          push(paint(c.green, `               ✓ ${otherHalf} · already inactive: AWS rejected these credentials, no rotation needed`));
+        } else if (e.awsVerified === "error") {
+          push(paint(c.red + c.bold, `               ⚠ ${otherHalf} · full working credential, rotate this one first`) +
+            paint(c.dim, ` (could not verify: ${e.awsVerifiedDetail || "unknown error"})`));
+        } else {
+          push(paint(c.red + c.bold, `               ⚠ ${otherHalf} · full working credential, rotate this one first`));
+        }
       }
       if (e.status === "acked") {
         push(paint(c.dim, `               acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} · ${e.fingerprint}`));

package/src/rotation.js

@@ -897,6 +897,18 @@ function renderRotation(findings, acks, dismissed = {}) {
         // usable credential pair, not just that a secret exists somewhere.
         pairedSecretPreview: null,
         pairedAccessKeyPreview: null,
+        // A JWT's own `exp` claim, decoded locally (see jwtExpiry.js): the
+        // one credential type residoo can say "still valid" or "expired"
+        // about with zero network calls, since expiry is inside the signed
+        // payload. null for every non-JWT finding, and for a JWT that
+        // failed to decode or carries no exp claim.
+        jwtExpiresAtMs: null,
+        // --verify only (see verify.js): whether AWS itself accepted this
+        // exact credential. null unless the scan was run with --verify AND
+        // this value is one half of a demonstrated pair; residoo makes no
+        // network calls otherwise.
+        awsVerified: null,
+        awsVerifiedDetail: null,
       };
       byFp.set(st.fingerprint, e);
     }
@@ -909,7 +921,9 @@ function renderRotation(findings, acks, dismissed = {}) {
     // honest, locally-derivable signal for "how stale is this." NOT proof a
     // credential was rotated or revoked, only that residoo hasn't seen it
     // paste anywhere more recently than this. residoo makes no network
-    // calls, so it never checks a provider for whether a key is still live.
+    // calls in the default path, so this alone never checks a provider for
+    // whether a key is still live (see awsVerified above for the opt-in
+    // exception, and jwtExpiresAtMs for the zero-network JWT case).
     if (typeof f.fileMTimeMs === "number" && (e.lastSeenMs === null || f.fileMTimeMs > e.lastSeenMs)) {
       e.lastSeenMs = f.fileMTimeMs;
     }
@@ -923,19 +937,35 @@ function renderRotation(findings, acks, dismissed = {}) {
     if (e.pairedAccessKeyPreview === null && typeof f.pairedAccessKeyPreview === "string") {
       e.pairedAccessKeyPreview = f.pairedAccessKeyPreview;
     }
+    if (e.jwtExpiresAtMs === null && typeof f.jwtExpiresAtMs === "number") {
+      e.jwtExpiresAtMs = f.jwtExpiresAtMs;
+    }
+    if (e.awsVerified === null && typeof f.awsVerified === "string") {
+      e.awsVerified = f.awsVerified;
+      e.awsVerifiedDetail = typeof f.awsVerifiedDetail === "string" ? f.awsVerifiedDetail : null;
+    }
   }
 
-  // A paired entry is a DEMONSTRATED usable credential (see pairing.js); an
-  // unpaired access-key-id or secret finding of the same rule and status is
-  // only a shape that matched a pattern. Sorted first within its status tier
-  // so a real pair is never the one the display cap (see renderRotationSection)
-  // pushes into "N more"; the report's own priority order (see the group
-  // sort just below in renderRotationSection) already applies the same
-  // "what needs attention most" logic one level up.
-  const isPaired = (e) => e.pairedSecretPreview !== null || e.pairedAccessKeyPreview !== null;
+  // Within a status tier, order by how demonstrated-urgent an entry is, not
+  // just its rule id: a real pair (see pairing.js) is a DEMONSTRATED usable
+  // credential, and --verify confirming AWS still accepts it is stronger
+  // evidence still; either way this entry must never be the one the display
+  // cap (see renderRotationSection) pushes into "N more." Proven dead
+  // credentials sort the other direction, LOWER than an ordinary unpaired
+  // finding: --verify confirming AWS rejected it, or a JWT's own signed exp
+  // claim already in the past, is proof this specific value needs no
+  // action, not just an absence of proof it does.
+  const priorityScore = (e) => {
+    if (e.awsVerified === "active") return -2;
+    if (e.pairedSecretPreview !== null || e.pairedAccessKeyPreview !== null) return -1;
+    if (e.awsVerified === "invalid") return 1;
+    if (e.jwtExpiresAtMs !== null && e.jwtExpiresAtMs < Date.now()) return 1;
+    return 0;
+  };
   const entries = [...byFp.values()].sort((a, b) => {
     if (a.status !== b.status) return STATUS_ORDER[a.status] - STATUS_ORDER[b.status];
-    if (isPaired(a) !== isPaired(b)) return isPaired(a) ? -1 : 1;
+    const pa = priorityScore(a), pb = priorityScore(b);
+    if (pa !== pb) return pa - pb;
     if (a.ruleId !== b.ruleId) return a.ruleId < b.ruleId ? -1 : 1;
     return a.fingerprint < b.fingerprint ? -1 : 1;
   });

package/src/scan.js

@@ -5,6 +5,14 @@ const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
 const { findDecodedMatches, findBoundaryMatches, contentProjection } = require("./decode");
 const { findPairedSecret } = require("./pairing");
 const { looksRandom } = require("./rarity");
+const { decodeJwtExpiryMs } = require("./jwtExpiry");
+const { isAwsCliAvailable, verifyAwsCredential } = require("./verify");
+
+// Never verify more than this many distinct AWS pairs in one scan: a
+// pathological transcript with dozens of distinct paired credentials should
+// not turn --verify into a long burst of outbound AWS calls. Real scans see
+// 0-2; this is a backstop, not the expected path.
+const MAX_AWS_VERIFICATIONS = 10;
 
 // Rule ids that findPairedSecret's window search applies to (see pairing.js):
 // AWS access key ids and STS session tokens both pair with the same shape
@@ -127,7 +135,7 @@ function safeName(file) { return path.basename(file); }
  * absolute path can itself carry a username or a project name the rest of
  * this report is careful never to print.
  */
-async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null } = {}) {
+async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null, verifyAws = false } = {}) {
   const rules = includeNoisy ? PATTERNS.concat(NOISY_PATTERNS) : PATTERNS;
   // The decode pass (see decode.js) only applies high-confidence, vendor-
   // prefixed rules to decoded bytes: random binary that decodes to printable
@@ -146,11 +154,24 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
   // browser-testing run is one leak, not ten) — never written to a report,
   // never leaves this function.
   const distinctByRule = new Map();
+  // --verify only (see verify.js): accessKeyValue -> { secretValue, refs }.
+  // Keyed by the RAW access key so the map itself dedupes distinct
+  // credentials for the AWS call (one call per key, no matter how many
+  // times it was echoed) while `refs` accumulates EVERY occurrence's
+  // finding-object pair, so the result reaches all of them, not only the
+  // first: an access key re-echoed across several lines gets several
+  // finding objects, and every one of them needs the same answer. Like
+  // distinctByRule above, this lives only for the duration of this scan()
+  // call; nothing in it is ever written to a finding until verification has
+  // REPLACED the raw values with a status string.
+  const pendingAwsVerifications = new Map();
 
   // One place raw matched text turns into a recorded finding: counts the
   // distinct value and pushes the redacted record. `extra` carries the
   // encoding / split markers for the decode and boundary passes; the raw pass
-  // passes none.
+  // passes none. Returns the finding object itself so a caller (the pairing
+  // and --verify logic) can attach more fields onto it later, after the
+  // fields that need real work (an AWS API round-trip) finish.
   const record = (rule, value, relFile, file, lineNo, mtimeMs, confidence, suppressedReason, extra) => {
     if (!distinctByRule.has(rule.id)) distinctByRule.set(rule.id, new Set());
     distinctByRule.get(rule.id).add(value);
@@ -166,6 +187,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
       fileMTimeMs: mtimeMs,
       ...(extra || {}),
     });
+    return findings[findings.length - 1];
   };
 
   // One suppression policy for all three passes (raw, decoded, boundary).
@@ -221,6 +243,8 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
           // next to it in the transcript, not just that a secret exists
           // somewhere in the scan.
           let pairedSecretPreview = null;
+          let secretFinding = null;
+          let rawPairedSecret = null;
           if (!suppressedReason && AWS_PAIR_RULE_IDS.has(rule.id)) {
             const paired = findPairedSecret(line, m[0], m.index);
             if (paired) {
@@ -229,18 +253,42 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
                 suppressedCount++;
               } else {
                 pairedSecretPreview = redact(paired);
-                record({ id: "aws_secret_access_key_paired", label: "AWS Secret Access Key (paired with access key id)" },
+                rawPairedSecret = paired;
+                secretFinding = record({ id: "aws_secret_access_key_paired", label: "AWS Secret Access Key (paired with access key id)" },
                   paired, relFile, file, lineNo, mtimeMs,
                   pairedSuppressedReason ? "low" : "high", pairedSuppressedReason,
                   { paired: true, pairedAccessKeyPreview: redact(m[0]) });
               }
             }
           }
-          record(rule, m[0], relFile, file, lineNo,
+          // Local, offline JWT expiry (see jwtExpiry.js): only ever reads
+          // the `exp` claim out of the decoded payload, nothing else, and
+          // only for the unsuppressed default `jwt` rule, since a
+          // suppressed placeholder/example match is not worth decoding.
+          const jwtExtra = (!suppressedReason && rule.id === "jwt")
+            ? { jwtExpiresAtMs: decodeJwtExpiryMs(m[0]) }
+            : null;
+          const akiaFinding = record(rule, m[0], relFile, file, lineNo,
             mtimeMs,
             resolveConfidence(rule.id, m[0], rule.confidence, suppressedReason),
             suppressedReason,
-            pairedSecretPreview ? { pairedSecretPreview } : undefined);
+            { ...(pairedSecretPreview ? { pairedSecretPreview } : {}), ...(jwtExtra || {}) });
+
+          // --verify only, and only for a DEMONSTRATED pair (both halves
+          // present, neither suppressed): queue it for the verification pass
+          // that runs once, after every file has been scanned (see below).
+          // The Map key dedupes the actual AWS call to one per distinct
+          // credential; `refs` still grows on every occurrence, so a key
+          // re-echoed across several lines gets several finding objects, and
+          // the eventual result is applied to every one of them, not only
+          // the first.
+          if (verifyAws && secretFinding && rawPairedSecret) {
+            if (!pendingAwsVerifications.has(m[0]) && pendingAwsVerifications.size < MAX_AWS_VERIFICATIONS) {
+              pendingAwsVerifications.set(m[0], { secretValue: rawPairedSecret, refs: [] });
+            }
+            const entry = pendingAwsVerifications.get(m[0]);
+            if (entry) entry.refs.push({ akiaFinding, secretFinding });
+          }
         }
         if (m.index === rule.re.lastIndex) rule.re.lastIndex++; // guard zero-width matches
       }
@@ -396,6 +444,41 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
     if (sourceScannedAnything) sourcesScanned.push(source.id());
   }
 
+  // --verify: runs once, here, after every file has been scanned, never
+  // interleaved with the matching pass above. A real network call per
+  // distinct pairing, one at a time (not concurrent), so this is the one
+  // place a scan's wall-clock time depends on something other than disk
+  // I/O; that tradeoff only exists when a caller explicitly asked for it.
+  if (verifyAws && pendingAwsVerifications.size > 0) {
+    const applyResult = (refs, result) => {
+      for (const ref of refs) {
+        ref.akiaFinding.awsVerified = result.status;
+        ref.akiaFinding.awsVerifiedDetail = result.detail;
+        ref.secretFinding.awsVerified = result.status;
+        ref.secretFinding.awsVerifiedDetail = result.detail;
+      }
+    };
+    if (!isAwsCliAvailable()) {
+      process.stderr.write(
+        "residoo --verify: the aws CLI was not found on PATH, so the " +
+        `${pendingAwsVerifications.size} AWS credential(s) found in this scan could not be checked. ` +
+        "Install it (https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to use --verify.\n"
+      );
+      const result = { status: "error", detail: "aws CLI not found on PATH" };
+      for (const { refs } of pendingAwsVerifications.values()) applyResult(refs, result);
+    } else {
+      process.stderr.write(
+        `residoo --verify: calling AWS sts:get-caller-identity for ${pendingAwsVerifications.size} ` +
+        "credential(s) found in this scan. This is a real network request to AWS, using the exact " +
+        "credential found in your transcript, one at a time.\n"
+      );
+      for (const [accessKeyValue, { secretValue, refs }] of pendingAwsVerifications) {
+        const result = verifyAwsCredential(accessKeyValue, secretValue);
+        applyResult(refs, result);
+      }
+    }
+  }
+
   const distinctCounts = {};
   for (const [ruleId, set] of distinctByRule) distinctCounts[ruleId] = set.size;
   return { findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount, distinctCounts, unreadableFiles };

package/src/verify.js

@@ -0,0 +1,132 @@
+"use strict";
+
+/**
+ * Opt-in live credential verification (--verify).
+ *
+ * Everything else in residoo is detection only: a shape matched a pattern,
+ * nothing more, zero network calls, by design (see README's "What it does
+ * not do"). This module is the one deliberate exception, and only when a
+ * user explicitly passes --verify: it takes an AWS access key id and its
+ * paired secret (see pairing.js) and asks AWS itself whether they still
+ * authenticate, via sts:get-caller-identity, the same free, read-only,
+ * permission-less call AWS's own docs and tools like the AWS CLI and
+ * aws-vault use for exactly this "is this credential still alive" check.
+ *
+ * Implemented by shelling out to the user's own `aws` CLI rather than
+ * hand-rolling AWS SigV4 request signing. Two reasons, not one: first,
+ * residoo ships zero runtime dependencies, and a correct SigV4
+ * implementation is real, easy-to-get-subtly-wrong cryptographic code this
+ * project cannot verify against a live AWS account in CI; a signing bug
+ * here would silently report every real key as "invalid," which is actively
+ * worse than not verifying at all. Second, the AWS CLI is exactly the
+ * client AWS itself maintains and tests against its own service, so
+ * whether a credential is live is answered by AWS's own tooling, not a
+ * reimplementation of it.
+ *
+ * Every environment variable the aws CLI reads is built from scratch here,
+ * never inherited from process.env: AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY
+ * are set to the exact values found in the scan, and AWS_CONFIG_FILE/
+ * AWS_SHARED_CREDENTIALS_FILE point at /dev/null so the CLI cannot fall
+ * back to the user's own real default profile if the found credential is
+ * malformed in some way that would otherwise trigger a fallback. A failed
+ * verification must never silently become "verified as the operator's own
+ * real AWS account" instead.
+ */
+
+const { spawnSync } = require("child_process");
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+/**
+ * Test-only escape hatch: when RESIDOO_TEST_AWS_CLI is set, every spawnSync
+ * call below runs that path instead of "aws" on PATH. Same pattern as
+ * keychain.js's RESIDOO_TEST_KEYCHAIN_FILE — crosses a spawned child
+ * process boundary (this project's own CLI e2e tests) via env var, so a
+ * test can point at a small fixture script and exercise the real spawnSync
+ * + argv + env + exit-code + stdout/stderr plumbing without ever spawning
+ * the real aws CLI or touching the network. Not a documented flag: no real
+ * user has a reason to set this.
+ */
+function awsBinary() {
+  return process.env.RESIDOO_TEST_AWS_CLI || "aws";
+}
+
+/** Strip control bytes and cap length: any text here may echo an AWS error message to a terminal. */
+function sanitizeDetail(s) {
+  return String(s || "").replace(/[\x00-\x1f\x7f]/g, "").slice(0, 200);
+}
+
+/**
+ * True if an `aws` binary is reachable on PATH and runs. Checked once per
+ * scan (not once per credential) so a missing CLI produces one clear
+ * message instead of N identical failures.
+ */
+function isAwsCliAvailable(spawnFn = spawnSync) {
+  try {
+    const r = spawnFn(awsBinary(), ["--version"], {
+      timeout: 5000,
+      env: { PATH: process.env.PATH || "" },
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return !r.error && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ask AWS whether this exact access key id / secret access key pair still
+ * authenticates. Returns { status, detail } where status is one of:
+ *   "active"    AWS accepted the credentials (sts:get-caller-identity
+ *               succeeded, or failed only on a follow-up permission check,
+ *               which still proves authentication succeeded)
+ *   "invalid"   AWS rejected the credentials outright (revoked, deleted,
+ *               or never valid)
+ *   "error"     could not determine either way (CLI missing, timeout,
+ *               network failure, or an AWS error this function does not
+ *               recognize) — never conflated with "invalid": an inability
+ *               to check is not evidence the credential is dead.
+ * Synchronous: spawnSync itself is synchronous, and calling this from a
+ * plain loop (not Promise.all) means verifications run one at a time, not
+ * as a burst of concurrent requests against one account.
+ */
+function verifyAwsCredential(accessKeyId, secretAccessKey, { spawnFn = spawnSync, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  let r;
+  try {
+    r = spawnFn(awsBinary(), ["sts", "get-caller-identity", "--output", "json"], {
+      timeout: timeoutMs,
+      encoding: "utf-8",
+      env: {
+        PATH: process.env.PATH || "",
+        AWS_ACCESS_KEY_ID: accessKeyId,
+        AWS_SECRET_ACCESS_KEY: secretAccessKey,
+        AWS_DEFAULT_REGION: "us-east-1",
+        AWS_EC2_METADATA_DISABLED: "true",
+        AWS_CONFIG_FILE: "/dev/null",
+        AWS_SHARED_CREDENTIALS_FILE: "/dev/null",
+      },
+    });
+  } catch (e) {
+    return { status: "error", detail: `aws CLI failed to run (${sanitizeDetail(e && e.message)})` };
+  }
+  if (r.error) {
+    if (r.error.code === "ENOENT") return { status: "error", detail: "aws CLI not found on PATH" };
+    return { status: "error", detail: `aws CLI failed to run (${sanitizeDetail(r.error.code || r.error.message)})` };
+  }
+  if (r.status === 0) {
+    return { status: "active", detail: "AWS accepted these credentials (sts:get-caller-identity)" };
+  }
+  const stderr = String(r.stderr || "");
+  if (/InvalidClientTokenId|SignatureDoesNotMatch|UnrecognizedClientException/.test(stderr)) {
+    return { status: "invalid", detail: "AWS rejected these credentials" };
+  }
+  if (/AccessDenied/.test(stderr)) {
+    // GetCallerIdentity needs no IAM permissions at all; an AccessDenied
+    // here (rare — e.g. an explicit deny policy) still means the
+    // credentials themselves authenticated before that policy was checked.
+    return { status: "active", detail: "AWS accepted these credentials (denied only on a follow-up permission check)" };
+  }
+  return { status: "error", detail: `could not verify: ${sanitizeDetail(stderr).slice(0, 120) || `aws exited ${r.status}`}` };
+}
+
+module.exports = { isAwsCliAvailable, verifyAwsCredential };