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

package/src/sandbox/backend-userspace.js

@@ -0,0 +1,100 @@
+// Userspace confinement backend (macOS family). Applies a deny-by-default
+// policy profile: reads allowed, writes confined to the sandbox root, no
+// network egress unless explicitly opted in.
+//
+// TIMEOUT SCOPE — read before trusting `status:'timeout'`. The wall-clock
+// timeout is `spawnSync`'s, which signals only the DIRECT child. Verified by
+// execution on this platform: with `timeoutMs: 1200`, a command that
+// backgrounded a 4-second child returned `status:'timeout'` while the
+// grandchild survived the timeout and completed its work afterwards. So
+// 'timeout' means "we stopped waiting and killed the process we spawned", NOT
+// "the process tree was terminated". Anything left running is still inside the
+// policy profile (its writes and network stay confined), but it is still
+// running. Callers that need a hard tree kill must supply it themselves.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { resolveUserspaceBin } from './capabilities.js';
+import { buildLimitPrelude } 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)',
+    '(deny default)',
+    '(allow process-exec process-fork)',
+    '(allow sysctl-read)',
+    '(allow file-read*)',
+    '(allow file-write* (subpath (param "ROOT")))',
+    allowNetwork ? '(allow network*)' : '',
+  ].filter(Boolean).join('\n');
+}
+
+export function runUserspace(argv, {
+  root,
+  timeoutMs = 10000,
+  allowNetwork = false,
+  limits = {},
+  env = {},
+  maxBuffer = 8 * 1024 * 1024,
+} = {}) {
+  // Documented shape, never a throw: a caller that wraps this in try/catch and
+  // "falls back" is a classic route to unconfined execution.
+  if (!root) return errorResult('userspace', 'runUserspace requires a sandbox root');
+
+  const bin = resolveUserspaceBin();
+  if (!bin) return errorResult('userspace', 'no userspace confinement binary found on this host');
+
+  let resolvedRoot;
+  try {
+    // Resolve symlinks (e.g. macOS /var -> /private/var) so the profile's
+    // subpath param matches the path the kernel actually sees.
+    resolvedRoot = fs.realpathSync(root);
+  } catch (e) {
+    return errorResult('userspace', `sandbox root is not usable: ${e.message}`);
+  }
+
+  const effectiveLimits = {
+    ...limits,
+    maxProcs: limits.maxProcs ?? (_ambientProcCount() + 64),
+  };
+
+  let prelude, unsupported;
+  try {
+    ({ prelude, unsupported } = buildLimitPrelude(effectiveLimits));
+  } catch (e) {
+    return errorResult('userspace', `invalid resource limit: ${e.message}`);
+  }
+  const inner = `${prelude}exec "$@"`;
+
+  const r = spawnSync(
+    bin,
+    ['-p', _profile({ allowNetwork }), '-D', `ROOT=${resolvedRoot}`,
+     '/bin/sh', '-c', inner, '_sbx', ...argv],
+    {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer,
+      cwd: resolvedRoot,
+      env: buildConfinedEnv({ root: resolvedRoot, env }),
+    },
+  );
+
+  return buildResult({ backend: 'userspace', spawnResult: r, unsupported });
+}

package/src/sandbox/capabilities.js

@@ -0,0 +1,53 @@
+// 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.
+import fs from 'node:fs';
+
+// Referenced by path, never by product name (see Global Constraints).
+//
+// Each family lists every plausible install location, probed in order. A
+// single hardcoded path is safe (a miss fails closed to 'disabled') but it is
+// a FALSE NEGATIVE: a host that does have the primitive somewhere else loses
+// the sandbox silently. Probing the candidate set removes that failure mode.
+export const CONFINE_BINS_USERSPACE = Object.freeze([
+  '/usr/bin/sandbox-exec',
+  '/usr/local/bin/sandbox-exec',
+]);
+export const CONFINE_BINS_NAMESPACE = Object.freeze([
+  '/usr/bin/unshare',
+  '/bin/unshare',
+  '/usr/local/bin/unshare',
+  '/sbin/unshare',
+  '/usr/sbin/unshare',
+]);
+
+// 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; }
+
+/** First executable candidate, or null when none of them exists. */
+export function resolveConfineBin(candidates) {
+  for (const p of candidates) if (_isExecutable(p)) return p;
+  return null;
+}
+
+export function resolveUserspaceBin() { return resolveConfineBin(CONFINE_BINS_USERSPACE); }
+export function resolveNamespaceBin() { return resolveConfineBin(CONFINE_BINS_NAMESPACE); }
+
+export function detectBackend({ force } = {}) {
+  if (force) return force;
+  if (_cached) return _cached;
+  let b = 'disabled';
+  if (process.platform === 'darwin' && resolveUserspaceBin()) b = 'userspace';
+  else if (process.platform === 'linux' && resolveNamespaceBin()) b = 'namespace';
+  _cached = b;
+  return b;
+}
+
+function _isExecutable(p) {
+  try { fs.accessSync(p, fs.constants.X_OK); return true; } catch { return false; }
+}

