@clear-capabilities/agentic-security-scanner 0.195.27 → 0.195.29

package/src/sast/workflow-flow.js

@@ -0,0 +1,272 @@
+// YAML-aware GitHub Actions analysis (PRD FR 06).
+//
+// Replaces context-free line matching for two rules with structural analysis:
+//   * template injection: is an untrusted value substituted into executable
+//     script text, passed as data through env, or later evaluated as code?
+//   * OIDC: `id-token: write` is read from the PARSED permissions map (a
+//     commented example is not a grant), and is reported as "trust policy not
+//     verifiable from the repository", never as a proven missing restriction.
+//
+// Pure: (file path, raw text) in, findings out. Returns null when the file is
+// not parseable workflow YAML so the caller can fall back to the line rules.
+// Nothing here executes workflow content.
+
+import { load } from '../util/yaml.js';
+
+// Event fields an outsider controls. Dispatch/reusable inputs are handled
+// separately: their author's privilege is assessed, and a `choice` input with
+// declared options is constrained.
+const UNTRUSTED_EVENT = [
+  /^github\.event\.(?:issue|pull_request|discussion)\.(?:title|body)$/,
+  /^github\.event\.(?:comment|review|review_comment)\.body$/,
+  /^github\.event\.pull_request\.head\.(?:ref|label|repo\.default_branch)$/,
+  /^github\.event\.(?:head_commit|commits\.\*|commits\[\d+\])\.(?:message|author\.(?:name|email))$/,
+  /^github\.event\.head_commit\.(?:message|author\.(?:name|email))$/,
+  /^github\.event\.workflow_run\.(?:head_branch|head_commit\.message|display_title)$/,
+  /^github\.head_ref$/,
+];
+const INPUT_EXPR = /^(?:github\.event\.inputs|inputs)\.([A-Za-z_][\w-]*)$/;
+const EXPR_RE = /\$\{\{\s*([^}]*?)\s*\}\}/g;
+
+// Second interpretation of an env-carried value: the shell re-parses its content as code.
+const EVAL_SINKS = (v) => [
+  new RegExp(`\\beval\\b[^\\n;|&]*\\$\\{?${v}\\b`),
+  new RegExp(`\\b(?:ba|z|da)?sh\\s+-c\\s+["']?[^\\n]*\\$\\{?${v}\\b`),
+  new RegExp(`\\bsource\\s+<\\(\\s*echo\\s+[^)]*\\$\\{?${v}\\b`),
+  new RegExp(`\\bInvoke-Expression\\b[^\\n]*\\$(?:env:)?${v}\\b`, 'i'),
+  new RegExp(`\\biex\\b[^\\n]*\\$(?:env:)?${v}\\b`, 'i'),
+  new RegExp(`\\bpwsh\\s+-(?:c|command)\\b[^\\n]*\\$(?:env:)?${v}\\b`, 'i'),
+];
+
+const AGENT_ACTION = /(?:^|\/)(?:claude-code|claude|codex|copilot|gemini|openhands|aider|swe-agent)[\w-]*(?:-action|-agent)?@/i;
+const UNTRUSTED_TRIGGERS = ['issues', 'issue_comment', 'pull_request_target', 'pull_request_review', 'pull_request_review_comment', 'discussion', 'discussion_comment'];
+
+function isUntrustedEvent(expr) { return UNTRUSTED_EVENT.some((re) => re.test(expr)); }
+
+function untrustedIn(text, inputs) {
+  const out = [];
+  if (typeof text !== 'string') return out;
+  for (const m of text.matchAll(EXPR_RE)) {
+    const expr = m[1].trim();
+    if (isUntrustedEvent(expr)) { out.push({ expr, origin: expr, kind: 'event-field' }); continue; }
+    const im = INPUT_EXPR.exec(expr);
+    if (im) {
+      const decl = inputs[im[1]];
+      // A choice input with declared options is constrained to those literals.
+      if (decl && decl.type === 'choice' && Array.isArray(decl.options) && decl.options.every((o) => /^[\w.\- ]*$/.test(String(o)))) continue;
+      out.push({ expr, origin: expr, kind: 'dispatch-input', input: im[1] });
+    }
+  }
+  return out;
+}
+
+function collectInputs(doc) {
+  const on = doc.on ?? doc[true]; // YAML 1.1 reads a bare `on` key as boolean true
+  const inputs = {};
+  if (on && typeof on === 'object') {
+    for (const ev of ['workflow_dispatch', 'workflow_call']) {
+      const i = on[ev]?.inputs;
+      if (i && typeof i === 'object') Object.assign(inputs, i);
+    }
+  }
+  return { on, inputs };
+}
+
+function triggers(on) {
+  if (typeof on === 'string') return [on];
+  if (Array.isArray(on)) return on.map(String);
+  if (on && typeof on === 'object') return Object.keys(on);
+  return [];
+}
+
+function lineOf(raw, needle, fromLine = 0) {
+  const lines = raw.split('\n');
+  for (let i = fromLine; i < lines.length; i++) if (lines[i].includes(needle)) return i + 1;
+  for (let i = 0; i < fromLine && i < lines.length; i++) if (lines[i].includes(needle)) return i + 1;
+  return 1;
+}
+
+function permissionsOf(p) {
+  if (p === 'write-all') return { all: 'write' };
+  return p && typeof p === 'object' ? p : {};
+}
+
+/** Remove shell comment lines so a commented example is not read as a sink. */
+function stripShellComments(script, shell) {
+  const hash = /^\s*#/;
+  return String(script).split('\n').filter((l) => !hash.test(l)).join('\n');
+}
+
+/** A validation guard that exits before the value is used, e.g. [[ "$X" =~ ^[a-z]+$ ]] || exit 1. */
+function validatedBeforeUse(script, v, useIdx) {
+  const lines = script.split('\n');
+  for (let i = 0; i < lines.length && i < useIdx; i++) {
+    const l = lines[i];
+    if (new RegExp(`\\$\\{?${v}\\b`).test(l) && /(?:=~|\bgrep\s+-[A-Za-z]*q|\bcase\b)/.test(l) && /(?:exit\s+\d|return\s+\d|\bthen\b[^\n]*exit|\|\|\s*exit)/.test(l)) return true;
+    if (new RegExp(`\\$\\{?${v}\\b`).test(l) && /-notmatch|-match/.test(l) && /exit/i.test(l)) return true;
+  }
+  return false;
+}
+
+export function analyzeWorkflow(fp, raw) {
+  let doc;
+  // js-yaml is quadratic on a long run of blank lines. A run that long carries no meaning, so collapse it for parsing only;
+  // lines are located in `raw`, not in the collapsed text.
+  try { doc = load(raw.replace(/(?:[ \t]*\r?\n){20,}/g, '\n')); } catch { return null; }
+  if (!doc || typeof doc !== 'object') return null;
+  // A composite action (`runs.using: composite`) has steps but no jobs; its `inputs.*` come from whichever workflow calls it.
+  const composite = !doc.jobs && doc.runs && doc.runs.using === 'composite' && Array.isArray(doc.runs.steps);
+  if (!composite && typeof doc.jobs !== 'object') return null;
+  const { on, inputs } = composite ? { on: {}, inputs: (doc.inputs && typeof doc.inputs === 'object') ? doc.inputs : {} } : collectInputs(doc);
+  const trig = triggers(on);
+  const wfPerm = permissionsOf(doc.permissions);
+  const wfEnv = doc.env && typeof doc.env === 'object' ? doc.env : {};
+  const findings = [];
+  const seen = new Set();
+  const push = (f) => { if (!seen.has(f.id)) { seen.add(f.id); findings.push(f); } };
+
+  const privilegedTrigger = trig.includes('pull_request_target') || trig.includes('workflow_run');
+  const dispatch = trig.includes('workflow_dispatch') || trig.includes('workflow_call');
+
+  const jobEntries = composite ? [['(composite action)', { steps: doc.runs.steps }]] : Object.entries(doc.jobs || {});
+  for (const [jobId, job] of jobEntries) {
+    if (!job || typeof job !== 'object') continue;
+    const jobPerm = job.permissions !== undefined ? permissionsOf(job.permissions) : wfPerm;
+    const jobEnv = { ...wfEnv, ...(job.env && typeof job.env === 'object' ? job.env : {}) };
+    const writes = Object.entries(jobPerm).filter(([, v]) => v === 'write').map(([k]) => k);
+    const steps = Array.isArray(job.steps) ? job.steps : [];
+
+    if (jobPerm['id-token'] === 'write') {
+      const line = lineOf(raw, 'id-token');
+      push({
+        id: `pipeline:${fp}:${line}:oidc:${jobId}`, kind: 'iac', severity: 'low',
+        vuln: 'Pipeline: OIDC id-token: write, cloud trust policy and audience not verifiable from the repository',
+        cwe: 'CWE-1188', stride: 'Elevation of privilege', file: fp, line, snippet: 'id-token: write',
+        fix: 'Confirm the cloud-side trust policy requires this repository, a specific audience and a restricted subject (branch or environment). If no step requests a token, remove the permission.',
+        workflow: fp, job: jobId, step: null, disposition: 'needs-review',
+        missingEvidence: ['cloud trust policy (audience and subject conditions)', 'whether any action in this job requests an OIDC token'],
+        sensitiveOperation: 'OIDC token minting', privilegeBoundary: `job permissions: ${writes.join(', ') || 'none'}`,
+      });
+    }
+
+    steps.forEach((step, idx) => {
+      if (!step || typeof step !== 'object') return;
+      const stepName = step.name || step.id || `step-${idx + 1}`;
+      const stepEnv = { ...jobEnv, ...(step.env && typeof step.env === 'object' ? step.env : {}) };
+      const shell = String(step.shell || job.defaults?.run?.shell || doc.defaults?.run?.shell || 'bash');
+
+      // Untrusted code checked out under a privileged trigger.
+      if (typeof step.uses === 'string' && /^actions\/checkout@/.test(step.uses) && privilegedTrigger) {
+        const ref = step.with?.ref;
+        if (typeof ref === 'string' && /github\.(?:event\.pull_request\.head\.(?:sha|ref)|head_ref)|workflow_run\.head_(?:sha|branch)/.test(ref)) {
+          const line = lineOf(raw, String(ref).trim());
+          push({
+            id: `pipeline:${fp}:${line}:untrusted-checkout`, kind: 'iac', severity: 'high',
+            vuln: 'Pipeline: pull_request_target checks out untrusted pull request code',
+            cwe: 'CWE-829', stride: 'Tampering', file: fp, line, snippet: `ref: ${ref}`,
+            fix: 'A privileged-trigger workflow runs with repository secrets. Do not check out and build the pull request head in it; use `pull_request`, or split the privileged step.',
+            workflow: fp, job: jobId, step: stepName, disposition: 'needs-review',
+            inputOrigin: ref, sensitiveOperation: 'checkout of attacker-controlled code', privilegeBoundary: `trigger ${trig.join(', ')}; permissions: ${writes.join(', ') || 'default'}`,
+          });
+        }
+      }
+
+      // Remote and unknown actions: a value the analysis cannot follow into the action.
+      if (typeof step.uses === 'string' && !step.uses.startsWith('./') && step.with && typeof step.with === 'object') {
+        for (const [wk, wv] of Object.entries(step.with)) {
+          for (const u of untrustedIn(String(wv), inputs)) {
+            const line = lineOf(raw, String(wv).trim().split('\n')[0].slice(0, 40));
+            const scriptInput = /^actions\/github-script@/.test(step.uses) && wk === 'script';
+            push({
+              id: `pipeline:${fp}:${line}:action-input:${jobId}:${idx}:${wk}:${u.expr}`, kind: 'iac',
+              severity: scriptInput && u.kind === 'event-field' ? 'critical' : 'low',
+              vuln: scriptInput ? 'Pipeline: untrusted github.event input interpolated into github-script source' : 'Pipeline: untrusted input passed to an action this analysis cannot inspect',
+              cwe: scriptInput ? 'CWE-94' : 'CWE-20', stride: 'Tampering', file: fp, line, snippet: `${wk}: ${String(wv).trim().split('\n')[0].slice(0, 80)}`,
+              fix: scriptInput ? 'Pass the value through `env:` and read it as data (process.env.NAME); never substitute it into the script text.' : 'Confirm how the action uses this input (shell, script or URL) and pin the action to a commit.',
+              workflow: fp, job: jobId, step: stepName, inputOrigin: u.origin, inputOriginKind: u.kind,
+              sensitiveOperation: scriptInput ? 'JavaScript executed by github-script' : `input "${wk}" of ${step.uses}`,
+              privilegeBoundary: `trigger ${trig.join(', ') || 'composite action (caller decides)'}; permissions: ${writes.join(', ') || 'default'}`,
+              disposition: scriptInput && u.kind === 'event-field' ? 'detected' : 'needs-review',
+              ...(scriptInput && u.kind === 'event-field' ? {} : { missingEvidence: [`source and handling of ${step.uses.split('@')[0]}`] }),
+            });
+          }
+        }
+      }
+
+      // Artifacts produced by an untrusted run are attacker-controlled data once a privileged workflow_run consumes them.
+      if (typeof step.uses === 'string' && /^actions\/download-artifact@/.test(step.uses) && trig.includes('workflow_run')) {
+        const line = lineOf(raw, 'download-artifact');
+        push({
+          id: `pipeline:${fp}:${line}:artifact:${jobId}:${idx}`, kind: 'iac', severity: writes.length ? 'medium' : 'low',
+          vuln: 'Pipeline: workflow_run consumes an artifact built by the triggering run',
+          cwe: 'CWE-829', stride: 'Tampering', file: fp, line, snippet: step.uses,
+          fix: 'Treat artifact content as untrusted data: validate it before use and never execute or source it in a job with write permissions or secrets.',
+          workflow: fp, job: jobId, step: stepName, inputOrigin: 'artifact from the triggering workflow run', inputOriginKind: 'artifact',
+          sensitiveOperation: 'use of artifact contents in a privileged workflow', privilegeBoundary: `trigger workflow_run; permissions: ${writes.join(', ') || 'default'}`,
+          disposition: 'needs-review', missingEvidence: ['whether the triggering run can be started from a fork', 'how the artifact contents are used after download'],
+        });
+      }
+
+      // Agent scenario: model-driven action with write authority and attacker-supplied prompt content.
+      if (typeof step.uses === 'string' && AGENT_ACTION.test(step.uses) && writes.length && trig.some((t) => UNTRUSTED_TRIGGERS.includes(t))) {
+        const line = lineOf(raw, step.uses.slice(0, 30));
+        push({
+          id: `pipeline:${fp}:${line}:agent:${jobId}:${idx}`, kind: 'iac', severity: 'medium',
+          vuln: 'Pipeline: AI agent with write permissions runs on attacker-supplied content',
+          cwe: 'CWE-77', stride: 'Elevation of privilege', file: fp, line, snippet: step.uses,
+          fix: 'Restrict the agent to read-only permissions, require an approval before it can write, or run it only for trusted authors. Prompt content from issues, comments and pull requests is untrusted.',
+          workflow: fp, job: jobId, step: stepName, inputOrigin: `event content from ${trig.filter((t) => UNTRUSTED_TRIGGERS.includes(t)).join(', ')}`, inputOriginKind: 'agent-prompt',
+          sensitiveOperation: `agent actions with ${writes.join(', ')} write authority`, privilegeBoundary: `permissions: ${writes.join(', ')}`,
+          disposition: 'needs-review', missingEvidence: ['which authors can trigger the workflow', 'whether the agent has an approval step or tool restrictions'],
+        });
+      }
+
+      if (typeof step.run !== 'string') return;
+      const script = stripShellComments(step.run, shell);
+
+      // 1. Untrusted expression substituted directly into the script text.
+      for (const u of untrustedIn(script, inputs)) {
+        const line = lineOf(raw, '${{', lineOf(raw, step.run.split('\n')[0].trim().slice(0, 40)) - 1);
+        const privileged = privilegedTrigger || writes.length > 0 || Object.keys(job.secrets || {}).length > 0 || /secrets\./.test(JSON.stringify(step));
+        push({
+          id: `pipeline:${fp}:${line}:script:${jobId}:${idx}:${u.expr}`, kind: 'iac',
+          severity: u.kind === 'dispatch-input' && !privilegedTrigger ? 'medium' : 'critical',
+          vuln: 'Pipeline: untrusted github.event input interpolated into shell context',
+          cwe: 'CWE-78', stride: 'Tampering', file: fp, line, snippet: `\${{ ${u.expr} }}`,
+          fix: 'Pass the value through an environment variable and reference it as data ("$VAR" / $env:VAR); never substitute it into script text.',
+          workflow: fp, job: jobId, step: stepName, inputOrigin: u.origin,
+          inputOriginKind: u.kind, sensitiveOperation: `shell script (${shell})`,
+          privilegeBoundary: `trigger ${trig.join(', ')}; ${privileged ? 'job has write permissions or secrets' : 'job is read-only'}`,
+          disposition: u.kind === 'dispatch-input' ? 'needs-review' : 'detected',
+          ...(u.kind === 'dispatch-input' ? { missingEvidence: ['privilege of the dispatch input author relative to the job'] } : {}),
+        });
+      }
+
+      // 2. env-carried untrusted value, then re-interpreted as code.
+      for (const [name, val] of Object.entries(stepEnv)) {
+        const us = untrustedIn(String(val), inputs);
+        if (!us.length || !/^[A-Za-z_]\w*$/.test(name)) continue;
+        const sinks = EVAL_SINKS(name);
+        const hit = sinks.map((re) => re.exec(script)).find(Boolean);
+        if (!hit) continue;
+        const useIdx = script.slice(0, hit.index).split('\n').length - 1;
+        const guarded = validatedBeforeUse(script, name, useIdx);
+        const line = lineOf(raw, hit[0].trim().slice(0, 30));
+        push({
+          id: `pipeline:${fp}:${line}:env-eval:${jobId}:${idx}:${name}`, kind: 'iac',
+          severity: guarded ? 'low' : 'critical',
+          vuln: 'Pipeline: untrusted github.event input interpolated into shell context (env value later evaluated as code)',
+          cwe: 'CWE-78', stride: 'Tampering', file: fp, line, snippet: hit[0].trim(),
+          fix: `Env placement is not a sanitizer: \$${name} is parsed as code by this command. Treat it as data only (fixed command, argument array), or validate it against an allow-list first.`,
+          workflow: fp, job: jobId, step: stepName, inputOrigin: us[0].origin, inputOriginKind: us[0].kind,
+          sensitiveOperation: `second interpretation of $${name} (${shell})`,
+          privilegeBoundary: `trigger ${trig.join(', ')}; permissions: ${writes.join(', ') || 'default'}`,
+          disposition: guarded ? 'needs-review' : 'detected',
+          guards: guarded ? [`validation of $${name} before use`] : [],
+        });
+      }
+    });
+  }
+  void dispatch;
+  return findings;
+}

