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

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

@@ -0,0 +1,124 @@
+// Host side of the YARA scan. YARA-X and the YARA Forge package are pinned registry entries; the work happens in yara-runner.mjs:
+// - Linux host: the runner runs natively; filtered and compiled rules are cached in the tools cache (never in the scanned repository).
+// - Any other host (Windows): the runner runs in the pinned Linux container with the YARA-X linux build, the rules zip, the vsg source
+//   and the scan target mounted read-only, no network, a read-only root and a tmpfs /tmp. Nothing is written to a host mount, so no
+//   compiled rules and no extracted rule source ever reach the host disk (where Defender quarantines them).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveTool } from '../../core/installer.mjs';
+import { defaultRegistryDir, packageRoot, platformKey, toolsDir } from '../../core/paths.mjs';
+import { YARA_MAX_FILE_BYTES } from './targets.mjs';
+import { assertStandaloneExecution } from '../../lattice/execution.mjs';
+import { withTransientDockerSource } from '../../lattice/source-acquirer.mjs';
+
+const RUNNER = path.join(packageRoot, 'src', 'checks', 'malware', 'yara-runner.mjs');
+export const YARA_TIMEOUT_SEC = 900;
+
+/** Rules recorded as excluded for the pinned YARA Forge release (tools/registry/yara-forge-exclusions.json). */
+export function loadExclusions(forgeVersion, dir = defaultRegistryDir) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(dir, 'yara-forge-exclusions.json'), 'utf8'));
+    return data.forgeVersion === forgeVersion && Array.isArray(data.excluded) ? data.excluded : [];
+  } catch { return []; }
+}
+
+const lastJson = (stdout) => {
+  for (const line of String(stdout).split('\n').reverse()) {
+    if (!line.startsWith('{')) continue;
+    try { return JSON.parse(line); } catch { /* keep looking */ }
+  }
+  return null;
+};
+
+/**
+ * Runs YARA over root-relative `files`. Returns
+ * { status: 'ran', mode, forge, matches, scanned, scanErrors, durationMs } or { status: 'not_run', reason }.
+ * Extra rules (a host file path) come from `extraRules`, used by tests and by VSG_YARA_EXTRA_RULES.
+ */
+export async function runYara(ctx, { root, files, extraRules, timeoutSec = YARA_TIMEOUT_SEC }) {
+  assertStandaloneExecution({ allowQualification: true });
+  if (ctx.selectedRuntime?.kind === 'lattice-artifact') {
+    const selected = ctx.selectedRuntime.selectedRuntime?.yara;
+    if (!selected) return { status: 'not_run', reason: 'The selected YARA runtime contract is missing; mixed-pack fallback is refused.' };
+    if (extraRules !== undefined || process.env.VSG_YARA_EXTRA_RULES) return { status: 'not_run', reason: 'Selected YARA runtime refuses caller and environment extra rules.' };
+    const yaraX = ctx.registry?.get('yara-x');
+    const runner = ctx.registry?.get('yara-runner');
+    const yr = yaraX ? resolveTool(yaraX) : null;
+    if (!yr || !runner?.image) return { status: 'not_run', reason: 'The verified YARA-X binary or pinned Linux runner image is unavailable. Run vsg setup --repair.' };
+    const timeoutMs = (timeoutSec + 240) * 1000;
+    try {
+      return await withTransientDockerSource(ctx, { image: runner.image, source: selected.source, label: 'yara' }, async ({ volume }) => {
+        const name = `vsg-selected-yara-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+        const inventory = path.join(ctx.selectedRuntime.root, ...selected.inventory.path.split('/'));
+        const args = [
+          'run', '--pull', 'never', '--rm', '--init', '-i', '--name', name, '--network', 'none', '--read-only', '--tmpfs', '/tmp:rw,exec,size=2g', '--memory', '4g', '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges',
+          '-v', `${path.join(packageRoot, 'src')}:/vsg/src:ro`, '-v', `${yr.path}:/vsg/in/yr:ro`,
+          '-v', `${inventory}:/vsg/in/inventory.json:ro`, '-v', `${volume}:/vsg/selected-source:ro`, '-v', `${root}:/scan:ro`,
+          '-w', '/scan', runner.image, 'node', '/vsg/src/checks/malware/yara-runner.mjs',
+          '--yr', '/vsg/in/yr', '--forge', '/vsg/selected-source/source.bin', '--inventory', '/vsg/in/inventory.json', '--root', '/scan', '--work', '/tmp',
+        ];
+        const input = JSON.stringify({
+          files, excludeRules: selected.excludedRules, selectionDigest: selected.selectionDigest, holdDigest: selected.holdDigest,
+          maxFileBytes: YARA_MAX_FILE_BYTES, timeoutSec,
+        });
+        const result = await ctx.runProcess({ command: 'docker', args, input, timeoutMs, maxOutputBytes: 256 * 1024 * 1024 });
+        if (result.status !== 'ran') {
+          await ctx.runProcess({ command: 'docker', args: ['rm', '-f', name], timeoutMs: 30_000 });
+          return { status: 'not_run', reason: `Selected YARA ${result.reason}` };
+        }
+        const out = lastJson(result.stdout);
+        if (!out) return { status: 'not_run', reason: `Selected YARA runner produced no result (exit ${result.exitCode}).` };
+        if (!out.ok) return { status: 'not_run', reason: `Selected YARA runner failed: ${out.error}` };
+        if (out.forge?.selectionDigest !== selected.selectionDigest || out.forge?.holdDigest !== selected.holdDigest) {
+          return { status: 'not_run', reason: 'Selected YARA runner returned a different selection identity.' };
+        }
+        return { status: 'ran', mode: 'selected-container', forge: out.forge, matches: out.matches, scanned: out.scanned, scanErrors: out.scanErrors, durationMs: out.durationMs };
+      });
+    } catch (error) {
+      return { status: 'not_run', reason: `Selected YARA ${error.message}` };
+    }
+  }
+  if (extraRules === undefined) extraRules = process.env.VSG_YARA_EXTRA_RULES;
+  const yaraX = ctx.registry?.get('yara-x');
+  const forge = ctx.registry?.get('yara-forge');
+  if (!yaraX || !forge) return { status: 'not_run', reason: 'YARA-X or the YARA Forge package is not in the tool registry.' };
+  const yr = resolveTool(yaraX);
+  const zip = resolveTool(forge);
+  if (!yr || !zip) return { status: 'not_run', reason: `${!yr ? 'YARA-X' : 'The YARA Forge package'} is not installed. Run vsg setup.` };
+  const input = JSON.stringify({ files, excludeRules: loadExclusions(forge.version), maxFileBytes: YARA_MAX_FILE_BYTES, timeoutSec });
+  const timeoutMs = (timeoutSec + 120) * 1000;
+  let r;
+  let mode;
+  if (yr.platform === platformKey() && process.platform === 'linux') {
+    mode = 'native';
+    // Compiled rules are derived, mutable cache data. Keep them outside the
+    // verified immutable install tree so tampering with the cache cannot make
+    // the installed rules package appear trusted.
+    const cache = path.join(toolsDir(), 'cache', 'yara-forge', forge.version, 'compiled');
+    const args = [RUNNER, '--yr', yr.path, '--forge', zip.path, '--root', root, '--cache', cache, '--work', os.tmpdir(), ...(extraRules ? ['--extra', extraRules] : [])];
+    r = await ctx.runProcess({ command: process.execPath, args, cwd: root, input, timeoutMs });
+  } else {
+    mode = 'container';
+    const runner = ctx.registry.get('yara-runner');
+    if (!runner?.image) return { status: 'not_run', reason: 'The yara-runner container image is not in the tool registry.' };
+    const docker = await ctx.runProcess({ command: 'docker', args: ['version', '--format', '{{.Server.Version}}'], timeoutMs: 20_000 });
+    if (docker.status !== 'ran' || docker.exitCode !== 0) return { status: 'not_run', reason: 'Docker is not available (the engine is not running), so YARA cannot run on this host. Start Docker and rerun.' };
+    const name = `vsg-yara-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+    const args = [
+      'run', '--rm', '-i', '--name', name, '--network', 'none', '--read-only', '--tmpfs', '/tmp:rw,exec,size=2g', '--memory', '4g', '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges',
+      '-v', `${path.join(packageRoot, 'src')}:/vsg/src:ro`, '-v', `${yr.path}:/vsg/in/yr:ro`, '-v', `${zip.path}:/vsg/in/forge.zip:ro`, '-v', `${root}:/scan:ro`,
+      ...(extraRules ? ['-v', `${path.resolve(extraRules)}:/vsg/in/extra.yar:ro`] : []),
+      '-w', '/scan', runner.image, 'node', '/vsg/src/checks/malware/yara-runner.mjs', '--yr', '/vsg/in/yr', '--forge', '/vsg/in/forge.zip', '--root', '/scan', '--work', '/tmp',
+      ...(extraRules ? ['--extra', '/vsg/in/extra.yar'] : []),
+    ];
+    r = await ctx.runProcess({ command: 'docker', args, input, timeoutMs });
+    if (r.status !== 'ran') await ctx.runProcess({ command: 'docker', args: ['rm', '-f', name], timeoutMs: 30_000 }); // a timed-out client leaves the container running
+  }
+  if (r.status !== 'ran') return { status: 'not_run', reason: `YARA ${r.reason}` };
+  const out = lastJson(r.stdout);
+  if (!out) return { status: 'not_run', reason: `YARA runner produced no result (exit ${r.exitCode}): ${String(r.stderr).trim().split('\n')[0]?.slice(0, 200) ?? ''}` };
+  if (!out.ok) return { status: 'not_run', reason: `YARA runner failed: ${out.error}` };
+  return { status: 'ran', mode, forge: out.forge, matches: out.matches, scanned: out.scanned, scanErrors: out.scanErrors, durationMs: out.durationMs };
+}

package/dist/security-runtime/src/checks/mobile-config/index.mjs

@@ -0,0 +1,173 @@
+// mobile-config (REQ-032): static review of Expo / React Native configuration, plus optional MobSF over a built APK.
+// app.json and app.config.json are parsed as data. app.config.js/.ts/.mjs/.cjs are only read as text (regex heuristics): vsg never executes repository code.
+import fs from 'node:fs';
+import path from 'node:path';
+import { listFiles } from '../../core/detect.mjs';
+import { importMobsf, runMobsf } from './mobsf.mjs';
+
+export const id = 'mobile-config';
+export const title = 'Mobile (Expo) configuration';
+export const modes = ['scan', 'deep', 'release'];
+export const requiredIn = [];
+export const timeoutSec = 1000;
+
+const base = (f) => f.slice(f.lastIndexOf('/') + 1);
+const dirOf = (f) => (f.includes('/') ? f.slice(0, f.lastIndexOf('/')) : '');
+const readText = (repo, rel) => { try { return fs.readFileSync(path.join(repo, rel), 'utf8'); } catch { return ''; } };
+const readJson = (repo, rel) => { try { return JSON.parse(readText(repo, rel)); } catch { return null; } };
+const CONFIG_JSON = new Set(['app.json', 'app.config.json']);
+const CONFIG_TEXT = /^app\.config\.(?:js|ts|mjs|cjs)$/;
+
+export const HIGH_RISK_PERMISSIONS = {
+  READ_SMS: 'reads text messages',
+  RECEIVE_SMS: 'receives text messages',
+  READ_CALL_LOG: 'reads the call log',
+  SYSTEM_ALERT_WINDOW: 'draws over other apps (a common overlay-attack permission)',
+  REQUEST_INSTALL_PACKAGES: 'can prompt to install other apps',
+  MANAGE_EXTERNAL_STORAGE: 'all-files access to shared storage',
+  ACCESS_BACKGROUND_LOCATION: 'reads location while the app is in the background',
+};
+const PERM_RE = new RegExp(`\\b(?:android\\.permission\\.)?(${Object.keys(HIGH_RISK_PERMISSIONS).join('|')})\\b`, 'g');
+
+/** Dependencies of the package.json in this directory or the nearest parent. */
+function depsNear(repo, dir) {
+  for (let d = dir; ; d = dirOf(d)) {
+    const j = readJson(repo, d ? `${d}/package.json` : 'package.json');
+    if (j) return new Set(['dependencies', 'devDependencies', 'optionalDependencies'].flatMap((k) => Object.keys(j[k] ?? {})));
+    if (!d) return new Set();
+  }
+}
+
+const quoted = (s) => [...String(s).matchAll(/['"`]([^'"`]+)['"`]/g)].map((m) => m[1]);
+
+/** Facts from a parsed Expo config object. */
+function factsFromJson(raw) {
+  const e = raw?.expo && typeof raw.expo === 'object' ? raw.expo : raw ?? {};
+  const plugins = Array.isArray(e.plugins) ? e.plugins : [];
+  const bp = plugins.filter((p) => Array.isArray(p) && p[0] === 'expo-build-properties').map((p) => p[1] ?? {});
+  const ats = e.ios?.infoPlist?.NSAppTransportSecurity ?? {};
+  const filters = Array.isArray(e.android?.intentFilters) ? e.android.intentFilters : [];
+  return {
+    updatesSigned: !!e.updates?.codeSigningCertificate,
+    cleartext: e.android?.usesCleartextTraffic === true || bp.some((p) => p.android?.usesCleartextTraffic === true),
+    atsArbitrary: Object.entries(ats).some(([k, v]) => /^NSAllowsArbitraryLoads/.test(k) && v === true),
+    atsDomains: Object.keys(ats.NSExceptionDomains ?? {}),
+    permissions: [...new Set((Array.isArray(e.android?.permissions) ? e.android.permissions : []).map((p) => String(p).replace(/^android\.permission\./, '')).filter((p) => HIGH_RISK_PERMISSIONS[p]))],
+    schemes: [].concat(e.scheme ?? []).map(String),
+    intentFilters: filters.flatMap((f) => [].concat(f.data ?? []).map((d) => `${d.scheme ?? '*'}://${d.host ?? ''}${d.pathPrefix ?? d.path ?? ''}`)).concat(filters.length && !filters.some((f) => f.data) ? ['(no data element)'] : []),
+    hasFilters: filters.length > 0,
+  };
+}
+
+/** Same facts from the text of a JS/TS config (regex only; the file is never loaded). */
+function factsFromText(text) {
+  const scheme = /\bscheme\s*:\s*(\[[^\]]*\]|['"`][^'"`]+['"`])/.exec(text);
+  return {
+    updatesSigned: /codeSigningCertificate/.test(text),
+    cleartext: /usesCleartextTraffic\s*:\s*true/.test(text),
+    atsArbitrary: /NSAllowsArbitraryLoads\w*\s*:\s*true/.test(text),
+    atsDomains: /NSExceptionDomains\s*:\s*\{\s*[^}\s]/.test(text) ? ['(see file)'] : [],
+    permissions: [...new Set([...text.matchAll(PERM_RE)].map((m) => m[1]))],
+    schemes: scheme ? quoted(scheme[1]) : [],
+    intentFilters: [],
+    hasFilters: /intentFilters\s*:/.test(text),
+  };
+}
+
+const lineOf = (text, re) => { const i = text.search(re); return i < 0 ? undefined : text.slice(0, i).split('\n').length; };
+
+function findingsFor(file, text, facts, { heuristic, hasUpdates }) {
+  const confidence = heuristic ? 'low' : 'high';
+  const how = heuristic ? ' (found by reading the file as text; vsg does not run JavaScript or TypeScript configs, so confirm it)' : '';
+  const mk = (key, severity, title, description, fix, re) => ({
+    category: 'config', severity, confidence, tool: 'vsg', ruleId: `vsg/mobile/${key}`, key: `mobile:${key}`, title,
+    description: description + how, location: { file, line: lineOf(text, re) }, evidence: `file: ${file}`, fix,
+  });
+  const out = [];
+  if (hasUpdates && !facts.updatesSigned) {
+    out.push(mk('updates-unsigned', 'medium', 'expo-updates is installed but over-the-air updates are not code-signed',
+      'The app depends on expo-updates and the config has no updates.codeSigningCertificate, so the app accepts any update the update server returns. Anyone who can alter the update host or the CDN path can ship code to every installation.',
+      'Generate a code-signing certificate and key (npx expo-updates codesigning:generate), set updates.codeSigningCertificate and updates.codeSigningMetadata in the app config, and sign each update when publishing. Keep the private key out of the repository.', /expo-updates|"updates"|updates\s*:/));
+  }
+  if (facts.cleartext) {
+    out.push(mk('android-cleartext', 'medium', 'Android cleartext (HTTP) traffic is allowed',
+      'android.usesCleartextTraffic is true, so the Android app may send and receive data over plain HTTP that anyone on the network can read or change.',
+      'Remove usesCleartextTraffic (or set it to false) and serve every endpoint over HTTPS. If one development host needs HTTP, scope it with a network security config for debug builds only.', /usesCleartextTraffic/));
+  }
+  if (facts.atsArbitrary) {
+    out.push(mk('ios-ats-disabled', 'medium', 'iOS App Transport Security is disabled (NSAllowsArbitraryLoads)',
+      'NSAppTransportSecurity allows arbitrary loads, which turns off the HTTPS requirement for the whole iOS app.',
+      'Remove NSAllowsArbitraryLoads and move every endpoint to HTTPS. If one legacy host cannot, use a narrow NSExceptionDomains entry for that host only.', /NSAllowsArbitraryLoads/));
+  }
+  if (facts.atsDomains.length) {
+    out.push(mk('ios-ats-exceptions', 'medium', `iOS App Transport Security exception domains: ${facts.atsDomains.join(', ')}`,
+      'NSExceptionDomains weakens the HTTPS requirement for the listed hosts (cleartext HTTP or older TLS).',
+      'Remove each exception once the host serves modern TLS. Keep the list to hosts you control and review it before each release.', /NSExceptionDomains/));
+  }
+  for (const p of facts.permissions) {
+    out.push(mk(`permission-${p}`, 'low', `High-risk Android permission requested: ${p}`,
+      `The app asks for ${p}, which ${HIGH_RISK_PERMISSIONS[p]}. Google Play restricts several of these, and a compromised app with them can do real harm.`,
+      `Confirm the feature needs ${p}. If it does not, remove it from android.permissions (and from any plugin that adds it).`, new RegExp(p)));
+  }
+  if (facts.schemes.length) {
+    out.push(mk('deep-link-schemes', 'info', `Deep link scheme(s): ${facts.schemes.join(', ')}`,
+      'Custom URL schemes can be claimed by any other app on the device. Listed so the agent review can read the handlers (Linking, Expo Router routes) and check that links never carry tokens or trigger sensitive actions without confirmation.',
+      'Prefer HTTPS app links or universal links for sign-in and payment redirects; treat every link parameter as untrusted input. See playbook/mobile-expo.md.', /\bscheme\b/));
+  }
+  if (facts.hasFilters) {
+    out.push(mk('intent-filters', 'info', `Android intent filters declared${facts.intentFilters.length ? `: ${facts.intentFilters.slice(0, 5).join(', ')}` : ''}`,
+      'Intent filters make the app reachable from links and other apps. Listed so the agent review can read the handlers behind them.',
+      'Verify autoVerify app links where possible and validate all incoming data. See playbook/mobile-expo.md.', /intentFilters/));
+  }
+  return out;
+}
+
+const isReactNative = (repo, detection) => detection.packageJsons.some((pj) => {
+  const j = readJson(repo, pj);
+  return j && ['dependencies', 'devDependencies'].some((k) => j[k]?.['react-native']);
+});
+
+export const applies = (ctx) => (ctx.detection.expo || isReactNative(ctx.repo, ctx.detection)
+  ? true
+  : { applies: false, reason: 'no Expo or React Native project was detected' });
+
+export async function run(ctx, deps = {}) {
+  const repo = ctx.repo;
+  const files = listFiles(repo);
+  const findings = [];
+  const configs = [];
+  for (const f of files) {
+    const b = base(f);
+    const deps_ = () => depsNear(repo, dirOf(f));
+    if (CONFIG_JSON.has(b)) {
+      const j = readJson(repo, f);
+      if (!j || typeof j !== 'object') { configs.push({ file: f, mode: 'unreadable' }); continue; }
+      const d = deps_();
+      if (!j.expo && !d.has('expo') && !d.has('react-native')) continue; // an app.json from some other tool
+      configs.push({ file: f, mode: 'json' });
+      findings.push(...findingsFor(f, readText(repo, f), factsFromJson(j), { heuristic: false, hasUpdates: d.has('expo-updates') }));
+    } else if (CONFIG_TEXT.test(b)) {
+      const text = readText(repo, f); // read as text only; never imported or executed
+      configs.push({ file: f, mode: 'text-heuristic' });
+      findings.push(...findingsFor(f, text, factsFromText(text), { heuristic: true, hasUpdates: deps_().has('expo-updates') }));
+    }
+  }
+
+  let mobsf;
+  const apk = ctx.config?.mobile?.apk ?? null;
+  if (!apk) mobsf = { status: 'skipped', reason: 'No mobile.apk is set in vsg.config.json, so MobSF did not run.' };
+  else {
+    const r = await runMobsf({ repo, apk, image: ctx.registry?.get('mobsf')?.image, runProcess: deps.runProcess ?? ctx.runProcess, fetchFn: deps.fetch });
+    if (r.status === 'ran') {
+      const imported = importMobsf(r.report, apk.replace(/\\/g, '/'));
+      findings.push(...imported);
+      mobsf = { status: 'ran', apk, imported: imported.length, image: ctx.registry?.get('mobsf')?.image };
+    } else mobsf = { status: r.status, apk, reason: r.reason };
+  }
+
+  const evidence = { configs, mobsf, note: configs.length ? undefined : 'No Expo config file (app.json, app.config.json, app.config.js/ts) was found.' };
+  const reason = mobsf.status === 'failed' ? `Config checks ran; MobSF failed: ${mobsf.reason}` : '';
+  return { status: 'ran', reason, findings, evidence };
+}
+
+export default { id, title, modes, requiredIn, timeoutSec, applies, run };

package/dist/security-runtime/src/checks/mobile-config/mobsf.mjs

@@ -0,0 +1,105 @@
+// MobSF (optional): static analysis of a built APK through the pinned container's REST API.
+// Container: --rm, published on 127.0.0.1 only (Docker chooses the port), per-run API key passed through the environment, never in argv.
+// API (MobSF v4.5.3): POST /api/v1/upload (multipart "file"), POST /api/v1/scan (form: hash, scan_type, file_name; returns the report),
+// POST /api/v1/report_json (form: hash). Auth: the key in the Authorization header.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const MOBSF_TIMEOUT_MS = 15 * 60 * 1000;
+const MAX_FINDINGS = 100;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const clean = (s, n = 400) => String(s ?? '').replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, n);
+
+/** High findings of a MobSF report as vsg raw findings (Medium, non-blocking, category config). */
+export function importMobsf(report, apkRel) {
+  const out = [];
+  const add = (kind, rule, title, description) => {
+    if (out.length >= MAX_FINDINGS) return;
+    out.push({
+      category: 'config', severity: 'medium', confidence: 'medium', tool: 'MobSF', ruleId: `mobsf/${kind}/${rule}`, key: `mobsf:${kind}:${rule}`,
+      title: `MobSF (high): ${clean(title, 160) || rule}`,
+      description: `${clean(description)} MobSF rates this High; vsg reports it as Medium because static APK analysis has false positives. Confirm it in the app code before acting.`,
+      location: { file: apkRel }, evidence: `source: MobSF ${kind}\nrule: ${rule}`,
+      fix: 'Review the MobSF finding against the app source and fix or document it. See playbook/mobile-expo.md.',
+    });
+  };
+  const manifest = report?.manifest_analysis;
+  for (const m of Array.isArray(manifest) ? manifest : manifest?.manifest_findings ?? []) {
+    if (m?.severity === 'high') add('manifest', m.rule ?? m.title, m.title, m.description);
+  }
+  for (const n of report?.network_security?.network_findings ?? []) {
+    if (n?.severity === 'high') add('network', crypto.createHash('sha256').update(String(n.description)).digest('hex').slice(0, 8), 'Network security configuration', n.description);
+  }
+  const code = report?.code_analysis;
+  for (const [rule, v] of Object.entries(code?.findings ?? code ?? {})) {
+    if (v?.metadata?.severity === 'high') add('code', rule, rule.replace(/_/g, ' '), `${v.metadata.description ?? ''} Files: ${Object.keys(v.files ?? {}).slice(0, 5).join(', ')}.`);
+  }
+  return out;
+}
+
+/**
+ * Runs the whole flow. deps (tests): { runProcess, fetch }. Returns
+ * { status: 'ran', report } | { status: 'skipped' | 'failed', reason }. The container is always stopped afterwards.
+ */
+export async function runMobsf({ repo, apk, image, runProcess, fetchFn = fetch, timeoutMs = MOBSF_TIMEOUT_MS }) {
+  const abs = path.resolve(repo, apk);
+  let st;
+  try { st = fs.statSync(abs); } catch { return { status: 'failed', reason: `mobile.apk "${apk}" does not exist.` }; }
+  if (!st.isFile() || !/\.apk$/i.test(abs)) return { status: 'failed', reason: `mobile.apk "${apk}" is not an .apk file.` };
+  if (!image) return { status: 'skipped', reason: 'The MobSF image is not in the tool registry.' };
+  const docker = await runProcess({ command: 'docker', args: ['version', '--format', '{{.Server.Version}}'], timeoutMs: 20_000 });
+  if (docker.status !== 'ran' || docker.exitCode !== 0) return { status: 'skipped', reason: 'Docker is not available (not installed or the engine is not running), so MobSF did not run.' };
+
+  const deadline = Date.now() + timeoutMs;
+  const key = crypto.randomBytes(24).toString('hex');
+  const name = `vsg-mobsf-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  const left = () => Math.max(1000, deadline - Date.now());
+  // fetch's own abort timer is unref'd and a refused connection holds no handle: keep the event loop alive until the container is stopped
+  const keepAlive = setInterval(() => {}, 1000);
+  try {
+    const started = await runProcess({
+      command: 'docker', timeoutMs: Math.min(left(), 10 * 60_000), extraEnv: { MOBSF_API_KEY: key },
+      args: ['run', '-d', '--rm', '--name', name, '-p', '127.0.0.1::8000', '--security-opt', 'no-new-privileges', '-e', 'MOBSF_API_KEY', image],
+    });
+    if (started.status !== 'ran' || started.exitCode !== 0) return { status: 'failed', reason: `The MobSF container did not start: ${started.reason ?? String(started.stderr).trim().split('\n').pop()}` };
+    const portOut = await runProcess({ command: 'docker', args: ['port', name, '8000/tcp'], timeoutMs: 20_000 });
+    const port = /:(\d+)\s*$/m.exec(String(portOut.stdout).trim())?.[1];
+    if (!port) return { status: 'failed', reason: 'Could not read the published MobSF port.' };
+    const base = `http://127.0.0.1:${port}`;
+    const call = async (p, init, ms = Infinity) => {
+      const r = await fetchFn(`${base}${p}`, { ...init, headers: { Authorization: key, ...(init?.headers ?? {}) }, signal: AbortSignal.timeout(Math.min(left(), ms)) });
+      const text = await r.text();
+      let json; try { json = JSON.parse(text); } catch { /* not JSON */ }
+      return { ok: r.ok, status: r.status, json, text };
+    };
+    // ready: the API answers (401 without a key proves the app is up; with the key a bad request is fine)
+    let ready = false;
+    while (Date.now() < deadline && !ready) {
+      try { const r = await call('/api/v1/scans', { method: 'GET' }, 5000); ready = r.status < 500; } catch { /* not up yet */ }
+      if (!ready) await sleep(3000);
+    }
+    if (!ready) return { status: 'failed', reason: 'MobSF did not become ready before the 15 minute limit.' };
+
+    const form = new FormData();
+    form.append('file', new Blob([fs.readFileSync(abs)]), path.basename(abs));
+    const up = await call('/api/v1/upload', { method: 'POST', body: form });
+    if (!up.ok || !up.json?.hash) return { status: 'failed', reason: `MobSF upload failed (HTTP ${up.status}): ${clean(up.json?.error ?? up.text, 150)}` };
+    const scan = await call('/api/v1/scan', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ hash: up.json.hash, scan_type: up.json.scan_type ?? 'apk', file_name: up.json.file_name ?? path.basename(abs) }).toString() });
+    if (!scan.ok) return { status: 'failed', reason: `MobSF scan failed (HTTP ${scan.status}): ${clean(scan.json?.error ?? scan.text, 150)}` };
+    let report = scan.json;
+    if (!report?.manifest_analysis && !report?.code_analysis) {
+      const rep = await call('/api/v1/report_json', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ hash: up.json.hash }).toString() });
+      if (!rep.ok) return { status: 'failed', reason: `MobSF report failed (HTTP ${rep.status}).` };
+      report = rep.json;
+    }
+    return { status: 'ran', report };
+  } catch (e) {
+    return { status: 'failed', reason: `MobSF ${e.name === 'TimeoutError' ? 'timed out (15 minute limit)' : `failed: ${e.message}`}` };
+  } finally {
+    clearInterval(keepAlive);
+    const stop = await runProcess({ command: 'docker', args: ['stop', '-t', '5', name], timeoutMs: 60_000 });
+    if (stop.status !== 'ran' || stop.exitCode !== 0) await runProcess({ command: 'docker', args: ['rm', '-f', name], timeoutMs: 60_000 });
+  }
+}

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