package/src/sandbox/index.js

@@ -0,0 +1,30 @@
+// Single entry point for confined execution.
+//
+// Fail-closed by construction: when no confinement primitive is available the
+// disabled backend is selected, which REFUSES to execute. There is deliberately
+// no code path that runs target code unconfined.
+//
+// Result shape (identical for every backend):
+//   { status, denied, stdout, stderr, exitCode, timedOut, backend }
+// status: 'ok' | 'blocked' | 'nonzero' | 'timeout' | 'disabled' | 'error'.
+// See result.js for what 'blocked' vs 'nonzero' mean and, importantly, what
+// `denied:false` does NOT prove. runConfined never throws — a bad root or an
+// invalid limit returns status 'error', because a caller that catches and
+// falls back is a route to unconfined execution.
+import { detectBackend } from './capabilities.js';
+import { runDisabled } from './backend-disabled.js';
+import { runUserspace } from './backend-userspace.js';
+import { runNamespace } from './backend-namespace.js';
+
+export { detectBackend, resetCapabilityCache } from './capabilities.js';
+
+export function sandboxAvailable() {
+  return detectBackend() !== 'disabled';
+}
+
+export function runConfined(argv, opts = {}) {
+  const backend = detectBackend({ force: opts.force });
+  if (backend === 'userspace') return runUserspace(argv, opts);
+  if (backend === 'namespace') return runNamespace(argv, opts);
+  return runDisabled(argv, opts);
+}

package/src/sandbox/limits.js

@@ -0,0 +1,42 @@
+// 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.
+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] limits 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/untrusted.js

