residoo 0.4.1 → 0.4.3

package/README.md

@@ -110,7 +110,13 @@ won't be built into the tool that writes it.
   a rule on its own) with a nearby confirmed access key id, and reports both
   at high confidence: the pairing is the vendor-specific signal, not the
   shape alone. Ambiguous pairings (more than one candidate nearby) are
-  reported as nothing rather than a guess. See `src/pairing.js`.
+  reported as nothing rather than a guess. See `src/pairing.js`. An access key
+  id alone cannot authenticate anything; it takes the paired secret too. So
+  when a scan turns up several access-key-id findings, the one with an actual
+  secret sitting next to it in the transcript is called out in red as a
+  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.
 - 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
@@ -122,10 +128,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.1 · find secrets your AI coding agent left
+  scanning starts (`residoo v0.4.3 · 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.1 · scanned 2026-01-01 12:00`; `--json`
+  it was run with (`residoo v0.4.3 · 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
@@ -349,7 +355,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.4.1
+  - uses: dandovdub/residoo@v0.4.3
 ```
 
 As a pre-commit hook:
@@ -357,7 +363,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.4.1
+    rev: v0.4.3
     hooks:
       - id: residoo
 ```

package/package.json

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

@@ -193,15 +193,23 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
   const MAX_SHOWN = 12;
   let shownCount = 0;
   let elided = 0;
+  // Tracked separately from `elided` so the closing line can say WHICH rule
+  // types got cut, not just how many entries. The cap is global across all
+  // groups (a report is a summary), so on a rule-heavy scan the elided
+  // remainder almost always spans multiple types, not more of whichever
+  // group happened to print right above the "N more" line; without this a
+  // reader sees that line directly under (say) an Anthropic group and
+  // reasonably reads it as "N more Anthropic keys," which it usually is not.
+  const elidedRuleLabels = new Set();
   for (const g of groupList) {
-    if (shownCount >= MAX_SHOWN) { elided += g.entries.length; continue; }
+    if (shownCount >= MAX_SHOWN) { elided += g.entries.length; elidedRuleLabels.add(g.label); continue; }
     push();
     const g0 = g.entries[0];
     const where = g0.guidance.rotateUrl ? `rotate: ${g0.guidance.rotateUrl}` : `where: ${g0.guidance.consolePath}`;
     push(`  ${paint(c.bold, g.label)}`);
     push(paint(c.dim, `    ${where}`));
     for (const e of g.entries) {
-      if (shownCount >= MAX_SHOWN) { elided++; continue; }
+      if (shownCount >= MAX_SHOWN) { elided++; elidedRuleLabels.add(g.label); continue; }
       shownCount++;
       // e.files always has exactly one entry: the fingerprint is derived
       // from this same basename (see fingerprintFinding in rotation.js), so
@@ -223,6 +231,19 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
       const lastSeenNote = typeof e.lastSeenMs === "number" ? `last seen ~${ageDays(e.lastSeenMs)}d ago` : null;
       push(`    ${STATUS_TAG[e.status]}  ${e.preview}  ${paint(c.dim, fileNote)}` +
         (lastSeenNote ? `  ${paint(c.dim, lastSeenNote)}` : ""));
+      // 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
+      // treatment as the ordering advisory above, because a value with this
+      // 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`));
+      }
       if (e.status === "acked") {
         push(paint(c.dim, `               acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} · ${e.fingerprint}`));
       } else if (e.status === "dismissed") {
@@ -234,7 +255,8 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
   }
   if (elided > 0) {
     push();
-    push(paint(c.dim, `  … and ${elided} more; see --json for the full list`));
+    const typeNote = elidedRuleLabels.size > 1 ? ` across ${elidedRuleLabels.size} rule types` : "";
+    push(paint(c.dim, `  … and ${elided} more${typeNote}; see --json for the full list`));
   }
   push();
   push(paint(c.dim, `  Full runbook: residoo explain <rule-id> · rotated: residoo ack <fp> · not a secret: residoo dismiss <fp>`));

