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

package/src/sast/oidc-trust.js

@@ -0,0 +1,74 @@
+// OIDC trust policy evidence found in the repository itself (PRD FR 06).
+//
+// A repository can only show the cloud trust policy when that policy is kept in it (Terraform, CloudFormation, a JSON policy). Absence
+// from the repository is not absence from the cloud account, so `absent` stays needs-review. Classification is of the `sub` (subject)
+// condition for the GitHub OIDC issuer:
+//   restrictive  every subject pins an exact repository and a ref or environment, with no wildcard beyond the ref part
+//   permissive   a wildcard repository or owner, or a trust statement for the issuer with no subject condition at all
+//   mismatched   no subject pins this repository (`ownRepository`, when it is known); a policy that trusts this repository and
+//                others as well is not a mismatch, since one role is often shared by several repositories
+//   absent       no policy for the GitHub issuer exists in the scanned files
+
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
+
+const ISSUER = /token\.actions\.githubusercontent\.com/;
+const SUB_RE = /token\.actions\.githubusercontent\.com(?::|"\s*:\s*\{?\s*")?\s*sub["']?\s*[:=]?\s*[\[\{]?\s*["']([^"'\]\}]+)["']/gi;
+const SUB_LOOSE = /["']?(?:token\.actions\.githubusercontent\.com:)?sub["']?\s*[:=]\s*\[?\s*["'](repo:[^"']+)["']/gi;
+
+export function classifyOidcTrust(files, { ownRepository = null } = {}) {
+  const policies = [];
+  for (const [file, text] of Object.entries(files || {})) {
+    if (typeof text !== 'string' || !ISSUER.test(text)) continue;
+    if (!/\.(?:tf|json|ya?ml|template|hcl)$/i.test(file)) continue;
+    const subs = new Set();
+    for (const re of [SUB_RE, SUB_LOOSE]) { re.lastIndex = 0; let m; while ((m = re.exec(text))) subs.add(m[1]); }
+    policies.push({ file, subjects: [...subs] });
+  }
+  if (!policies.length) return { status: 'absent', policies: [], note: 'no trust policy for the GitHub OIDC issuer in the scanned files; the cloud account may still have one' };
+  const subjects = policies.flatMap((p) => p.subjects.map((s) => ({ file: p.file, subject: s })));
+  if (!subjects.length) return { status: 'permissive', policies, note: 'a trust statement names the GitHub OIDC issuer but no subject condition was found' };
+  const bad = subjects.find(({ subject }) => /^\*$|^repo:\*|^repo:[^/:*]+\/\*(?::|$)|:\*$/.test(subject) && !/^repo:[^/:*]+\/[^/:*]+:(?:ref|environment|pull_request)/.test(subject));
+  if (bad) return { status: 'permissive', policies, evidence: bad, note: `subject "${bad.subject}" admits more than one repository or any ref` };
+  if (ownRepository) {
+    const repoOf = (subject) => { const m = /^repo:([^/:*]+\/[^/:*]+)/.exec(subject); return m ? m[1].toLowerCase() : null; };
+    const mine = subjects.some(({ subject }) => repoOf(subject) === ownRepository.toLowerCase());
+    if (!mine) {
+      const other = subjects.find(({ subject }) => repoOf(subject));
+      return { status: 'mismatched', policies, evidence: other || subjects[0], note: `no subject pins ${ownRepository}; the policy in the repository is not the one this workflow's token is checked against` };
+    }
+  }
+  return { status: 'restrictive', policies, note: 'every subject pins one repository and a ref or environment' };
+}
+
+/** Apply the classification to OIDC findings in place. Never closes a finding on repository evidence alone. */
+export function applyOidcTrust(findings, files, opts = {}) {
+  const c = classifyOidcTrust(files, opts);
+  for (const f of findings || []) {
+    if (!f || !/^Pipeline: OIDC id-token: write/.test(String(f.vuln || ''))) continue;
+    f.oidcTrust = { status: c.status, note: c.note, ...(c.evidence ? { evidence: c.evidence } : {}), ownRepository: opts.ownRepository || null, ownRepositoryBasis: opts.ownRepositoryBasis || (opts.ownRepository ? 'supplied' : 'unknown: the mismatched check was not made') };
+    if (c.status === 'permissive' || c.status === 'mismatched') { f.severity = 'high'; f.disposition = 'needs-review'; f.missingEvidence = ['confirm the deployed trust policy matches the one in the repository']; }
+    else if (c.status === 'restrictive') { f.missingEvidence = ['confirm the deployed trust policy matches the one in the repository']; f.severity = 'low'; }
+    // absent: unchanged, the cloud-side policy is simply not verifiable from here
+  }
+  return c;
+}
+
+/**
+ * This repository's GitHub name (`owner/repo`), with the basis it came from: the `origin` remote of the scanned tree, else
+ * `GITHUB_REPOSITORY` when the scan runs inside GitHub Actions on its own checkout. Null when neither names a GitHub repository;
+ * the mismatched check is then not made, and the report says so.
+ */
+export function resolveOwnRepository(scanRoot, env = process.env) {
+  if (scanRoot) {
+    const r = spawnSync('git', hardenGitArgs(['config', '--get', 'remote.origin.url']), { cwd: scanRoot, env: hardenGitEnv({}), encoding: 'utf8' });
+    const url = r.status === 0 ? String(r.stdout || '').trim() : '';
+    const m = /^(?:https?:\/\/(?:[^@/]+@)?github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?\/?$/.exec(url);
+    if (m) return { name: m[1], basis: 'git remote origin' };
+  }
+  if (env.GITHUB_ACTIONS === 'true' && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(env.GITHUB_REPOSITORY || '') && env.GITHUB_WORKSPACE && scanRoot && path.resolve(env.GITHUB_WORKSPACE) === path.resolve(scanRoot)) {
+    return { name: env.GITHUB_REPOSITORY, basis: 'GITHUB_REPOSITORY (GitHub Actions)' };
+  }
+  return null;
+}

package/src/sast/pipeline.js

@@ -1,3 +1,4 @@
+import { analyzeWorkflow } from './workflow-flow.js';
 // 0.7.0 Feat-9: Pipeline / GitHub Actions integrity detector with PBOM emitter.
 //
 // Catches the canonical CI/CD security mistakes:
@@ -10,7 +11,8 @@
 //
 // Same finding shape as scanIaC; produced separately so the rule set is small and tunable.
 
-const _GH_WORKFLOW_RE = /(?:^|\/)\.github\/workflows\/.*\.ya?ml$/i;
+// Workflows, and composite actions kept in the repository (`.github/actions/<name>/action.yml`, or an action.yml at any depth).
+const _GH_WORKFLOW_RE = /(?:^|\/)\.github\/workflows\/.*\.ya?ml$|(?:^|\/)\.github\/actions\/.*\.ya?ml$|(?:^|\/)action\.ya?ml$/i;
 const _NONPROD_RE = /(?:^|\/)(?:tests?|examples?|fixtures?)\//i;
 
 
@@ -135,6 +137,14 @@ const PIPELINE_PATTERNS = [
   },
 ];
 
+// Rules the YAML-aware analyzer (workflow-flow.js) now owns. They are kept as line
+// patterns only as the fallback for a file that does not parse as workflow YAML.
+const STRUCTURAL_VULNS = new Set([
+  'Pipeline: pull_request_target checks out untrusted pull request code',
+  'Pipeline: untrusted github.event input interpolated into shell context',
+  'Pipeline: OIDC id-token: write without explicit aud restriction',
+]);
+
 export function scanPipeline(fp, raw) {
   if (!_GH_WORKFLOW_RE.test(fp.replace(/\\/g, '/'))) return [];
   if (_NONPROD_RE.test(fp.replace(/\\/g, '/'))) return [];
@@ -142,7 +152,10 @@ export function scanPipeline(fp, raw) {
   const lines = raw.split('\n');
   const findings = [];
   const seen = new Set();
+  const structural = analyzeWorkflow(fp, raw);
+  if (structural) for (const f of structural) { seen.add(f.id); findings.push(f); }
   for (const p of PIPELINE_PATTERNS) {
+    if (structural && STRUCTURAL_VULNS.has(p.vuln)) continue;
     if (p.contextRe) {
       const present = p.contextRe.test(raw);
       if (p.contextNeg && present) continue; // suppress: required context exists

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