residoo 0.11.0 → 0.13.0

package/README.md

@@ -99,7 +99,7 @@ while losing rows, then fixed in public against the classes it was losing
 
 ## What it does
 
-- Scans your local AI-agent session transcripts for 79 high-confidence
+- Scans your local AI-agent session transcripts for 84 high-confidence
   secret patterns: cloud provider keys, private key blocks, OAuth/API
   tokens, database connection strings, and more. See
   [`src/patterns.js`](src/patterns.js).

package/package.json

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

package/src/guard.js

@@ -153,13 +153,14 @@ const GUARDED_TOOL_NAMES = new Set(["Bash", "Read"]);
  */
 function evaluateToolInput(toolName, toolInput) {
   if (!GUARDED_TOOL_NAMES.has(toolName) || !toolInput || typeof toolInput !== "object") {
-    return { block: false, reason: null };
+    return { block: false, label: null, reason: null };
   }
   const candidate = toolName === "Bash" ? toolInput.command : toolInput.file_path;
   const label = matchSensitivePath(candidate);
-  if (!label) return { block: false, reason: null };
+  if (!label) return { block: false, label: null, reason: null };
   return {
     block: true,
+    label,
     reason: `residoo guard: this looks like a read of ${label}. Blocked before it could be written to the session transcript. ` +
       `If this is intentional and safe, ask the human to read it themselves, or disable this hook in .claude/settings.json.`,
   };
@@ -183,20 +184,44 @@ const PROMPT_GUARD_RULES = PATTERNS.filter((r) => r.confidence === "high");
  * evaluateToolInput above, not just a copy of the same bar.
  */
 function evaluatePromptText(promptText) {
-  if (typeof promptText !== "string" || !promptText) return { block: false, reason: null };
+  if (typeof promptText !== "string" || !promptText) return { block: false, label: null, preview: null, reason: null };
   for (const rule of PROMPT_GUARD_RULES) {
     rule.re.lastIndex = 0;
     const m = rule.re.exec(promptText);
     if (!m) continue;
     const value = m[0];
     if (VENDOR_EXAMPLE_VALUES.has(value) || zeroEntropyTail(value)) continue;
+    const preview = redact(value);
     return {
       block: true,
-      reason: `residoo guard: this prompt looks like it contains ${rule.label} (${redact(value)}). ` +
+      label: rule.label,
+      preview,
+      reason: `residoo guard: this prompt looks like it contains ${rule.label} (${preview}). ` +
         `Blocked before it could be sent. If this is a false positive, rephrase or remove it, or disable this hook in .claude/settings.json.`,
     };
   }
-  return { block: false, reason: null };
+  return { block: false, label: null, preview: null, reason: null };
+}
+
+/**
+ * Writes one structured audit line to stderr for a block decision --
+ * CONTRIBUTING.md's own hard rule (rule 3) names `~/.residoo/rotations.json`
+ * as "the only file residoo ever writes outside an explicit --seal...
+ * nothing else may claim this carve-out," so this is NOT a new file, the
+ * same choice `cred`'s own audit trail already made for the same reason
+ * (see src/credRun.js). Durability is the operator's choice: redirect the
+ * hook's own stderr at launch if you want it kept, same as `cred`.
+ * Never the raw matched value -- `preview` is already redact()'d by the
+ * caller (rule 4: no raw value in any log line, ever), and PreToolUse
+ * decisions carry no value at all, only a path-pattern label.
+ */
+function logAuditLine(errOutput, { event, label, preview, sessionId, cwd }) {
+  try {
+    errOutput.write(JSON.stringify({
+      ts: new Date().toISOString(), tool: "residoo guard", event, decision: "block",
+      label, ...(preview ? { preview } : {}), sessionId: sessionId || null, cwd: cwd || null,
+    }) + "\n");
+  } catch { /* stderr write failing is never a reason to fail the hook decision itself */ }
 }
 
 /**
@@ -207,9 +232,11 @@ function evaluatePromptText(promptText) {
  * response protocol to `output` (default stdout) -- exit code is the
  * caller's job (bin/residoo.js), this returns the intended process exit
  * code instead of calling process.exit itself, matching every other run*
- * function in cli.js.
+ * function in cli.js. Every BLOCK decision also gets one structured line
+ * on `errOutput` (default stderr) -- see logAuditLine's own docstring for
+ * why stderr, never a file.
  */
-async function runGuard({ input = process.stdin, output = process.stdout } = {}) {
+async function runGuard({ input = process.stdin, output = process.stdout, errOutput = process.stderr } = {}) {
   const chunks = [];
   for await (const chunk of input) chunks.push(chunk);
   const raw = Buffer.concat(chunks.map((c) => (Buffer.isBuffer(c) ? c : Buffer.from(c)))).toString("utf-8");
@@ -231,6 +258,10 @@ async function runGuard({ input = process.stdin, output = process.stdout } = {})
   if (payload.hook_event_name === "UserPromptSubmit") {
     const decision = evaluatePromptText(payload.prompt);
     if (!decision.block) return 0;
+    logAuditLine(errOutput, {
+      event: "UserPromptSubmit", label: decision.label, preview: decision.preview,
+      sessionId: payload.session_id, cwd: payload.cwd,
+    });
     output.write(JSON.stringify({ decision: "block", reason: decision.reason }) + "\n");
     return 0;
   }
@@ -238,6 +269,10 @@ async function runGuard({ input = process.stdin, output = process.stdout } = {})
   const decision = evaluateToolInput(payload.tool_name, payload.tool_input);
   if (!decision.block) return 0;
 
+  logAuditLine(errOutput, {
+    event: "PreToolUse", label: decision.label,
+    sessionId: payload.session_id, cwd: payload.cwd,
+  });
   output.write(JSON.stringify({
     hookSpecificOutput: {
       hookEventName: "PreToolUse",

package/src/patterns.js

@@ -539,6 +539,49 @@ const PATTERNS = [
   // same bare/opaque shape already excluded elsewhere in this file.
   { id: "akamai_edgegrid_token", label: "Akamai EdgeGrid token", confidence: "high",
     re: /\bakab-[a-z0-9]{16,32}-[a-z0-9]{6,32}\b/g },
+  // Doppler: seven distinct token kinds, all sharing the same dp.<tag>.
+  // structure. Confirmed via Doppler's own docs
+  // (docs.doppler.com/reference/auth-token-formats), which state plainly
+  // that "each token type uses a distinct prefix to enable identification
+  // during secret scanning operations" -- a format designed to be
+  // regex-detected, not inferred. Service tokens (dp.st.) alone carry an
+  // optional environment segment between the tag and the body; every other
+  // kind goes straight from the tag to the 40-44-char body.
+  { id: "doppler_token", label: "Doppler token", confidence: "high",
+    re: /\bdp\.(?:ct|pt|sa|said|scim|audit)\.[A-Za-z0-9]{40,44}\b|\bdp\.st\.(?:[a-z0-9_-]{2,35}\.)?[A-Za-z0-9]{40,44}\b/g },
+  // Postman API key. Postman's own docs describe how to generate one but
+  // not its literal format; sourced instead from gitleaks' own
+  // production-tested rule (config/gitleaks.toml, id "postman-api-token"),
+  // same tier as azure_ad_client_secret's sourcing earlier in this file.
+  { id: "postman_token", label: "Postman API key", confidence: "high",
+    re: /\bPMAK-[a-f0-9]{24}-[a-f0-9]{34}\b/gi },
+  // Figma personal access token. Figma's own docs don't publish the
+  // format either; sourced from trufflehog's own shipped detectors, which
+  // track two real, distinct generations: figd_ (the long-established
+  // form, trufflehog's v2 detector) and figp_ (a newer form, trufflehog's
+  // v3 detector, no keyword-proximity needed unlike v1's bare UUID shape,
+  // which is NOT included here for the same reason Bitbucket's keyword-
+  // dependent Client ID/Secret rules were declined -- no distinctive
+  // standalone prefix).
+  { id: "figma_token", label: "Figma personal access token", confidence: "high",
+    re: /\bfig[dp]_[A-Za-z0-9_=-]{40,54}\b/g },
+  // Bitbucket App Password (distinct from Bitbucket's Client ID/Secret,
+  // declined elsewhere in this file's history for being keyword-dependent
+  // with no standalone prefix). Confirmed via an Atlassian staff reply on
+  // Atlassian's own community forum naming ATBB as the current App
+  // Password prefix -- the same source already used for atlassian_api_token.
+  { id: "bitbucket_app_password", label: "Bitbucket App Password", confidence: "high",
+    re: /\bATBB[a-zA-Z0-9]{32}\b/g },
+  // SonarQube/SonarCloud token. gitleaks' own rule needs "sonar" keyword
+  // proximity because its body class also has to catch a bare unprefixed
+  // 40-char fallback -- unsafe as a standalone rule, so only the three
+  // confirmed literal prefixes are used here, which need no such context.
+  // squ_/sqp_/sqa_ confirmed real and current via SonarSource's own docs
+  // (docs.sonarsource.com), whose own worked example (sqp_ followed by
+  // 1aa323...8a1d13) is added to VENDOR_EXAMPLE_VALUES in scan.js as a
+  // documented example, not a findable secret.
+  { id: "sonarqube_token", label: "SonarQube/SonarCloud token", confidence: "high",
+    re: /\b(?:squ|sqp|sqa)_[a-z0-9=_-]{40}\b/g },
 ];
 
 /**

package/src/rotation.js

@@ -1093,6 +1093,58 @@ const ROTATION_GUIDANCE = {
     ],
     revokeNote: "Deactivation is immediate; anything still using the old credential starts failing authentication at once.",
   },
+  // docs.doppler.com/reference/auth-token-formats confirms the prefix
+  // table; the tokens page itself is login-walled.
+  doppler_token: {
+    label: "Doppler token",
+    consolePath: "dashboard.doppler.com > the relevant project/workplace > Access > Tokens (or Service Tokens / Service Accounts, matching which prefix leaked)",
+    steps: [
+      "Identify which token kind leaked from its prefix (dp.pt. personal, dp.st. service, dp.sa. service account, dp.scim. SCIM, dp.audit. audit log)",
+      "Revoke it from that kind's own settings page",
+      "Create a replacement and update whatever used the old one",
+    ],
+    revokeNote: "A dp.sa. (Service Account) or dp.st. (Service Token) leak can reach every secret in its assigned project/config -- treat it as broader than a personal token leak.",
+  },
+  postman_token: {
+    label: "Postman API key",
+    consolePath: "Postman > Settings (gear icon) > API keys",
+    steps: [
+      "Open API keys under your account settings",
+      "Delete the leaked key",
+      "Generate a replacement and update whatever used the old one",
+    ],
+    revokeNote: "Deletion is immediate; anything still using the old key starts failing authentication at once.",
+  },
+  figma_token: {
+    label: "Figma personal access token",
+    consolePath: "Figma > account Settings > Personal access tokens",
+    steps: [
+      "Open Personal access tokens under account Settings",
+      "Revoke the leaked token",
+      "Create a replacement and update whatever used the old one",
+    ],
+    revokeNote: "Revocation is immediate; anything still using the old token starts failing authentication at once.",
+  },
+  bitbucket_app_password: {
+    label: "Bitbucket App Password",
+    consolePath: "id.atlassian.com > Security > App passwords",
+    steps: [
+      "Open App passwords under account Security settings",
+      "Delete the leaked app password",
+      "Create a replacement with the narrowest scopes it needs",
+    ],
+    revokeNote: "Atlassian is steering users toward API tokens/Access tokens instead of App Passwords -- consider migrating rather than just replacing like-for-like.",
+  },
+  sonarqube_token: {
+    label: "SonarQube/SonarCloud token",
+    consolePath: "SonarQube/SonarCloud > My Account > Security",
+    steps: [
+      "Open the Security tab under My Account",
+      "Revoke the leaked token",
+      "Generate a replacement and update whatever used the old one",
+    ],
+    revokeNote: "Revocation is immediate; anything still using the old token starts failing authentication at once.",
+  },
 
   // ── NOISY_PATTERNS (only reachable via --include-noisy) ───────────────
   generic_password_assignment: {

package/src/scan.js

@@ -217,6 +217,11 @@ function zeroEntropyTail(value) {
 const VENDOR_EXAMPLE_VALUES = new Set([
   "AKIAIOSFODNN7EXAMPLE",
   "AKIAI44QH8DHBEXAMPLE",
+  // SonarSource's own worked example, repeated across its docs.sonarsource.com
+  // documentation (an API-key usage snippet, not a "this is our example
+  // secret" callout page, but used identically and repeatedly the same way
+  // AWS's own documented example key is).
+  "sqp_" + "1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13",
   "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
   "gho_16C7e42F292c6912E7710c838347Ae178B4a",
   "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",