package/src/sca/basis.js

@@ -0,0 +1,88 @@
+// Dependency finding basis (PRD FR 08). Records WHY a dependency finding exists
+// and how strong the evidence about the dependency itself is, kept apart from
+// reachability. A version match is a version match: unknown reachability is
+// recorded as unknown and is never a reason to drop or call the finding safe.
+//
+// Version bases, weakest to strongest. None of them is deployment evidence:
+//   declared-constraint  a range or pin in a manifest
+//   locked               an entry in a lock file
+//   resolved-graph       a resolved dependency graph (not produced by this scanner today)
+//   deployment-evidence  an artifact or runtime inventory (never inferred from the repository)
+
+const LOCK_FILES = /(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|poetry\.lock|Pipfile\.lock|go\.sum|Gemfile\.lock|composer\.lock|gradle\.lockfile|packages\.lock\.json|stack\.yaml\.lock|cabal\.project\.freeze|flake\.lock|mix\.lock|pubspec\.lock)$/;
+
+export function versionBasisOf(file) {
+  return LOCK_FILES.test(String(file || '')) ? 'locked' : 'declared-constraint';
+}
+
+function rangesOf(sc) {
+  if (Array.isArray(sc.affectedRanges) && sc.affectedRanges.length) return sc.affectedRanges;
+  return null;
+}
+
+/** Add `basis` to every dependency vulnerability finding. Pure with respect to severity and visibility. */
+export function annotateScaBasis(supplyChain) {
+  for (const sc of supplyChain || []) {
+    if (!sc || sc.type !== 'vulnerable_dep') continue;
+    const vb = versionBasisOf(sc.file);
+    const gaps = [];
+    if (!rangesOf(sc)) gaps.push('affected range not recorded for this advisory');
+    if (!sc.advisoryModified) gaps.push('advisory timestamp not recorded');
+    if (!sc.fixedVersions || !sc.fixedVersions.length) gaps.push('no fixed version known');
+    if (vb === 'declared-constraint') gaps.push('version comes from a declared constraint; the installed version may differ');
+    gaps.push('no deployment evidence: a dependency listed here is not proof that it is deployed');
+    sc.basis = {
+      schema: 'sca-basis/1',
+      ecosystem: sc.ecosystem || null,
+      package: sc.name || null,
+      resolvedVersion: sc.version || null,
+      versionBasis: vb,
+      source: { file: sc.file || null, line: sc.line ?? null, direct: sc.isDirect ?? null, chain: sc.depChain || [] },
+      advisory: {
+        id: sc.osvId || null,
+        aliases: sc.cveAliases || [],
+        affectedRanges: rangesOf(sc),
+        fixedVersions: sc.fixedVersions || [],
+        source: sc.advisorySource || 'osv.dev',
+        modified: sc.advisoryModified || null,
+        published: sc.advisoryPublished || null,
+      },
+      matchBasis: 'version-range',
+      reachability: sc.functionReachable || (sc.reachable ? 'import-reachable' : 'unknown'),
+      reachabilityNote: 'reachability is optional context and never removes a valid version match',
+      deploymentEvidence: 'none',
+      gaps,
+    };
+  }
+  return supplyChain;
+}
+
+/**
+ * Merge findings that are the same advisory under different identifiers (an
+ * OSV/GHSA id and its CVE alias) for the same package version. The merged
+ * finding keeps every identifier and every affected occurrence, so no
+ * component or file is lost. Returns the new list; inputs are not mutated.
+ */
+export function dedupeAdvisoryAliases(supplyChain) {
+  const out = [];
+  const groups = new Map(); // component key -> [{ids:Set, primary}]
+  for (const sc of supplyChain || []) {
+    if (!sc || sc.type !== 'vulnerable_dep') { out.push(sc); continue; }
+    const ck = `${sc.ecosystem}\0${sc.name}\0${sc.version}`;
+    const ids = new Set([sc.osvId, ...(sc.cveAliases || [])].filter(Boolean));
+    const list = groups.get(ck) || groups.set(ck, []).get(ck);
+    const hit = list.find((g) => [...ids].some((i) => g.ids.has(i)));
+    const occ = { file: sc.file || null, line: sc.line ?? null, direct: sc.isDirect ?? null, chain: sc.depChain || [] };
+    if (!hit) {
+      const primary = { ...sc, occurrences: [occ], advisoryIds: [...ids].sort() };
+      list.push({ ids, primary });
+      out.push(primary);
+      continue;
+    }
+    for (const i of ids) hit.ids.add(i);
+    hit.primary.advisoryIds = [...hit.ids].sort();
+    if (!hit.primary.occurrences.some((o) => o.file === occ.file && o.line === occ.line)) hit.primary.occurrences.push(occ);
+    if (sc.osvId && sc.osvId !== hit.primary.osvId) (hit.primary.mergedAdvisories ||= []).push(sc.osvId);
+  }
+  return out;
+}

