residoo 0.3.3 → 0.3.4

package/README.md

@@ -104,6 +104,18 @@ won't be built into the tool that writes it.
 - Covers Stripe keys in both modes: live (`sk_live`/`rk_live`) and test
   (`sk_test`/`rk_test`), because a leaked test key still holds real
   permissions in its sandbox and reveals account structure.
+- Pairs an AWS secret access key (40 base64 characters, no vendor prefix, not
+  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`.
+- 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
+  placeholder, or a variable name is suppressed with its own stated reason
+  instead of padding the count; a value that reads as random gets its
+  confidence raised to `medium`. Never applied to the default high-confidence
+  rules. See `src/rarity.js`.
 - Redacts everything in its own output. You get a shape and a first/last-4
   preview, never the real value, including in `--json` mode. A decoded or
   rejoined secret is redacted exactly like a plain one.
@@ -292,7 +304,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.3.3
+  - uses: dandovdub/residoo@v0.3.4
 ```
 
 As a pre-commit hook:
@@ -300,7 +312,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.3.3
+    rev: v0.3.4
     hooks:
       - id: residoo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.3.3",
+  "version": "0.3.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/pairing.js

@@ -0,0 +1,83 @@
+"use strict";
+
+/**
+ * Feature 3: paired-secret detection.
+ *
+ * An AWS secret access key is a 40-character base64 value with no
+ * vendor-recognizable prefix. Reported alone, it is indistinguishable from
+ * a hash, a session id, or any other base64-shaped string, so it is not one
+ * of patterns.js's own PATTERNS: a bare rule for it would be exactly the
+ * noisy, low-confidence shape that file's own header keeps out of the
+ * default set.
+ *
+ * But an AWS secret key is never leaked alone: every real credential pair
+ * ships an access key id alongside it (the id names WHICH key; the secret
+ * authenticates it, and one is useless to an attacker without the other),
+ * so every AWS SDK config, env file, or credentials file that leaks the
+ * secret leaks the id in the same breath. Instead of a standalone rule,
+ * this looks for a 40-char base64 run within a tight window of an
+ * already-confirmed AKIA/ASIA match: the PAIRING is the vendor-specific
+ * signal, not the shape alone. Same idea as betterleaks' `components`
+ * mechanism (pairing a low-signal shape to a nearby high-confidence rule to
+ * raise combined confidence), built offline and dependency-free like every
+ * other mechanism here: no rule is added to the default set, and a bare
+ * 40-char base64 string anywhere else on a line, with no access key nearby,
+ * is still silently ignored exactly as before this feature existed.
+ */
+
+const WINDOW = 400; // chars searched on each side of the access-key match
+
+// AWS secret keys are exactly 40 base64-alphabet characters (40 is a
+// multiple of 4, so real keys carry no "=" padding). \b on both sides so a
+// candidate embedded in a longer alnum run (a hash, a dash-free UUID) is
+// not mistaken for one — the same boundary discipline every rule in
+// patterns.js already applies to its own matches.
+const CANDIDATE_RE = /\b[A-Za-z0-9/+]{40}\b/g;
+
+/**
+ * A run of 12+ identical characters at either end. This is the same
+ * placeholder tell as scan.js's zeroEntropyTail, reimplemented locally (not
+ * imported) because it must check BOTH ends here: a candidate window can
+ * hold a placeholder abutting real text on either side, where scan.js's own
+ * rules only ever see a value anchored at a rule's own prefix, so only the
+ * tail end needs checking there.
+ */
+function looksZeroEntropy(value) {
+  const isRun = (s) => {
+    for (let i = 1; i < s.length; i++) if (s[i] !== s[0]) return false;
+    return true;
+  };
+  return isRun(value.slice(0, 12)) || isRun(value.slice(-12));
+}
+
+/**
+ * Find an AWS secret access key candidate paired with an already-matched
+ * access key id or session token on this line. `akiaValue` and `akiaIndex`
+ * locate the paired match so the search can be windowed around it and so
+ * the access key's own text is never re-matched as its own pair.
+ *
+ * Returns the candidate string, or null when there is none, or when more
+ * than one distinct candidate sits in the window. Ambiguous pairing is
+ * reported as nothing at all: for a finding whose whole point is "this is
+ * high confidence because of what it's next to," guessing wrong is worse
+ * than staying silent.
+ */
+function findPairedSecret(line, akiaValue, akiaIndex) {
+  const start = Math.max(0, akiaIndex - WINDOW);
+  const end = Math.min(line.length, akiaIndex + akiaValue.length + WINDOW);
+  const around = line.slice(start, end);
+  CANDIDATE_RE.lastIndex = 0;
+  let m;
+  let found = null;
+  while ((m = CANDIDATE_RE.exec(around)) !== null) {
+    const value = m[0];
+    if (value !== akiaValue && !looksZeroEntropy(value)) {
+      if (found !== null && found !== value) return null;
+      found = value;
+    }
+    if (m.index === CANDIDATE_RE.lastIndex) CANDIDATE_RE.lastIndex++;
+  }
+  return found;
+}
+
+module.exports = { findPairedSecret };

package/src/rarity.js

@@ -0,0 +1,75 @@
+"use strict";
+
+/**
+ * "Rare, not random" — a lightweight, offline approximation of betterleaks'
+ * BPE-tokenization rarity filter (see their "Rare Not Random" writeup),
+ * applied only to NOISY_PATTERNS matches: a bare `password = "..."` or
+ * `api_key = "..."` assignment is the hardest class of finding precisely
+ * because most matches are placeholders, variable names, or ordinary
+ * English ("password = correcthorsebattery", "secret = temporary_value"),
+ * not real secrets.
+ *
+ * A real BPE tokenizer needs an embedded merge-rules vocabulary (GPT-2's is
+ * roughly 50,000 entries) — far too heavy for a zero-dependency, small CLI.
+ * This approximates the same signal ("does this look like language, or like
+ * noise") with a small, hand-picked table of common English letter bigrams
+ * (standard digraph-frequency tables — "th", "he", "in", "er"... together
+ * cover a large majority of ordinary English text) instead of a learned
+ * vocabulary: real secret material is high-entropy machine output and
+ * essentially never strings together English digraphs at the rate real
+ * words and sentences do, while a placeholder, a variable name, or a
+ * pasted sentence almost always does.
+ *
+ * This is deliberately not a security boundary. It only ever adjusts
+ * confidence on the already-opt-in, already low-confidence NOISY_PATTERNS
+ * rules (see patterns.js's own header on why those are opt-in) and is never
+ * applied to, and never changes the outcome of, any of the default 38
+ * high/medium-confidence rules.
+ */
+
+// The most frequent English letter bigrams (standard digraph-frequency
+// tables, e.g. Konheim's letter-pair frequency study). Not exhaustive by
+// design: the point is common, unmistakably-linguistic pairs, not full
+// coverage of every English bigram.
+const COMMON_BIGRAMS = new Set([
+  "th", "he", "in", "er", "an", "re", "on", "at", "en", "nd",
+  "ti", "es", "or", "te", "of", "ed", "is", "it", "al", "ar",
+  "st", "to", "nt", "ng", "se", "ha", "as", "ou", "io", "le",
+  "ve", "co", "me", "de", "hi", "ri", "ro", "ic", "ne", "ea",
+  "ra", "ce", "li", "ch", "ll", "be", "ma", "si", "om", "ur",
+]);
+
+/**
+ * Fraction of the value's consecutive lowercase-letter bigrams that are one
+ * of the common English digraphs above. A non-letter character (digit,
+ * punctuation, symbol) breaks a bigram pair rather than being skipped over:
+ * a real secret's occasional letter run should not accidentally read as
+ * language just because two of its letters happen to land next to each
+ * other and spell a common pair across what was actually a digit boundary.
+ */
+function commonBigramFraction(value) {
+  const lower = value.toLowerCase();
+  let total = 0;
+  let common = 0;
+  for (let i = 0; i < lower.length - 1; i++) {
+    const a = lower[i], b = lower[i + 1];
+    if (a >= "a" && a <= "z" && b >= "a" && b <= "z") {
+      total++;
+      if (COMMON_BIGRAMS.has(a + b)) common++;
+    }
+  }
+  return total === 0 ? 0 : common / total;
+}
+
+// Above this fraction, a value reads as language (or a language-shaped
+// placeholder) rather than machine-random output. Calibrated against common
+// English words and phrases scoring well above it, and random/base64/hex
+// strings scoring at or near zero (see tests/smoke.js).
+const LANGUAGE_THRESHOLD = 0.20;
+
+/** True when `value` reads as machine-random rather than as language. */
+function looksRandom(value) {
+  return commonBigramFraction(value) < LANGUAGE_THRESHOLD;
+}
+
+module.exports = { looksRandom, commonBigramFraction };

package/src/rotation.js

@@ -97,6 +97,21 @@ const ROTATION_GUIDANCE = {
     ],
     revokeNote: "Deactivate before delete: a deactivated key can be re-enabled while you hunt down stragglers, a deleted one cannot.",
   },
