@clear-capabilities/agentic-security-scanner 0.130.0 → 0.132.0

package/src/sandbox/backend-userspace.js

@@ -14,26 +14,9 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import { resolveUserspaceBin } from './capabilities.js';
-import { buildLimitPrelude } from './limits.js';
+import { buildLimitPrelude, ambientRelativeMaxProcs } from './limits.js';
 import { buildResult, errorResult, buildConfinedEnv } from './result.js';
 
-// `ulimit -u` (RLIMIT_NPROC) is a per-uid, system-wide cap on this platform,
-// not a per-process-tree cap (verified by execution in Task 2). A fixed
-// default like the 64 in buildLimitPrelude() breaks ordinary, non-adversarial
-// runs on any host whose user already has more than ~64 ambient processes —
-// which is common. So unless the caller passes an explicit maxProcs, we
-// compute one relative to the ambient count for this uid, the same
-// workaround Task 2 used in its own test, to keep default behavior usable
-// without pretending a low fixed cap is real containment.
-function _ambientProcCount() {
-  try {
-    const out = spawnSync('/bin/sh', ['-c', 'ps -U "$(id -un)" -o pid= | wc -l'], { encoding: 'utf8' });
-    return Number(String(out.stdout || '').trim()) || 200;
-  } catch {
-    return 200;
-  }
-}
-
 function _profile({ allowNetwork }) {
   return [
     '(version 1)',
@@ -72,7 +55,7 @@ export function runUserspace(argv, {
 
   const effectiveLimits = {
     ...limits,
-    maxProcs: limits.maxProcs ?? (_ambientProcCount() + 64),
+    maxProcs: limits.maxProcs ?? ambientRelativeMaxProcs(),
   };
 
   let prelude, unsupported;

package/src/sandbox/capabilities.js

@@ -1,7 +1,28 @@
 // Detects which OS confinement primitive is available. Fail-closed: when none
 // is found we report 'disabled', which REFUSES execution rather than running
 // target code unconfined.
+//
+// DETECTION IS FUNCTIONAL, NOT PRESENCE-BASED. An earlier version concluded
+// "available" from "the confinement binary is executable". That is a different
+// question from the one callers are actually asking. Verified on a Linux CI
+// runner: the kernel-namespace tool is installed and executable, but the
+// distribution restricts unprivileged user-namespace creation, so every
+// privilege variant fails and no confined command can start. Presence-based
+// detection reported the backend as available anyway, and `sandboxAvailable()`
+// — the signal callers use to decide whether it is safe to EXECUTE UNTRUSTED
+// CODE — answered true while nothing could actually be confined. False
+// assurance about confinement is precisely the failure this module exists to
+// prevent, so a backend now counts as available only if it just ran a trivial
+// command through its real code path.
+//
+// The probe result is cached for the process (one spawn, not one per call —
+// detection sits on the path of ordinary scans) and cleared by
+// `resetCapabilityCache()`.
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { runUserspace } from './backend-userspace.js';
+import { runNamespace } from './backend-namespace.js';
 
 // Referenced by path, never by product name (see Global Constraints).
 //
@@ -21,13 +42,49 @@ export const CONFINE_BINS_NAMESPACE = Object.freeze([
   '/usr/sbin/unshare',
 ]);
 
+// The filesystem-attach utility used by the namespace backend to establish
+// write confinement (read-only rebind of the whole mount tree, read-write
+// rebind of the sandbox root). Resolved by path for the same reason as the
+// others. Absent => the namespace backend cannot establish write confinement
+// and fails closed; it never runs a command with the filesystem open.
+export const CONFINE_BINS_MOUNT = Object.freeze([
+  '/usr/bin/mount',
+  '/bin/mount',
+  '/sbin/mount',
+  '/usr/sbin/mount',
+]);
+
+// The privilege-dropping utility used to remove CAP_SYS_ADMIN (and everything
+// else) from the confined process *after* the mounts are in place, so the
+// payload cannot simply undo the read-only rebinds. Best-effort hardening on
+// top of the mount confinement, not the confinement itself: when it is absent
+// the run still happens under the read-only mount tree and the result declares
+// `privilegeDrop` unenforced rather than staying silent about it.
+export const CONFINE_BINS_PRIVDROP = Object.freeze([
+  '/usr/bin/setpriv',
+  '/bin/setpriv',
+  '/sbin/setpriv',
+  '/usr/sbin/setpriv',
+]);
+
 // Back-compat single-path exports: the first (canonical) candidate.
 export const CONFINE_BIN_USERSPACE = CONFINE_BINS_USERSPACE[0];
 export const CONFINE_BIN_NAMESPACE = CONFINE_BINS_NAMESPACE[0];
 
 let _cached = null;
 
-export function resetCapabilityCache() { _cached = null; }
+// Which namespace-flag variant actually works on this host, keyed by the
+// requested confinement shape. Probing costs a process spawn, so it is done
+// once; `undefined` means "not probed yet", `null` means "probed and nothing
+// worked" (which the backend turns into a fail-closed error, never a run).
+const _nsVariant = new Map();
+
+export function resetCapabilityCache() { _cached = null; _nsVariant.clear(); }
+
+export function cachedNamespaceVariant(key) {
+  return _nsVariant.has(key) ? _nsVariant.get(key) : undefined;
+}
+export function cacheNamespaceVariant(key, value) { _nsVariant.set(key, value); }
 
 /** First executable candidate, or null when none of them exists. */
 export function resolveConfineBin(candidates) {
@@ -37,13 +94,84 @@ export function resolveConfineBin(candidates) {
 
 export function resolveUserspaceBin() { return resolveConfineBin(CONFINE_BINS_USERSPACE); }
 export function resolveNamespaceBin() { return resolveConfineBin(CONFINE_BINS_NAMESPACE); }
+export function resolveMountBin() { return resolveConfineBin(CONFINE_BINS_MOUNT); }
+export function resolvePrivDropBin() { return resolveConfineBin(CONFINE_BINS_PRIVDROP); }
 
-export function detectBackend({ force } = {}) {
+// Bounded on purpose: a capability check must never hang a scan. The probe is
+// a single `exit 0` under confinement, so anything beyond a couple of seconds
+// is a host that is not going to answer.
+const PROBE_TIMEOUT_MS = Math.max(
+  250,
+  Number(process.env.AGENTIC_SECURITY_SANDBOX_PROBE_TIMEOUT_MS) || 4000,
+);
+
+/**
+ * Run a trivial command through a backend's real code path and report whether
+ * confinement actually worked. Anything other than a clean confined run — a
+ * missing binary, a refused namespace, a timeout, a throw — is `false`. There
+ * is deliberately no branch that relaxes confinement to make a probe pass: a
+ * backend that can only succeed with a flag dropped is not available, it is
+ * `'disabled'`.
+ */
+function _probeThroughBackend(runner) {
+  let root = null;
+  try {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'agsec-sbx-probe-'));
+    const r = runner(['/bin/sh', '-c', 'exit 0'], { root, timeoutMs: PROBE_TIMEOUT_MS });
+    return r?.status === 'ok';
+  } catch {
+    return false;
+  } finally {
+    if (root) { try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ } }
+  }
+}
+
+/**
+ * The real probes, one per backend. The binary check stays only as a cheap
+ * pre-filter that avoids a pointless temp dir on a host that plainly lacks the
+ * primitive — it is no longer the answer, just the fast negative.
+ */
+export function defaultProbes() {
+  return {
+    userspace: () => (resolveUserspaceBin() ? _probeThroughBackend(runUserspace) : false),
+    namespace: () => (resolveNamespaceBin() ? _probeThroughBackend(runNamespace) : false),
+  };
+}
+
+/** Backends worth probing on a platform, most-appropriate first. */
+export function backendCandidates(platform = process.platform) {
+  if (platform === 'darwin') return ['userspace'];
+  if (platform === 'linux') return ['namespace'];
+  return [];
+}
+
+/**
+ * @param {object}   [o]
+ * @param {string}   [o.force]      Bypass detection entirely (tests, and callers
+ *                                  that want the disabled path deliberately).
+ * @param {object}   [o.probes]     Probe map override — a seam for tests to drive
+ *                                  the selection contract with stand-ins on any
+ *                                  platform. Cannot cause unconfined execution:
+ *                                  dispatch still goes to the real backend.
+ * @param {string[]} [o.candidates] Candidate order override (same seam).
+ */
+export function detectBackend({ force, probes, candidates } = {}) {
   if (force) return force;
   if (_cached) return _cached;
+
+  const probeMap = probes || defaultProbes();
+  const order = candidates || backendCandidates();
+
   let b = 'disabled';
-  if (process.platform === 'darwin' && resolveUserspaceBin()) b = 'userspace';
-  else if (process.platform === 'linux' && resolveNamespaceBin()) b = 'namespace';
+  for (const name of order) {
+    const probe = probeMap[name];
+    if (typeof probe !== 'function') continue;
+    let works = false;
+    try { works = probe() === true; } catch { works = false; }
+    if (works) { b = name; break; }
+    // Otherwise fall through to the next candidate, and ultimately to
+    // 'disabled' — never to "run it anyway".
+  }
   _cached = b;
   return b;
 }

package/src/sandbox/limits.js

@@ -4,6 +4,27 @@
 // verified by execution. We therefore DECLARE it unsupported rather than
 // emitting a limit that silently does nothing, which would be a false
 // assurance of containment.
+import { spawnSync } from 'node:child_process';
+
+// `ulimit -u` (RLIMIT_NPROC) is charged per *uid*, system-wide, on both
+// platforms this module supports — it is not a per-process-tree cap. A fixed
+// default like the 64 below therefore breaks ordinary, non-adversarial runs on
+// any host whose user already owns more than ~64 processes, which is most of
+// them: the confined shell cannot even fork the helpers it needs to set itself
+// up, and the failure looks like a broken sandbox rather than a cap doing its
+// job. So unless a caller passes an explicit `maxProcs`, both real backends
+// derive one from the ambient count for this uid. That keeps default behaviour
+// usable without pretending a low fixed cap is real containment — see the
+// "fork-storm containment is weak" note in the module guide.
+export function ambientRelativeMaxProcs(headroom = 64) {
+  let ambient = 200;
+  try {
+    const out = spawnSync('/bin/sh', ['-c', 'ps -U "$(id -un)" -o pid= | wc -l'], { encoding: 'utf8' });
+    ambient = Number(String(out.stdout || '').trim()) || 200;
+  } catch { /* fall through to the conservative default */ }
+  return ambient + headroom;
+}
+
 export function buildLimitPrelude({
   maxProcs = 64,
   maxFileSizeKb = 65536,

package/src/sandbox/result.js

@@ -63,7 +63,7 @@ export function buildResult({ backend, spawnResult, unsupported = [] }) {
     status,
     denied,
     stdout: r.stdout ?? '',
-    stderr: rawStderr + (unsupported.length ? `\n[sandbox] limits not enforceable here: ${unsupported.join(', ')}` : ''),
+    stderr: rawStderr + (unsupported.length ? `\n[sandbox] not enforceable here: ${unsupported.join(', ')}` : ''),
     exitCode: r.status ?? null,
     timedOut,
     backend,

package/src/util/glob.js

@@ -0,0 +1,173 @@
+// File discovery on top of the Node standard library only.
+//
+// Two entry points, both replacing a third-party glob package that used to be a
+// production dependency:
+//
+//   listFiles(root, {ignore})  — the scan-tree walk behind readScan/readTree.
+//   globFiles(pattern, {cwd})  — resolve a user-supplied glob to regular files.
+//
+// `globFiles` is a thin wrapper: `fs.promises.glob` matches the old behaviour
+// for the way those call sites used it (dot:false, onlyFiles:true, symlinks
+// followed), so all it adds is the files-only filter.
+//
+// `listFiles` cannot be a thin wrapper, and the reasons are worth stating
+// precisely, because each one is a way file discovery could silently change:
+//
+//   * dot — the built-in glob (like every minimatch-derived matcher) will not
+//     let `*` or `**` match a path segment starting with `.`, and exposes no
+//     option to change that. The scan tree must include hidden files and must
+//     descend into hidden directories, so the walk is done with fs.readdir
+//     instead, where visibility is simply not a concept.
+//   * onlyFiles — a glob walk yields directories as well; only regular files
+//     are wanted. readdir's Dirent gives that directly, with no extra stat.
+//   * followSymbolicLinks:false — the built-in glob follows symlinked
+//     directories with no option to stop it, which would let a link inside the
+//     tree pull unrelated content (or content outside the scan root) into the
+//     scan. readdir's Dirent is lstat-derived: a symlink reports isSymbolicLink
+//     and neither isDirectory nor isFile, so links are skipped by construction
+//     and their targets are never reached.
+//   * suppressErrors — an unreadable directory must not abort the walk. Each
+//     readdir is individually guarded.
+//   * ignore — patterns are still matched with the built-in path.matchesGlob;
+//     only the dot-blindness above is compensated for (see unhide()).
+//
+// Ordering matches the previous implementation's breadth-first shape: every
+// entry of one depth is emitted before any entry of the next.
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+// Two properties of path.matchesGlob have to be corrected, and both are
+// corrected the same way: by rewriting the subject *and* the pattern through
+// the same injective transform, so the built-in matcher does the actual glob
+// work while the transform carries the semantics it will not.
+//
+//  1. Dot-blindness. A wildcard will not match a path segment starting with
+//     `.`, and there is no option to change that. Rewriting a segment's leading
+//     dot to a control character makes wildcards dot-permissive while keeping
+//     an explicitly-named segment literal: pattern `.git` becomes `<1>git`,
+//     which still matches a directory named `.git` and still does not match one
+//     named `git`. Only applied where dot-permissive matching is wanted.
+//  2. Partial case-folding. The matcher folds case in some positions — e.g.
+//     `UPPER/MiXeD.JS` matches `**/*.js` — while `Test/a.js` does not match
+//     `**/test/**`. That inconsistency is worse than either rule on its own,
+//     and case-folding is not what the previous implementation did. Encoding
+//     each upper-case letter as a control character plus its lower-case form
+//     makes matching case-sensitive everywhere: no folded comparison can
+//     reintroduce the marker.
+//
+// Neither control character can appear in a filename produced by any of the
+// filesystems this runs on, so the transform cannot collide with real content.
+const DOT = String.fromCharCode(1);
+const UP = String.fromCharCode(2);
+const HAS_UPPER = /[A-Z]/;
+const ALL_UPPER = /[A-Z]/g;
+const foldUp = c => UP + c.toLowerCase();
+
+function prepPath(p, dot) {
+  let s = p;
+  if (dot && s.includes('.')) {
+    const segs = s.split('/');
+    for (let i = 0; i < segs.length; i++) {
+      if (segs[i].charCodeAt(0) === 46) segs[i] = DOT + segs[i].slice(1);
+    }
+    s = segs.join('/');
+  }
+  return HAS_UPPER.test(s) ? s.replace(ALL_UPPER, foldUp) : s;
+}
+
+/**
+ * True when `rel` (a '/'-separated relative path) matches any of `patterns`.
+ * Case-sensitive; wildcards match hidden segments.
+ */
+export function matchesAnyGlob(rel, patterns) {
+  if (!patterns || patterns.length === 0) return false;
+  const subject = prepPath(rel, true);
+  for (const pat of patterns) {
+    if (path.matchesGlob(subject, prepPath(pat, true))) return true;
+  }
+  return false;
+}
+
+// A directory may be skipped wholesale only when a pattern provably excludes
+// every possible descendant. `<prefix>/**` is exactly that shape: `**` absorbs
+// any number of trailing segments, so if the directory matches `<prefix>` then
+// nothing beneath it can survive. Anything else (`<prefix>/*`, `**/*.min.js`)
+// may exclude some descendants and keep others, so those directories are walked
+// and their files filtered individually. Pruning is therefore only ever a
+// speed-up: correctness comes from the per-file check.
+function prunable(subject, prepared) {
+  for (const p of prepared) {
+    if (p.subtree && path.matchesGlob(subject, p.subtree)) return true;
+  }
+  return false;
+}
+
+function prepare(patterns) {
+  return patterns.map(pat => {
+    const glob = prepPath(pat, true);
+    return { glob, subtree: glob.endsWith('/**') ? glob.slice(0, -3) : null };
+  });
+}
+
+/**
+ * Every regular file under `root`, as '/'-separated paths relative to `root`.
+ * Hidden entries included; directories and symlinks excluded; unreadable
+ * directories skipped; `ignore` globs applied to each file path.
+ */
+export async function listFiles(root, { ignore = [] } = {}) {
+  const prepared = prepare(ignore);
+  const out = [];
+  let level = [''];
+  while (level.length) {
+    const next = [];
+    for (const dir of level) {
+      let entries;
+      try {
+        entries = await fs.readdir(dir ? path.join(root, dir) : root, { withFileTypes: true });
+      } catch {
+        continue; // unreadable or vanished — skip it, keep walking
+      }
+      for (const e of entries) {
+        const rel = dir ? `${dir}/${e.name}` : e.name;
+        const subject = prepared.length ? prepPath(rel, true) : '';
+        if (e.isDirectory()) {
+          if (!prunable(subject, prepared)) next.push(rel);
+        } else if (e.isFile()) {
+          let skip = false;
+          for (const p of prepared) {
+            if (path.matchesGlob(subject, p.glob)) { skip = true; break; }
+          }
+          if (!skip) out.push(rel);
+        }
+        // symlinks, sockets, fifos and block/char devices are not files
+      }
+    }
+    level = next;
+  }
+  return out;
+}
+
+/**
+ * Resolve a user-supplied glob to regular files, relative to `cwd`. Hidden
+ * paths are not matched (the built-in default) and symlinks are followed, both
+ * matching the previous behaviour at these call sites.
+ *
+ * Two corrections are layered on the built-in walk: results are narrowed to
+ * regular files (a glob yields directories too), and the partial case-folding
+ * described above is undone by re-checking each result against the pattern
+ * case-sensitively — a `.SARIF` file must not answer to `*.sarif`. Symlink
+ * cycles are the one place this is deliberately not bug-compatible: the
+ * built-in stops at a cycle instead of re-enumerating the tree through it.
+ */
+export async function globFiles(pattern, { cwd = process.cwd() } = {}) {
+  const strict = prepPath(pattern, false);
+  const out = [];
+  for await (const p of fs.glob(pattern, { cwd })) {
+    if (!path.matchesGlob(prepPath(p, false), strict)) continue;
+    try {
+      const st = await fs.stat(path.isAbsolute(p) ? p : path.join(cwd, p));
+      if (st.isFile()) out.push(p);
+    } catch { /* vanished or dangling link — not a file */ }
+  }
+  return out;
+}