@@ -0,0 +1,148 @@
+// Untrusted-content hardening primitives (addition #4: meta-security —
+// self-hardening the agent surface).
+//
+// Attacker-authored code and finding text reach several LLM prompts, several
+// rendered outputs (issue / PR / ticket bodies), and audit writers. This module
+// is the single, tested place that neutralizes that content before it crosses a
+// trust boundary. See docs/AGENT_THREAT_MODEL.md for the path→CWE map.
+//
+// Design notes:
+//   - Pure + dependency-light (node:crypto, node:fs only). No network, no state.
+//   - Fail-closed: unknown/adversarial input degrades to the safe value ('' or
+//     `false`), never throws.
+//   - Deterministic: fenceUntrusted derives its nonce from the content hash so
+//     the wrapping is reproducible and testable (no Date.now / random source).
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ─── escapeMarkdown ──────────────────────────────────────────────────────────
+// Neutralize markdown/HTML control characters so attacker-controlled finding
+// text cannot inject markup, links, or code spans when interpolated into an
+// issue / PR / ticket body. HTML-dangerous chars (& < >) are entity-encoded so
+// no raw tag can render in any markdown flavour; markdown-structural chars
+// (backtick [ ] ! and backslash) are backslash-escaped.
+//
+// Non-strings collapse to '' (fail-closed — a null vuln never becomes "null").
+//
+// Order is load-bearing: escape `&` before we emit `&amp;`/`&lt;`/`&gt;`, and
+// escape literal `\` before we introduce our own backslashes, so nothing is
+// double-consumed.
+export function escapeMarkdown(s) {
+  if (typeof s !== 'string') return '';
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\\/g, '\\\\')
+    .replace(/`/g, '\\`')
+    .replace(/\[/g, '\\[')
+    .replace(/\]/g, '\\]')
+    .replace(/!/g, '\\!');
+}
+
+// ─── fenceUntrusted ──────────────────────────────────────────────────────────
+// Wrap untrusted text in a clearly-delimited block whose delimiter carries a
+// per-call nonce, so an injected close-delimiter inside the text cannot
+// terminate the fence early (the classic prompt-injection "break out of the
+// data block" move). Intended for the LLM-prompt paths (triage / dedup / fix)
+// where the model must treat the wrapped span as inert data.
+//
+// The nonce is derived deterministically from a sha256 of the content (first 8
+// hex). That makes it (a) reproducible/testable and (b) unguessable by the
+// author of the content — an attacker cannot pre-compute the resulting nonce to
+// forge a matching close-delimiter, because the nonce depends on the very bytes
+// they would have to write.
+//
+// Returns { text, nonce }.
+export function fenceUntrusted(s, label = 'untrusted') {
+  const content = typeof s === 'string' ? s : '';
+  const lbl = String(label || 'untrusted').replace(/[^A-Za-z0-9_-]/g, '');
+  const nonce = createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 8);
+  const open = `<<BEGIN ${lbl} ${nonce}>>`;
+  const close = `<<END ${lbl} ${nonce}>>`;
+  return { text: `${open}\n${content}\n${close}`, nonce };
+}
+
+// ─── isAllowedFetchHost ──────────────────────────────────────────────────────
+// Guard for any outbound fetch whose URL can be influenced by untrusted finding
+// data (e.g. a metadata/advisory URL lifted from a dependency manifest). Blocks
+// SSRF against link-local / loopback / RFC1918 targets AND enforces an explicit
+// allowlist — a host must be BOTH non-internal AND on the allowlist. Empty
+// allowlist ⇒ nothing passes (fail-closed). Malformed URL ⇒ false.
+export function isAllowedFetchHost(url, allowlist = []) {
+  let host;
+  try {
+    host = new URL(String(url)).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  if (!host) return false;
+  // Strip IPv6 brackets: "[::1]" → "::1".
+  const h = host.replace(/^\[/, '').replace(/\]$/, '');
+
+  // Block internal / link-local / loopback destinations up front — these must
+  // never be reachable even if an operator mistakenly allowlists one.
+  if (h === 'localhost' || h.endsWith('.localhost')) return false;
+  if (h === '::1' || h === '0.0.0.0') return false;
+  if (h === '169.254.169.254' || h.startsWith('169.254.')) return false; // link-local + cloud metadata
+  if (h.startsWith('127.')) return false;                                 // loopback /8
+  if (h.startsWith('10.')) return false;                                  // RFC1918 /8
+  if (h.startsWith('192.168.')) return false;                            // RFC1918 /16
+  const m172 = h.match(/^172\.(\d{1,3})\./);                              // RFC1918 172.16-31/12
+  if (m172) {
+    const oct = Number(m172[1]);
+    if (oct >= 16 && oct <= 31) return false;
+  }
+
+  const allow = Array.isArray(allowlist)
+    ? allowlist.map((a) => String(a).toLowerCase())
+    : [];
+  if (allow.length === 0) return false; // fail-closed: no allowlist ⇒ deny all
+  return allow.includes(h);
+}
+
+// ─── redactSecrets ───────────────────────────────────────────────────────────
+// Mask token-shaped substrings before finding-adjacent text is written to an
+// audit log or handed to an LLM. The provider/scheme prefix is preserved so a
+// human triager can still tell WHAT kind of credential leaked without seeing
+// its value. Non-strings collapse to ''.
+const _REDACTED = '***REDACTED***';
+export function redactSecrets(s) {
+  if (typeof s !== 'string') return '';
+  return s
+    // URL basic-auth: scheme://user:password@ → keep user, mask password.
+    .replace(/(\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:)[^\s@/]+@/gi, `$1${_REDACTED}@`)
+    // Authorization: Bearer <token>
+    .replace(/\b(Authorization\s*:\s*Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, `$1${_REDACTED}`)
+    // ?access_token= / &token= / ?token= / &access_token=
+    .replace(/([?&](?:access_token|token)=)[^&\s#]+/gi, `$1${_REDACTED}`)
+    // Raw provider token prefixes (GitHub PATs, Anthropic keys). Keep prefix.
+    .replace(/\b(ghp_|gho_|ghu_|ghs_|github_pat_|sk-ant-)[A-Za-z0-9_-]+/g, `$1${_REDACTED}`);
+}
+
+// ─── secure filesystem writes ────────────────────────────────────────────────
+// Audit logs, scan state, and any file that may carry finding text or secrets
+// must be owner-only. openSync's mode argument is still masked by the process
+// umask, so writeSecure ALSO chmods explicitly — the file is 0600 regardless of
+// the ambient umask. secureDirMode is the matching 0700 for any parent dir we
+// have to create.
+export const secureFileMode = 0o600;
+export const secureDirMode = 0o700;
+
+export function writeSecure(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: secureDirMode });
+    try { fs.chmodSync(dir, secureDirMode); } catch { /* best-effort */ }
+  }
+  const fd = fs.openSync(filePath, 'w', secureFileMode);
+  try {
+    fs.writeSync(fd, typeof data === 'string' ? data : String(data ?? ''));
+  } finally {
+    fs.closeSync(fd);
+  }
+  // Force the mode down even if umask loosened it at creation time.
+  fs.chmodSync(filePath, secureFileMode);
+  return filePath;
+}

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;