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

package/src/sandbox/limits.js

@@ -0,0 +1,63 @@
+// Resource caps applied as a shell prelude, shared by every real backend.
+//
+// Address-space capping (`ulimit -v`) is NOT enforced on the macOS family —
+// 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,
+  maxAddressSpaceKb = null,
+} = {}) {
+  const parts = [];
+  const unsupported = [];
+
+  if (maxProcs != null) parts.push(`ulimit -u ${_num('maxProcs', maxProcs)}`);
+  if (maxFileSizeKb != null) parts.push(`ulimit -f ${_num('maxFileSizeKb', maxFileSizeKb)}`);
+
+  if (maxAddressSpaceKb != null) {
+    if (process.platform === 'linux') parts.push(`ulimit -v ${_num('maxAddressSpaceKb', maxAddressSpaceKb)}`);
+    else unsupported.push('maxAddressSpaceKb');
+  }
+
+  const prelude = parts.length ? parts.join('; ') + '; ' : '';
+  return { prelude, unsupported };
+}
+
+/**
+ * Limit values are interpolated into a shell fragment, so a non-numeric value
+ * is shell text. Verified by execution: `maxProcs: '999; echo INJECTED'`
+ * emitted `ulimit -u 999; echo INJECTED` and the payload ran. That is not a
+ * sandbox escape (the prelude runs INSIDE the confinement) but it lets a
+ * config-derived value silently DISABLE the very limits it was meant to set —
+ * e.g. `'0 2>/dev/null; true'` swallows the failure. Coerce and reject
+ * anything that is not a finite, non-negative number.
+ */
+function _num(name, v) {
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new RangeError(`${name} must be a finite, non-negative number (got ${JSON.stringify(v)})`);
+  }
+  return Math.floor(n);
+}

package/src/sandbox/result.js

@@ -0,0 +1,104 @@
+// Shared result construction for every real backend.
+//
+// WHY THIS EXISTS (the misread it prevents): status used to be derived purely
+// from the exit code — `exitCode !== 0` was reported as `'blocked'`. That
+// conflates two entirely different outcomes:
+//
+//   1. A program that ran fine and chose to exit non-zero (a failing test, a
+//      grep with no match) was labelled 'blocked' — a false confinement claim.
+//   2. A program whose out-of-root write was DENIED but which still exited 0
+//      was labelled 'ok' — the caller saw a clean run and could not tell that
+//      the sandbox had refused something. Verified by execution: the denied
+//      write returns exit 0 when the command swallows the failure.
+//
+// So the two signals are now separated:
+//
+//   - `denied`  — a confinement violation was OBSERVED in the child's error
+//                 output. Best effort, see the honesty note below.
+//   - `status`  — 'blocked' when a denial was observed, 'nonzero' when the
+//                 command merely exited non-zero with no denial signal, 'ok'
+//                 only when it exited 0 with no denial signal.
+//
+// HONESTY NOTE — what `denied:false` does and does not mean. The denial signal
+// is read from the confined process's own stderr (the OS primitives here do
+// not hand the parent a structured violation channel). A program that writes
+// out of root and swallows its own error message produces NO signal, so
+// `denied:false` means "no denial was observed", NOT "no denial occurred".
+// Never treat `status:'ok'` as proof that nothing was refused. It is proof
+// only that the command exited 0 and said nothing about a refusal.
+
+const DENIAL_PATTERNS = [
+  /operation not permitted/i,
+  /permission denied/i,
+  /read-only file system/i,
+  /deny file-write/i,
+  /deny network/i,
+  /network is unreachable/i,
+];
+
+/** True iff the confined process's error output shows an observed denial. */
+export function detectDenial(stderr) {
+  const s = String(stderr || '');
+  return DENIAL_PATTERNS.some((re) => re.test(s));
+}
+
+/**
+ * Build the single result shape every backend returns. `status` is one of
+ * 'ok' | 'blocked' | 'nonzero' | 'timeout' | 'disabled' | 'error'.
+ */
+export function buildResult({ backend, spawnResult, unsupported = [] }) {
+  const r = spawnResult;
+  const rawStderr = r.stderr ?? '';
+  const timedOut = r.error?.code === 'ETIMEDOUT';
+  const denied = detectDenial(rawStderr);
+
+  let status;
+  if (timedOut) status = 'timeout';
+  else if (r.error) status = 'error';
+  else if (denied) status = 'blocked';
+  else if (r.status !== 0) status = 'nonzero';
+  else status = 'ok';
+
+  return {
+    status,
+    denied,
+    stdout: r.stdout ?? '',
+    stderr: rawStderr + (unsupported.length ? `\n[sandbox] not enforceable here: ${unsupported.join(', ')}` : ''),
+    exitCode: r.status ?? null,
+    timedOut,
+    backend,
+  };
+}
+
+/** Documented-shape error result: runConfined never throws at its callers. */
+export function errorResult(backend, message) {
+  return {
+    status: 'error',
+    denied: false,
+    stdout: '',
+    stderr: `agentic-security: ${message}`,
+    exitCode: null,
+    timedOut: false,
+    backend,
+  };
+}
+
+/**
+ * Minimal environment handed to untrusted code. The parent environment is NOT
+ * forwarded: it routinely carries credentials (tokens, cloud keys, registry
+ * auth) and the confined program can read and exfiltrate them. This is a
+ * distinct exposure from the accepted "reads are not confined" scope cut —
+ * that one is about files on disk, this one is about secrets the parent hands
+ * over for free. Callers that need extra variables pass them explicitly via
+ * `opts.env`, which is merged on top of this base.
+ */
+export function buildConfinedEnv({ root, env = {} } = {}) {
+  return {
+    PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
+    ROOT: root,
+    HOME: root,
+    TMPDIR: root,
+    LANG: 'C',
+    ...env,
+  };
+}

package/src/sca/dep-confusion.js

@@ -9,7 +9,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 import { createRequire } from 'node:module';
 
 const _require = createRequire(import.meta.url);

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;
+}

package/src/util/yaml.js

@@ -0,0 +1,24 @@
+// Thin wrapper over js-yaml.
+//
+// js-yaml 5 throws on empty input ("expected a document, but the input is
+// empty") where 4.x returned undefined. Every YAML file this scanner reads is
+// user-authored config — .agentic-security/rules.yml, suppressions.yml,
+// profiles, policies — and an empty or fully commented-out config is a normal,
+// intentional state, not an error. Without this shim a blank rules.yml prints a
+// spurious parse error on every scan.
+//
+// Import this instead of js-yaml directly anywhere config is read.
+import * as _yaml from 'js-yaml';
+
+/** Parse YAML, returning undefined for blank/comment-only input (4.x behaviour). */
+export function load(text, opts) {
+  if (typeof text !== 'string') return undefined;
+  // A document that is only whitespace and/or comments has no content. js-yaml
+  // 4 returned undefined here; preserve that rather than surfacing a throw.
+  const stripped = text.replace(/^\s*#.*$/gm, '').trim();
+  if (stripped === '') return undefined;
+  return _yaml.load(text, opts);
+}
+
+export const dump = _yaml.dump;
+export const CORE_SCHEMA = _yaml.CORE_SCHEMA;