+  // The secret half of the same pair (see pairing.js): reported only when
+  // found near a matched aws_access_key_id, so the same key is the one that
+  // needs deactivating. Same console flow, called out separately because the
+  // finding itself is a distinct rule id and deserves its own runbook rather
+  // than silently reusing aws_access_key_id's guidance under a different name.
+  aws_secret_access_key_paired: {
+    label: "AWS IAM secret access key (paired with a leaked access key id)",
+    rotateUrl: "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html",
+    steps: [
+      "This is the secret half of the access key id also found on this line",
+      "Console: IAM > Users > your user > Security credentials > Access keys",
+      "Deactivate and delete the paired access key; its secret dies with it",
+    ],
+    revokeNote: "An AWS secret key cannot be revoked on its own: deactivating its paired access key id is what invalidates it.",
+  },
   // Fetched https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html
   // (2026-09-02): "Revoke IAM role temporary security credentials", console
   // path IAM > Roles > role > Revoke sessions tab.

package/src/scan.js

@@ -3,6 +3,17 @@
 const path = require("path");
 const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
 const { findDecodedMatches, findBoundaryMatches, contentProjection } = require("./decode");
+const { findPairedSecret } = require("./pairing");
+const { looksRandom } = require("./rarity");
+
+// 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
+// of 40-char base64 secret value.
+const AWS_PAIR_RULE_IDS = new Set(["aws_access_key_id", "aws_session_token"]);
+
+// The two NOISY_PATTERNS ids (see patterns.js): the only rules the rarity
+// check (rarity.js) ever touches. Never applied to the default 38 rules.
+const NOISY_RULE_IDS = new Set(["generic_password_assignment", "generic_secret_assignment"]);
 
 /**
  * Text immediately before a match that strongly suggests "this is an example
@@ -165,27 +176,62 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
   // last and only where surrounding text exists (`before` is null for the
   // decode and boundary passes, whose transforms have no stable "40 chars
   // before" in the original line).
-  const suppressionReason = (value, before) => {
+  const suppressionReason = (value, before, ruleId) => {
     if (VENDOR_EXAMPLE_VALUES.has(value)) return "vendor-documented example value";
     if (zeroEntropyTail(value)) return "zero-entropy body";
     if (before !== null && SUPPRESS_CONTEXT_RE.test(before)) return "placeholder-like context";
+    // Rarity check (rarity.js): only the two opt-in NOISY_PATTERNS rules ever
+    // reach here with a matching ruleId. A generic password/secret
+    // assignment whose value reads as English (a placeholder, a variable
+    // name, a pasted sentence) is exactly the false-positive class those
+    // rules are known for; a value that reads as machine-random is not.
+    if (ruleId && NOISY_RULE_IDS.has(ruleId) && !looksRandom(value)) return "reads like natural language, not random";
     return null;
   };
 
+  // Confidence for a NOISY_PATTERNS match that survives every suppression
+  // check is bumped from the rule's default "low" to "medium" when the
+  // value also reads as machine-random (rarity.js): passing both "not a
+  // known placeholder shape" AND "doesn't read like language" is a real
+  // signal boost, not just the absence of a red flag. Never touches any of
+  // the default 38 rules' own confidence.
+  const resolveConfidence = (ruleId, value, defaultConfidence, suppressedReason) => {
+    if (suppressedReason) return "low";
+    if (NOISY_RULE_IDS.has(ruleId) && looksRandom(value)) return "medium";
+    return defaultConfidence;
+  };
+
   const matchLine = (line, file, relFile, lineNo, mtimeMs) => {
     for (const rule of rules) {
       rule.re.lastIndex = 0; // rules are reused across files; reset global regex state
       let m;
       while ((m = rule.re.exec(line)) !== null) {
         const before = line.slice(Math.max(0, m.index - CONTEXT_WINDOW), m.index);
-        const suppressedReason = suppressionReason(m[0], before);
+        const suppressedReason = suppressionReason(m[0], before, rule.id);
         if (suppressedReason && !includeSuppressed) {
           suppressedCount++;
         } else {
           record(rule, m[0], relFile, file, lineNo,
             mtimeMs,
-            suppressedReason ? "low" : rule.confidence,
+            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.
+          if (!suppressedReason && AWS_PAIR_RULE_IDS.has(rule.id)) {
+            const paired = findPairedSecret(line, m[0], m.index);
+            if (paired) {
+              const pairedSuppressedReason = suppressionReason(paired, null);
+              if (pairedSuppressedReason && !includeSuppressed) {
+                suppressedCount++;
+              } else {
+                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 });
+              }
+            }
+          }
         }
         if (m.index === rule.re.lastIndex) rule.re.lastIndex++; // guard zero-width matches
       }
@@ -217,7 +263,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
   // caller and reused across both of a line's pairs.
   const boundaryPair = (contentA, contentB, file, relFile, lineNoA, mtimeMs) => {
     for (const b of findBoundaryMatches(contentA, contentB, rules)) {
-      const suppressedReason = suppressionReason(b.value, null);
+      const suppressedReason = suppressionReason(b.value, null, b.ruleId);
       if (suppressedReason && !includeSuppressed) {
         // One straddling match is one suppressed match, even though an
         // unsuppressed one records against both contributing lines.
@@ -225,7 +271,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
         continue;
       }
       const span = [lineNoA, lineNoA + 1];
-      const conf = suppressedReason ? "low" : b.confidence;
+      const conf = resolveConfidence(b.ruleId, b.value, b.confidence, suppressedReason);
       record({ id: b.ruleId, label: b.label }, b.value, relFile, file, lineNoA, mtimeMs, conf, suppressedReason, { spanLines: span });
       record({ id: b.ruleId, label: b.label }, b.value, relFile, file, lineNoA + 1, mtimeMs, conf, suppressedReason, { spanLines: span });
     }