@clear-capabilities/agentic-security-scanner 0.162.0 → 0.163.1

package/src/capabilities/runner.js

@@ -0,0 +1,236 @@
+// The capability runner (X-502, X-503, X-504): where a manifest stops being a
+// description and becomes a boundary.
+//
+// `runCapabilityTask(bound, request, opts)` executes ONE structured command (an
+// absolute executable plus an argument array, never a shell string) for one
+// bound task, and what it can touch is decided by the operating system, not by
+// this file or by a hook:
+//
+//   filesystem  reads are confined to the declared roots (plus the handful of
+//               system paths a process needs to start), writes to the declared
+//               write roots and a private per-run scratch directory, protected
+//               host paths are read-denied on top; a symbolic link or `..` that
+//               leaves the roots is stopped by the kernel
+//   commands    the executable and arguments are checked against the manifest
+//               first (decide.js); the argument array reaches `exec` as an array,
+//               so command substitution and expansion in an argument stay text;
+//               shells, language runtimes and launchers are refused unless the
+//               manifest declares them scoped with their exact arguments
+//   network     no network at all unless the manifest declares destinations; then
+//               exactly one door, the loopback mediation proxy (proxy.js); the
+//               proxy settings are in the environment of the whole process tree,
+//               and a socket opened any other way is refused by the kernel
+//   descendants inherit all of the above (the confinement is inherited by every
+//               child), are tracked, and are terminated on deadline,
+//               cancellation, output flood or exit, with the evidence returned
+//
+// Gate, in order, each step typed and none of them a warning:
+//   1. the `capability-enforcement` feature (operator-only: a project file cannot
+//      turn it on), then the kill switches
+//   2. the platform: only an advertised backend is `enforced`. A backend that is
+//      not advertised (macOS) is `unsupported` for isolation-required tasks
+//      unless the caller opts in with `allowUnadvertisedBackend`, in which case
+//      the run is labelled `host-proved` and nothing is claimed enforced
+//   3. the binding, the secret-free environment, the command policy, protected
+//      paths
+//   4. the active probes: any control the manifest depends on that is not
+//      `proved` BLOCKS the run, and the target is never executed
+//
+// Incomplete backend controls block; they are never a warning and never a quiet
+// fallback to less. On Linux the namespace backend does not implement the
+// controls this needs yet, so every Linux run is blocked with the missing control
+// named, and the platform statement says `unverified`.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveAssuranceConfig, featureStatus, typed, limitValues } from '../posture/assurance/config.js';
+import { detectBackend } from '../sandbox/capabilities.js';
+import { runConfinedSupervised } from '../sandbox/supervise.js';
+import { protectedReadPaths, assertNoSecretMaterial } from '../sandbox/trust-domains.js';
+import { mediate } from './recovery.js';
+import { reasonText } from './reasons.js';
+import { canonicalPath, overlaps } from './paths.js';
+import { probeCapabilityControls, requiredControlsFor, unmetControls, isAdvertisedBackend } from './probes.js';
+import { startMediationProxy } from './proxy.js';
+import { sanitizeLogText } from './outbound.js';
+import { toCapabilityDecisionRecord } from './records.js';
+import { buildCapabilityReport } from './report.js';
+
+const FEATURE = 'capability-enforcement';
+
+function blocked(code, reason, extra = {}) {
+  return typed('blocked', code, reason, { executed: false, outcome: 'not-run', ...extra });
+}
+
+// X-506: a denial carries the missing capability and a reviewable proposed manifest
+// change. The proposal is data for an operator; nothing here applies it.
+function denied(m, extra = {}) {
+  const d = m.decision;
+  return blocked('capability-denied', `${d.code}: ${d.reason}`, {
+    policyCode: d.code, decisions: [d], missing: m.missing, proposal: m.proposal,
+    attemptsRemaining: m.attemptsRemaining, exhausted: m.exhausted, ...extra,
+  });
+}
+
+function scrub(text, canaries) {
+  return sanitizeLogText(text, canaries);
+}
+
+/**
+ * @param {{manifest: object, binding: object}} bound  from `bindManifest`
+ * @param {{executable: string, args?: string[], env?: object, cwd?: string}} request
+ * @param {object} opts
+ * @param {{taskId:string, revision:string, policyVersion:number}} opts.binding  the identity the caller acts for
+ * @param {object} [opts.config]   resolved assurance config; default resolves from `opts.scanRoot` and the environment
+ * @param {string} [opts.scanRoot]
+ * @param {string[]} [opts.labelDirs]    sealed-label directories (never readable by the task)
+ * @param {string[]} [opts.evidenceDirs] authoritative-evidence directories (never readable by the task)
+ * @param {string[]} [opts.protectedPaths] further paths the task may never read
+ * @param {string[]} [opts.canaries]     values that must not appear in arguments, environment, outbound payloads or returned output
+ * @param {boolean} [opts.allowUnadvertisedBackend] run on a host-proved, non-advertised backend (development)
+ * @param {AbortSignal} [opts.signal]
+ * @param {string} [opts.force]          backend override (tests: 'disabled')
+ * @param {object} [opts.controlProbes]  probe overrides (test seam)
+ * @param {(host:string)=>Promise<string[]>} [opts.resolve] name resolution seam for the proxy
+ * @param {string} [opts.home]           home directory whose credential directories are protected
+ * @param {object} [opts.denialGuard]    from recovery.js `createDenialGuard`: bounds repeated denials of one action (X-506.AC03)
+ */
+export async function runCapabilityTask(bound, request, opts = {}) {
+  const {
+    binding, scanRoot = null, labelDirs = [], evidenceDirs = [], protectedPaths: extraProtected = [], canaries = [],
+    allowUnadvertisedBackend = false, signal, force, controlProbes, resolve, home, denialGuard,
+  } = opts;
+
+  if (!request || typeof request !== 'object') return blocked('invalid-config', 'no task request');
+
+  // 1. feature gate
+  const config = opts.config || resolveAssuranceConfig({ scanRoot: scanRoot || undefined });
+  const gate = featureStatus(config, FEATURE);
+  let platformOptIn = false;
+  if (gate.status === 'unsupported' && gate.code === 'platform-unsupported' && allowUnadvertisedBackend) platformOptIn = true;
+  else if (gate.status !== 'ok') return { ...gate, executed: false, outcome: 'not-run' };
+
+  if (!bound?.manifest || !bound?.binding) return blocked('invalid-config', 'no bound capability manifest');
+  const ctx = { binding, canaries, protectedPaths: [] };
+
+  // 3a. a secret-free environment, before anything else looks at the request
+  const env = request && typeof request.env === 'object' && request.env ? request.env : {};
+  const secrets = assertNoSecretMaterial(env);
+  if (!secrets.ok) return blocked('capability-denied', `secret-looking environment variables are refused for tasks: ${secrets.offenders.join(', ')}`, { policyCode: 'secret-in-argument' });
+  for (const [k, v] of Object.entries(env)) {
+    if (typeof v !== 'string') return blocked('capability-denied', `environment variable ${k} is not a string`, { policyCode: 'args-invalid' });
+    if (canaries.some((c) => c && String(v).includes(c))) return blocked('capability-denied', `environment variable ${k} carries a registered canary`, { policyCode: 'secret-in-argument' });
+  }
+
+  // 3b. command policy (also checks the binding)
+  const protectedPaths = protectedReadPaths({ ...(home ? { home } : {}), labelDirs, evidenceDirs, extra: extraProtected });
+  ctx.protectedPaths = protectedPaths;
+  const cmdM = mediate(bound, { kind: 'command', executable: request?.executable, args: request?.args ?? [] }, ctx, { guard: denialGuard });
+  const cmd = cmdM.decision;
+  if (cmdM.status !== 'ok') return denied(cmdM);
+
+  // 3c. the manifest's own roots may not contain protected paths
+  const m = bound.manifest;
+  const roots = [...m.filesystem.read, ...m.filesystem.write];
+  for (const r of roots) {
+    const cr = canonicalPath(r) ?? r;
+    const clash = protectedPaths.find((p) => overlaps(cr, canonicalPath(p) ?? p));
+    if (clash) return blocked('capability-denied', `protected-path: ${reasonText('protected-path')}`, { policyCode: 'protected-path', decisions: [] });
+  }
+  let cwdRequest = null;
+  if (request.cwd !== undefined) {
+    const cwdM = mediate(bound, { kind: 'filesystem-read', path: request.cwd }, ctx, { guard: denialGuard });
+    if (cwdM.status !== 'ok') return denied(cwdM);
+    cwdRequest = request.cwd;
+  }
+
+  // 2/4. backend and active probes
+  const backend = detectBackend({ force });
+  if (backend === 'disabled') {
+    return typed('blocked', 'missing-execution-backend', 'no confinement backend works on this host; the task was not executed', { executed: false, outcome: 'not-run', backend });
+  }
+  const advertised = isAdvertisedBackend(backend);
+  if (!advertised && !allowUnadvertisedBackend) {
+    return typed('unsupported', 'platform-unsupported',
+      `the ${backend} backend on ${process.platform} is not an advertised backend for enforced capability tasks; isolation-required tasks are unsupported here`,
+      { executed: false, outcome: 'not-run', backend });
+  }
+  const probeReport = await probeCapabilityControls({ force, probes: controlProbes || {} });
+  const required = requiredControlsFor(m);
+  const unmet = unmetControls(probeReport, required);
+  if (unmet.length) {
+    return typed('blocked', 'missing-execution-backend',
+      `incomplete backend controls block the task: ${unmet.map((u) => `${u.control} is ${u.state}`).join('; ')}`,
+      {
+        executed: false, outcome: 'not-run', backend, unmet,
+        report: buildCapabilityReport({ bound, probeReport, level: 'none', required }),
+      });
+  }
+  const level = advertised ? 'enforced' : 'host-proved';
+
+  // 5. build the confinement and run
+  const scratch = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'agsec-cap-run-')));
+  let proxy = null;
+  try {
+    const exeReal = fs.realpathSync(request.executable);
+    const limits = limitValues(config);
+    const timeoutMs = m.resources.timeoutMs ?? limits.timeoutMs;
+    const maxOutputBytes = m.resources.maxOutputBytes ?? limits.maxOutputBytes;
+    const taskEnv = { ...env };
+    if (m.network.length) {
+      proxy = await startMediationProxy({ bound, canaries, resolve, scanRoot });
+      for (const k of ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy', 'ALL_PROXY', 'all_proxy']) taskEnv[k] = proxy.url;
+      taskEnv.NO_PROXY = ''; taskEnv.no_proxy = '';
+    }
+    const cwd = cwdRequest || (m.filesystem.write[0] ?? scratch);
+    const r = await runConfinedSupervised([request.executable, ...(request.args ?? [])], {
+      root: scratch, cwd,
+      readRoots: [...m.filesystem.read, ...m.filesystem.write, exeReal],
+      writeRoots: m.filesystem.write,
+      denyReadPaths: protectedPaths,
+      env: taskEnv, networkProxyPort: proxy ? proxy.port : null,
+      timeoutMs, graceMs: 1000, maxOutputBytes, signal, force,
+      limits: m.resources.maxFileSizeKb ? { maxFileSizeKb: m.resources.maxFileSizeKb } : {},
+    });
+    const executed = r.supervised === true;
+    if (!executed) {
+      return typed('blocked', 'missing-execution-backend', `the confined run could not start: ${scrub(String(r.stderr || '').split('\n')[0], canaries)}`, {
+        executed: false, outcome: 'not-run', backend, report: buildCapabilityReport({ bound, probeReport, level: 'none', required }),
+      });
+    }
+    const term = r.termination || { signalled: null, killedPids: [], survivors: [] };
+    let outcome = 'exited';
+    if (r.cancelled) outcome = 'cancelled';
+    else if (r.timedOut) outcome = 'timeout';
+    else if (r.outputCapped) outcome = 'output-limit';
+    const cleanup = { signalled: term.signalled, killedPids: [...term.killedPids], survivors: [...term.survivors], complete: term.survivors.length === 0 };
+    const report = buildCapabilityReport({ bound, probeReport, level, required });
+    const enforced = level === 'enforced';
+    const mk = (d, mediation) => toCapabilityDecisionRecord(d, { mediation, enforced, backend, probeDigest: probeReport.probeDigest });
+    const records = [mk(cmd, 'runner')];
+    for (const root of m.filesystem.read) records.push(mk({ ...cmd, kind: 'filesystem-read', subject: root }, 'runner'));
+    for (const root of m.filesystem.write) records.push(mk({ ...cmd, kind: 'filesystem-write', subject: root }, 'runner'));
+    if (proxy) {
+      for (const n of proxy.records) {
+        records.push(mk({
+          kind: 'network', decision: n.outcome, code: n.code, reason: reasonText(n.code), taskId: m.taskId,
+          subject: `${n.scheme ?? 'unknown'}://${n.destinationClass}#${n.hostDigest}:${n.port ?? 0}`,
+        }, 'proxy'));
+      }
+    }
+    const status = cleanup.complete ? 'ok' : 'degraded';
+    return typed(status, cleanup.complete ? null : 'limit-exceeded',
+      cleanup.complete ? `ran under ${level} confinement (${backend})` : 'processes survived termination', {
+        executed: true, outcome, level, enforced, backend, exitCode: r.exitCode, denied: r.denied === true,
+        timedOut: r.timedOut === true, cancelled: r.cancelled === true, outputCapped: r.outputCapped === true,
+        // Everything the task printed is data from an untrusted party.
+        output: { trust: 'untrusted', stdout: scrub(r.stdout, canaries), stderr: scrub(r.stderr, canaries) },
+        cleanup, decisions: [cmd], capabilityDecisions: records.filter((x) => x.ok).map((x) => x.record),
+        network: proxy ? { records: [...proxy.records], stats: { ...proxy.stats } } : null,
+        report,
+      });
+  } finally {
+    if (proxy) await proxy.close();
+    try { fs.rmSync(scratch, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}

package/src/capabilities/secrets.js

@@ -0,0 +1,26 @@
+// One secret scrubber for the capability layer: provider-shaped credentials
+// (mcp/redact.js, which is the list the scanner's own detector mirrors), then
+// assignment, bearer, connection-string and high-entropy-literal shapes
+// (llm-validator/redact.js). Pure. The count is of replacements made, so a
+// caller can ask "did this text carry a secret" without keeping the secret.
+import { redactSecretShapes } from '../mcp/redact.js';
+import { redactSecrets } from '../llm-validator/redact.js';
+
+/**
+ * True when the text carries a provider-shaped credential or a quoted credential
+ * assignment. The high-entropy-literal heuristic is deliberately NOT used here:
+ * an argument list is mostly paths and scripts, and refusing every long quoted
+ * path would make the policy unusable. Scrubbing for output and logs (below) is
+ * allowed to be broader than refusing an argument.
+ */
+export function detectSecretShapes(text) {
+  return typeof text === 'string' && redactSecretShapes(text).redactions > 0;
+}
+
+export function scrubSecretText(text) {
+  if (typeof text !== 'string' || !text) return { text: typeof text === 'string' ? text : '', redactions: 0 };
+  const a = redactSecretShapes(text);
+  let b;
+  try { b = redactSecrets(a.text); } catch { return { text: '[unprintable]', redactions: a.redactions + 1 }; }
+  return { text: b.text, redactions: a.redactions + b.redactions };
+}

package/src/capabilities/tool-gate.js

@@ -0,0 +1,119 @@
+// The MCP tool gate (X-505.AC01, X-505.AC03).
+//
+// Every tool call is checked against the SAME decision function the runner and
+// the hooks use (`decide`), for the CURRENT task identity, before its handler
+// runs. The identity is the one the operator bound to the server; nothing the
+// calling agent sends can change it: tool arguments are closed schemas, and an
+// identity named in the request metadata is compared with the bound one and
+// refused when it differs (`identity-spoofed`).
+//
+//   no policy, feature off   the gate is inactive: behaviour is exactly what it
+//                            was before this module existed
+//   feature on, no policy    read tools pass; a mutating or externally
+//                            communicating tool is refused (`identity-missing`),
+//                            because there is no task to check it for
+//   policy bound             every tool is checked: it must be a declared tool
+//                            action (deny by default), a mutating one must also
+//                            have the session root inside a declared write root,
+//                            and a tool missing from the classification table is
+//                            refused (`tool-unclassified`)
+//
+// A denial is synchronous and final for that call: no prompt, no waiting, no
+// retry inside the gate. It carries the missing capability and a reviewable
+// proposed change (recovery.js); repeated denials hit the finite limit there.
+//
+// This is POLICY at the tool boundary. The tool then runs in the MCP server
+// process, so the decision is recorded as `in-process-policy` and never
+// `enforced`; the runner is the only enforcement layer.
+import { resolveAssuranceConfig } from '../posture/assurance/config.js';
+import { reasonText, sanitizeSubject } from './reasons.js';
+import { toolCapabilityFor, isMutatingOrExternal } from './tool-registry.js';
+import { mediate, createDenialGuard } from './recovery.js';
+import { toCapabilityDecisionRecord } from './records.js';
+
+const FEATURE = 'capability-enforcement';
+const MAX_KEPT = 500;
+
+function synthetic(bound, kind, code, subject) {
+  return Object.freeze({
+    decision: 'deny', code, reason: reasonText(code), kind, subject: sanitizeSubject(subject),
+    taskId: bound?.binding?.taskId ?? null, manifestDigest: bound?.binding?.digest ?? null,
+  });
+}
+
+/** Whether the OPERATOR enabled the feature (environment only; a project file can never enable it). */
+export function featureEnabledByOperator(env = process.env) {
+  try { return resolveAssuranceConfig({ env }).features?.[FEATURE]?.enabled === true; } catch { return false; }
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.sessionRoot
+ * @param {{bound: object, binding: object}|null} [o.policy]  the task's bound manifest and the identity it acts for
+ * @param {object} [o.guard]    denial guard (default: a fresh one with the default limits)
+ * @param {object} [o.env]
+ */
+export function createToolGate({ sessionRoot, policy = null, guard, env = process.env } = {}) {
+  let current = policy && policy.bound && policy.binding ? { bound: policy.bound, binding: policy.binding } : null;
+  const denialGuard = guard || createDenialGuard();
+  const kept = [];
+
+  function record(decision) {
+    const r = toCapabilityDecisionRecord(decision, { mediation: 'in-process-policy', enforced: false, backend: null });
+    if (r.ok) { kept.push(r.record); if (kept.length > MAX_KEPT) kept.shift(); }
+    return r.ok ? r.record : null;
+  }
+
+  function refused(d) {
+    return Object.freeze({
+      allowed: false, blocked: true, code: d.code, reason: d.reason, decision: d,
+      missing: Object.freeze({ capability: 'tool', code: d.code, detail: d.subject }),
+      proposal: null, attemptsRemaining: null, exhausted: false, record: record(d),
+    });
+  }
+
+  function blockedResult(m, extra = {}) {
+    return Object.freeze({
+      allowed: false, blocked: true, code: m.decision.code, reason: m.decision.reason, decision: m.decision, missing: m.missing,
+      proposal: m.proposal, attemptsRemaining: m.attemptsRemaining, exhausted: m.exhausted, record: record(m.decision), ...extra,
+    });
+  }
+
+  const self = {
+    /** The gate is active when a policy is bound or the operator turned the feature on. */
+    active: () => current !== null || featureEnabledByOperator(env),
+    hasPolicy: () => current !== null,
+    /** Operator-side: replace the bound policy (a new policy version, a different task). Stale bindings are then refused. */
+    update(next) { current = next && next.bound && next.binding ? { bound: next.bound, binding: next.binding } : null; },
+    decisions: () => kept.slice(),
+    guard: denialGuard,
+
+    /**
+     * @param {string} name   the tool the agent asked for
+     * @param {{claimedTaskId?: string}} [req]   identity claimed in the request, if any
+     */
+    check(name, { claimedTaskId } = {}) {
+      if (!self.active()) return Object.freeze({ allowed: true, skipped: true, decision: null });
+      if (!current) {
+        if (!isMutatingOrExternal(name)) return Object.freeze({ allowed: true, skipped: true, decision: null });
+        return refused(synthetic(null, 'tool', 'identity-missing', String(name)));
+      }
+      const { bound, binding } = current;
+      if (claimedTaskId !== undefined && claimedTaskId !== binding.taskId) {
+        return refused(synthetic(bound, 'tool', 'identity-spoofed', `${String(name)} (claimed task ${sanitizeSubject(claimedTaskId, 60)})`));
+      }
+      const cap = toolCapabilityFor(name);
+      if (!cap) return refused(synthetic(bound, 'tool', 'tool-unclassified', String(name)));
+      const ctx = { binding };
+      const decisions = [];
+      for (const req of cap.requires) {
+        const action = req === 'tool' ? { kind: 'tool', tool: name } : { kind: 'filesystem-write', path: sessionRoot };
+        const m = mediate(bound, action, ctx, { guard: denialGuard });
+        if (m.status !== 'ok') return blockedResult(m, { checked: decisions.length });
+        decisions.push(m.decision); record(m.decision);
+      }
+      return Object.freeze({ allowed: true, skipped: false, decision: decisions[0], decisions });
+    },
+  };
+  return Object.freeze(self);
+}

package/src/capabilities/tool-registry.js

@@ -0,0 +1,60 @@
+// The capability classification of every registered MCP tool (X-505.AC01).
+//
+// A tool that writes, runs a project command or reaches the network must say so,
+// and the gate (tool-gate.js) checks what it declares before the handler runs. A
+// tool that is not in this table is refused when the gate is active
+// (`tool-unclassified`), so adding a tool to the MCP registry without classifying
+// it fails closed and fails a test (test/capabilities/tools.test.js compares this
+// table with the registry in both directions).
+//
+//   effect    'read'      reads local state only
+//             'mutating'  writes project or agent state, or runs project code
+//             'external'  reaches, or may reach, the network through a package
+//                         manager or another tool the server process runs
+//   requires  the capability checks made before the handler:
+//               'tool'               the tool is a declared tool action
+//               'write:sessionRoot'  the session root is inside a declared write root
+//
+// What this table does NOT do: it does not route a tool's own file or network
+// activity through the capability runner. A tool runs in the MCP server process;
+// the decision is made at the tool boundary, so it is policy (`in-process-policy`),
+// never enforced isolation, and the report says so.
+const read = (note) => Object.freeze({ effect: 'read', requires: Object.freeze(['tool']), note });
+const mutating = (note, extra = []) => Object.freeze({ effect: 'mutating', requires: Object.freeze(['tool', 'write:sessionRoot', ...extra]), note });
+const external = (note, extra = []) => Object.freeze({ effect: 'external', requires: Object.freeze(['tool', ...extra]), note });
+
+export const TOOL_CAPABILITIES = Object.freeze({
+  scan_diff: read('scans files in memory'),
+  query_taint: read('reads the last verified scan'),
+  explain_finding: read('reads the last verified scan'),
+  find_rule_module: read('reads scanner source names'),
+  read_scratchpad: read('reads the agent scratchpad'),
+  read_agents_memory: read('reads the continual-learning file'),
+  lookup_cve: read('reads the local advisory caches'),
+  query_triage_memory: read('reads past triage decisions'),
+  query_findings_memory: read('reads accumulated scan memory'),
+  query_cache_telemetry: read('reads the session transcript statistics'),
+  synthesize_fix: read('returns a stored patch'),
+  dataflow_get_graph: read('reads the signed graph artifact'),
+  dataflow_get_node: read('reads the signed graph artifact'),
+  dataflow_get_edge: read('reads the signed graph artifact'),
+  dataflow_get_flow: read('reads the signed graph artifact'),
+  invariant_scenario_export: read('builds a read-only scenario export from a supplied contract, confined to the session root'),
+  portfolio_progress: read('builds a read-only progress view from a portfolio store, ledger and optional inputs, confined to the session root'),
+  apply_fix: mutating('writes verified patches into the project'),
+  verify_fix: mutating('runs the project linter and tests and appends fix metrics'),
+  append_scratchpad: mutating('writes under the agent scratchpad'),
+  append_agents_memory: mutating('appends to the continual-learning file'),
+  synthesize_sca_upgrade: external('runs a package manager dry-run, which may reach a registry'),
+  apply_sca_upgrade: external('runs the package manager and the project tests and rewrites manifests', ['write:sessionRoot']),
+});
+
+export function toolCapabilityFor(name) {
+  return typeof name === 'string' && Object.prototype.hasOwnProperty.call(TOOL_CAPABILITIES, name) ? TOOL_CAPABILITIES[name] : null;
+}
+
+/** Tools whose effect is not read-only: the ones that must always be checked. */
+export function isMutatingOrExternal(name) {
+  const c = toolCapabilityFor(name);
+  return c ? c.effect !== 'read' : true; // an unclassified tool is treated as the riskiest
+}

package/src/dataflow/CLAUDE.md

@@ -16,6 +16,7 @@ Layer-2 taint engine. Walks the Layer-1 IR (`../ir/`) with field-sensitive forwa
     - Guarded by `bench/mutation/runner.mjs` (`npm run bench:mutation:check`), which scores verdict-flip correctness over metamorphic rewrites (verdict must hold) and adversarial near-misses (verdict must flip). Removing the family check makes it exit non-zero.
   - **`match.receiver`** (optional, regex source string) constrains a call to call sites whose receiver chain has a matching segment. Callee matching is by *bare name*, so `callee: 'write'` otherwise matches `process.stdout.write` and `fh.write` as readily as `document.write`. Works for both sinks (via `matchSinkOrSanitizer`) and sources (via `matchSource`'s CALL-source path). `match.receiverBase` is an optional, independent second pattern (both `_receiverAllowed` checks must pass) — use it when `receiver` alone would still match an unrelated same-named local, e.g. `py-flask-args-get` requires *both* a property segment (`args`/`form`/`headers`/…) *and* a `request`/`req` segment, so `args = parse(); args.get(x)` doesn't fire just because some catalog entry happens to be named `get`.
   - **`match.receiverExclude`** (optional, regex source string) is the only NEGATIVE form — `receiver`/`receiverBase` can only ever REQUIRE a match, which cannot express "fire on a bare call, but not on THIS receiver." `py-compile` needs exactly that: Python's dangerous `compile()` builtin (`compile(source, filename, mode)`, equivalent to `eval` when followed by `exec`) is called BARE, but the catalog's bare-name last-segment fallback (`_calleeIndexHits`) makes the same key also match `re.compile(pattern)` — an ordinary regex compiler with no code-execution capability. `receiverExclude: '^re$'` fixes it. Checked FIRST, independently of `receiver`/`receiverBase`, and a bare call (no receiver segments) can never match an exclude pattern — so setting only `receiverExclude` never blocks the no-receiver case it exists to preserve. Found via this project's own self-scan once `_calleeReceiverTainted` (below) started correctly propagating taint through `.get()`-style calls on a tainted dict/file-read chain — the sink was always mismatched; the engine fix just gave taint a path to reach it. Guarded by `test/catalog-code-injection.test.js`.
+  - **`match.receiverTypeExclude`** (optional, array of regex sources) is the type-level negative form: a CONFIDENTLY resolved receiver type matching it removes the entry (`_receiverTypeAllowed`); an unresolved type never excludes, so unknown stays conservative. `js-exec` uses `['^RegExp$']` because a regex's `.exec()` shares its method name with `child_process.exec` and is far more common on request data (it was a high-volume false positive). The type comes from three places: `catalog.js`'s `_inlineReceiverType` (a regex literal or `RegExp(...)` call as the receiver, applied inside `matchSinkOrSanitizer` so every caller gets it), CHA `classOfVar` (in-function `new RegExp`), and `engine.js`'s `_regexNamesByFile` (a file-wide name set: every assignment to the name anywhere in the file is a regex initialiser and it is never a parameter; built by `_buildRegexNames` at the start of `runTaintEngine`, because CHA cannot see a module-scope const from inside a handler). The name set is deliberately scope-blind, so a name bound to anything else anywhere in the file is not trusted. Guarded by `test/rx-exec-receiver.test.js` and the `rx-exec-*` cases in `bench/mutation/runner.mjs`.
   - **`language`** is enforced by `_languageAllowed` (Phase 2) via a table (`_LANG_EXT` in `catalog.js`) covering all ten catalog languages — `js`, `py`, `cs`, `kt`, `go`, `php`, `rb`, `java`, `rs` by literal regex kept byte-identical to `ir/index.js`'s own dispatch regexes (pinned by `test/phase2-scoping.test.js`, which compares `.source` directly, not just "does this regex literal appear somewhere in the file"), and `cpp` by delegating to `ir/parser-cpp.js`'s `cppExtRe()` so it can't drift from the parser. A language with no table entry stays permissive (matches any file) — additive by design, so it can't regress a language before its entry exists.
 - **Path feasibility.** Constant-folds `if` conditions to prune unreachable branches.
 - **Per-flow source attribution.** Sources reported on a finding are the ones actually reaching the sink argument (via free-var matching in the sink expression), NOT the first source the worklist happened to see. Premortem-derived.
@@ -73,6 +74,35 @@ Layer-2 taint engine. Walks the Layer-1 IR (`../ir/`) with field-sensitive forwa
 
 `engine.js` `dropGuardedFindings(findings, fc)` runs after all detectors and drops a CWE-918 (SSRF) finding when the sink window has a host allow/deny check (deny/allow-list, `getHost`/`hostname` comparison, RFC1918/`169.254.169.254` prefix check, `ipaddress`/`getaddrinfo`/`ssrf-req-filter`), or a CWE-22 (path) finding when the window has a containment guard (`basename`/`GetFileName`/`secure_filename`/`send_from_directory`, or canonicalize+`startsWith`). It's the single source of truth so every emitter (regex, structural, per-language flow, PY-SAST, CSHARP, GO) is treated uniformly. The window is **comment-stripped** (a "no allow-list / 169.254…" vuln comment must not read as a guard). Opt out: `AGENTIC_SECURITY_NO_GUARD_RECOGNITION=1`.
 
+### Guard recognition must prove DOMINANCE (`guard-dominance.js`, QA-005.AC02)
+
+`dropGuardedFindings` and the safe-sink-shape check used to clear a finding whenever guard-shaped TEXT sat within -25/+5 lines and shared an
+identifier with the sink line. That answers "is there guard-looking text nearby", not "is every path to the sink forced through this guard". A guard
+written AFTER the sink, one in a function nobody calls, one in a block that had already closed, a check whose failing branch only logs, a membership
+test computed and never branched on, and a line that merely DEFINES the allow-list all cleared real findings.
+
+`guardDominatesSink({ lines, guardIdx, sinkIdx, file })` now decides, over the same lines, and returns `{ dominates, reason }`. It is conservative
+toward KEEPING a finding: anything it cannot place is `not proven`. Rules: the guard precedes the sink; a data declaration is not a check; a boolean
+result needs a later branch on it; the guard's enclosing named function must contain the sink, or end before it with the sink's own code calling that
+helper first and the guard unavoidable inside the helper; the guard's block must still be open at the sink; a conditional guard must either contain the
+sink in its branch or have a failing branch that leaves (return, throw, raise, exit, abort, an HTTP error). Braces vs indentation comes from the file
+extension, else a whole-file vote. Known limit: polarity is not judged (`if (allowed) { return }` reads like a guard), and this is not a control-flow
+graph. A CWE-601 target guard (`IsLocalUrl`, a relative-path check, a host allow-list) joined the same pass.
+
+`_guardWindow` also stopped treating the `//` in `"https://"` as a comment start (it erased the allow-list check on that line and a neighbouring
+declaration stood in for it); `_stripCommentsKeepLines` is string-aware and keeps every newline so window indices are file indices.
+Guard-recognized drops are written to the suppression ledger with `id`, `cwe`, `family`, `line` and `guard-recognized:<kind>:dominates@<guardLine>:<why>`.
+Tests: `test/evaluation/guard-dominance.test.js`.
+
+### Sink argument context and request-object sources (QA-006)
+
+`match.requireStaticPrefix: { index, pattern }` (engine.js `_staticPrefixSatisfied`) gates a sink on the leading STATIC text of a partly tainted
+argument, read from the leftmost literal of a concatenation or template; an unknown leading piece fails closed. It separates
+`header("Location: " . $x)` (open redirect, `php-header-location`) from `header("X-Trace: " . $x)` (header injection only). Go's `http.Redirect` (target is
+argument 2) and `c.Redirect(code, url)` (argument 1) are sinks. Laravel `$request->input()/query()/post()/all()/...` are sources (receiver must be a
+request-named variable). `cs-aspnet-implicit-action-param` and `java-spring-implicit-mapped-param` are annotation sources fed by `ir/implicit-handler-params.js`.
+Tests: `test/evaluation/engine-mechanisms.test.js`.
+
 ## Entry points
 
 - `runTaintEngine(perFileIR, callGraph, opts)` — the public entry. Runs from `engine.js` when `AGENTIC_SECURITY_DEEP=1`. **R1 (PRD §5):** the CLI entry (`bin/agentic-security.js#cmdScan`) sets that env var by default for local/interactive scans (not in CI, and not when `--no-deep`/`AGENTIC_SECURITY_DEEP=0`), so the default `/scan --all` runs deep. In-process callers (tests, the cve-replay corpus) invoke `runScan()` directly without the CLI default and therefore stay deep-off unless they set the env var themselves (e.g. `test/deep-taint.test.js`).

package/src/dataflow/catalog.js

@@ -79,7 +79,7 @@ export const CATALOG = [
     vuln: { name: 'SQL Injection (db.execute)', severity: 'critical', cwe: 'CWE-89',
             remediation: 'Use parameterized queries: db.execute("SELECT * FROM t WHERE id = ?", [id]).' } },
   // OS command.
-  { kind: 'sink', id: 'js-exec',     language: 'js', framework: 'node', match: { type: 'call', callee: 'exec'     }, argIndex: 0,
+  { kind: 'sink', id: 'js-exec',     language: 'js', framework: 'node', match: { type: 'call', callee: 'exec', receiverTypeExclude: ['^RegExp$'] }, argIndex: 0,
     vuln: { name: 'Command Injection (child_process.exec)', severity: 'critical', cwe: 'CWE-78',
             remediation: 'Use execFile or spawn with an argv array instead of exec — exec invokes the shell. If shell features are required, escape with shell-escape, never string-concat user input.' } },
   { kind: 'sink', id: 'js-execSync', language: 'js', framework: 'node', match: { type: 'call', callee: 'execSync' }, argIndex: 0,
@@ -265,6 +265,10 @@ export const CATALOG = [
   { kind: 'source', id: 'cs-aspnet-fromform',    language: 'cs', framework: 'aspnet', match: { type: 'annotation', name: 'FromForm' },    label: '[FromForm] (ASP.NET Core)' },
   { kind: 'source', id: 'cs-aspnet-fromroute',   language: 'cs', framework: 'aspnet', match: { type: 'annotation', name: 'FromRoute' },   label: '[FromRoute] (ASP.NET Core)' },
   { kind: 'source', id: 'cs-aspnet-fromheader',  language: 'cs', framework: 'aspnet', match: { type: 'annotation', name: 'FromHeader' },  label: '[FromHeader] (ASP.NET Core)' },
+  // QA-006: the IMPLICIT forms. A controller action's plain string parameter and a Spring-mapped method's plain String parameter are
+  // request-bound with no annotation at all; the IR frontends (ir/implicit-handler-params.js) tag them with these decorator names.
+  { kind: 'source', id: 'cs-aspnet-implicit-action-param', language: 'cs', framework: 'aspnet', match: { type: 'annotation', name: 'ImplicitMvcActionParam' }, label: 'controller action parameter (ASP.NET model binding)' },
+  { kind: 'source', id: 'java-spring-implicit-mapped-param', language: 'java', framework: 'spring', match: { type: 'annotation', name: 'ImplicitSpringMappedParam' }, label: 'mapped handler parameter (Spring request binding)' },
   { kind: 'source', id: 'js-nestjs-query',   language: 'js', framework: 'nestjs', match: { type: 'annotation', name: 'Query' },   label: '@Query() (NestJS)',   provenance: 'url-param' },
   { kind: 'source', id: 'js-nestjs-body',    language: 'js', framework: 'nestjs', match: { type: 'annotation', name: 'Body' },    label: '@Body() (NestJS)',    provenance: 'http-body' },
   { kind: 'source', id: 'js-nestjs-param',   language: 'js', framework: 'nestjs', match: { type: 'annotation', name: 'Param' },   label: '@Param() (NestJS)',   provenance: 'path-param' },
@@ -410,6 +414,11 @@ export const CATALOG = [
   { kind: 'source', id: 'php-symfony-files',   language: 'php', framework: 'symfony', match: { type: 'member', object: '$request', prop: 'files' },   label: '$request->files (Symfony)' },
   { kind: 'source', id: 'php-symfony-content', language: 'php', framework: 'symfony', match: { type: 'call', callee: 'getContent' },                  label: '$request->getContent() (Symfony)' },
   { kind: 'source', id: 'php-symfony-get',     language: 'php', framework: 'symfony', match: { type: 'call', callee: 'get' },                         label: '$request->get() (Symfony)' },
+  // QA-006: Laravel / Illuminate request accessors. `$request->input('x')` is the framework's primary way to read user input and had no
+  // source at all (only Symfony's property-shaped and `get` accessors did), so a controller reading its input the Laravel way was invisible.
+  // The receiver must be a request-named variable: `input`/`all`/`file` are common method names on unrelated objects.
+  ...['input', 'query', 'post', 'all', 'cookie', 'header', 'file', 'json', 'string', 'str', 'only', 'except', 'collect', 'getContent'].map((m) => (
+    { kind: 'source', id: `php-laravel-request-${m.toLowerCase()}`, language: 'php', framework: 'laravel', match: { type: 'call', callee: m, receiver: '^\\$?(?:request|req)$' }, label: `$request->${m}() (Laravel)` })),
 
   // SARD PHP corpus: file/stream/process-output sources. This corpus's
   // dominant "source" shape is NOT a superglobal at all — it's a value read
@@ -1383,6 +1392,10 @@ export const CATALOG = [
             remediation: 'Strip/validate CR/LF from any user-controlled value before using it as a header. Prefer an allow-listed set of header values.' } },
   { kind: 'source', id: 'py-flask-request-get-data', language: 'py', framework: 'flask', match: { type: 'call', callee: 'get_data' }, label: 'request.get_data() (Flask raw body)', provenance: 'http-body' },
   { kind: 'source', id: 'py-django-request-body',    language: 'py', framework: 'django', match: { type: 'member', object: 'request', prop: 'body' }, label: 'request.body (Django raw body)', provenance: 'http-body' },
+  // QA-006: header("Location: " . $x) is an open redirect, not only header injection. The CRLF entry below still applies to the same call.
+  { kind: 'sink', id: 'php-header-location', language: 'php', framework: 'stdlib', match: { type: 'call', callee: 'header', requireStaticPrefix: { index: 0, pattern: '^\\s*Location\\s*:' } }, argIndex: 0,
+    vuln: { name: 'Open Redirect (header Location)', severity: 'medium', cwe: 'CWE-601',
+            remediation: 'Validate the redirect target against an allow-list of relative paths or known hosts before putting it in a Location header.' } },
   { kind: 'sink', id: 'php-header', language: 'php', framework: 'stdlib', match: { type: 'call', callee: 'header' }, argIndex: 0,
     vuln: { name: 'HTTP Response Splitting / CRLF Injection (header())', severity: 'high', cwe: 'CWE-113',
             remediation: 'Strip/validate CR/LF from any user-controlled value before passing it to header().' } },
@@ -1424,6 +1437,14 @@ export const CATALOG = [
   { kind: 'sink', id: 'kt-servlet-setheader', language: 'kt', framework: 'servlet', match: { type: 'call', callee: 'setHeader' }, argIndex: 1,
     vuln: { name: 'HTTP Response Splitting / Header Injection (HttpServletResponse.setHeader)', severity: 'high', cwe: 'CWE-113',
             remediation: 'Strip/validate CR/LF from any user-controlled value before using it as a header value.' } },
+  // QA-006: Go redirect helpers. net/http `http.Redirect(w, r, url, code)` takes the target as its THIRD argument; gin/echo
+  // `c.Redirect(code, url)` take it second; fiber `c.Redirect(url)` first. None was a sink, so a request-derived target went unseen.
+  { kind: 'sink', id: 'go-http-redirect', language: 'go', framework: 'net/http', match: { type: 'call', callee: 'Redirect', receiver: '^http$' }, argIndex: 2,
+    vuln: { name: 'Open Redirect (http.Redirect)', severity: 'medium', cwe: 'CWE-601',
+            remediation: 'Only redirect to a relative path you validate (starts with "/" and not "//") or to a host on an allow-list.' } },
+  { kind: 'sink', id: 'go-ctx-redirect-second', language: 'go', framework: 'gin/echo', match: { type: 'call', callee: 'Redirect', receiver: '^(?:c|ctx|context)$' }, argIndex: 1,
+    vuln: { name: 'Open Redirect (context.Redirect)', severity: 'medium', cwe: 'CWE-601',
+            remediation: 'Only redirect to a relative path you validate or to a host on an allow-list.' } },
   { kind: 'sink', id: 'go-header-set', language: 'go', framework: 'net/http', match: { type: 'call', callee: 'Set', receiver: 'Header' }, argIndex: 1,
     vuln: { name: 'HTTP Response Splitting / Header Injection (Header().Set)', severity: 'high', cwe: 'CWE-113',
             remediation: 'net/http rejects raw CR/LF in header values since Go 1.x, but still validate/allow-list user-controlled header values.' } },
@@ -2360,6 +2381,13 @@ function _receiverAllowed(entry, calleeExpr) {
 // vocabulary. Over-matching here is the safe direction: it only ever
 // *permits* a match the pattern layer already made.
 function _receiverTypeAllowed(entry, receiverType) {
+  // `receiverTypeExclude` is the NEGATIVE counterpart of `receiverTypeIn`: a
+  // confidently resolved receiver type that matches it removes the entry. An
+  // unresolved type (null) never excludes, so the conservative behaviour is
+  // unchanged whenever the engine cannot tell. `js-exec` uses it to drop a
+  // RegExp's `.exec()`, which shares its method name with child_process.exec.
+  const ex = entry.match && entry.match.receiverTypeExclude;
+  if (ex && ex.length && receiverType && ex.some((p) => new RegExp(p).test(String(receiverType)))) return false;
   const pats = entry.match && entry.match.receiverTypeIn;
   if (!pats || !pats.length) return true;
   if (!receiverType) return true;
@@ -2617,8 +2645,21 @@ export function matchSource(expr, file, receiverType) {
   return null;
 }
 
+// A receiver whose type is evident from the expression itself, with no
+// binding to resolve: a regex literal (`/x/.exec(s)`) or a direct construction
+// (`new RegExp(p).exec(s)`). Returns 'RegExp' or null. Callers that can also
+// resolve a bound variable pass their own `receiverType`, which wins.
+function _inlineReceiverType(calleeExpr) {
+  const o = calleeExpr && typeof calleeExpr === 'object' && calleeExpr.kind === 'member' ? calleeExpr.object : null;
+  if (!o) return null;
+  if (o.kind === 'literal' && o.isRegex) return 'RegExp';
+  if (o.kind === 'call' && o.callee && o.callee.kind === 'ident' && o.callee.name === 'RegExp') return 'RegExp';
+  return null;
+}
+
 export function matchSinkOrSanitizer(calleeExpr, file, receiverType) {
   if (!calleeExpr) return null;
+  receiverType = receiverType || _inlineReceiverType(calleeExpr);
   const raw = _calleeIndexHits(calleeExpr);
   if (!raw.length) return null;
   const hits = filterByProvenance(raw)