@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/dist/security-runtime/src/checks/malware/index.mjs

@@ -0,0 +1,186 @@
+// malware (REQ-018): antivirus plus YARA over the working tree, dependency folders, build output and configured artifacts.
+// Engines: Microsoft Defender on Windows (MpCmdRun custom scan), ClamAV on Linux when installed, and YARA-X with the pinned YARA Forge
+// core package everywhere (in a Linux container on Windows; see yara.mjs). An antivirus detection is a Critical, blocking finding.
+// YARA severity (REQ-037): YARA Forge rules carry a `score` meta (0 to 100). A YARA-only detection scored below 70 is a heuristic: Medium
+// and non-blocking. It stays Critical and blocking when the score is 70 or more (or missing), when an antivirus engine also flags the
+// file, or when two distinct YARA rules match the same file.
+// The check needs at least one engine to finish; a missing or failed engine is named in the reason and in evidence.
+import path from 'node:path';
+import { CLAMAV_TIMEOUT_MS, clamscanArgs, parseClamav } from './clamav.mjs';
+import { DEFENDER_TIMEOUT_MS, defenderArgs, findDefender, parseDefender } from './defender.mjs';
+import { avTargets, resolveArtifacts, selectForYara, walkTree, YARA_FILTER } from './targets.mjs';
+import { runYara } from './yara.mjs';
+
+export const id = 'malware';
+export const title = 'Malware (antivirus and YARA)';
+export const modes = ['deep', 'release'];
+export const requiredIn = ['deep', 'release'];
+// Run after project scripts so newly-created build output is included in the tree walk.
+export const phase = 2;
+export const timeoutSec = 2700;
+export const applies = () => true;
+
+const FIX = 'Do not ship this file. Remove it, or rebuild it from a trusted source, and find how it got into the tree or build. If the machine that built it may be compromised, rotate its secrets. If you have verified a false positive, Richard records it in vsg.accept.json.';
+const HEURISTIC_FIX = 'This is a low-score YARA heuristic that no antivirus engine confirmed, so it does not block. Check the file: if it is ordinary code that matches a generic pattern, leave it; if you do not recognize it, treat it as malware. Richard can record a verified false positive in vsg.accept.json.';
+const DOCKER_ENV = ['DOCKER_HOST', 'DOCKER_CONTEXT', 'DOCKER_CONFIG'];
+
+const toRel = (repo, file) => {
+  const rel = path.relative(repo, file);
+  return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel.split(path.sep).join('/') : file.split(path.sep).join('/');
+};
+
+export const YARA_BLOCKING_SCORE = 70;
+/** The YARA Forge `score` meta as a number, or null when absent or not numeric. */
+export const yaraScore = (meta) => { const n = Number(meta?.score); return meta?.score !== undefined && meta?.score !== '' && Number.isFinite(n) ? n : null; };
+
+/** Supplied YARA author identification as single-line text, or null when absent. Author identities are never truncated. */
+const yaraAuthor = (meta) => typeof meta?.author === 'string' && meta.author.trim()
+  ? meta.author.replace(/\s+/g, ' ').trim()
+  : null;
+
+/**
+ * Severity for one YARA match. `others` is the number of distinct YARA rules matching the same file, `avAgrees` whether an antivirus
+ * engine flagged it. Returns { severity, heuristic, why }.
+ */
+export function yaraSeverity(score, { others, avAgrees }) {
+  if (avAgrees) return { severity: 'critical', heuristic: false, why: 'an antivirus engine also detected this file' };
+  if (others >= 2) return { severity: 'critical', heuristic: false, why: `${others} distinct YARA rules matched this file` };
+  if (score === null) return { severity: 'critical', heuristic: false, why: 'the rule has no score, so it is treated as a signature' };
+  if (score >= YARA_BLOCKING_SCORE) return { severity: 'critical', heuristic: false, why: `rule score ${score} is ${YARA_BLOCKING_SCORE} or more` };
+  return { severity: 'medium', heuristic: true, why: `rule score ${score} is below ${YARA_BLOCKING_SCORE} and nothing else corroborates it` };
+}
+
+function rawFinding({ engine, signature, file, description, confidence, severity = 'critical', heuristic = false }) {
+  return {
+    category: 'malware', severity, confidence, tool: engine, ruleId: signature, key: `${engine}:${signature}`,
+    title: heuristic ? `Malware heuristic from ${engine}: ${signature}` : `Malware detected by ${engine}: ${signature}`,
+    description: description ?? `${engine} reported the signature or rule "${signature}" for this file.`,
+    location: { file }, evidence: `engine: ${engine}\nsignature: ${signature}\nfile: ${file}${heuristic ? '\nclassification: heuristic (does not block)' : ''}`, fix: heuristic ? HEURISTIC_FIX : FIX,
+  };
+}
+
+/** Microsoft Defender over each target. Returns { status: 'ran'|'failed', detections, durationMs, reason, targets }. */
+async function runDefender(ctx, mp, targets) {
+  const started = Date.now();
+  const detections = [];
+  for (const target of targets) {
+    const left = DEFENDER_TIMEOUT_MS - (Date.now() - started);
+    if (left <= 0) return { status: 'failed', reason: 'Defender time budget (30 min) was used up', detections, targets: targets.length, durationMs: Date.now() - started };
+    const r = await ctx.runProcess({ command: mp, args: defenderArgs(target), timeoutMs: left });
+    if (r.status !== 'ran') return { status: 'failed', reason: `Defender ${r.reason}`, detections, targets: targets.length, durationMs: Date.now() - started };
+    const p = parseDefender(`${r.stdout}\n${r.stderr}`, r.exitCode, target);
+    if (p.status === 'error') return { status: 'failed', reason: `${p.reason} (${toRel(ctx.repo, target)})`, detections, targets: targets.length, durationMs: Date.now() - started };
+    for (const t of p.threats) for (const f of t.files.length ? t.files : [target]) detections.push({ signature: t.name, file: f });
+  }
+  return { status: 'ran', detections, targets: targets.length, durationMs: Date.now() - started };
+}
+
+async function runClamav(ctx, targets) {
+  const started = Date.now();
+  const r = await ctx.runProcess({ command: 'clamscan', args: clamscanArgs(targets), cwd: ctx.repo, timeoutMs: CLAMAV_TIMEOUT_MS });
+  if (r.status !== 'ran') return { status: 'failed', reason: `ClamAV ${r.reason}`, detections: [], targets: targets.length, durationMs: Date.now() - started };
+  const p = parseClamav(r.stdout, r.stderr, r.exitCode);
+  if (p.status === 'error') return { status: 'failed', reason: p.reason, detections: [], targets: targets.length, durationMs: Date.now() - started };
+  return { status: 'ran', detections: p.detections.map((d) => ({ signature: d.signature, file: d.file })), targets: targets.length, durationMs: Date.now() - started };
+}
+
+/** deps lets tests replace the engines: { platform, findDefender, runYara }. */
+export async function run(ctx, deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const yara = deps.runYara ?? runYara;
+  const repo = ctx.repo;
+  const t0 = Date.now();
+
+  const outRel = ctx.out ? toRel(repo, ctx.out) : '.vsg';
+  const nested = (ctx.nestedRepos ?? []).map((n) => n.path); // other checkouts inside the tree: not part of this repository
+  const skip = ['.vsg', ...(outRel.startsWith('..') || path.isAbsolute(outRel) ? [] : [outRel])];
+  const artifacts = resolveArtifacts(repo, ctx.config?.artifacts ?? []);
+  const files = walkTree(repo, { skip: [...skip, ...nested] });
+  const sel = selectForYara(repo, files, artifacts.inside);
+  const walkMs = Date.now() - t0;
+
+  const engines = {};
+  const missing = [];
+  let avFailed = false; // an antivirus engine that started but did not finish: nothing can be said about a clean result
+  const findings = [];
+  const add = (f) => findings.push(rawFinding(f));
+  const avTargetList = [...avTargets(repo, { skip, nested }), ...artifacts.outside];
+
+  // antivirus
+  if (platform === 'win32') {
+    const mp = deps.findDefender ? deps.findDefender() : findDefender();
+    if (!mp) missing.push('Microsoft Defender (MpCmdRun.exe was not found)');
+    else {
+      const d = await runDefender(ctx, mp, avTargetList);
+      engines.defender = { status: d.status, targets: d.targets, detections: d.detections.length, durationMs: d.durationMs, ...(d.reason ? { reason: d.reason } : {}) };
+      if (d.status === 'failed') { avFailed = true; missing.push(`Microsoft Defender did not finish: ${d.reason}`); }
+      for (const x of d.detections) add({ engine: 'Microsoft Defender', signature: x.signature, file: toRel(repo, x.file), confidence: 'high' });
+    }
+  } else if (platform === 'linux') {
+    const probe = await ctx.runProcess({ command: 'clamscan', args: ['--version'], timeoutMs: 15_000 });
+    if (probe.status !== 'ran' || probe.exitCode !== 0) missing.push('ClamAV (clamscan is not installed; install it and run freshclam)');
+    else {
+      const c = await runClamav(ctx, avTargetList.map((t) => toRel(repo, t)));
+      engines.clamav = { status: c.status, targets: c.targets, detections: c.detections.length, durationMs: c.durationMs, version: probe.stdout.trim().split('\n')[0], ...(c.reason ? { reason: c.reason } : {}) };
+      if (c.status === 'failed') { avFailed = true; missing.push(`ClamAV did not finish: ${c.reason}`); }
+      for (const x of c.detections) add({ engine: 'ClamAV', signature: x.signature, file: toRel(repo, path.resolve(repo, x.file)), confidence: 'high' });
+    }
+  } else missing.push(`an antivirus engine (none is supported on ${platform})`);
+
+  // YARA
+  const y = await yara({ ...ctx, runProcess: (o) => ctx.runProcess({ envNames: DOCKER_ENV, ...o }) }, { root: repo, files: sel.list });
+  if (y.status === 'ran') {
+    engines.yara = { status: 'ran', mode: y.mode, filesScanned: y.scanned, scanErrors: y.scanErrors, matches: y.matches.length, forge: { total: y.forge.total, compiled: y.forge.compiled, excluded: y.forge.excluded.length, dropped: y.forge.dropped.length, cached: y.forge.cached }, durationMs: y.durationMs };
+    const avFiles = new Set(findings.map((f) => f.location.file.toLowerCase()));
+    const rulesByFile = new Map();
+    const yfile = (m) => toRel(repo, path.resolve(repo, m.file));
+    for (const m of y.matches) {
+      const k = yfile(m).toLowerCase();
+      if (!rulesByFile.has(k)) rulesByFile.set(k, new Set());
+      rulesByFile.get(k).add(`${m.namespace}:${m.rule}`);
+    }
+    let heuristics = 0;
+    for (const m of y.matches) {
+      const where = `${m.namespace ? `${m.namespace}:` : ''}${m.rule}`;
+      const file = yfile(m);
+      const score = yaraScore(m.meta);
+      const author = yaraAuthor(m.meta);
+      const sev = yaraSeverity(score, { others: rulesByFile.get(file.toLowerCase()).size, avAgrees: avFiles.has(file.toLowerCase()) });
+      if (sev.heuristic) heuristics++;
+      add({
+        engine: 'YARA', signature: where, file, confidence: 'medium', severity: sev.severity, heuristic: sev.heuristic,
+        description: `YARA rule "${m.rule}" matched${m.meta?.description ? `: ${String(m.meta.description).slice(0, 200)}` : ''}${author ? ` (author: ${author})` : ''}${m.tags?.length ? ` (tags: ${m.tags.join(', ')})` : ''}. Rule score ${score ?? 'unknown'}; ${sev.heuristic ? 'heuristic, does not block' : 'blocking'} because ${sev.why}.`,
+      });
+    }
+    engines.yara.heuristicOnly = heuristics;
+    engines.yara.severityPolicy = `YARA-only matches scored below ${YARA_BLOCKING_SCORE} are Medium and non-blocking; a score of ${YARA_BLOCKING_SCORE} or more, an antivirus detection on the same file, or two distinct YARA rules on one file stay Critical`;
+  } else {
+    engines.yara = { status: 'not_run', reason: y.reason };
+    missing.push(`YARA did not run: ${y.reason}`);
+  }
+
+  const evidence = {
+    engines, missingEngines: missing,
+    scope: {
+      filesWalked: files.length, avTargets: avTargetList.length, yaraFiles: sel.counts.selected, yaraArtifactFiles: sel.counts.artifacts, yaraSkippedLarge: sel.counts.skippedLarge,
+      artifactsConfigured: ctx.config?.artifacts ?? [], artifactsMissing: artifacts.missing, artifactsOutsideRepoAvOnly: artifacts.outside.length, walkMs, totalMs: Date.now() - t0,
+    },
+    yaraFilter: YARA_FILTER,
+  };
+  const finished = Object.values(engines).filter((e) => e.status === 'ran').length;
+  if (!findings.length && (finished === 0 || avFailed)) return { status: 'not_run', reason: `Scanning did not complete:${missing.join('; ')}`, findings: [], evidence };
+  const reason = missing.length ? `Reduced coverage, not run: ${missing.join('; ')}` : '';
+  const toolVersion = [ctx.registry?.get('yara-x') && `yara-x ${ctx.registry.get('yara-x').version}`, engines.clamav?.version].filter(Boolean).join(', ') || null;
+  return {
+    status: 'ran', reason, findings, evidence, toolVersion,
+    dataVersions: ctx.selectedRuntime?.kind === 'lattice-artifact'
+      ? {
+        selectedYara: ctx.selectedRuntime.selectedRuntime.yara.selectionDigest.slice(0, 12),
+        selectedYaraRules: String(ctx.selectedRuntime.selectedRuntime.yara.selectedRuleIds.length),
+        excludedYaraHolds: String(ctx.selectedRuntime.selectedRuntime.yara.excludedRules.length),
+      }
+      : { yaraForge: ctx.registry?.get('yara-forge')?.version ?? null },
+  };
+}
+
+export default { id, title, modes, requiredIn, phase, timeoutSec, applies, run };

