residoo 0.3.4 → 0.3.6

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
@@ -119,6 +121,17 @@ won't be built into the tool that writes it.
 - 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.
@@ -304,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.4
+  - uses: dandovdub/residoo@v0.3.6
 ```
 
 As a pre-commit hook:
@@ -312,12 +325,15 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.3.4
+    rev: v0.3.6
     hooks:
       - id: residoo
 ```
 
-Or with no integration at all: `npx --yes residoo scan --project . --fail-on-find`.
+Or with no integration at all: `npm install -g residoo && residoo scan --project . --fail-on-find`
+(more reliable in CI than `npx --yes`, which failed consistently in real
+GitHub Actions runs while working fine locally; see the design note at the
+top of `action.yml`).
 Exit codes, inputs, and exactly what project mode does and does not see are
 documented in [docs/ci.md](docs/ci.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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/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 };