residoo 0.23.1 → 0.24.0

package/README.md

@@ -53,8 +53,10 @@ again, since there's nothing to lose. `residoo guard` blocks an obviously
 sensitive file read before it happens (100% recall, 0% false positives on
 its own [scored 81-case corpus](bench/guard/RESULTS.md)) and, via a second
 hook, a secret typed directly into the prompt itself — confirmed against
-Claude Code's own docs to block before the model ever processes it. All
-four are covered in [docs/features.md](docs/features.md).
+Claude Code's own docs to block before the model ever processes it.
+`residoo dashboard` is this same report as a local, read-only web page
+instead of a terminal, opened in your browser on demand. All five are
+covered in [docs/features.md](docs/features.md).
 
 > [!NOTE]
 > gitleaks and trufflehog scan **commits**. residoo scans the **conversation
@@ -148,10 +150,11 @@ while losing rows, then fixed in public against the classes it was losing
   acknowledgement ledger. See [docs/architecture.md](docs/architecture.md#rotation-from-found-to-closed).
 - `--project <dir>` scans a repository checkout instead of the machine,
   for CI and pre-commit. See [docs/ci.md](docs/ci.md).
-- `residoo watch` / `residoo mcp` / `residoo cred` / `residoo guard`:
-  continuous scanning, conversational queries, credential injection
-  without pasting, and blocking a sensitive file read or a sensitive
-  prompt before either happens. See [docs/features.md](docs/features.md).
+- `residoo watch` / `residoo mcp` / `residoo cred` / `residoo guard` /
+  `residoo dashboard`: continuous scanning, conversational queries,
+  credential injection without pasting, blocking a sensitive file read or
+  a sensitive prompt before either happens, and a local read-only web UI.
+  See [docs/features.md](docs/features.md).
 
 ## What it does not do
 
@@ -243,7 +246,7 @@ residoo ack <fingerprint> [--note <text>]           mark one finding rotated
 residoo unseal <vault-dir>                          list a vault's contents
 residoo unseal <vault-dir> --restore <n> --out <p>  restore one file, hash-verified
 
-residoo watch / mcp / cred / guard                  see docs/features.md
+residoo watch / mcp / cred / guard / dashboard      see docs/features.md
 ```
 
 The vault passphrase comes from `RESIDOO_PASSPHRASE` or a hidden interactive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.23.1",
+  "version": "0.24.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/cli.js

@@ -12,6 +12,7 @@ const {
   ROTATION_GUIDANCE, guidanceFor, loadAcks, loadDismissed, ackFinding, dismissFinding, renderRotation,
 } = require("./rotation");
 const { startWatch, isTailable } = require("./watch");
+const { startDashboardServer, openBrowser } = require("./dashboard");
 const { startMcpServer } = require("./mcp");
 const { buildTools } = require("./mcpTools");
 const { runGuard: runGuardEngine, buildHookConfig } = require("./guard");
@@ -218,6 +219,30 @@ Watch:
   Ctrl+C stops cleanly and prints a session summary (skipped with --json,
   where the same information is one final NDJSON event).
 
+Dashboard:
+  residoo dashboard        the exact "scan --html" report, served live at
+                          a local URL instead of written to disk, and
+                          opened in your browser automatically. Read-only:
+                          this only visualizes what a scan already shows
+                          you, it never acks/dismisses/seals anything.
+                          Every page reload re-scans from scratch -- there
+                          is no separate refresh action, and nothing here
+                          is cached across requests.
+  --port <n>              use a specific port instead of letting the OS
+                          assign one
+  --no-open               print the URL instead of opening a browser tab
+                          automatically
+  --include-noisy, --include-suppressed, --include-pii,
+  --include-injection, --no-integrity, --project [dir]
+                          same meaning as scan
+  Bound to 127.0.0.1 only, never your network, and every request must
+  present a random token generated fresh for this run (printed as part
+  of the URL) -- the same local-security model Jupyter Notebook uses.
+  The server also rejects any request whose Host header isn't
+  127.0.0.1/localhost, closing the DNS-rebinding class this project's
+  own cve.js already catalogued two real MCP SDK CVEs for. Ctrl+C stops
+  it; nothing is left running in the background afterward.
+
 MCP:
   residoo mcp              run residoo as an MCP server over stdio, so
                           Claude Code (or any other MCP client) can query
@@ -853,6 +878,138 @@ async function runWatch(args) {
   return 0;
 }
 
+/**
+ * `residoo dashboard`: the exact `--html` report, served live over a local,
+ * read-only HTTP server instead of written to disk -- see dashboard.js's
+ * own header for the DNS-rebinding defense, the per-run token, and why
+ * this is strictly more locked-down than the static file it's built from.
+ * On-demand only (this session's own explicit scope decision, matching
+ * `watch`'s "you run a command when you want it" model, not an always-on
+ * background service): the server runs until Ctrl-C, same shutdown
+ * contract as `runWatch` above. Every request re-scans from scratch, so
+ * reloading the page in the browser is how you refresh it -- no separate
+ * "refresh" action, no cached-at-startup snapshot going stale.
+ */
+async function runDashboard(args) {
+  const includeNoisy = args.includes("--include-noisy");
+  const includeSuppressed = args.includes("--include-suppressed");
+  const includePii = args.includes("--include-pii");
+  const includeInjection = args.includes("--include-injection");
+  const wantsIntegrity = !args.includes("--no-integrity");
+  const noBrowser = args.includes("--no-open");
+
+  let port = 0; // 0: OS assigns an ephemeral port
+  const portArg = argValue(args, "--port");
+  if (portArg !== null) {
+    const n = Number(portArg);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1 || n > 65535) {
+      process.stderr.write(`--port must be an integer between 1 and 65535; got "${portArg}".\n`);
+      return 2;
+    }
+    port = n;
+  }
+
+  let projectRoot = null;
+  const projectIdx = args.indexOf("--project");
+  if (projectIdx >= 0) {
+    const next = args[projectIdx + 1];
+    projectRoot = path.resolve(next && !next.startsWith("--") ? next : ".");
+  }
+
+  let sources;
+  if (projectRoot) {
+    const projectArtifacts = require("./sources/project-artifacts");
+    const src = projectArtifacts.withRoot(projectRoot);
+    if (!src.available()) {
+      process.stderr.write(`--project: "${projectRoot}" is not a readable directory.\n`);
+      return 2;
+    }
+    sources = [src];
+  } else {
+    sources = availableSources();
+    if (sources.length === 0) {
+      process.stderr.write(
+        "No known transcript sources found on this machine; nothing to show.\n" +
+        `Checked: ${sourceStatusList()}.\n`
+      );
+      return 0;
+    }
+  }
+
+  // Same crash-degrades-to-a-visible-warning contract runIntegrity() in
+  // the scan path above already has, duplicated rather than shared: this
+  // function does its own arg parsing and orchestration independently of
+  // the scan-command code path (the same "one small self-contained CLI
+  // command function" split runWatch/runMcp already establish), rather
+  // than risking a regression in the far more heavily depended-on scan
+  // path by factoring it out.
+  const runIntegrityOnce = () => {
+    try {
+      const integ = checkIntegrity(projectRoot ? { home: projectRoot, cwd: projectRoot, projectMode: true } : {});
+      if (projectRoot) {
+        integ.scopeNote = "Integrity checks cover the --project directory only (paths shown relative to it); this machine's home-level agent configs were not examined on this run.";
+      }
+      return integ;
+    } catch (e) {
+      const why = String((e && e.message) || e).replace(/[\x00-\x1f\x7f]/g, "").slice(0, 200);
+      return {
+        findings: [{
+          severity: "warn", kind: "integrity-crashed", file: "(integrity checker)",
+          detail: `integrity checks crashed (${why}). Config locations are UNVERIFIED, not clean; the secret-scan results are unaffected`,
+        }],
+        filesChecked: [],
+        scopeNote: "Integrity checks did not complete on this run.",
+      };
+    }
+  };
+
+  // Called fresh on every HTTP request (see dashboard.js) -- never caches
+  // across requests, so a reload always reflects the current machine
+  // state, not a snapshot from when the server started.
+  const gatherData = async () => {
+    const acks = loadAcks();
+    const dismissed = loadDismissed();
+    const integrity = wantsIntegrity ? runIntegrityOnce() : null;
+    const result = await scan({
+      sources, includeNoisy, includeSuppressed, includePii, includeInjection,
+      verify: false, noColor: false,
+    });
+    const rotation = renderRotation(result.findings, acks, dismissed);
+    return { result, integrity, rotation };
+  };
+
+  let started;
+  try {
+    started = await startDashboardServer({ port, gatherData });
+  } catch (err) {
+    process.stderr.write(`residoo dashboard: could not start the local server: ${(err && err.message) || err}\n`);
+    return 1;
+  }
+
+  process.stderr.write(
+    `residoo dashboard: ${started.url}\n` +
+    "Read-only, localhost only -- nothing here leaves this machine, and nothing here can change anything on it.\n" +
+    "Every page reload re-scans from scratch. Press Ctrl-C to stop.\n"
+  );
+  if (!noBrowser) openBrowser(started.url);
+
+  let signalled = false;
+  return new Promise((resolve) => {
+    const onSignal = () => {
+      if (signalled) return;
+      signalled = true;
+      started.stop().then(() => {
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+        process.stderr.write("residoo dashboard: stopped.\n");
+        resolve(0);
+      });
+    };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+  });
+}
+
 /**
  * `residoo guard --print-config`: print the merged .claude/settings.json
  * a user would need to register all three guard hooks, without ever
@@ -1084,6 +1241,7 @@ async function main(argv) {
   if (cmd === "ack") return runAck(args);
   if (cmd === "dismiss") return runDismiss(args);
   if (cmd === "watch") return runWatch(args);
+  if (cmd === "dashboard") return runDashboard(args);
   if (cmd === "mcp") return runMcp(args);
   if (cmd === "cred") return runCred(args);
   if (cmd === "guard") {

package/src/dashboard.js

@@ -0,0 +1,175 @@
+"use strict";
+
+const http = require("http");
+const crypto = require("crypto");
+// Not destructured: `cp.spawn(...)` at the call site, matching notify.js's
+// own documented reasoning -- a test can monkey-patch
+// `require("child_process").spawn` on the shared module object.
+const cp = require("child_process");
+const { renderHtml } = require("./report");
+
+/**
+ * `residoo dashboard`'s engine: a local, read-only HTTP server serving the
+ * exact same self-contained page `residoo scan --html` writes to disk
+ * (`renderHtml`, unmodified -- see report.js), except regenerated fresh on
+ * every request instead of written once. No new rendering code, no new
+ * data model: this is `--html`'s own output, served live instead of saved.
+ *
+ * SECURITY, taken as seriously as this project takes everything else it
+ * ships -- this is the first HTTP server residoo has ever run, and this
+ * project spent the last two releases cataloguing exactly what goes wrong
+ * when a local MCP server gets this wrong (see cve.js: CVE-2025-66414 and
+ * CVE-2025-66416, both "DNS rebinding protection not enabled by default"
+ * in the MCP TypeScript/Python SDKs). The same lesson, applied here:
+ *
+ *   - **DNS rebinding**: binding to 127.0.0.1 alone does NOT stop a
+ *     malicious webpage's browser tab from reaching this server -- an
+ *     attacker-controlled domain can be made to resolve to 127.0.0.1
+ *     after an initial same-origin check passes, letting page JavaScript
+ *     read the response as if it were same-origin. The actual fix (the
+ *     one those two CVEs shipped) is validating the `Host` header
+ *     server-side on every request: rejected outright unless it's
+ *     exactly `127.0.0.1:<this server's port>` or `localhost:<port>`.
+ *   - **A random per-run token**, required on every request (checked
+ *     AFTER the Host check, so a wrong-Host request never even reaches
+ *     token comparison) -- the same well-established local-security model
+ *     Jupyter Notebook has used for years. Defense in depth beyond DNS
+ *     rebinding: it also stops another local process or another user
+ *     account on a shared machine from stumbling onto the port and
+ *     reading a scan (already-redacted, but still real file paths and
+ *     rotation status) without ever being invited to.
+ *   - **Response headers** a static file has no mechanism to carry at
+ *     all: `X-Frame-Options: DENY` and `frame-ancestors 'none'` (no
+ *     clickjacking-by-iframe), `X-Content-Type-Options: nosniff`, a CSP
+ *     that blocks any REMOTE resource load (`default-src 'self'`) while
+ *     still allowing the page's own inline `<style>`/`<script>` --
+ *     which is server-generated, not reflecting unescaped request data
+ *     (every finding field already goes through `escapeHtml()` in
+ *     report.js). This makes the dashboard strictly more defended than
+ *     the plain `--html` file it's built from, which ships with none of
+ *     these headers because a file on disk has nowhere to put them.
+ *   - **No write path at all**: every request is a GET of `/`; nothing
+ *     here can mutate state, matching this release's own scoped-down
+ *     "visualize existing data, take no actions" decision. A future
+ *     action-taking dashboard (ack/dismiss/seal from the UI) is a
+ *     separate, later decision -- see README/features.md.
+ *   - **No CORS headers are ever sent.** The browser's own same-origin
+ *     policy already blocks a different-origin page's JavaScript from
+ *     reading this response; adding a permissive
+ *     `Access-Control-Allow-Origin` would undo that for no benefit here.
+ */
+
+/**
+ * Cross-platform "open this URL in the default browser," best-effort only
+ * -- the terminal always prints the URL too, so a failure here just means
+ * the user clicks/copies it instead of it opening automatically. Never
+ * throws, matching notify.js's own "a UI convenience must never affect
+ * the caller" contract.
+ */
+function openBrowser(url) {
+  try {
+    if (process.platform === "darwin") {
+      const child = cp.spawn("open", [url], { stdio: "ignore" });
+      child.on("error", () => {});
+      child.unref();
+    } else if (process.platform === "win32") {
+      // cmd's built-in `start` treats its first quoted argument as the
+      // window TITLE, not the target -- the empty "" is required so `url`
+      // is parsed as the target instead.
+      const child = cp.spawn("cmd.exe", ["/c", "start", "", url], { stdio: "ignore", windowsHide: true });
+      child.on("error", () => {});
+      child.unref();
+    } else {
+      const child = cp.spawn("xdg-open", [url], { stdio: "ignore" });
+      child.on("error", () => {});
+      child.unref();
+    }
+  } catch {
+    // Best-effort only -- see function docstring.
+  }
+}
+
+const CSP =
+  "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; " +
+  "frame-ancestors 'none'; connect-src 'self'; img-src 'self' data:";
+
+/**
+ * Start the dashboard's HTTP server. `gatherData()` is an async function
+ * returning `{ result, integrity, rotation }` (the same three arguments
+ * `renderHtml` already takes) -- called fresh on every request, so
+ * reloading the page in the browser re-scans rather than showing a
+ * cached-at-startup snapshot. `port` 0 (the default) lets the OS assign
+ * an ephemeral port; a caller-chosen port is used verbatim.
+ *
+ * Resolves to `{ url, stop }` once the server is actually listening --
+ * `url` already carries the per-run token as a query parameter, ready to
+ * open directly. `stop()` closes the server and resolves once fully shut
+ * down (never leaves a lingering listener behind on Ctrl-C).
+ */
+function startDashboardServer({ port = 0, gatherData }) {
+  const token = crypto.randomBytes(16).toString("hex");
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const hostHeader = String(req.headers.host || "");
+      const hostname = hostHeader.split(":")[0];
+      if (hostname !== "127.0.0.1" && hostname !== "localhost") {
+        res.writeHead(403, { "Content-Type": "text/plain" });
+        res.end("Forbidden: unexpected Host header");
+        return;
+      }
+
+      let url;
+      try { url = new URL(req.url, `http://${hostHeader || "localhost"}`); }
+      catch { res.writeHead(400, { "Content-Type": "text/plain" }); res.end("Bad request"); return; }
+
+      if (url.searchParams.get("token") !== token) {
+        res.writeHead(403, { "Content-Type": "text/plain" });
+        res.end("Forbidden: missing or incorrect token");
+        return;
+      }
+
+      if (req.method !== "GET" || url.pathname !== "/") {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not found");
+        return;
+      }
+
+      const { result, integrity, rotation } = await gatherData();
+      const html = renderHtml(result, integrity, rotation);
+      res.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "X-Frame-Options": "DENY",
+        "X-Content-Type-Options": "nosniff",
+        "Content-Security-Policy": CSP,
+        // Every response is a fresh scan; a cached stale one defeats the
+        // whole point of reloading to see current state.
+        "Cache-Control": "no-store",
+      });
+      res.end(html);
+    } catch {
+      // A scan/render failure must not crash the server or hang the
+      // request -- degrade to a visible 500, the same "never a silent
+      // all-clear, never a silent crash" discipline every other part of
+      // this project already holds to.
+      try {
+        res.writeHead(500, { "Content-Type": "text/plain" });
+        res.end("residoo dashboard: the scan failed while rendering this page. Check the terminal residoo is running in for details.");
+      } catch { /* response already sent/destroyed */ }
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      const actualPort = server.address().port;
+      const url = `http://127.0.0.1:${actualPort}/?token=${token}`;
+      resolve({
+        url,
+        stop: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+module.exports = { startDashboardServer, openBrowser };