@clear-capabilities/agentic-security-scanner 0.144.0 → 0.147.0

package/src/server/security.js

@@ -0,0 +1,111 @@
+// security.js — Milestone 3, sub-project Server, increment 1.
+//
+// Security primitives for the `explore` loopback HTTP server: session-token
+// generation/comparison and Host-header validation (the T2 DNS-rebinding
+// defense — see docs/DATA_FLOW_EXPLORER_THREAT_MODEL.md). No node:http
+// usage here — this module is pure and independently unit-testable.
+
+import * as crypto from 'node:crypto';
+
+/** 32 random bytes, hex-encoded (64 hex chars) — the per-session token. */
+export function generateSessionToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+/**
+ * Constant-time string comparison. Wraps crypto.timingSafeEqual, which
+ * THROWS on unequal-length buffers — guarded here the same way
+ * posture/integrity.js's verifyLastScan guards its own HMAC comparison
+ * (`stored.length !== expected.length`), which this function mirrors as
+ * its template. Never throws; returns false on any malformed input.
+ */
+export function constantTimeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+  if (bufA.length !== bufB.length) return false;
+  try {
+    return crypto.timingSafeEqual(bufA, bufB);
+  } catch {
+    return false;
+  }
+}
+
+// Loopback hostnames this server ever legitimately answers to. Anything
+// else in a Host header is either a stray/misconfigured client or a
+// DNS-rebinding attempt from a hostile page — reject it (T2).
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+
+/**
+ * Validates a request's `Host` header against the port the server is
+ * actually listening on. Accepts only `127.0.0.1`/`localhost`/`::1`
+ * (`::1` written either bare or bracketed, `[::1]`), each carrying the
+ * expected port explicitly — this is the ENTIRE T2 (DNS rebinding)
+ * defense: a hostile page that points a fetch() at 127.0.0.1:<port> still
+ * sends the ATTACKER'S origin's Host header value (its own hostname), not
+ * "127.0.0.1", so this check rejects it regardless of same-origin policy
+ * quirks in any particular browser.
+ *
+ * A bare host with no port suffix is accepted ONLY when expectedPort is
+ * the default HTTP port (80) — browsers omit :80 for a default-port
+ * http:// request. In practice this server always listens on a
+ * non-default port, so that branch is effectively unreachable but is kept
+ * for RFC-correctness rather than special-cased away.
+ *
+ * @param {string|undefined} hostHeader
+ * @param {number} expectedPort
+ * @returns {boolean}
+ */
+export function isValidHost(hostHeader, expectedPort) {
+  if (typeof hostHeader !== 'string' || hostHeader.length === 0) return false;
+  if (typeof expectedPort !== 'number' || !Number.isInteger(expectedPort) || expectedPort <= 0) return false;
+
+  const host = hostHeader.trim();
+  if (host.length !== hostHeader.length) return false; // reject leading/trailing whitespace outright
+  if (/\s/.test(host)) return false; // no embedded whitespace/control chars in a well-formed Host header
+
+  let hostname;
+  let port = null;
+
+  if (host.startsWith('[')) {
+    // Bracketed IPv6 literal form: [::1] or [::1]:port
+    const closeIdx = host.indexOf(']');
+    if (closeIdx === -1) return false;
+    hostname = host.slice(1, closeIdx); // strip brackets
+    const rest = host.slice(closeIdx + 1);
+    if (rest.length) {
+      if (!rest.startsWith(':')) return false;
+      const portStr = rest.slice(1);
+      if (!/^\d+$/.test(portStr)) return false;
+      port = Number(portStr);
+    }
+  } else {
+    const parts = host.split(':');
+    if (parts.length === 1) {
+      hostname = parts[0];
+    } else if (parts.length === 2) {
+      hostname = parts[0];
+      if (!/^\d+$/.test(parts[1])) return false;
+      port = Number(parts[1]);
+    } else {
+      // More than one colon with no brackets: either a malformed header or
+      // a bare (unbracketed) IPv6 literal, which is not valid Host syntax
+      // (RFC 7230 §5.4 requires brackets for an IPv6 literal). Reject.
+      return false;
+    }
+  }
+
+  hostname = hostname.toLowerCase();
+  if (!LOOPBACK_HOSTS.has(hostname)) return false;
+
+  if (port === null) return expectedPort === 80;
+  return port === expectedPort;
+}
+
+// This server serves JSON only in this increment (no HTML, no inline
+// script/style, no static assets) — `frontend/`'s own static assets are a
+// later increment's (Wire's) job, not S1's. `default-src 'none'` is
+// therefore the correct, maximally-restrictive policy: nothing this
+// server ever returns should load or execute ANY sub-resource. Revisit
+// only when a future increment starts serving HTML/JS itself.
+export const CSP_HEADER_VALUE = "default-src 'none'; frame-ancestors 'none'";