package/src/scope/flags.js

@@ -0,0 +1,55 @@
+// CLI flags for the scan scope (PRD FR 01 / FR 09). Pure: argv in, plain
+// object out. Repeatable flags (`--include-path a --include-path b`) are why
+// this is not read from the CLI's generic last-one-wins flag map.
+
+const VALUE_FLAGS = new Set(['--include-path', '--exclude-path', '--include-ignored-path', '--ignore-source']);
+const BOOL_FLAGS = new Set(['--explain-scope', '--respect-gitignore', '--no-respect-gitignore']);
+
+export function parseScopeFlags(argv) {
+  const out = { active: false, explain: false, errors: [], scope: { respectGitignore: true, ignoreSource: 'local', includePaths: [], excludePaths: [], includeIgnoredPaths: [] } };
+  for (let i = 0; i < argv.length; i++) {
+    let [k, v] = argv[i].startsWith('--') ? argv[i].split(/=(.*)/s, 2) : [argv[i]];
+    if (BOOL_FLAGS.has(k)) {
+      out.active = true;
+      if (k === '--explain-scope') out.explain = true;
+      else out.scope.respectGitignore = k === '--respect-gitignore';
+    } else if (VALUE_FLAGS.has(k)) {
+      out.active = true;
+      if (v === undefined) v = argv[++i];
+      if (v === undefined || v.startsWith('--')) { out.errors.push(`${k} needs a value`); continue; }
+      if (k === '--ignore-source') {
+        if (v === 'all') out.scope.ignoreSource = 'local';
+        else if (v === 'repository') out.scope.ignoreSource = 'repository';
+        else out.errors.push(`--ignore-source must be "all" or "repository", got "${v}"`);
+      } else if (k === '--include-path') out.scope.includePaths.push(v);
+      else if (k === '--exclude-path') out.scope.excludePaths.push(v);
+      else out.scope.includeIgnoredPaths.push(v);
+    }
+  }
+  return out;
+}
+
+/** Human-readable scope preview: included paths, excluded subtrees, reasons, overrides, policy. */
+export function renderScopePreview(inv, { maxLines = 40 } = {}) {
+  const L = [];
+  const p = inv.policy;
+  L.push(`Scope mode: ${p.mode}${p.respectGitignore ? '' : ' (git ignore rules disabled)'}; tracked-file semantics: ${p.trackedFileSemantics ? 'yes' : 'no'}`);
+  if (p.ruleDigest) L.push(`Effective ignore-rule digest: ${p.ruleDigest}`);
+  for (const d of p.disclosures) L.push(`Disclosure: ${d}`);
+  L.push(`Included: ${inv.included.length} file(s)`);
+  for (const f of inv.included.slice(0, maxLines)) L.push(`  + ${f}`);
+  if (inv.included.length > maxLines) L.push(`  ... ${inv.included.length - maxLines} more`);
+  const byReason = new Map();
+  for (const s of inv.skipped) (byReason.get(s.reason) || byReason.set(s.reason, []).get(s.reason)).push(s);
+  L.push(`Skipped: ${inv.skipped.length} entr${inv.skipped.length === 1 ? 'y' : 'ies'}`);
+  for (const [reason, items] of [...byReason].sort()) {
+    L.push(`  ${reason}: ${items.length}`);
+    for (const s of items.slice(0, 5)) L.push(`    - ${s.path}${s.segment ? ` (segment ${s.segment})` : ''}`);
+    if (items.length > 5) L.push(`    ... ${items.length - 5} more`);
+  }
+  if (inv.overrides.length) {
+    L.push(`Overrides: ${inv.overrides.length}`);
+    for (const o of inv.overrides) L.push(`  ! ${o.path} overrode ${o.overrode}`);
+  }
+  return L.join('\n') + '\n';
+}