package/dist/security-runtime/src/checks/malware/targets.mjs

@@ -0,0 +1,147 @@
+// What the malware check scans: the working tree (.git only for hooks), dependency folders, build output and configured artifacts.
+// Antivirus engines scan the whole tree. YARA scans a file-type subset (YARA_FILTER) plus every file in configured artifacts.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEP_DIRS = new Set(['node_modules', '.venv', 'venv', 'site-packages']);
+const BUILD_DIRS = new Set(['.next', 'dist', 'build', 'out']);
+const GENERATED = new Set([...DEP_DIRS, ...BUILD_DIRS]);
+export const YARA_MAX_FILE_BYTES = 100 * 1024 * 1024;
+const SCRIPT_BYTES_CAP = 5 * 1024 * 1024; // bundles and minified files above this are not worth rule-matching as scripts
+
+const EXECUTABLE = 'exe dll sys scr com msi msp cpl ocx drv efi so dylib ko o obj lib a node pyd jar war apk aab ipa dex class elf bin dat'.split(' ');
+const SCRIPT = 'bat cmd ps1 psm1 psd1 vbs vbe wsf wsh hta lnk pif sh bash zsh py pyw pl rb php php5 phtml jsp jspx asp aspx cgi lua'.split(' ');
+const JS = ['js', 'mjs', 'cjs'];
+const ARCHIVE = 'zip 7z rar gz tgz bz2 xz tar cab iso img dmg vhd vhdx rpm deb'.split(' ');
+const OFFICE = 'doc docm dot dotm xls xlsm xlsb ppt pptm rtf chm'.split(' ');
+const KNOWN = new Set([...EXECUTABLE, ...SCRIPT, ...JS, ...ARCHIVE, ...OFFICE]);
+const SNIFF_EXT = new Set(['', 'bin', 'dat', 'tmp', 'out']);
+
+/** Human-readable statement of the YARA file-type filter (recorded in every run's evidence). */
+export const YARA_FILTER = 'YARA runs on executables and libraries, scripts, archives, Office/CHM files and extensionless or .bin/.dat/.tmp files whose first bytes are an executable, script or archive signature, plus every file in configured artifacts. JavaScript files (.js, .mjs, .cjs) are included outside dependency and build folders when 5 MB or smaller. Text, images, JSON, Markdown and source such as .ts are not scanned by YARA. Files over 100 MB are skipped.';
+
+const posix = (p) => p.split(path.sep).join('/');
+const extOf = (rel) => path.posix.extname(rel).slice(1).toLowerCase();
+
+/** Walks a directory without following symlinks. Skips .git (but not .git/hooks) and the given relative directories. Returns [{ rel }]. */
+export function walkTree(root, { skip = [], start = '' } = {}) {
+  const skipSet = new Set(skip);
+  const files = [];
+  const walk = (rel) => {
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (skipSet.has(r)) continue;
+        if (r === '.git') { if (fs.existsSync(path.join(root, '.git', 'hooks'))) walk('.git/hooks'); continue; }
+        walk(r);
+      } else if (e.isFile()) files.push(r);
+    }
+  };
+  if (start) {
+    let st;
+    try { st = fs.lstatSync(path.join(root, start)); } catch { return files; }
+    if (st.isFile()) return [start];
+    if (st.isSymbolicLink()) return files;
+  }
+  walk(start);
+  return files;
+}
+
+/** True when the first bytes look like an executable, script or archive. */
+function sniff(abs) {
+  let fd;
+  try {
+    fd = fs.openSync(abs, 'r');
+    const b = Buffer.alloc(8);
+    const n = fs.readSync(fd, b, 0, 8, 0);
+    if (n < 2) return false;
+    const hex = b.subarray(0, n).toString('hex');
+    return b[0] === 0x4d && b[1] === 0x5a // MZ
+      || hex.startsWith('7f454c46') // ELF
+      || hex.startsWith('2321') // #!
+      || /^(cafebabe|feedface|feedfacf|cefaedfe|cffaedfe)/.test(hex) // Mach-O, universal
+      || hex.startsWith('504b0304') || hex.startsWith('1f8b') || hex.startsWith('377abcaf') || hex.startsWith('526172');
+  } catch { return false; } finally { if (fd !== undefined) try { fs.closeSync(fd); } catch { /* ignore */ } }
+}
+
+/**
+ * Chooses the files YARA scans. `files` are root-relative posix paths, `artifactFiles` the subset that are configured artifacts.
+ * Returns { list, counts: { total, selected, artifacts, skippedLarge } }.
+ */
+export function selectForYara(root, files, artifactFiles = new Set()) {
+  const list = [];
+  const counts = { total: files.length, selected: 0, artifacts: 0, skippedLarge: 0 };
+  for (const rel of files) {
+    const isArtifact = artifactFiles.has(rel);
+    const ext = extOf(rel);
+    const generated = rel.split('/').some((seg) => GENERATED.has(seg));
+    let pick = isArtifact;
+    if (!pick) {
+      if (JS.includes(ext)) pick = !generated;
+      else if (KNOWN.has(ext) && !['bin', 'dat'].includes(ext)) pick = true;
+      else if (SNIFF_EXT.has(ext)) pick = sniff(path.join(root, rel));
+    }
+    if (!pick) continue;
+    let size = 0;
+    try { size = fs.statSync(path.join(root, rel)).size; } catch { continue; }
+    if (size > YARA_MAX_FILE_BYTES) { counts.skippedLarge++; continue; }
+    if (!isArtifact && JS.includes(ext) && size > SCRIPT_BYTES_CAP) continue;
+    list.push(rel);
+    counts.selected++;
+    if (isArtifact) counts.artifacts++;
+  }
+  return { list, counts };
+}
+
+/**
+ * Resolves vsg.config.json "artifacts" (files or directories, relative to the repository). Returns
+ * { inside: [root-relative files], insideEntries, outside: [absolute paths], missing: [configured value] }.
+ */
+export function resolveArtifacts(repo, artifacts = []) {
+  const inside = new Set();
+  const insideEntries = [];
+  const outside = [];
+  const missing = [];
+  for (const a of artifacts) {
+    const abs = path.resolve(repo, a);
+    if (!fs.existsSync(abs)) { missing.push(a); continue; }
+    const rel = posix(path.relative(repo, abs));
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) { outside.push(abs); continue; }
+    insideEntries.push(rel);
+    for (const f of walkTree(repo, { start: rel })) inside.add(f);
+  }
+  return { inside, insideEntries, outside, missing };
+}
+
+/**
+ * Paths handed to antivirus engines (absolute). With a .git directory each top-level entry is scanned separately so .git is skipped
+ * (except .git/hooks); output and .vsg directories are skipped too. `skip` and `nested` are root-relative paths; engines scan a directory
+ * recursively, so a directory that holds a nested repository or worktree is replaced by its entries, level by level, until that path is left out.
+ */
+export function avTargets(repo, { skip = [], nested = [] } = {}) {
+  const skipSet = new Set(['.vsg', ...skip, ...nested]);
+  const ancestors = new Set();
+  for (const p of nested) for (let i = p.indexOf('/'); i > 0; i = p.indexOf('/', i + 1)) ancestors.add(p.slice(0, i));
+  let entries;
+  try { entries = fs.readdirSync(repo, { withFileTypes: true }); } catch { return [repo]; }
+  if (!entries.some((e) => e.name === '.git') && !nested.length) return [repo];
+  const targets = [];
+  const expand = (rel, list) => {
+    for (const e of list) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isSymbolicLink() || skipSet.has(r) || (!rel && e.name === '.git')) continue;
+      if (e.isDirectory() && ancestors.has(r)) {
+        let inner;
+        try { inner = fs.readdirSync(path.join(repo, r), { withFileTypes: true }); } catch { continue; }
+        expand(r, inner);
+      } else targets.push(path.join(repo, r));
+    }
+  };
+  expand('', entries);
+  const hooks = path.join(repo, '.git', 'hooks');
+  if (fs.existsSync(hooks)) targets.push(hooks);
+  return targets;
+}