package/src/rotation.js

@@ -889,6 +889,14 @@ function renderRotation(findings, acks, dismissed = {}) {
         ackedAt: st.ackedAt,
         ackNote: st.ackNote,
         lastSeenMs: null,
+        // An access key id and an AWS secret are only dangerous TOGETHER
+        // (see pairing.js): one is useless to an attacker without the
+        // other. These carry the OTHER half's redacted preview when
+        // scan.js found one sitting next to this value, so a report with
+        // several access-key-id findings can say which one is an actual
+        // usable credential pair, not just that a secret exists somewhere.
+        pairedSecretPreview: null,
+        pairedAccessKeyPreview: null,
       };
       byFp.set(st.fingerprint, e);
     }
@@ -905,10 +913,29 @@ function renderRotation(findings, acks, dismissed = {}) {
     if (typeof f.fileMTimeMs === "number" && (e.lastSeenMs === null || f.fileMTimeMs > e.lastSeenMs)) {
       e.lastSeenMs = f.fileMTimeMs;
     }
+    // Take the first pairing seen across this fingerprint's occurrences: if
+    // the same value ever appeared next to its pair on ANY line, that's
+    // enough to flag it, even if a later re-echo of the same value elsewhere
+    // (e.g. Claude confirming "got it") dropped the neighboring secret.
+    if (e.pairedSecretPreview === null && typeof f.pairedSecretPreview === "string") {
+      e.pairedSecretPreview = f.pairedSecretPreview;
+    }
+    if (e.pairedAccessKeyPreview === null && typeof f.pairedAccessKeyPreview === "string") {
+      e.pairedAccessKeyPreview = f.pairedAccessKeyPreview;
+    }
   }
 
+  // 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;
   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;
     if (a.ruleId !== b.ruleId) return a.ruleId < b.ruleId ? -1 : 1;
     return a.fingerprint < b.fingerprint ? -1 : 1;
   });

package/src/scan.js

@@ -211,14 +211,16 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
         if (suppressedReason && !includeSuppressed) {
           suppressedCount++;
         } else {
-          record(rule, m[0], relFile, file, lineNo,
-            mtimeMs,
-            resolveConfidence(rule.id, m[0], rule.confidence, suppressedReason),
-            suppressedReason);
-          // Feature 3: paired-secret detection (see pairing.js). Only
-          // attempted for an UNSUPPRESSED access-key finding — pairing a
-          // vendor-example or placeholder access key with a random-looking
-          // neighbor would be a false amplification, not a real finding.
+          // Feature 3: paired-secret detection (see pairing.js), computed
+          // BEFORE the access-key-id finding is recorded so that finding can
+          // carry the paired secret's own redacted preview. An access key id
+          // alone cannot authenticate anything (see pairing.js's docstring);
+          // it is only a usable credential once its secret is known too, so
+          // a report showing several access-key-id findings needs to say,
+          // on each one's own line, which one actually has a secret sitting
+          // next to it in the transcript, not just that a secret exists
+          // somewhere in the scan.
+          let pairedSecretPreview = null;
           if (!suppressedReason && AWS_PAIR_RULE_IDS.has(rule.id)) {
             const paired = findPairedSecret(line, m[0], m.index);
             if (paired) {
@@ -226,12 +228,19 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
               if (pairedSuppressedReason && !includeSuppressed) {
                 suppressedCount++;
               } else {
+                pairedSecretPreview = redact(paired);
                 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 });
+                  pairedSuppressedReason ? "low" : "high", pairedSuppressedReason,
+                  { paired: true, pairedAccessKeyPreview: redact(m[0]) });
               }
             }
           }
+          record(rule, m[0], relFile, file, lineNo,
+            mtimeMs,
+            resolveConfidence(rule.id, m[0], rule.confidence, suppressedReason),
+            suppressedReason,
+            pairedSecretPreview ? { pairedSecretPreview } : undefined);
         }
         if (m.index === rule.re.lastIndex) rule.re.lastIndex++; // guard zero-width matches
       }