package/src/scope/inventory.js

@@ -0,0 +1,241 @@
+// Scan inventory (PRD FR 01): one eligibility decision per candidate path,
+// made BEFORE any file content is read, with a recorded reason for every skip.
+//
+// Git decides what Git ignores. Ignore semantics are never reimplemented here:
+// `git ls-files -z` handles nested .gitignore files, negation, anchoring,
+// directory patterns, escaping and unusual filenames. This module only layers
+// the scanner's own policy on top, in the PRD's order:
+//
+//   1. root and filesystem safety (no symlinks, nothing outside the root)
+//   2. explicit scanner exclusion      (excludePaths)
+//   3. exact explicit inclusion        (includePaths, includeIgnoredPaths)
+//   4. Git selection                   (tracked + untracked-not-ignored)
+//   5. narrowly defined scanner defaults (build-output directory SEGMENTS)
+//
+// A tracked file stays eligible even when a later ignore pattern matches it.
+// Defaults match whole path segments, never substrings: `.github/workflows/
+// buck2.yml` and `tools/buck2/` are not build output.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import * as cp from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
+
+/** Generated-output directory names, matched as exact path segments. */
+export const GENERATED_DIR_SEGMENTS = Object.freeze([
+  'buck-out', 'dist-newstyle', '.stack-work', '.cabal-sandbox',
+]);
+
+export const SCOPE_MODES = Object.freeze({ LOCAL: 'local', REPOSITORY: 'repository' });
+
+function git(root, args, { env = {}, maxBuffer = 256 * 1024 * 1024 } = {}) {
+  const r = cp.spawnSync('git', hardenGitArgs(args), {
+    cwd: root, env: hardenGitEnv(env), maxBuffer, encoding: 'buffer',
+  });
+  return r.status === 0 ? r.stdout : null;
+}
+
+function nulList(buf) {
+  return buf.toString('utf8').split('\0').filter(Boolean);
+}
+
+function norm(p) {
+  return p.split(path.sep).join('/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+function segmentOf(rel, segments) {
+  for (const s of rel.split('/')) if (segments.includes(s)) return s;
+  return null;
+}
+
+function sha(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+function digestRules(root, mode) {
+  // Digest of every ignore source that can change the selection. Hashing the
+  // rule files (not the selected set) lets a rule edit invalidate scope caches.
+  const sources = [];
+  const listed = git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  const files = (listed ? nulList(listed) : []).filter((f) => path.posix.basename(f) === '.gitignore').sort();
+  for (const f of files) {
+    try { sources.push(`${f}\0${fs.readFileSync(path.join(root, f), 'utf8')}`); } catch { /* vanished */ }
+  }
+  if (mode === SCOPE_MODES.LOCAL) {
+    for (const f of [path.join('.git', 'info', 'exclude')]) {
+      try { sources.push(`${f}\0${fs.readFileSync(path.join(root, f), 'utf8')}`); } catch { /* absent */ }
+    }
+    const gx = git(root, ['config', '--get', 'core.excludesFile']);
+    if (gx) {
+      const p = gx.toString('utf8').trim().replace(/^~(?=\/)/, process.env.HOME || '~');
+      try { sources.push(`global\0${fs.readFileSync(p, 'utf8')}`); } catch { /* absent */ }
+    }
+  }
+  return sha(sources.join('\n--\n'));
+}
+
+function isGitWorkTree(root) {
+  const out = git(root, ['rev-parse', '--is-inside-work-tree']);
+  return !!out && out.toString('utf8').trim() === 'true';
+}
+
+/**
+ * Ask Git for the selected file set and the ignored subtrees, without reading
+ * any file content and without enumerating inside an ignored directory.
+ */
+function gitSelection(root, mode) {
+  const env = mode === SCOPE_MODES.REPOSITORY ? { GIT_CONFIG_GLOBAL: '/dev/null' } : {};
+  // Repository mode: honour only .gitignore files in the tree. --exclude-standard
+  // would add .git/info/exclude and the global file, which differ between
+  // machines, so name the per-directory source explicitly instead.
+  const ignoreArgs = mode === SCOPE_MODES.REPOSITORY ? ['--exclude-per-directory=.gitignore'] : ['--exclude-standard'];
+  const cands = git(root, ['ls-files', '-z', '--cached', '--others', ...ignoreArgs], { env });
+  if (!cands) return null;
+  // --directory collapses an ignored directory to one entry instead of walking it.
+  const ign = git(root, ['ls-files', '-z', '--others', '--ignored', '--directory', ...ignoreArgs], { env });
+  const tracked = git(root, ['ls-files', '-z', '--cached'], { env });
+  // Gitlinks (submodules) are index entries with mode 160000.
+  const staged = git(root, ['ls-files', '-z', '--stage'], { env });
+  const gitlinks = new Set((staged ? nulList(staged) : []).filter((l) => l.startsWith('160000 ')).map((l) => norm(l.slice(l.indexOf('\t') + 1))));
+  return {
+    gitlinks,
+    candidates: nulList(cands).map(norm),
+    ignored: ign ? nulList(ign).map((d) => d.replace(/^\.\//, '')) : [],
+    tracked: new Set(tracked ? nulList(tracked).map(norm) : []),
+  };
+}
+
+function unitKind(abs, isGitlink) {
+  if (isGitlink) return 'submodule';
+  try { if (fs.lstatSync(abs).isDirectory() && fs.existsSync(path.join(abs, '.git'))) return 'nested-repository'; } catch { /* gone */ }
+  return null;
+}
+
+function lstatKind(abs) {
+  try {
+    const st = fs.lstatSync(abs);
+    if (st.isSymbolicLink()) return 'symlink';
+    if (st.isFile()) return 'file';
+    return 'other';
+  } catch { return 'missing'; }
+}
+
+function underRoot(root, abs) {
+  let real;
+  try { real = fs.realpathSync(abs); } catch { return false; }
+  const r = fs.realpathSync(root);
+  return real === r || real.startsWith(r + path.sep);
+}
+
+/**
+ * Build the inventory. Never reads file contents.
+ *
+ * @param {string} root
+ * @param {object} [o]
+ * @param {boolean} [o.respectGitignore=true]
+ * @param {'local'|'repository'} [o.ignoreSource='local']
+ * @param {string[]} [o.includePaths]         exact paths; beat Git ignore and default build exclusions
+ * @param {string[]} [o.includeIgnoredPaths]  exact ignored files, opted in explicitly
+ * @param {string[]} [o.excludePaths]         path or directory prefixes; beat every inclusion
+ * @param {string[]} [o.generatedSegments]
+ * @returns {{included: string[], skipped: object[], overrides: object[], policy: object}}
+ */
+export function buildScanInventory(root, o = {}) {
+  const {
+    respectGitignore = true, ignoreSource = SCOPE_MODES.LOCAL,
+    includePaths = [], includeIgnoredPaths = [], excludePaths = [],
+    generatedSegments = GENERATED_DIR_SEGMENTS,
+  } = o;
+  const mode = ignoreSource === SCOPE_MODES.REPOSITORY ? SCOPE_MODES.REPOSITORY : SCOPE_MODES.LOCAL;
+  const included = [];
+  const skipped = [];
+  const overrides = [];
+  const exclude = excludePaths.map(norm);
+  const include = new Set([...includePaths, ...includeIgnoredPaths].map(norm));
+  const ignoredInclude = new Set(includeIgnoredPaths.map(norm));
+
+  const sel = respectGitignore && isGitWorkTree(root) ? gitSelection(root, mode) : null;
+  const policy = {
+    mode: sel ? mode : 'walk',
+    respectGitignore,
+    trackedFileSemantics: !!sel,
+    ruleDigest: sel ? digestRules(root, mode) : null,
+    disclosures: sel ? [] : [
+      respectGitignore
+        ? 'not a Git work tree: .gitignore rules are not applied and tracked-file semantics are unavailable'
+        : 'Git ignore rules disabled by explicit option',
+    ],
+  };
+
+  let candidates;
+  if (sel) {
+    candidates = sel.candidates;
+    for (const d of sel.ignored) {
+      // Reported once per collapsed subtree, never enumerated.
+      skipped.push({ path: d, reason: 'git-ignored', rule: d.endsWith('/') ? 'directory' : 'file' });
+    }
+  } else {
+    candidates = walkAll(root);
+  }
+
+  const seen = new Set();
+  for (const rel of candidates) {
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    const abs = path.join(root, rel);
+    const kind = lstatKind(abs);
+    if (kind === 'missing') { skipped.push({ path: rel, reason: 'missing-tracked-file', coverageCondition: true }); continue; }
+    if (kind === 'symlink') { skipped.push({ path: rel, reason: 'symlink' }); continue; }
+    if (kind === 'other') {
+      // A directory that Git lists as one entry is a submodule or a nested repository: a separate scan unit that was not scanned.
+      const unit = unitKind(abs, sel && sel.gitlinks.has(rel));
+      skipped.push({ path: rel, reason: unit || 'unsupported-entry', coverageCondition: true, ...(unit ? { note: 'separate repository: declare it as its own scan target to cover it' } : {}) });
+      continue;
+    }
+    if (!underRoot(root, abs)) { skipped.push({ path: rel, reason: 'outside-root' }); continue; }
+    if (exclude.some((e) => rel === e || rel.startsWith(e + '/'))) { skipped.push({ path: rel, reason: 'explicit-exclude' }); continue; }
+    const seg = segmentOf(rel, generatedSegments);
+    if (seg && !include.has(rel)) {
+      // Tracked files do not override a generated-output default; only an exact inclusion does.
+      skipped.push({ path: rel, reason: 'generated-default', segment: seg });
+      continue;
+    }
+    if (seg && include.has(rel)) overrides.push({ path: rel, overrode: 'generated-default', segment: seg });
+    included.push(rel);
+  }
+
+  // Exact inclusions of files Git ignored (or that the walk never produced).
+  for (const rel of include) {
+    if (seen.has(rel)) continue;
+    if (exclude.some((e) => rel === e || rel.startsWith(e + '/'))) { skipped.push({ path: rel, reason: 'explicit-exclude' }); continue; }
+    const abs = path.join(root, rel);
+    const kind = lstatKind(abs);
+    if (kind !== 'file' || !underRoot(root, abs) || rel.startsWith('../') || path.isAbsolute(rel)) {
+      skipped.push({ path: rel, reason: kind === 'symlink' ? 'symlink' : 'include-rejected', coverageCondition: true });
+      continue;
+    }
+    included.push(rel);
+    overrides.push({ path: rel, overrode: ignoredInclude.has(rel) ? 'git-ignore' : 'selection', evidenceOnly: false });
+  }
+
+  included.sort();
+  return { included, skipped, overrides, policy };
+}
+
+function walkAll(root) {
+  const out = [];
+  const stack = [''];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir ? path.join(root, dir) : root, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const rel = dir ? `${dir}/${e.name}` : e.name;
+      if (e.name === '.git') continue;
+      if (e.isDirectory()) stack.push(rel);
+      else out.push(rel);
+    }
+  }
+  return out;
+}