residoo 0.3.3 → 0.3.5

package/README.md

@@ -58,11 +58,13 @@ precise about rather than lumping together:
   do nothing for the months of transcripts already sitting on disk, or for
   any session run without the hook active. residoo scans **retroactively, at
   rest**: every file already there, from every past session.
-- **agentsweep** is a genuine, welcome peer covering similar ground. Broader,
-  in fact: 31 agent sources and 209 detection rules to residoo's smaller set,
-  plus in-place redaction, SARIF output, and a pre-commit hook. The tradeoffs
-  are worth naming precisely rather than either dismissing it or copying it
-  blindly. It needs Python 3.11+ and three pip packages (all clean ones, on
+- **agentsweep** is a genuine, welcome peer covering similar ground. Broader
+  on detection rules (209 to residoo's smaller, deliberately high-confidence
+  set) and it does in-place redaction, where residoo's `--seal` makes an
+  encrypted copy instead. residoo has more agent sources (43 to 31), and
+  both now ship SARIF output and a pre-commit hook. The tradeoffs are worth
+  naming precisely rather than either dismissing it or copying it blindly.
+  It needs Python 3.11+ and three pip packages (all clean ones, on
   inspection; no known CVEs), where residoo needs nothing beyond Node. Its
   own README documents that its in-place redaction leaves the pre-redaction
   original sitting in a **plaintext** `.bak` file, and its issue tracker shows
@@ -104,9 +106,32 @@ 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.
+- `--sarif` emits SARIF 2.1.0 for GitHub code scanning's Security tab and
+  inline pull-request annotations, the same format gitleaks/trufflehog/
+  agentsweep already speak, so residoo's own Action and pre-commit hook plug
+  straight into GitHub's native UI. `--json` remains the format for the full
+  picture (findings, integrity, rotation) together.
+- `--seal --keychain` stores the vault key in the OS's own secure credential
+  store (macOS today, Linux with `secret-tool` installed) instead of a typed
+  passphrase: nothing to remember, and a truly random key instead of one
+  whose strength depends on what you typed. Tradeoff stated plainly: a
+  keychain-backed vault lives on that machine/account only, a passphrase
+  travels, a keychain-backed key does not. See `src/keychain.js`.
 - 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.
@@ -292,7 +317,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.5
 ```
 
 As a pre-commit hook:
@@ -300,7 +325,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.3.3
+    rev: v0.3.5
     hooks:
       - id: residoo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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

@@ -1,9 +1,11 @@
 "use strict";
 
 const path = require("path");
+const fs = require("fs");
+const crypto = require("crypto");
 const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
-const { render, renderIntegrity, renderJson } = require("./report");
+const { render, renderIntegrity, renderJson, renderSarif } = require("./report");
 const { checkIntegrity } = require("./integrity");
 const {
   ROTATION_GUIDANCE, guidanceFor, loadAcks, ackFinding, renderRotation,
@@ -62,6 +64,10 @@ Usage:
 
 Scan options:
   --json                  machine-readable output (full detail, still redacted)
+  --sarif                 SARIF 2.1.0 output (secret findings only), for
+                          GitHub code scanning's Security tab and inline PR
+                          annotations. Use --json for the full picture
+                          (findings + integrity + rotation) instead.
   --project [dir]         scan a repository checkout instead of this machine
                           (default dir: current directory). Covers committed
                           agent transcripts, agent config/rules files, and
@@ -101,6 +107,14 @@ Seal options (used with scan):
   --seal                  after scanning, encrypt every transcript that carried a
                           finding into a local vault directory (AES-256-GCM,
                           passphrase-derived key; originals are left untouched)
+  --keychain              with --seal (or unseal): use a truly random key stored
+                          in the OS keychain instead of a typed passphrase.
+                          Nothing to remember, and the key's strength no longer
+                          depends on passphrase choice. macOS today; Linux when
+                          secret-tool (libsecret) is installed. TRADEOFF: a
+                          keychain-backed vault lives on THIS machine/account
+                          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
@@ -116,6 +130,10 @@ Unseal:
                                                   restore one entry, verified
                                                   byte-identical via its
                                                   recorded SHA-256
+  --keychain              add to either unseal form above: retrieve the vault
+                          key from the OS keychain instead of prompting for a
+                          passphrase. Only works for a vault that was sealed
+                          with --keychain on this same machine/account.
 
 The passphrase is read from RESIDOO_PASSPHRASE, or prompted (hidden) on a TTY.
 
@@ -138,6 +156,52 @@ async function getPassphrase({ confirmNew }) {
   return p1;
 }
 
+/**
+ * The sealing secret for `scan --seal`: a keychain-generated random key (see
+ * keychain.js), or a typed passphrase. `vaultId` is null in passphrase mode;
+ * in keychain mode the caller writes it to `.keychain-id` inside the vault
+ * once sealFindings has created the directory, so unseal can find it again.
+ * The generated secret is passed straight through to the SAME
+ * sealFindings/deriveKey path a typed passphrase would use — scrypt on a
+ * full 256-bit-entropy input is harmless extra defense, and reusing that
+ * already-tested path means no change to sealcrypto.js/sealvault.js at all.
+ */
+async function resolveSealSecret(args) {
+  if (!args.includes("--keychain")) {
+    return { passphrase: await getPassphrase({ confirmNew: true }), vaultId: null };
+  }
+  const keychain = require("./keychain");
+  if (!keychain.isSupported()) throw new Error(`--keychain: ${keychain.unsupportedReason()}`);
+  const vaultId = crypto.randomUUID();
+  const passphrase = crypto.randomBytes(32).toString("base64");
+  keychain.store(vaultId, passphrase);
+  return { passphrase, vaultId };
+}
+
+/** The unsealing secret for `unseal`: a keychain-retrieved key, or a typed passphrase. */
+async function resolveUnsealSecret(args, vaultDir) {
+  if (!args.includes("--keychain")) return getPassphrase({ confirmNew: false });
+  const keychain = require("./keychain");
+  if (!keychain.isSupported()) throw new Error(`--keychain: ${keychain.unsupportedReason()}`);
+  const idPath = path.join(vaultDir, ".keychain-id");
+  if (!fs.existsSync(idPath)) {
+    throw new Error(
+      `No .keychain-id marker in ${vaultDir}: this vault was not sealed with --keychain, ` +
+      `or the marker file was moved separately from the vault. Try unsealing without --keychain.`
+    );
+  }
+  const vaultId = fs.readFileSync(idPath, "utf-8").trim();
+  try {
+    return keychain.retrieve(vaultId);
+  } catch {
+    throw new Error(
+      "Could not retrieve this vault's key from the OS keychain. It may have been removed, " +
+      "or this may be a different machine/account than the one that sealed it: a keychain-backed " +
+      "vault is not portable across machines."
+    );
+  }
+}
+
 async function runSeal(result, args) {
   const { sealFindings, uploadVaultToCloudRoam } = require("./sealvault");
 
@@ -149,21 +213,27 @@ async function runSeal(result, args) {
 
   const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
   const vaultDir = argValue(args, "--vault-dir") || path.resolve(`residoo-vault-${stamp}`);
-  const passphrase = await getPassphrase({ confirmNew: true });
+  const { passphrase, vaultId } = await resolveSealSecret(args);
 
   process.stdout.write(`\nSealing ${filesWithFindings.length} file(s) with findings into ${vaultDir}\n`);
   const { entries } = await sealFindings({
     files: filesWithFindings, vaultDir, passphrase,
     log: (s) => process.stdout.write(s + "\n"),
   });
+  // Written only after sealFindings has created vaultDir. Plaintext, but
+  // holds nothing sensitive: a random id with no meaning outside this
+  // keychain lookup, never the key itself and never anything about what the
+  // vault contains.
+  if (vaultId) fs.writeFileSync(path.join(vaultDir, ".keychain-id"), vaultId, { mode: 0o600 });
   const totalPlain = entries.reduce((s, e) => s + e.plainBytes, 0);
   const totalSealed = entries.reduce((s, e) => s + e.sealedBytes, 0);
   process.stdout.write(
     `\nSealed ${entries.length} file(s): ${(totalPlain / 1024 / 1024).toFixed(1)}MB plain -> ` +
     `${(totalSealed / 1024 / 1024).toFixed(1)}MB encrypted.\n` +
     `Originals were NOT touched. Once you've verified a restore works\n` +
-    `(residoo unseal ${path.basename(vaultDir)} --restore 0001.sealed --out /tmp/check), removing the\n` +
-    `plaintext originals is your call; residoo never deletes anything itself.\n`
+    `(residoo unseal ${path.basename(vaultDir)}${vaultId ? " --keychain" : ""} --restore 0001.sealed --out /tmp/check), removing the\n` +
+    `plaintext originals is your call; residoo never deletes anything itself.\n` +
+    (vaultId ? `The vault key is stored in the OS keychain, never typed, never written in plaintext to disk.\n` : "")
   );
 
   if (args.includes("--upload-cloudroam")) {
@@ -192,7 +262,7 @@ async function runUnseal(args) {
   const vaultDir = args[1];
   if (!vaultDir) { process.stderr.write("usage: residoo unseal <vault-dir> [--restore <n> --out <path>]\n"); return 2; }
 
-  const passphrase = await getPassphrase({ confirmNew: false });
+  const passphrase = await resolveUnsealSecret(args, vaultDir);
   let manifest;
   try {
     manifest = openManifest(vaultDir, passphrase);
@@ -314,6 +384,7 @@ async function main(argv) {
   }
 
   const wantsJson = args.includes("--json");
+  const wantsSarif = args.includes("--sarif");
   const includeNoisy = args.includes("--include-noisy");
   const includeSuppressed = args.includes("--include-suppressed");
   const failOnFind = args.includes("--fail-on-find");
@@ -402,7 +473,11 @@ async function main(argv) {
   if (sources.length === 0) {
     const empty = emptyResult();
     const integrity = wantsIntegrity ? runIntegrity() : null;
-    if (wantsJson) {
+    if (wantsSarif) {
+      // Same contract as --json below: a CI step consuming SARIF must
+      // always get a valid SARIF document, even with nothing to scan.
+      process.stdout.write(renderSarif(empty) + "\n");
+    } else if (wantsJson) {
       // A --json caller (CI, a script piping into jq) must always get valid JSON
       // on stdout, even on the "nothing to scan" path — a plain-text message on
       // stderr with exit 0 silently breaks that contract.
@@ -422,9 +497,11 @@ async function main(argv) {
   const result = await scan({ sources, includeNoisy, includeSuppressed });
   const integrity = wantsIntegrity ? runIntegrity() : null;
   const rotation = renderRotation(result.findings, acks);
-  process.stdout.write((wantsJson
-    ? renderJson(result, integrity, rotation)
-    : render(result, { noColor, integrity, rotation })) + "\n");
+  process.stdout.write((wantsSarif
+    ? renderSarif(result)
+    : wantsJson
+      ? renderJson(result, integrity, rotation)
+      : render(result, { noColor, integrity, rotation })) + "\n");
 
   if (args.includes("--seal")) {
     const sealExit = await runSeal(result, args);

package/src/keychain.js

@@ -0,0 +1,143 @@
+"use strict";
+
+const { execFileSync } = require("child_process");
+
+/**
+ * OS-native secure credential storage for `scan --seal --keychain` and
+ * `unseal --keychain`. Instead of a user-typed passphrase run through
+ * scrypt, residoo generates a truly random, high-entropy secret and hands
+ * it to the OS's own secure store: nothing needs to be typed or
+ * remembered, and the vault's strength no longer depends on a human's
+ * passphrase choice (the weak spot a security audit flagged in passphrase
+ * mode, where the only floor was an 8-character length check).
+ *
+ * The secret itself is still passed straight through to sealcrypto.js's
+ * existing deriveKey(passphrase, salt) exactly as a typed passphrase would
+ * be: scrypt on a full 256-bit-entropy input is harmless extra defense in
+ * depth, and reusing the same, already-tested code path here means no
+ * change to sealcrypto.js or sealvault.js at all — only how the secret is
+ * obtained changes.
+ *
+ * Scoped honestly rather than half-built everywhere: macOS via the
+ * `security` CLI (built into the OS, no new dependency) is the primary,
+ * fully-supported path. Linux via `secret-tool` (libsecret) works when it's
+ * installed and is treated as best-effort, gated by isSupported() the same
+ * way every source in this codebase declares availability rather than
+ * assuming it. Windows has no equivalent built-in CLI story and is refused
+ * outright with a clear message rather than half-implemented against a
+ * module residoo would have to newly depend on.
+ *
+ * IMPORTANT TRADEOFF, stated plainly: a keychain-backed vault key lives in
+ * THIS machine's (or account's) secure store. It is not portable the way a
+ * passphrase is — unseal it on a different machine and there is nothing to
+ * retrieve. Use a passphrase instead when a vault needs to travel.
+ */
+const SERVICE = "residoo-vault";
+
+/**
+ * Test-only escape hatch, macOS only: when RESIDOO_TEST_KEYCHAIN_FILE is
+ * set, every operation below scopes to that keychain FILE instead of the
+ * real default login keychain. Exists so this project's own tests can run
+ * a genuine store/retrieve/remove round trip against a throwaway keychain
+ * created and destroyed within the test (see tests/smoke.js), crossing a
+ * spawned child process boundary via env var rather than a function
+ * parameter, without ever touching, prompting about, or depending on
+ * whatever machine happens to run them. Not a documented flag: no real
+ * user has a reason to set this, and even if one did, the only effect is
+ * redirecting to a named file instead of the default keychain, never an
+ * unexpected access to anything.
+ */
+function testKeychainFile() {
+  return process.env.RESIDOO_TEST_KEYCHAIN_FILE || null;
+}
+
+function isSupported() {
+  if (process.platform === "darwin") return true;
+  if (process.platform === "linux") {
+    try {
+      execFileSync("which", ["secret-tool"], { stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+function unsupportedReason() {
+  if (process.platform === "darwin") return null;
+  if (process.platform === "linux") {
+    return "secret-tool (libsecret) is not installed. Install it (e.g. \"apt install libsecret-tools\" or \"dnf install libsecret\") or omit --keychain to use a passphrase instead.";
+  }
+  return `--keychain is not supported on ${process.platform} yet. Omit --keychain to use a passphrase instead.`;
+}
+
+/**
+ * Store `secret` (a string) under `account` in the OS keychain, for later
+ * retrieve(account). `keychainFile`, macOS only, is an escape hatch used
+ * ONLY by this project's own tests: passing a path scopes the operation to
+ * that specific keychain FILE instead of the real default login keychain,
+ * so a test round-trip never touches, prompts about, or depends on the
+ * developer's actual keychain. The real feature (seal/unseal) never passes
+ * this — it always targets the default keychain, which is the whole point.
+ */
+function store(account, secret, keychainFile) {
+  if (process.platform === "darwin") {
+    // -U updates the entry in place if `account` already exists, rather
+    // than erroring on a name collision.
+    const kf = keychainFile || testKeychainFile();
+    const args = ["add-generic-password", "-a", account, "-s", SERVICE, "-w", secret, "-U"];
+    if (kf) args.push(kf);
+    execFileSync("security", args, { stdio: "ignore" });
+    return;
+  }
+  if (process.platform === "linux") {
+    // secret-tool reads the secret from stdin, never a CLI argument, so it
+    // never appears in a process listing or shell history.
+    execFileSync("secret-tool", [
+      "store", "--label", "residoo sealed vault key", "service", SERVICE, "account", account,
+    ], { input: secret, stdio: ["pipe", "ignore", "ignore"] });
+    return;
+  }
+  throw new Error(unsupportedReason());
+}
+
+/** Retrieve a secret previously stored under `account`. Throws if not found or unsupported. See store() re: keychainFile. */
+function retrieve(account, keychainFile) {
+  if (process.platform === "darwin") {
+    const kf = keychainFile || testKeychainFile();
+    const args = ["find-generic-password", "-a", account, "-s", SERVICE, "-w"];
+    if (kf) args.push(kf);
+    return execFileSync("security", args, { encoding: "utf8" }).trim();
+  }
+  if (process.platform === "linux") {
+    return execFileSync("secret-tool", [
+      "lookup", "service", SERVICE, "account", account,
+    ], { encoding: "utf8" }).trim();
+  }
+  throw new Error(unsupportedReason());
+}
+
+/**
+ * Remove a previously stored secret. Not used by seal/unseal (a vault's
+ * keychain entry is meant to outlive the command that created it); exists
+ * for callers that manage a keychain entry's lifecycle themselves, and for
+ * this project's own tests to clean up after a real round-trip check
+ * without leaving entries behind. See store() re: keychainFile.
+ */
+function remove(account, keychainFile) {
+  if (process.platform === "darwin") {
+    const kf = keychainFile || testKeychainFile();
+    const args = ["delete-generic-password", "-a", account, "-s", SERVICE];
+    if (kf) args.push(kf);
+    execFileSync("security", args, { stdio: "ignore" });
+    return;
+  }
+  if (process.platform === "linux") {
+    execFileSync("secret-tool", ["clear", "service", SERVICE, "account", account], { stdio: "ignore" });
+    return;
+  }
+  throw new Error(unsupportedReason());
+}
+
+module.exports = { isSupported, unsupportedReason, store, retrieve, remove };

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/report.js

@@ -318,4 +318,75 @@ function renderJson(result, integrity = null, rotation = null) {
   );
 }
 
-module.exports = { render, renderIntegrity, renderRotationSection, renderJson };
+// confidence -> SARIF level. "high"/"medium" map to the two levels GitHub's
+// code-scanning UI treats as real alerts ("error" surfaces most
+// prominently); "low" only ever appears with --include-suppressed (a
+// placeholder/example match) and maps to "note", SARIF's own tier for
+// exactly that: worth showing, not worth alarming over.
+const SARIF_LEVEL = { high: "error", medium: "warning", low: "note" };
+
+/**
+ * SARIF 2.1.0 output (--sarif): the format GitHub's code-scanning Security
+ * tab, and inline pull-request annotations, both consume. residoo already
+ * ships a GitHub Action and a pre-commit hook, so not emitting the one
+ * format that plugs a scan straight into GitHub's native UI was a real gap
+ * for exactly the CI audience those two things target.
+ *
+ * Scoped to secret findings only (result.findings), not the separate
+ * integrity checks (planted hooks, droppers): those don't share the same
+ * per-line, per-file location shape, and forcing them into one schema badly
+ * would be worse than a stated, honest scope limit. --json remains the
+ * format that carries everything (findings, integrity, rotation) together.
+ *
+ * partialFingerprints carries residoo's own stable fingerprint
+ * (fingerprintFinding, already proven stable across line-number and
+ * directory changes, see tests/smoke.js) under a versioned key, so GitHub's
+ * own alert-dedup logic can track one finding across reruns without
+ * depending on line numbers moving, exactly the property SARIF's
+ * fingerprinting is designed around.
+ */
+function renderSarif(result) {
+  const { version } = require("../package.json");
+  const rules = new Map();
+  const results = result.findings.map((f) => {
+    if (!rules.has(f.ruleId)) {
+      rules.set(f.ruleId, {
+        id: f.ruleId,
+        name: f.label,
+        shortDescription: { text: f.label },
+        properties: { "security-severity": f.confidence === "high" ? "9.0" : f.confidence === "medium" ? "6.0" : "3.0" },
+      });
+    }
+    return {
+      ruleId: f.ruleId,
+      level: SARIF_LEVEL[f.confidence] || "warning",
+      message: { text: `${f.label} (redacted: ${f.preview})` },
+      locations: [{
+        physicalLocation: {
+          artifactLocation: { uri: f.relFile },
+          ...(Number.isInteger(f.line) ? { region: { startLine: f.line } } : {}),
+        },
+      }],
+      partialFingerprints: { "residooFingerprint/v1": fingerprintFinding(f) },
+      properties: { source: f.source, confidence: f.confidence },
+    };
+  });
+
+  return JSON.stringify({
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [{
+      tool: {
+        driver: {
+          name: "residoo",
+          version,
+          informationUri: "https://github.com/dandovdub/residoo",
+          rules: [...rules.values()],
+        },
+      },
+      results,
+    }],
+  }, null, 2);
+}
+
+module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif };

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 });
     }