package/src/server/static-assets.js

@@ -0,0 +1,139 @@
+// static-assets.js — Milestone 3, sub-project Wire.
+//
+// Confines the `explore` server's new same-origin static-asset surface to an
+// explicit ALLOWLIST of `frontend/`'s own real, servable files. This is the
+// first place scanner/src/server/ ever reads arbitrary requested paths off
+// disk — S1's five JSON endpoints never touched the filesystem beyond the
+// one already-loaded, already-verified graph — so path confinement here is
+// genuinely load-bearing, not decorative (see the M3-Wire scoping doc's
+// Decision 2, and the threat-model doc's T4 entry).
+//
+// `resolveStaticAsset()` is a PURE function: no fs/http access anywhere in
+// this file, fully unit-testable in isolation. http-server.js is the only
+// caller that actually reads a resolved file off disk.
+
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Located the SAME way scanner/src/mcp/server.js locates files relative to
+// its own module (path.dirname(fileURLToPath(import.meta.url))) — the real,
+// existing precedent for this pattern in this codebase, not a new one.
+// scanner/src/server/ -> ../../../frontend, computed (not guessed) and
+// confirmed to resolve to the real frontend/ directory.
+const _here = path.dirname(fileURLToPath(import.meta.url));
+export const FRONTEND_ROOT = path.resolve(_here, '..', '..', '..', 'frontend');
+
+export const CONTENT_TYPE_MAP = Object.freeze({
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+});
+
+// Same-origin-permitting CSP for the static/HTML surface — deliberately
+// DIFFERENT from security.js's CSP_HEADER_VALUE ("default-src 'none'"),
+// which stays correct for the JSON-only /api/v1/* routes (unchanged). This
+// one needs to let the page load its OWN same-origin script/style and make
+// its OWN same-origin fetch() calls, while still denying everything
+// cross-origin — no remote scripts/fonts/analytics, matching
+// frontend/README.md's own "no CDN scripts, remote fonts, analytics" rule.
+//
+// Grepped across the whole frontend/ tree for any inline <script>/
+// style="..." attribute/<style> tag beyond the one index.html inline
+// <script type="module"> block this increment moves into main.js (see
+// item 5 of the plan): none found (confirmed this session, 2026-09-01).
+// So a strict script-src 'self'/style-src 'self' needs no 'unsafe-inline'
+// exception — do not add one without re-running that grep.
+export const STATIC_CSP_HEADER_VALUE =
+  "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'";
+
+// Deliberately restrictive character class (no backslash, no space, no
+// percent sign, no null) — every real filename in frontend/'s inventory is
+// plain ASCII with letters/digits/hyphen/underscore/dot/slash, and keeping
+// the allowlist regex this narrow means an unexpected character in a
+// request path fails allowlisting by default rather than being silently
+// accepted and handed to a platform-specific path.join() later.
+const SRC_JS_RE = /^src\/[A-Za-z0-9/_.-]+\.js$/;
+const STYLES_CSS_RE = /^styles\/[A-Za-z0-9_.-]+\.css$/; // top-level only under styles/, no nested subdirectories — matches the real, current inventory
+
+/**
+ * Resolves a request pathname (e.g. `/`, `/src/app.js`, `/styles/tokens.css`)
+ * against `frontend/`'s explicit servable-file allowlist. Returns
+ * `{ok:true, relativePath, contentType}` or `{ok:false, reason}`.
+ *
+ * Deliberately an ALLOWLIST, not merely a `../`-traversal guard: `test/`,
+ * `scripts/`, `package.json`, `README.md`, `CLAUDE.md`, and `.gitignore` are
+ * all real files that exist under FRONTEND_ROOT on disk and must NEVER be
+ * served — a naive "stays inside frontend/" confinement check would still
+ * happily serve every one of them.
+ */
+export function resolveStaticAsset(requestPath) {
+  if (typeof requestPath !== 'string' || requestPath.length === 0) {
+    return { ok: false, reason: 'invalid-path' };
+  }
+  if (requestPath.includes('\0')) {
+    return { ok: false, reason: 'null-byte' };
+  }
+  // Absolute-URL-looking input: a scheme (`http://...`) or a
+  // protocol-relative `//host/...` — neither is a valid same-origin
+  // pathname this server should ever try to resolve.
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(requestPath) || requestPath.startsWith('//')) {
+    return { ok: false, reason: 'absolute-url' };
+  }
+  if (!requestPath.startsWith('/')) {
+    return { ok: false, reason: 'invalid-path' };
+  }
+
+  let decoded;
+  try {
+    decoded = decodeURIComponent(requestPath);
+  } catch {
+    return { ok: false, reason: 'malformed-encoding' };
+  }
+  if (decoded.includes('\0')) {
+    // Catches a %00-encoded null byte the raw-string check above can't see.
+    return { ok: false, reason: 'null-byte' };
+  }
+
+  if (decoded === '/' || decoded === '') {
+    return { ok: true, relativePath: 'index.html', contentType: CONTENT_TYPE_MAP['.html'] };
+  }
+  if (decoded.startsWith('//')) {
+    return { ok: false, reason: 'absolute-url' };
+  }
+
+  const candidate = decoded.slice(1); // strip the single leading '/'
+
+  // Normalize using POSIX rules regardless of host OS — this is a URL path,
+  // never a platform filesystem path, and must be treated as forward-slash
+  // segments even on a host where path.normalize would use backslashes.
+  const normalized = path.posix.normalize(candidate);
+
+  // Re-check for a traversal escape AFTER normalization — never trust
+  // normalize() alone to have removed a traversal attempt (a classic
+  // traversal-bypass class): explicitly reject anything that still IS, or
+  // still CONTAINS, a `..` segment, or that normalized to an absolute path.
+  if (
+    normalized === '..' ||
+    normalized === '.' ||
+    normalized.startsWith('../') ||
+    normalized.includes('/../') ||
+    normalized.endsWith('/..') ||
+    normalized.startsWith('/')
+  ) {
+    return { ok: false, reason: 'path-traversal' };
+  }
+
+  // --- The actual ALLOWLIST (default: deny) ---
+
+  if (normalized === 'index.html') {
+    return { ok: true, relativePath: normalized, contentType: CONTENT_TYPE_MAP['.html'] };
+  }
+  if (SRC_JS_RE.test(normalized)) {
+    return { ok: true, relativePath: normalized, contentType: CONTENT_TYPE_MAP['.js'] };
+  }
+  if (STYLES_CSS_RE.test(normalized)) {
+    return { ok: true, relativePath: normalized, contentType: CONTENT_TYPE_MAP['.css'] };
+  }
+
+  return { ok: false, reason: 'not-allowlisted' };
+}