package/dist/security-runtime/src/checks/malware/yara-runner.mjs

@@ -0,0 +1,201 @@
+// YARA runner for the malware check. Runs on Linux only: natively on a Linux host, or inside the pinned Linux container on Windows
+// (so no compiled rules and no extracted rule source ever touch the Windows disk, where Defender quarantines them).
+//
+//   node yara-runner.mjs --yr <yr binary> --forge <forge zip> --root <dir to scan> [--cache <dir>] [--extra <rules file>] [--work <dir>]
+//
+// stdin: JSON { files: [paths relative to --root], excludeRules: [{ rule, reason }], maxFileBytes, timeoutSec }
+// stdout: one JSON line { ok, error?, forge: { total, compiled, excluded, dropped, cached }, matches, scanned, scanErrors, durationMs }.
+//
+// The YARA Forge package contains the EICAR test string in one rule. Any rule block that contains it is removed before the
+// source is written anywhere, so the string never reaches a file. Everything is written to --work (a container /tmp) or --cache.
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { listZip } from '../../core/archive.mjs';
+
+// the marker is assembled so this file does not contain the full test string, only its start
+const EICAR_TEXT = new RegExp(`${'X5O!P'}%@AP`);
+const EICAR_HEX = /58\s*35\s*4[fF]\s*21\s*50\s*25\s*40\s*41\s*50/;
+const RULE_START = /^(?=(?:(?:private|global)\s+)*rule\s+\w+)/m;
+const RULE_NAME = /^(?:(?:private|global)\s+)*rule\s+(\w+)/m;
+const sha = (b) => crypto.createHash('sha256').update(b).digest('hex');
+const CANDIDATE_DECISIONS = new Set(['candidate-attribution', 'candidate-attribution-sharealike', 'candidate-explicit-apache']);
+const canonical = (value) => {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+};
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > 0 ? process.argv[i + 1] : undefined;
+}
+const readStdin = () => { try { return fs.readFileSync(0, 'utf8'); } catch { return ''; } };
+const run = (cmd, args, o = {}) => spawnSync(cmd, args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, ...o });
+
+/** Splits rule source into blocks and removes excluded ones. Returns { text, total, excluded: [{ rule, reason }] }. */
+export function filterRules(source, excludeNames = new Map()) {
+  const blocks = source.split(RULE_START);
+  const excluded = [];
+  let total = 0;
+  const kept = blocks.filter((b) => {
+    const m = RULE_NAME.exec(b);
+    if (!m) return true; // header comments and imports
+    total++;
+    if (EICAR_TEXT.test(b) || EICAR_HEX.test(b)) { excluded.push({ rule: m[1], reason: 'contains the EICAR test string; excluded by vsg safety policy' }); return false; }
+    if (excludeNames.has(m[1])) { excluded.push({ rule: m[1], reason: excludeNames.get(m[1]) }); return false; }
+    return true;
+  });
+  return { text: kept.join(''), total, excluded };
+}
+
+/** Rules that `yr compile --ignore-invalid-rules` reports as ignored: "  - Name: error: ...". */
+export function ignoredRules(stderr) {
+  const out = [];
+  const at = stderr.indexOf('the following rules were ignored');
+  if (at < 0) return out;
+  for (const line of stderr.slice(at).split('\n').slice(1)) {
+    const m = /^\s+-\s+(\S+?):\s*(.*)$/.exec(line);
+    if (m) out.push({ rule: m[1], reason: m[2].trim().slice(0, 200) });
+  }
+  return out;
+}
+
+/** Maps `yr scan -o ndjson` lines to { file, rule, namespace, tags, meta }. */
+export function parseNdjson(stdout) {
+  const matches = [];
+  for (const line of stdout.split('\n')) {
+    if (!line.trim()) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    for (const r of o.rules ?? []) {
+      const meta = Object.fromEntries(Array.isArray(r.meta) ? r.meta : Object.entries(r.meta ?? {}));
+      matches.push({ file: o.path, rule: r.identifier, namespace: r.namespace ?? '', tags: r.tags ?? [], meta });
+    }
+  }
+  return matches;
+}
+
+function normalizedRule(rule) {
+  return {
+    rule: rule.rule, blockSha256: rule.blockSha256, author: rule.author, sourceUrl: rule.sourceUrl,
+    candidateLicense: rule.candidateLicense, decision: rule.decision, licenseMetadata: rule.licenseMetadata,
+  };
+}
+
+/** Verifies every source block and derives the exact frozen selected/held identities inside Linux. */
+export function verifySelectedInventory({ forgeZip, inventoryPath, expectedSelectionDigest, expectedHoldDigest }) {
+  const zip = fs.readFileSync(forgeZip);
+  const inventory = JSON.parse(fs.readFileSync(inventoryPath, 'utf8'));
+  if (inventory.archiveVersion !== '20260927' || inventory.archiveSha256 !== sha(zip)
+    || inventory.totalRules !== 5110 || !Array.isArray(inventory.rules) || inventory.rules.length !== 5110) {
+    throw new Error('Selected YARA inventory identity does not match the mounted source archive.');
+  }
+  const blocks = new Map();
+  for (const entry of listZip(zip).filter((item) => !item.dir && /\.ya?ra?$/i.test(item.name))) {
+    for (const block of entry.data().toString('utf8').split(RULE_START)) {
+      const match = RULE_NAME.exec(block);
+      if (!match) continue;
+      if (blocks.has(match[1])) throw new Error(`Selected YARA source contains duplicate rule ${match[1]}.`);
+      blocks.set(match[1], block.replace(/\r\n/g, '\n'));
+    }
+  }
+  if (blocks.size !== inventory.rules.length) throw new Error('Selected YARA source rule count does not match the inventory.');
+  for (const rule of inventory.rules) {
+    const block = blocks.get(rule.rule);
+    if (!block || sha(Buffer.from(block, 'utf8')) !== rule.blockSha256) throw new Error(`Selected YARA source block changed for ${rule.rule}.`);
+  }
+  const selected = inventory.rules.filter((rule) => CANDIDATE_DECISIONS.has(rule.decision)).map(normalizedRule).sort((a, b) => a.rule.localeCompare(b.rule));
+  const held = inventory.rules.filter((rule) => !CANDIDATE_DECISIONS.has(rule.decision)).map(normalizedRule).sort((a, b) => a.rule.localeCompare(b.rule));
+  const selectionDigest = sha(Buffer.from(canonical(selected)));
+  const holdDigest = sha(Buffer.from(canonical(held)));
+  if (selected.length !== 4536 || held.length !== 574 || selectionDigest !== expectedSelectionDigest || holdDigest !== expectedHoldDigest) {
+    throw new Error('Selected YARA selection or hold identity changed.');
+  }
+  return {
+    selected: selected.map((rule) => rule.rule),
+    excluded: held.map((rule) => ({ rule: rule.rule, reason: `frozen selection hold: ${rule.decision}` })),
+    selectionDigest,
+    holdDigest,
+  };
+}
+
+function prepareForge({ yr, forgeZip, cacheDir, workDir, excludeNames, extra, strict = false }) {
+  const zip = fs.readFileSync(forgeZip);
+  const key = sha(Buffer.concat([zip, Buffer.from(JSON.stringify([...excludeNames])), Buffer.from(sha(fs.readFileSync(yr)))])).slice(0, 16);
+  const cachedRules = cacheDir && !extra ? path.join(cacheDir, `forge-${key}.yarc`) : null;
+  const cachedReport = cachedRules ? `${cachedRules}.json` : null;
+  if (cachedRules && fs.existsSync(cachedRules) && fs.existsSync(cachedReport)) {
+    return { rules: cachedRules, report: { ...JSON.parse(fs.readFileSync(cachedReport, 'utf8')), cached: true } };
+  }
+  const entries = listZip(zip).filter((e) => !e.dir && /\.ya?ra?$/i.test(e.name));
+  if (!entries.length) throw new Error('the YARA Forge package contains no .yar rule file');
+  const sources = [];
+  let total = 0;
+  const excluded = [];
+  entries.forEach((e, i) => {
+    const f = filterRules(e.data().toString('utf8'), excludeNames);
+    total += f.total;
+    excluded.push(...f.excluded);
+    const file = path.join(workDir, `forge-${i}.yar`);
+    fs.writeFileSync(file, f.text);
+    sources.push(`forge${i}:${file}`);
+  });
+  if (extra) sources.push(`custom:${extra}`);
+  const out = cachedRules ?? path.join(workDir, 'rules.yarc');
+  let c = run(yr, ['compile', '-w', '-o', out, ...sources]);
+  let dropped = [];
+  if (c.status !== 0) {
+    if (strict) throw new Error(`YARA-X could not strictly compile the selected rules: ${String(c.stderr).split('\n').find((l) => l.startsWith('error')) ?? `exit ${c.status}`}`);
+    c = run(yr, ['compile', '-w', '--ignore-invalid-rules', '-o', out, ...sources]);
+    if (c.status !== 0) throw new Error(`YARA-X could not compile the rules: ${String(c.stderr).split('\n').find((l) => l.startsWith('error')) ?? `exit ${c.status}`}`);
+    dropped = ignoredRules(c.stderr);
+  }
+  const report = { total, compiled: total - excluded.length - dropped.length, excluded, dropped, cached: false };
+  if (cachedReport) fs.writeFileSync(cachedReport, JSON.stringify(report));
+  return { rules: out, report };
+}
+
+function main() {
+  const started = Date.now();
+  try {
+    const yrIn = arg('yr');
+    const root = arg('root');
+    const input = JSON.parse(readStdin() || '{}');
+    const work = fs.mkdtempSync(path.join(arg('work') ?? os.tmpdir(), 'vsg-yara-'));
+    // a copy that is executable even when the source is a read-only bind mount from a Windows host
+    const yr = path.join(work, 'yr');
+    fs.copyFileSync(yrIn, yr);
+    fs.chmodSync(yr, 0o755);
+    const cache = arg('cache');
+    if (cache) fs.mkdirSync(cache, { recursive: true });
+    let exclusions = input.excludeRules ?? [];
+    let selection = null;
+    if (arg('inventory')) {
+      selection = verifySelectedInventory({
+        forgeZip: arg('forge'), inventoryPath: arg('inventory'),
+        expectedSelectionDigest: input.selectionDigest, expectedHoldDigest: input.holdDigest,
+      });
+      if (canonical(exclusions) !== canonical(selection.excluded)) throw new Error('Selected YARA exclusions differ from the frozen hold inventory.');
+    }
+    const excludeNames = new Map(exclusions.map((e) => [e.rule, e.reason]));
+    const { rules, report } = prepareForge({ yr, forgeZip: arg('forge'), cacheDir: cache, workDir: work, excludeNames, extra: arg('extra'), strict: Boolean(arg('inventory')) });
+    if (selection && (report.total !== 5110 || report.compiled !== 4536 || report.excluded.length !== 574 || report.dropped.length !== 0)) {
+      throw new Error('Selected YARA runtime counts differ from the frozen selection.');
+    }
+    const list = path.join(work, 'files.txt');
+    fs.writeFileSync(list, `${(input.files ?? []).join('\n')}\n`);
+    const scan = run(yr, ['scan', '--scan-list', '-C', '-o', 'ndjson', '-m', '-g',...(input.maxFileBytes ? ['-z', String(input.maxFileBytes)] : []), rules, list], { cwd: root, timeout: (input.timeoutSec ?? 1200) * 1000 });
+    if (scan.error || scan.status !== 0) throw new Error(`yr scan failed: ${scan.error?.message ?? `exit ${scan.status}: ${String(scan.stderr).slice(0, 300)}`}`);
+    const scanErrors = String(scan.stderr).split('\n').filter((l) => l.startsWith('error')).length;
+    fs.rmSync(work, { recursive: true, force: true });
+    process.stdout.write(`${JSON.stringify({ ok: true, forge: { ...report, ...(selection ? { selectionDigest: selection.selectionDigest, holdDigest: selection.holdDigest } : {}) }, matches: parseNdjson(scan.stdout), scanned: (input.files ?? []).length, scanErrors, durationMs: Date.now() - started })}\n`);
+  } catch (e) {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: e.message, durationMs: Date.now() - started })}\n`);
+  }
+}
+
+import { fileURLToPath } from 'node:url';
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) main();