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

package/src/runScan.js

@@ -3,12 +3,16 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as cp from 'node:child_process';
+import * as fsSync from 'node:fs';
 import { listFiles } from './util/glob.js';
+import { buildScanInventory } from './scope/inventory.js';
 import { hardenGitArgs, hardenGitEnv } from './util/git-hardening.js';
 import { runFullScan, shouldScan, isKubernetesManifest, isCloudFormationTemplate, isInstructionFile } from './engine.js';
 import { appendScanSnapshot } from './posture/security-trend.js';
 import { recover as recoverFixHistory } from './posture/fix-history.js';
 import { stampScan } from './posture/ruleset-version.js';
+import { annotateFindingRecords, buildScanRecord } from './pipeline/evidence-record.js';
+import { SCANNER_VERSION } from './posture/version.js';
 import { isLanguageManifest, isLanguageExcludedPath, isLanguageSource, readExplicitExports, WALK_IGNORE_GLOBS, impactedFiles, buildImportGraph, importClosure } from './language/discovery.js';
 
 const DEP_FILE_NAMES = new Set([
@@ -77,8 +81,23 @@ const DEFAULT_IGNORE = [
   ...WALK_IGNORE_GLOBS,
 ];
 
-export async function readTree(root, { ignore = [] } = {}) {
-  const entries = await listFiles(root, { ignore: [...DEFAULT_IGNORE, ...ignore] });
+// Directory names a Git-scoped scan still refuses regardless of Git state:
+// dependency trees and Git's own metadata. The broader DEFAULT_IGNORE list
+// (vendor, test, bin, ...) does NOT apply in Git-scoped mode: tracked code is
+// not discarded because of its folder name (PRD FR 01).
+const GIT_SCOPE_SAFETY_IGNORE = ['**/node_modules/**', '**/.git/**'];
+
+export async function readTree(root, { ignore = [], gitScope = process.env.AGENTIC_SECURITY_GIT_SCOPE === '1', scope = {} } = {}) {
+  let entries;
+  let inventory = null;
+  if (gitScope) {
+    // One inventory decides eligibility before any content is read.
+    inventory = buildScanInventory(root, scope);
+    const drop = [...GIT_SCOPE_SAFETY_IGNORE, ...ignore];
+    entries = inventory.included.filter((rel) => !drop.some((g) => path.matchesGlob(rel, g)));
+  } else {
+    entries = await listFiles(root, { ignore: [...DEFAULT_IGNORE, ...ignore] });
+  }
   const fileContents = {};
   const depFileContents = {};
   const oversize = [];
@@ -104,6 +123,7 @@ export async function readTree(root, { ignore = [] } = {}) {
     else if (/\.proto$/i.test(base)) depFileContents[rel] = content;
     else if (/\.(?:graphql|gql)$/i.test(base)) depFileContents[rel] = content;
     else if (/\.tf$/i.test(base)) depFileContents[rel] = content;
+    else if (/^(?:BUCK|TARGETS)(?:\.v2)?$/.test(base) && /\bhaskell_|prebuilt_haskell_library/.test(content)) depFileContents[rel] = content;
     // A Kubernetes manifest is admitted on CONTENT, not on living under a
     // directory named k8s/ — see isKubernetesManifest. Without this the
     // k8s-admission detector is wired into the dispatch and never invoked by it.
@@ -113,7 +133,7 @@ export async function readTree(root, { ignore = [] } = {}) {
     // A CloudFormation template is a `.yaml`/`.json` that no path predicate can
     // recognise — same problem as a Kubernetes manifest, same fix, and the same
     // requirement that BOTH gates open: runFullScan re-filters this exact list.
-    if (shouldScan(rel) || isKubernetesManifest(rel, content) || isCloudFormationTemplate(rel, content) || isInstructionFile(rel)) fileContents[rel] = content;
+    if (shouldScan(rel, !!gitScope) || isKubernetesManifest(rel, content) || isCloudFormationTemplate(rel, content) || isInstructionFile(rel)) fileContents[rel] = content;
     // Auxiliary files: .properties files are referenced by Java rules
     // (e.g. OWASP Benchmark's benchmark.properties resolves algorithm
     // aliases). They are not scannable for vulns themselves, but the
@@ -127,7 +147,7 @@ export async function readTree(root, { ignore = [] } = {}) {
     const { contents } = readExplicitExports(root, manifests);
     for (const [rel, text] of Object.entries(contents)) depFileContents[rel] = text;
   } catch { /* exports are best-effort evidence */ }
-  return { fileContents, depFileContents, oversize };
+  return { fileContents, depFileContents, oversize, inventory };
 }
 
 // Feat-10: incremental scan via `--changed-since <git-ref>`. Returns the set of
@@ -174,6 +194,16 @@ export async function languageFilesIgnoredByPolicy(root, fileContents, depFileCo
   return all.filter((rel) => (isLanguageSource(rel) || isLanguageManifest(rel)) && !isLanguageExcludedPath(rel) && !seen.has(rel)).sort().slice(0, 500);
 }
 
+// FR 02: an explicit package layout for Buck or custom builds, `{ "packages": { "name": ["dir", ...] } }`.
+// Read as data only; nothing in the map is executed and the build is not run.
+function loadHaskellSourceMap(file, root) {
+  if (!file) return null;
+  const abs = path.resolve(root, file);
+  const doc = JSON.parse(fsSync.readFileSync(abs, 'utf8'));
+  if (!doc || typeof doc !== 'object' || !doc.packages || typeof doc.packages !== 'object') throw new Error(`Haskell source map ${file} must be {"packages": {"<name>": ["<dir>", ...]}}`);
+  return { packages: doc.packages, file: path.relative(root, abs) };
+}
+
 export async function runScan(rootDir, opts = {}) {
   const root = path.resolve(rootDir);
   const startedAt = new Date().toISOString();
@@ -202,6 +232,7 @@ export async function runScan(rootDir, opts = {}) {
   // false claim of coverage.
   let completeScan = true;
   let sizeSkipped = [];
+  let scopeInventory = null;
   if (opts.fileContents) {
     // Caller-supplied file list (MCP `scan_diff`, the LSP's on-save scan): by
     // construction a subset of the tree, not a scan of it.
@@ -209,7 +240,7 @@ export async function runScan(rootDir, opts = {}) {
     depFileContents = opts.depFileContents || {};
     completeScan = false;
   } else {
-    ({ fileContents, depFileContents, oversize: sizeSkipped } = await readTree(root, opts));
+    ({ fileContents, depFileContents, oversize: sizeSkipped, inventory: scopeInventory } = await readTree(root, opts));
   }
 
   // Haskell/Nix sources under a default-ignored directory (tests, specs, mocks, bin, build, dist, vendor) are not
@@ -254,10 +285,33 @@ export async function runScan(rootDir, opts = {}) {
 
   // R8: `resume` is opt-in. Left undefined here, runFullScan falls back to the
   // AGENTIC_SECURITY_RESUME=1 env var, which is off by default.
-  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume, deep: opts.deep, deepInCi: opts.deepInCi, completeScan, policyExcluded, sizeSkipped }, opts.onProgress || (()=>{}));
+  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume, deep: opts.deep, deepInCi: opts.deepInCi, completeScan, policyExcluded, sizeSkipped, haskellSourceMap: loadHaskellSourceMap(opts.haskellSourceMap, root), gitScope: !!scopeInventory }, opts.onProgress || (()=>{}));
   // Premortem 2R4.2: stamp ruleset version + source on the scan result, and
   // notify if the operator pinned a different version than what's installed.
   try { stampScan(root, scan); } catch {}
+  // FR 01: additive scope record (never replaces an existing field). Skipped paths are
+  // capped; the counts are exact.
+  if (scopeInventory) {
+    const reasons = {};
+    for (const x of scopeInventory.skipped) reasons[x.reason] = (reasons[x.reason] || 0) + 1;
+    scan.scope = {
+      schema: 1,
+      policy: scopeInventory.policy,
+      includedCount: scopeInventory.included.length,
+      // The included list itself lets a later comparison tell "no longer reported because it was fixed" from "no longer reported
+      // because a narrower scan did not look". Kept only when small enough not to bloat the record.
+      ...(scopeInventory.included.length <= 5000 ? { included: scopeInventory.included } : { includedOmitted: true }),
+      skippedCount: scopeInventory.skipped.length,
+      skippedByReason: reasons,
+      skipped: scopeInventory.skipped.slice(0, 500),
+      overrides: scopeInventory.overrides,
+      coverageConditions: scopeInventory.skipped.filter((x) => x.coverageCondition).slice(0, 100),
+    };
+  }
+  // FR 10: additive evidence contract. Finding records carry the source hash and span; the scan record ties the run to a commit,
+  // dirty-file digests, the ignore-policy digest and the invocation. Neither replaces an existing field.
+  try { annotateFindingRecords(scan.findings, fileContents, { engineVersion: SCANNER_VERSION }); } catch {}
+  try { scan.scanRecord = buildScanRecord({ root, scan, meta: { mode: opts.changedSince ? 'incremental' : 'full', durationMs: Date.now() - t0 }, argv: opts.invocation || [], engineVersion: SCANNER_VERSION }); } catch {}
   // Append snapshot to history for /security-trend (non-blocking, never throws)
   try { appendScanSnapshot(scan, root); } catch {}
   return {

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