package/src/util/git-hardening.js

@@ -0,0 +1,128 @@
+// Hardening for every `git` subprocess call this scanner makes against a
+// SCANNED repository it does not control — i.e. any git invocation whose
+// `cwd` (or `-C <dir>`) is a project the scanner was asked to scan, as
+// opposed to this project's own trusted checkout.
+//
+// Verified RCE (second independent Finding Provenance PRD audit,
+// FR-PROV-024 / PRD Section 8 "never run repository hooks or untrusted
+// build scripts"): git-evidence.js's `_run` invoked `git` with no config
+// hardening at all. A hostile repo's `.git/config` can set `core.fsmonitor`
+// to point at an attacker script; git executes it on an ordinary READ-ONLY
+// command like `git status --porcelain` — no clone, no checkout, no
+// deliberate command needed, just `getRepoState()` reading repo state.
+// Reproduced against this exact repro shape before this module existed:
+// `getRepoState()` alone wrote a marker file outside the repo.
+//
+// Four independent hostile-config surfaces, each closed by a different
+// flag/env var (do not assume one covers another — a same-class RCE
+// survived the first round of this hardening precisely because
+// `--no-textconv` was assumed to cover `git diff` the same way it covers
+// `git show`/`git log -p`/`git blame`, and it does not):
+//   - `core.fsmonitor`   -> fires on `git status` (and other porcelain
+//                           commands that consult the index). Closed by
+//                           `-c core.fsmonitor=` (empty value disables it).
+//   - `core.hooksPath`   -> redirects git's hook lookup to an
+//                           attacker-controlled directory (pre-commit,
+//                           post-checkout, ...). None of THIS module's
+//                           read-only operations should fire a hook, but a
+//                           caller elsewhere in the tree that does invoke a
+//                           hook-shaped command (checkout, commit) inherits
+//                           the same exposure — hardened uniformly rather
+//                           than relying on each call site to reason about
+//                           whether its own command can trigger a hook.
+//                           Closed by `-c core.hooksPath=/dev/null`
+//                           (verified: git tries to stat
+//                           `/dev/null/<hookname>`, which is not a
+//                           directory, so hook lookup fails closed — this
+//                           is NOT relying on /dev/null being an empty
+//                           *file*, it works because it isn't a directory).
+//   - `.gitattributes`   -> a `diff=<name>` attribute + a matching
+//     textconv driver     `diff.<name>.textconv` config key points a text
+//                           filter at an attacker script; fires on any
+//                           command that renders blob/diff CONTENT (`git
+//                           show`/`git diff`/`git log -p`/`git log -L`/
+//                           `git blame`) unless `--no-textconv` is passed.
+//                           Verified per-subcommand: `git show -s` (no
+//                           content shown) and `git show <sha>:<path>`
+//                           (blob cat, not a diff) were NOT exploitable in
+//                           this git version, but `git show -U0`, `git log
+//                           -L`, and `git blame` all were.
+//   - `.git/config` /       an EXTERNAL diff driver — `.gitattributes`
+//     `.gitattributes`      `diff=<name>` + `.git/config [diff "<name>"]
+//     external diff driver  command=<script>`, or the repo-local/global
+//                           `diff.external` config key — is a DIFFERENT
+//                           mechanism from the textconv driver above and is
+//                           NOT closed by `--no-textconv`. VERIFIED: `git
+//                           -c core.fsmonitor= -c core.hooksPath=/dev/null
+//                           diff --unified=0 --no-textconv <ref>...HEAD`
+//                           still runs the attacker's `diff.evil.command`
+//                           script — `--no-textconv` only suppresses the
+//                           TEXTCONV driver, and `git diff` (unlike `git
+//                           show`/`git log -p`/`git blame`, which were all
+//                           verified safe with just `--no-textconv`) honours
+//                           an external diff driver by default regardless.
+//                           Closed by `--no-ext-diff`, which must be passed
+//                           explicitly on every `git diff` invocation (same
+//                           reason `--no-textconv` isn't a `-c` flag: it's a
+//                           diff-machinery option, not repo config). This
+//                           was the live RCE a second review found after the
+//                           first round of this hardening shipped —
+//                           material-change.js's `classifyGitDiff` (the real
+//                           entry point for `/scan --diff`) had
+//                           `--no-textconv` but not `--no-ext-diff` and was
+//                           still exploitable end-to-end.
+//
+// A FIFTH surface is known but not exploitable through any call site in this
+// codebase today, so it is documented rather than closed: a `clean` smudge
+// filter (`.gitattributes` `filter=<name>` + `filter.<name>.clean`) fires on
+// a WORKTREE diff (e.g. `git diff --name-only HEAD` with no `<ref>` on the
+// other side) and has no git flag to disable it at all (unlike textconv/
+// ext-diff). Every `git diff` call site in this codebase diffs two refs
+// (`<ref>...HEAD`), never the worktree against HEAD, so nothing here hits
+// it — but a future worktree-diff call site would silently reintroduce this
+// exact vulnerability class and must not assume `hardenGitArgs` covers it.
+//
+// `GIT_CONFIG_NOSYSTEM=1` additionally blocks a SYSTEM-level git config
+// (outside any repository, e.g. /etc/gitconfig) from re-introducing a
+// hostile setting the `-c` flags above didn't anticipate; `GIT_TERMINAL_PROMPT=0`
+// stops a git invocation from ever blocking on an interactive credential
+// prompt (a hostile repo pointing `origin`/a submodule at a URL that
+// prompts). Both are environment variables, not `-c` flags — git does not
+// expose either as repo-local config.
+//
+// Every `git` subprocess call this scanner makes against a scan target's
+// repository MUST route its args through `hardenGitArgs` and its env
+// through `hardenGitEnv`. A `git show`/`git diff`/`git log -p`/`git log -L`/
+// `git blame` invocation must ALSO pass `--no-textconv` explicitly (it is
+// not a `-c` config value, so it isn't folded into `GIT_HARDENED_CONFIG_ARGS`
+// — it must appear in the invocation's own args, after the config args), and
+// a `git diff` invocation must ADDITIONALLY pass `--no-ext-diff` (a
+// different flag for a different surface — see above; `--no-textconv` does
+// not imply it).
+
+export const GIT_HARDENED_CONFIG_ARGS = Object.freeze([
+  '-c', 'core.fsmonitor=',
+  '-c', 'core.hooksPath=/dev/null',
+]);
+
+export const GIT_HARDENED_ENV = Object.freeze({
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_TERMINAL_PROMPT: '0',
+});
+
+// Prepend the hardening `-c` flags to a git argv. These are GLOBAL options
+// and must appear before the subcommand, which is why this always prepends
+// rather than appending — a `-c` after the subcommand name is parsed as a
+// positional argument to that subcommand, not a global option.
+export function hardenGitArgs(args) {
+  return [...GIT_HARDENED_CONFIG_ARGS, ...(Array.isArray(args) ? args : [])];
+}
+
+// Build the `env` option for execFileSync/spawnSync. Node's `env` option
+// REPLACES the child's environment rather than merging with it, so this
+// always spreads `process.env` first — passing `hardenGitEnv()` with no
+// argument must be behaviourally identical to inheriting the parent
+// environment plus the two hardening vars, never a stripped-down one.
+export function hardenGitEnv(extraEnv) {
+  return { ...process.env, ...GIT_HARDENED_ENV, ...(extraEnv || {}) };
+}