@@ -0,0 +1,133 @@
+// posture (REQ-021): repository settings on GitHub. Warning only: findings are category "posture", which never blocks, and the check
+// is never required. Needs a token (GH_TOKEN or GITHUB_TOKEN); without one it is not_run: no token. The token is sent only to
+// api.github.com through the fetch wrapper and never appears in findings, evidence or logs.
+export const id = 'posture';
+export const title = 'GitHub repository posture';
+export const modes = ['scan', 'deep', 'release'];
+export const requiredIn = [];
+export const timeoutSec = 180;
+
+export const API = 'https://api.github.com';
+const tokenFromEnv = () => process.env.GH_TOKEN || process.env.GITHUB_TOKEN || '';
+
+/** Parses a github.com remote (https, ssh or scp-style, with or without credentials). Returns { owner, repo } or null. */
+export function parseGithubRemote(url) {
+  const s = String(url ?? '').trim();
+  const m = /^(?:https?:\/\/(?:[^@/]+@)?|ssh:\/\/(?:[^@/]+@)?|git@)github\.com[/:]([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?\/?$/i.exec(s);
+  return m ? { owner: m[1], repo: m[2] } : null;
+}
+
+async function originOf(ctx) {
+  const r = await ctx.runProcess({ command: 'git', args: ['-C', ctx.repo, 'remote', 'get-url', 'origin'], cwd: ctx.repo, timeoutMs: 15_000 });
+  return r.status === 'ran' && r.exitCode === 0 ? parseGithubRemote(r.stdout) : null;
+}
+
+export async function applies(ctx) {
+  return (await originOf(ctx)) ? true : { applies: false, reason: 'no github.com "origin" remote' };
+}
+
+const finding = (key, title, description, fix, severity = 'medium') => ({
+  tool: 'github-api', ruleId: key, key, category: 'posture', severity, confidence: 'high', title, description, fix,
+  location: { url: 'https://github.com' },
+});
+const unchecked = (what, why) => finding(`unchecked-${what}`, `Could not check ${what}`, `${why}. This setting was not verified.`, 'Run vsg with a token that can read repository settings (a fine-grained token with Administration: read).', 'info');
+
+/**
+ * Runs the four checks. `get(path)` returns { status, json }. Returns { findings, checked: { item: 'ok' | 'finding' | 'could not check' } }.
+ * Exported for tests with recorded responses.
+ */
+export async function checkPosture({ owner, repo, get }) {
+  const findings = [];
+  const checked = {};
+  const base = `/repos/${owner}/${repo}`;
+  const repoRes = await get(base);
+  if (repoRes.status !== 200) return { fatal: `GitHub returned HTTP ${repoRes.status} for the repository (check the token and that the repository exists)`, findings, checked };
+  const branch = repoRes.json?.default_branch;
+
+  // (a) default-branch protection. Classic protection only: a 404 "Branch not protected" means none; other statuses mean we could not tell.
+  if (!branch) {
+    checked.branchProtection = 'could not check';
+    findings.push(unchecked('default-branch protection', 'GitHub did not report a default branch'));
+  } else {
+    const r = await get(`${base}/branches/${encodeURIComponent(branch)}/protection`);
+    if (r.status === 200) checked.branchProtection = 'ok';
+    else if (r.status === 404 && /not protected/i.test(r.json?.message ?? '')) {
+      checked.branchProtection = 'finding';
+      findings.push(finding('branch-protection', `Default branch "${branch}" has no branch protection`,
+        'Anyone with write access can push directly to the default branch, or force-push it, without review or required checks. Only classic branch protection rules were checked; repository rulesets were not.',
+        'Enable branch protection or a ruleset on the default branch: require a pull request and the vsg status check, and block force pushes.'));
+    } else {
+      checked.branchProtection = 'could not check';
+      findings.push(unchecked('default-branch protection', `GitHub returned HTTP ${r.status}`));
+    }
+  }
+
+  // (b) secret scanning and push protection, from security_and_analysis (only returned to tokens with admin access)
+  const sa = repoRes.json?.security_and_analysis;
+  for (const [key, label, fix] of [
+    ['secret_scanning', 'secret scanning', 'Enable secret scanning under Settings, Code security.'],
+    ['secret_scanning_push_protection', 'secret scanning push protection', 'Enable push protection under Settings, Code security, so commits containing secrets are rejected.'],
+  ]) {
+    const status = sa?.[key]?.status;
+    if (status === 'enabled') checked[key] = 'ok';
+    else if (status === 'disabled') {
+      checked[key] = 'finding';
+      findings.push(finding(key, `${label[0].toUpperCase()}${label.slice(1)} is disabled`, `GitHub ${label} is turned off for this repository.`, fix));
+    } else {
+      checked[key] = 'could not check';
+      findings.push(unchecked(label, 'GitHub did not return security_and_analysis for this token'));
+    }
+  }
+
+  // (c) Dependabot alerts: 204 enabled, 404 disabled
+  const alerts = await get(`${base}/vulnerability-alerts`);
+  if (alerts.status === 204) checked.dependabotAlerts = 'ok';
+  else if (alerts.status === 404) {
+    checked.dependabotAlerts = 'finding';
+    findings.push(finding('dependabot-alerts', 'Dependabot alerts are disabled', 'GitHub is not alerting on vulnerable dependencies in this repository.', 'Enable Dependabot alerts under Settings, Code security.'));
+  } else {
+    checked.dependabotAlerts = 'could not check';
+    findings.push(unchecked('Dependabot alerts', `GitHub returned HTTP ${alerts.status}`));
+  }
+
+  // (d) default GITHUB_TOKEN permissions for Actions
+  const perms = await get(`${base}/actions/permissions/workflow`);
+  if (perms.status === 200) {
+    if (perms.json?.default_workflow_permissions === 'write') {
+      checked.actionsTokenPermissions = 'finding';
+      findings.push(finding('actions-default-write', 'Actions default token permission is read and write',
+        'Every workflow that does not set its own permissions gets a GITHUB_TOKEN with write access to the repository.',
+        'Under Settings, Actions, General, set Workflow permissions to "Read repository contents and packages permissions", and grant write per job.'));
+    } else checked.actionsTokenPermissions = 'ok';
+  } else {
+    checked.actionsTokenPermissions = 'could not check';
+    findings.push(unchecked('default Actions token permissions', `GitHub returned HTTP ${perms.status}`));
+  }
+  for (const f of findings) f.location = { url: `https://github.com/${owner}/${repo}` };
+  return { findings, checked };
+}
+
+export async function run(ctx) {
+  const token = tokenFromEnv();
+  if (!token) return { status: 'not_run', reason: 'no token: set GH_TOKEN or GITHUB_TOKEN to check repository posture' };
+  const origin = await originOf(ctx);
+  if (!origin) return { status: 'not_applicable', reason: 'no github.com "origin" remote' };
+  const get = async (p) => {
+    const res = await ctx.fetch(`${API}${p}`, {
+      timeoutMs: 20_000,
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'vsg' },
+    });
+    let json = null;
+    try { json = res.body.length ? JSON.parse(res.body.toString('utf8')) : null; } catch { /* not JSON */ }
+    return { status: res.status, json };
+  };
+  const { findings, checked, fatal } = await checkPosture({ ...origin, get });
+  if (fatal) return { status: 'not_run', reason: fatal };
+  return {
+    status: 'ran', reason: '', findings,
+    dataVersions: { api: 'GitHub REST 2022-11-28' },
+    evidence: { repository: `${origin.owner}/${origin.repo}`, checked },
+  };
+}
+
+export default { id, title, modes, requiredIn, timeoutSec, applies, run };