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

package/dist/security-runtime/src/live/analyze.mjs

@@ -0,0 +1,101 @@
+// Pure analyzers for live-basic: security headers, cookie flags and CORS. Each returns raw findings (category "live").
+// Evidence never carries a cookie value or any response body.
+export const UNTRUSTED_ORIGIN = 'https://untrusted.example';
+
+const live = (f) => ({ category: 'live', confidence: 'high', tool: 'vsg-live', refs: [], ...f });
+
+const HEADER_FIXES = {
+  'strict-transport-security': 'Send `Strict-Transport-Security: max-age=31536000; includeSubDomains` on every HTTPS response.',
+  'content-security-policy': "Send a Content-Security-Policy that limits script sources, for example `default-src 'self'`, and avoid 'unsafe-inline' for scripts (use nonces or hashes).",
+  'x-content-type-options': 'Send `X-Content-Type-Options: nosniff`.',
+  'frame-protection': "Send `Content-Security-Policy: frame-ancestors 'self'` (or `X-Frame-Options: SAMEORIGIN`).",
+  'referrer-policy': 'Send `Referrer-Policy: strict-origin-when-cross-origin` (or stricter).',
+  'permissions-policy': 'Send a Permissions-Policy that turns off features the site does not use, for example `camera=(), microphone=(), geolocation=()`.',
+};
+
+function missingHeader(key, title, severity, url, why) {
+  return live({ ruleId: `header-${key}`, key: `header:${key}`, severity, title, location: { url }, description: why, evidence: `Response from ${url} did not include this header.`, fix: HEADER_FIXES[key], cwe: [693] });
+}
+
+/** headers: a Headers object from the entry page. */
+export function analyzeHeaders(headers, url) {
+  const out = [];
+  const https = new URL(url).protocol === 'https:';
+  const get = (n) => headers.get(n);
+  if (https) {
+    const hsts = get('strict-transport-security');
+    if (!hsts) out.push(missingHeader('strict-transport-security', 'HSTS header missing', 'medium', url, 'Without Strict-Transport-Security a browser can be downgraded to plain HTTP by a network attacker.'));
+    else {
+      const age = Number(/max-age\s*=\s*(\d+)/i.exec(hsts)?.[1] ?? 0);
+      if (age < 15_552_000) out.push(live({ ruleId: 'header-hsts-short', key: 'header:hsts-short', severity: 'low', title: 'HSTS max-age is under 180 days', location: { url }, description: 'A short HSTS lifetime leaves returning visitors unprotected once it expires.', evidence: `Strict-Transport-Security: ${hsts}`, fix: HEADER_FIXES['strict-transport-security'], cwe: [319] }));
+    }
+  }
+  const csp = get('content-security-policy');
+  if (!csp) {
+    out.push(missingHeader('content-security-policy', 'Content-Security-Policy header missing', 'medium', url, 'A Content-Security-Policy limits what an injected script can do. Without one, any cross-site scripting flaw has full reach.'));
+  } else {
+    const directives = new Map(csp.split(';').map((d) => d.trim()).filter(Boolean).map((d) => { const [name, ...v] = d.split(/\s+/); return [name.toLowerCase(), v]; }));
+    const scripts = directives.get('script-src') ?? directives.get('default-src') ?? [];
+    if (scripts.includes("'unsafe-inline'") && !scripts.some((v) => /^'(nonce-|sha(256|384|512)-)/.test(v) || v === "'strict-dynamic'")) {
+      out.push(live({ ruleId: 'header-csp-unsafe-inline', key: 'header:csp-unsafe-inline', severity: 'low', title: "Content-Security-Policy allows 'unsafe-inline' scripts", location: { url }, description: "'unsafe-inline' lets injected inline scripts run, which removes most of the protection of the policy.", evidence: `script-src: ${scripts.join(' ')}`, fix: HEADER_FIXES['content-security-policy'], cwe: [693] }));
+    }
+  }
+  const frameAncestors = csp && /(^|;)\s*frame-ancestors\b/i.test(csp);
+  if (!get('x-frame-options') && !frameAncestors) out.push(missingHeader('frame-protection', 'No clickjacking protection (X-Frame-Options or frame-ancestors)', 'low', url, 'Another site can embed this page in a frame and trick visitors into clicking hidden controls.'));
+  if (!/nosniff/i.test(get('x-content-type-options') ?? '')) out.push(missingHeader('x-content-type-options', 'X-Content-Type-Options header missing', 'low', url, 'Browsers may guess content types and run uploaded files as scripts.'));
+  if (!get('referrer-policy')) out.push(missingHeader('referrer-policy', 'Referrer-Policy header missing', 'low', url, 'Full URLs, including private paths and query strings, can leak to other sites through the Referer header.'));
+  if (!get('permissions-policy')) out.push(missingHeader('permissions-policy', 'Permissions-Policy header missing', 'low', url, 'Browser features such as camera, microphone and geolocation are not restricted for this page or embedded content.'));
+  return out;
+}
+
+const SESSION_LIKE = /(sess|sid\b|token|auth|jwt|login|sb-|csrf|xsrf|connect\.sid)/i;
+
+/** setCookies: array of Set-Cookie header strings. Reports flags per cookie; the value is never read into a finding. */
+export function analyzeCookies(setCookies, url) {
+  const out = [];
+  for (const raw of setCookies) {
+    const [pair, ...attrs] = raw.split(';').map((s) => s.trim());
+    const name = pair.split('=')[0];
+    const flags = new Set(attrs.map((a) => a.split('=')[0].toLowerCase()));
+    const sameSite = attrs.find((a) => /^samesite=/i.test(a))?.split('=')[1]?.toLowerCase();
+    const sessionLike = SESSION_LIKE.test(name);
+    const missing = [];
+    if (!flags.has('secure')) missing.push('Secure');
+    if (sessionLike && !flags.has('httponly')) missing.push('HttpOnly');
+    if (!sameSite) missing.push('SameSite');
+    else if (sameSite === 'none' && !flags.has('secure')) missing.push('Secure (required with SameSite=None)');
+    if (!missing.length) continue;
+    out.push(live({
+      ruleId: 'cookie-flags', key: `cookie:${name}`, severity: sessionLike && (missing.includes('Secure') || missing.includes('HttpOnly')) ? 'medium' : 'low',
+      title: `Cookie "${name}" is missing ${missing.join(', ')}`, location: { url },
+      description: `${sessionLike ? 'This looks like a session or token cookie. ' : ''}Without these flags the cookie can be read by page scripts, sent over plain HTTP, or sent on cross-site requests.`,
+      evidence: `Cookie ${name}: attributes set = ${[...flags].join(', ') || 'none'}; SameSite = ${sameSite ?? 'not set'}; value not recorded.`,
+      fix: 'Set `Secure; HttpOnly; SameSite=Lax` (or Strict) on session cookies, and at least `Secure; SameSite=Lax` on the others.', cwe: [614, 1004, 1275],
+    }));
+  }
+  return out;
+}
+
+/** headers: response to a request that carried `Origin: https://untrusted.example`. */
+export function analyzeCors(headers, url) {
+  const acao = headers.get('access-control-allow-origin');
+  const creds = (headers.get('access-control-allow-credentials') ?? '').toLowerCase() === 'true';
+  if (!acao) return [];
+  const fix = 'Allow only an explicit list of trusted origins, never echo the Origin header, and never combine a broad origin policy with Access-Control-Allow-Credentials.';
+  if (acao === UNTRUSTED_ORIGIN && creds) {
+    return [live({ ruleId: 'cors-reflected-credentials', key: 'cors:reflected-credentials', severity: 'high', confidence: 'confirmed', title: 'CORS reflects any origin and allows credentials', location: { url },
+      description: 'Any website can make credentialed requests to this site from a visitor\'s browser and read the responses, including account data.',
+      evidence: `Request Origin: ${UNTRUSTED_ORIGIN} returned Access-Control-Allow-Origin: ${acao} and Access-Control-Allow-Credentials: true.`, fix, cwe: [942] })];
+  }
+  if (acao === '*') {
+    return [live({ ruleId: 'cors-wildcard', key: 'cors:wildcard', severity: 'medium', title: 'CORS allows any origin (wildcard)', location: { url },
+      description: 'Any website can read responses from this URL. That is fine for public data and wrong for anything user-specific.',
+      evidence: `Access-Control-Allow-Origin: *${creds ? ' with Access-Control-Allow-Credentials: true (browsers reject this combination)' : ''}`, fix, cwe: [942] })];
+  }
+  if (acao === UNTRUSTED_ORIGIN) {
+    return [live({ ruleId: 'cors-reflected', key: 'cors:reflected', severity: 'medium', title: 'CORS echoes any requested origin', location: { url },
+      description: 'The server reflects the Origin header, so any website can read responses that do not need credentials.',
+      evidence: `Request Origin: ${UNTRUSTED_ORIGIN} returned Access-Control-Allow-Origin: ${acao}.`, fix, cwe: [942] })];
+  }
+  return [];
+}

package/dist/security-runtime/src/live/exposure.mjs

@@ -0,0 +1,79 @@
+// Sensitive-file probes for live-basic: a fixed list of at most 15 well-known paths, read with ordinary GETs.
+// A hit needs a content signature (an HTML error page is never a hit) and must differ from a random-path baseline,
+// so sites that answer every path with 200 (soft 404) are not flagged. Evidence never contains file content beyond key names.
+import crypto from 'node:crypto';
+import { sha256 } from '../core/findings.mjs';
+
+const text = (b) => b.toString('utf8');
+const looksHtml = (b, ct) => /html/i.test(ct ?? '') || /^\s*(<!doctype|<html|<head|<body)/i.test(text(b.subarray(0, 512)));
+const ENV_LINE = /^\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_.]*\s*=/;
+
+function envKeys(b) {
+  const lines = text(b).split(/\r?\n/).filter((l) => l.trim() && !l.trim().startsWith('#'));
+  const keys = lines.filter((l) => ENV_LINE.test(l)).map((l) => l.split('=')[0].replace(/^\s*export\s+/, '').trim());
+  return lines.length && keys.length / lines.length >= 0.6 ? keys : null;
+}
+
+const envCheck = (b, ct) => { const k = looksHtml(b, ct) ? null : envKeys(b); return k && `${k.length} variable name(s): ${k.slice(0, 8).join(', ')}${k.length > 8 ? ', ...' : ''} (values not recorded)`; };
+const zipCheck = (b) => b.length > 4 && b[0] === 0x50 && b[1] === 0x4b && b[2] === 3 && b[3] === 4 && 'ZIP archive';
+const sqlCheck = (b, ct) => !looksHtml(b, ct) && /(CREATE TABLE|INSERT INTO|DROP TABLE|-- MySQL dump|-- PostgreSQL database dump)/i.test(text(b)) && 'SQL dump statements';
+
+/** The reviewed list. `check(buf, contentType)` returns a short description when the content has the file's signature. */
+export const SENSITIVE_FILES = [
+  { path: '/.env', kind: 'env', severity: 'high', what: 'environment file', check: envCheck },
+  { path: '/.env.local', kind: 'env', severity: 'high', what: 'environment file', check: envCheck },
+  { path: '/.env.production', kind: 'env', severity: 'high', what: 'environment file', check: envCheck },
+  { path: '/.git/HEAD', kind: 'vcs', severity: 'high', what: 'Git repository metadata', check: (b) => /^(ref:\s*refs\/\S+|[0-9a-f]{40})\s*$/.test(text(b.subarray(0, 200))) && 'Git HEAD pointer' },
+  { path: '/.git/config', kind: 'vcs', severity: 'high', what: 'Git repository configuration', check: (b, ct) => !looksHtml(b, ct) && /\[core\]/.test(text(b)) && /repositoryformatversion|\[remote |\[branch /.test(text(b)) && 'Git config sections' },
+  { path: '/.svn/entries', kind: 'vcs', severity: 'high', what: 'Subversion metadata', check: (b) => /^\d+\r?\n(\r?\n)?(dir|file|svn:)/.test(text(b.subarray(0, 100))) && 'Subversion entries file' },
+  { path: '/.DS_Store', kind: 'metadata', severity: 'medium', what: 'macOS folder metadata (lists file names)', check: (b) => b.length > 8 && b.readUInt32BE(0) === 1 && text(b.subarray(4, 8)) === 'Bud1' && 'DS_Store header' },
+  { path: '/backup.zip', kind: 'backup', severity: 'high', what: 'backup archive', check: zipCheck },
+  { path: '/backup.tar.gz', kind: 'backup', severity: 'high', what: 'backup archive', check: (b) => b.length > 2 && b[0] === 0x1f && b[1] === 0x8b && 'gzip archive' },
+  { path: '/site.zip', kind: 'backup', severity: 'high', what: 'site archive', check: zipCheck },
+  { path: '/www.zip', kind: 'backup', severity: 'high', what: 'site archive', check: zipCheck },
+  { path: '/backup.sql', kind: 'backup', severity: 'high', what: 'database dump', check: sqlCheck },
+  { path: '/db.sql', kind: 'backup', severity: 'high', what: 'database dump', check: sqlCheck },
+  { path: '/dump.sql', kind: 'backup', severity: 'high', what: 'database dump', check: sqlCheck },
+  { path: '/.htpasswd', kind: 'credentials', severity: 'high', what: 'password file', check: (b, ct) => !looksHtml(b, ct) && /^[^\s:]+:(\$apr1\$|\$2[aby]\$|\{SHA\}|\$5\$|\$6\$)/m.test(text(b)) && 'password hash entries' },
+];
+
+const FIX = {
+  env: 'Remove the file from the web root and the deployment, then rotate every value it held. Keep environment files out of anything the web server can serve.',
+  vcs: 'Remove the repository metadata from the deployed site (deploy build output only) and block dot-directories at the web server. Assume the source and history were copied; rotate any secret that was ever committed.',
+  metadata: 'Delete the file from the deployment and add it to .gitignore.',
+  backup: 'Remove the file from the web root. Treat its contents as exposed and rotate any credential or review any data it held.',
+  credentials: 'Remove the file from the web root and change every password it lists.',
+};
+
+/** Returns { findings, probed, baseline } using session.get. Baseline is a random path that cannot exist. */
+export async function probeSensitiveFiles(session) {
+  const randomPath = `/vsg-${crypto.randomBytes(8).toString('hex')}`;
+  let baselineHash = null;
+  let baselineStatus = null;
+  try {
+    const base = await session.get(randomPath, { maxBytes: 65_536 });
+    baselineStatus = base.status;
+    baselineHash = sha256(base.body);
+  } catch { /* an unreadable baseline only removes the extra comparison; content signatures still apply */ }
+  const findings = [];
+  const probed = [];
+  for (const f of SENSITIVE_FILES) {
+    let res;
+    try { res = await session.get(f.path, { maxBytes: 65_536 }); } catch (e) { probed.push({ path: f.path, error: e.message }); continue; }
+    probed.push({ path: f.path, status: res.status });
+    if (res.status !== 200 && res.status !== 206) continue;
+    if (baselineHash && sha256(res.body) === baselineHash) continue; // same page as a random path: soft 404
+    const ct = res.headers.get('content-type') ?? '';
+    const sig = f.check(res.body, ct);
+    if (!sig) continue;
+    const url = new URL(f.path, session.origin).href;
+    findings.push({
+      category: 'live', tool: 'vsg-live', ruleId: `exposed-${f.kind}`, key: `exposed:${f.path}`, severity: f.severity, confidence: 'confirmed',
+      title: `${f.what[0].toUpperCase()}${f.what.slice(1)} is publicly readable: ${f.path}`, location: { url },
+      description: `${url} served its content (${f.what}) to an anonymous request. Anyone can download it.`,
+      evidence: `HTTP ${res.status}, ${ct || 'no content type'}, ${res.truncated ? 'over 64 KB' : `${res.body.length} bytes`}; ${sig}.${baselineStatus ? ` A random path returned HTTP ${baselineStatus}.` : ''}`,
+      fix: FIX[f.kind], refs: [], cwe: [538, 540],
+    });
+  }
+  return { findings, probed, baselineStatus };
+}

package/dist/security-runtime/src/live/secrets.mjs

@@ -0,0 +1,31 @@
+// JWT and Supabase inspection for live-js-secrets. Tokens are decoded in memory only; results carry redactions and a short hash.
+import { redact, sha256 } from '../core/findings.mjs';
+
+const JWT = /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g;
+const SUPABASE_URL = /https?:\/\/([a-z0-9]{20})\.supabase\.(?:co|in)\b/gi;
+
+const decode = (part) => { try { return JSON.parse(Buffer.from(part, 'base64url').toString('utf8')); } catch { return null; } };
+
+/**
+ * Finds JWT-looking strings and decodes them. Returns [{ hash, redacted, role, ref, iss, token }]; `token` is for hashing and
+ * matching only and must not be written anywhere. Strings that do not decode to a JSON header and payload are ignored.
+ */
+export function inspectJwts(text) {
+  const seen = new Set();
+  const out = [];
+  for (const [token] of String(text).matchAll(JWT)) {
+    if (seen.has(token)) continue;
+    seen.add(token);
+    const [h, p] = token.split('.');
+    const header = decode(h);
+    const payload = decode(p);
+    if (!header || typeof header !== 'object' || !payload || typeof payload !== 'object') continue;
+    out.push({ token, hash: sha256(token).slice(0, 12), redacted: redact(token), role: typeof payload.role === 'string' ? payload.role : null, ref: typeof payload.ref === 'string' ? payload.ref : null, iss: typeof payload.iss === 'string' ? payload.iss : null });
+  }
+  return out;
+}
+
+/** Supabase project URLs (as project refs) found in a document. */
+export function supabaseRefs(text) {
+  return [...new Set([...String(text).matchAll(SUPABASE_URL)].map((m) => m[1].toLowerCase()))];
+}

package/dist/security-runtime/src/live/session.mjs

@@ -0,0 +1,98 @@
+// A live session: the only way live checks touch the network. Every request is an ordinary GET or HEAD to the one registered
+// origin, passes one shared rate limiter (including retries and redirects), and has a 20 s timeout. It also shares the entry page
+// and the same-origin script files between checks so each is fetched once.
+import { FetchError } from '../core/errors.mjs';
+import { readCapped, vfetch } from '../core/fetch.mjs';
+import { scrubUrl } from '../core/findings.mjs';
+
+const TIMEOUT_MS = 20_000;
+export const MAX_SCRIPT_FILES = 200;
+export const MAX_SCRIPT_BYTES = 50 * 1024 * 1024;
+const MAX_ONE_SCRIPT = 15 * 1024 * 1024;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const NO_BODY = new Set([101, 204, 205, 304]);
+
+const SCRIPT_TAG = /<script\b[^>]*?\bsrc\s*=\s*["']?([^"'\s>]+)/gi;
+const LINK_JS = /<link\b[^>]*?\bhref\s*=\s*["']?([^"'\s>]+?\.m?js(?:\?[^"'\s>]*)?)["']?/gi;
+const NEXT_STATIC = /_next\/static\/[A-Za-z0-9_\-./%[\]~@]+?\.js/g;
+
+/** Candidate script URLs in a document, as absolute same-origin URLs. */
+export function scriptUrlsIn(text, baseUrl, origin) {
+  const found = new Set();
+  const add = (raw) => {
+    try {
+      const u = new URL(raw.replace(/&amp;/g, '&'), baseUrl);
+      if (u.origin !== origin || !/^https?:$/.test(u.protocol)) return;
+      u.hash = '';
+      found.add(u.href);
+    } catch { /* not a URL */ }
+  };
+  for (const re of [SCRIPT_TAG, LINK_JS]) for (const m of text.matchAll(re)) add(m[1]);
+  for (const m of text.matchAll(NEXT_STATIC)) add(`/${m[0]}`);
+  return [...found];
+}
+
+/**
+ * opts: { origin, url, environment, rps, fetchImpl, resolver }.
+ * get(pathOrUrl, { headers, maxBytes, method }) returns { status, headers, body, truncated, url } or throws FetchError.
+ */
+export function createSession({ origin, url, displayUrl = scrubUrl(url), environment = 'staging', rps = 2, fetchImpl = globalThis.fetch, resolver = null }) {
+  const originUrl = new URL(origin);
+  const interval = 1000 / rps;
+  let nextSlot = 0;
+  const requests = [];
+
+  async function slot() {
+    const now = Date.now();
+    const at = Math.max(now, nextSlot);
+    nextSlot = at + interval; // reserved synchronously, so concurrent callers queue behind each other
+    if (at > now) await sleep(at - now);
+  }
+
+  async function get(target, { headers = {}, maxBytes = 2 * 1024 * 1024, method = 'GET' } = {}) {
+    if (method !== 'GET' && method !== 'HEAD') throw new FetchError(`Live checks only send GET or HEAD, not ${method}.`);
+    const u = new URL(target, url);
+    if (u.origin !== origin) throw new FetchError(`Refusing ${u.origin}: outside the registered origin ${origin}.`);
+    let truncated = false;
+    const limited = async (reqUrl, init) => {
+      await slot();
+      const res = await fetchImpl(reqUrl, init);
+      requests.push({ method: init.method, path: new URL(reqUrl).pathname, status: res.status });
+      const { buf, truncated: t } = await readCapped(res, maxBytes);
+      if (t) truncated = true;
+      return new Response(NO_BODY.has(res.status) ? null : buf, { status: res.status, statusText: res.statusText, headers: res.headers });
+    };
+    const res = await vfetch(u.href, { method, headers: { 'user-agent': 'vsg-passive-check', accept: '*/*', ...headers }, timeoutMs: TIMEOUT_MS, allowHosts: [originUrl.host], strictHosts: true, fetchImpl: limited });
+    return { status: res.status, headers: res.headers, body: res.body, truncated, url: u.href };
+  }
+
+  let pagePromise;
+  /** The entry page, fetched once. Throws FetchError when it cannot be read. */
+  const page = () => (pagePromise ??= get(url, { maxBytes: 5 * 1024 * 1024 }).then((r) => ({ ...r, text: r.body.toString('utf8') })));
+
+  let scriptsPromise;
+  /** Same-origin scripts found in the entry page and, for Next.js chunks, inside other scripts. Capped at 200 files and 50 MB. */
+  const scripts = () => (scriptsPromise ??= (async () => {
+    const p = await page();
+    const queue = scriptUrlsIn(p.text, p.url, origin);
+    const seen = new Set(queue);
+    const items = [];
+    const failed = [];
+    let bytes = 0;
+    let capped = false;
+    let notScanned = 0;
+    while (queue.length) {
+      const next = queue.shift();
+      if (items.length >= MAX_SCRIPT_FILES || bytes >= MAX_SCRIPT_BYTES) { capped = true; notScanned = queue.length + 1; break; }
+      let r;
+      try { r = await get(next, { maxBytes: Math.min(MAX_ONE_SCRIPT, MAX_SCRIPT_BYTES - bytes) }); } catch (e) { failed.push({ url: next, reason: e.message }); continue; }
+      if (r.status !== 200) { failed.push({ url: next, reason: `HTTP ${r.status}` }); continue; }
+      bytes += r.body.length;
+      items.push({ url: next, body: r.body, headers: r.headers, truncated: r.truncated });
+      for (const more of scriptUrlsIn(r.body.toString('latin1'), next, origin)) if (!seen.has(more)) { seen.add(more); queue.push(more); }
+    }
+    return { items, failed, bytes, capped, notScanned };
+  })());
+
+  return { origin, url, displayUrl, host: originUrl.host, hostname: originUrl.hostname, environment, rps, resolver, requests, get, page, scripts };
+}

package/dist/security-runtime/src/live/targets.mjs

@@ -0,0 +1,81 @@
+// Target registration (REQ-024, DEC-004). A live check runs only for an origin listed in ~/.vsg/targets.json (honoring VSG_HOME)
+// or in the product's vsg.config.json "urls". Authorization happens before any request is made.
+import fs from 'node:fs';
+import path from 'node:path';
+import { UsageError } from '../core/errors.mjs';
+import { scrubUrl } from '../core/findings.mjs';
+
+const ENVIRONMENTS = ['local', 'staging', 'production'];
+
+/** Parses a target URL. Only http(s), no embedded credentials. */
+export function parseTargetUrl(text) {
+  let u;
+  try { u = new URL(String(text)); } catch { throw new UsageError(`"${scrubUrl(text)}" is not a valid URL. Pass a full URL such as https://staging.example.com.`); }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new UsageError(`"${u.protocol}" URLs are not supported. Use http or https.`);
+  if (u.username || u.password) throw new UsageError('Target URLs must not contain a username or password.');
+  return u;
+}
+
+const originOf = (text, where) => {
+  try { return parseTargetUrl(text).origin; } catch (e) { throw new UsageError(`${where}: ${e.message}`); }
+};
+
+/** Loads the machine-level targets file. Returns { file, entries: [{ product, origins, environment }], notes }. A missing file means no targets. */
+export function loadTargets(home) {
+  const file = path.join(home, 'targets.json');
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { file, entries: [], notes: [] }; }
+  let data;
+  try { data = JSON.parse(text); } catch (e) { throw new UsageError(`${file} is not valid JSON (${e.message}). Fix it and rerun.`); }
+  const list = Array.isArray(data) ? data : data?.targets;
+  if (!Array.isArray(list)) throw new UsageError(`${file} must be an array or { "targets": [] } of { product, origins, environment }.`);
+  const notes = [];
+  if (data && !Array.isArray(data) && 'active' in data) notes.push(`${file}: the "active" field is ignored. Live checks are passive only.`);
+  const entries = list.map((t, i) => {
+    const where = `${file} entry ${i + 1}`;
+    if (!t || typeof t !== 'object') throw new UsageError(`${where} must be an object.`);
+    if (typeof t.product !== 'string' || !t.product.trim()) throw new UsageError(`${where} needs a "product" name.`);
+    if (!Array.isArray(t.origins) || !t.origins.length) throw new UsageError(`${where} needs a non-empty "origins" array.`);
+    if (!ENVIRONMENTS.includes(t.environment)) throw new UsageError(`${where} needs "environment" set to local, staging or production.`);
+    if ('active' in t) notes.push(`${where} ("${t.product}"): the "active" field is ignored. Live checks are passive only.`);
+    return { product: t.product, origins: t.origins.map((o) => originOf(o, where)), environment: t.environment };
+  });
+  return { file, entries, notes };
+}
+
+export const isLoopback = (hostname) => hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '127.0.0.1' || hostname === '[::1]';
+
+/**
+ * Finds the entry that authorizes `urlText`, or throws a UsageError (exit 3) without touching the network.
+ * Returns { url, displayUrl, origin, hostname, host, environment, entry, description, notes }.
+ */
+export function authorize(urlText, { home, repoConfig = null, repoPath = null }) {
+  const url = parseTargetUrl(urlText);
+  const { file, entries, notes } = loadTargets(home);
+  const hit = entries.find((e) => e.origins.includes(url.origin));
+  const base = { url: url.href, displayUrl: scrubUrl(url.href), origin: url.origin, hostname: url.hostname, host: url.host, notes };
+  if (hit) {
+    return { ...base, environment: hit.environment, entry: { source: file, product: hit.product },
+      description: `${file}: product "${hit.product}", origin ${url.origin}, environment ${hit.environment}` };
+  }
+  const cfgHit = (repoConfig?.urls ?? []).some((u) => { try { return new URL(u).origin === url.origin; } catch { return false; } });
+  if (cfgHit) {
+    const where = repoPath ? path.join(repoPath, 'vsg.config.json') : 'vsg.config.json';
+    return { ...base, environment: isLoopback(url.hostname) ? 'local' : 'staging', entry: { source: where, product: null },
+      description: `${where}: urls entry for ${url.origin}` };
+  }
+  throw new UsageError(`${url.origin} is not a registered target, so no request was made. Add its origin to ${file} (Richard approves this) or to "urls" in the product's vsg.config.json.`);
+}
+
+export const MAX_RPS = 2;
+export const MAX_LOCAL_RPS = 100;
+
+/** Requests per second: 2 by default. Only a targets.json entry with environment "local" on a loopback host may go faster. */
+export function resolveRate(rateFlag, auth) {
+  if (rateFlag === undefined) return MAX_RPS;
+  const n = Number(rateFlag);
+  if (!Number.isFinite(n) || n <= 0) throw new UsageError('--rate must be a positive number of requests per second.');
+  const localEntry = auth.environment === 'local' && isLoopback(auth.hostname) && path.basename(auth.entry.source) === 'targets.json';
+  if (n > MAX_RPS && !localEntry) throw new UsageError(`--rate above ${MAX_RPS} requests per second is allowed only for a loopback origin registered as local in targets.json.`);
+  return Math.min(n, MAX_LOCAL_RPS);
+}

package/dist/security-runtime/src/portfolio/index.mjs

@@ -0,0 +1,116 @@
+// Portfolio runner (REQ-030): runs each registered product through the same pipeline, one after another, and writes a summary.
+import fs from 'node:fs';
+import path from 'node:path';
+import { UsageError } from '../core/errors.mjs';
+import { scrubText, scrubUrl } from '../core/findings.mjs';
+import { EXIT_CODES } from '../core/gate.mjs';
+import { runPipeline } from '../core/pipeline.mjs';
+
+export const KEEP_DAYS = 90;
+const RANK = { PASS: 0, INCOMPLETE: 1, BLOCKED: 2 };
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const worst = (verdicts) => verdicts.reduce((a, b) => (RANK[b] > RANK[a] ? b : a), 'PASS');
+
+/** Reads and validates portfolio.json. Relative product paths resolve against the config file's folder. */
+export function loadPortfolio(file) {
+  let data;
+  try { data = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) {
+    throw new UsageError(e.code === 'ENOENT' ? `${file} does not exist. Create it as { "schemaVersion": 1, "products": [{ "name", "path", "url"?, "mode": "scan"|"deep" }] }.` : `${file} is not valid JSON (${e.message}). Fix it and rerun.`);
+  }
+  if (data?.schemaVersion !== 1 || !Array.isArray(data.products)) throw new UsageError(`${file} must be { "schemaVersion": 1, "products": [...] }.`);
+  const names = new Set();
+  return data.products.map((p, i) => {
+    const where = `${file} product ${i + 1}`;
+    if (!p || typeof p !== 'object') throw new UsageError(`${where} must be an object.`);
+    if (typeof p.name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(p.name)) throw new UsageError(`${where} needs a "name" of letters, digits, dot, dash or underscore (it becomes a folder name).`);
+    if (names.has(p.name.toLowerCase())) throw new UsageError(`${where}: duplicate name "${p.name}".`);
+    names.add(p.name.toLowerCase());
+    if (typeof p.path !== 'string' || !p.path.trim()) throw new UsageError(`${where} ("${p.name}") needs a "path".`);
+    if (!['scan', 'deep'].includes(p.mode)) throw new UsageError(`${where} ("${p.name}") needs "mode" set to scan or deep.`);
+    if (p.url !== undefined && typeof p.url !== 'string') throw new UsageError(`${where} ("${p.name}"): "url" must be a string.`);
+    return { name: p.name, path: path.resolve(path.dirname(file), p.path), url: p.url, mode: p.mode };
+  });
+}
+
+const inside = (child, parent) => { const r = path.relative(parent, child); return r === '' || (!r.startsWith('..') && !path.isAbsolute(r)); };
+
+/** Removes dated folders (YYYY-MM-DD) older than KEEP_DAYS. Returns the removed names. */
+export function prune(root, now) {
+  const removed = [];
+  let entries;
+  try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { return removed; }
+  for (const e of entries) {
+    if (!e.isDirectory() || !/^\d{4}-\d{2}-\d{2}$/.test(e.name)) continue;
+    const t = Date.parse(`${e.name}T00:00:00Z`);
+    if (!Number.isNaN(t) && now - t > KEEP_DAYS * DAY_MS) { fs.rmSync(path.join(root, e.name), { recursive: true, force: true }); removed.push(e.name); }
+  }
+  return removed;
+}
+
+const fromResult = (r) => ({ verdict: r.verdict, mustFix: r.counts.blocking, notRun: r.coverage.filter((c) => c.status === 'not_run').map((c) => c.id), report: r.outputs.report });
+
+/**
+ * Runs every product. deps: { home, checks, registry, now, progress, prepareLive } where prepareLive(url, repo) authorizes a url
+ * (throwing on an unregistered origin) and returns { flags, info }.
+ */
+export async function runPortfolio(products, { home, checks, registry, now = () => new Date(), progress = () => {}, prepareLive }) {
+  const date = now().toISOString().slice(0, 10);
+  const root = path.join(home, 'portfolio');
+  const dir = path.join(root, date);
+  fs.mkdirSync(dir, { recursive: true });
+  const rows = [];
+  for (const p of products) {
+    const out = path.join(dir, p.name);
+    const row = { name: p.name, path: p.path, mode: p.mode, verdict: 'INCOMPLETE', mustFix: 0, notRun: [], report: null, url: null, error: null };
+    try {
+      if (!fs.existsSync(p.path) || !fs.statSync(p.path).isDirectory()) throw new Error(`path "${p.path}" is not a directory`);
+      if (inside(out, p.path)) throw new Error(`the output folder ${out} is inside the product; set VSG_HOME outside the repository`);
+      progress(`${p.name}: ${p.mode}`);
+      const r = await runPipeline({ mode: p.mode, repo: p.path, out, checks, registry, now, progress });
+      Object.assign(row, fromResult(r));
+      if (p.url) {
+        let live = null;
+        try { live = prepareLive(p.url, p.path); } catch (e) {
+          row.url = { status: 'not run', reason: scrubText(e.message) };
+          row.verdict = worst([row.verdict, 'INCOMPLETE']);
+        }
+        if (live) {
+          progress(`${p.name}: url ${live.info?.target ?? scrubUrl(p.url)}`);
+          try {
+            const u = await runPipeline({ mode: 'url', repo: p.path, out: path.join(out, 'url'), checks, registry, now, progress,
+              flags: { ...live.flags, target: live.info.target, authorization: live.info.authorization } });
+            const x = fromResult(u);
+            row.url = { status: 'ran', ...x };
+            row.verdict = worst([row.verdict, x.verdict]);
+            row.mustFix += x.mustFix;
+            row.notRun.push(...x.notRun.map((id) => `url:${id}`));
+          } catch (e) { row.url = { status: 'failed', reason: e.message }; row.verdict = worst([row.verdict, 'INCOMPLETE']); }
+        }
+      }
+    } catch (e) {
+      row.verdict = 'INCOMPLETE';
+      row.error = e.message;
+    }
+    rows.push(row);
+  }
+  const verdict = worst(rows.map((r) => r.verdict));
+  const summary = { schemaVersion: 1, date, verdict, exitCode: EXIT_CODES[verdict], products: rows };
+  fs.writeFileSync(path.join(dir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
+  fs.writeFileSync(path.join(dir, 'summary.md'), summaryMarkdown(summary));
+  const pruned = prune(root, now().getTime());
+  return { summary, dir, pruned, exitCode: summary.exitCode };
+}
+
+const cell = (s) => String(s).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+
+export function summaryMarkdown(s) {
+  const lines = [`# Portfolio ${s.verdict}: ${s.date}`, '', `${s.products.length} product(s). Exit code ${s.exitCode}.`, '',
+    '| Product | Mode | Verdict | Must fix | Checks not run | Report |', '| --- | --- | --- | --- | --- | --- |'];
+  for (const p of s.products) {
+    const notRun = p.error ? `run failed: ${p.error}` : p.notRun.length ? `${p.notRun.length}: ${p.notRun.join(', ')}` : 'none';
+    lines.push(`| ${cell(p.name)} | ${p.mode} | ${p.verdict} | ${p.mustFix} | ${cell(notRun)} | ${cell(p.report ?? 'none')} |`);
+  }
+  const urlNotes = s.products.filter((p) => p.url && p.url.status !== 'ran');
+  if (urlNotes.length) lines.push('', '## Live checks that did not run', '', ...urlNotes.map((p) => `- ${p.name}: ${p.url.status}: ${p.url.reason}`));
+  return `${lines.join('\n')}\n`;
+}

package/dist/security-runtime/tools/registry/betterleaks.json

@@ -0,0 +1,29 @@
+{
+  "name": "betterleaks",
+  "version": "1.9.0",
+  "license": "MIT",
+  "homepage": "https://github.com/betterleaks/betterleaks",
+  "releaseUrl": "https://github.com/betterleaks/betterleaks/releases/tag/v1.9.0",
+  "checksumsUrl": "https://github.com/betterleaks/betterleaks/releases/download/v1.9.0/checksums.txt",
+  "platforms": {
+    "win32-x64": {
+      "url": "https://github.com/betterleaks/betterleaks/releases/download/v1.9.0/betterleaks_1.9.0_windows_x64.zip",
+      "sha256": "b765daec9fda475b031b5a5159798cbe4294a3f2a50683cbc0471226e376d3da",
+      "archive": "zip",
+      "bin": "betterleaks.exe"
+    },
+    "linux-x64": {
+      "url": "https://github.com/betterleaks/betterleaks/releases/download/v1.9.0/betterleaks_1.9.0_linux_x64.tar.gz",
+      "sha256": "f8b185a39ffcece2a1ca82bf3a4e7435cd81963ffd16b7a9128daf75f35f6de7",
+      "archive": "tar.gz",
+      "bin": "betterleaks"
+    }
+  },
+  "verify": {
+    "args": [
+      "version"
+    ],
+    "expect": "1.9.0"
+  },
+  "timeoutSec": 600
+}

package/dist/security-runtime/tools/registry/guarddog.json

@@ -0,0 +1,9 @@
+{
+  "name": "guarddog",
+  "version": "3.2.0",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/DataDog/guarddog",
+  "releaseUrl": "https://github.com/DataDog/guarddog/releases/tag/v3.2.0",
+  "image": "ghcr.io/datadog/guarddog:v3.2.0@sha256:5b0804d480e83405120fc90c62b60ad844310418c836e567055b1ba8843e033d",
+  "timeoutSec": 120
+}

package/dist/security-runtime/tools/registry/mobsf.json

@@ -0,0 +1,10 @@
+{
+  "name": "mobsf",
+  "version": "v4.5.3",
+  "license": "GPL-3.0 (Mobile Security Framework)",
+  "homepage": "https://github.com/MobSF/Mobile-Security-Framework-MobSF",
+  "releaseUrl": "https://github.com/MobSF/Mobile-Security-Framework-MobSF/releases/tag/v4.5.3",
+  "image": "opensecurity/mobile-security-framework-mobsf:v4.5.3@sha256:5113fbad0727445dda01afdccafea5e107bfa8632ead8a169492f5caa8aa1b7c",
+  "purpose": "Optional static analysis of a built APK (vsg.config.json mobile.apk). Runs as a --rm container published on 127.0.0.1 only, with a per-run API key (MOBSF_API_KEY). The digest is the multi-arch index digest of tag v4.5.3, read from Docker Hub on 2026-10-06 (linux/amd64 d4e9ca08..., linux/arm64 78fe55cf...).",
+  "timeoutSec": 900
+}

package/dist/security-runtime/tools/registry/opengrep.json

@@ -0,0 +1,28 @@
+{
+  "name": "opengrep",
+  "version": "1.30.0",
+  "license": "LGPL-2.1",
+  "homepage": "https://github.com/opengrep/opengrep",
+  "releaseUrl": "https://github.com/opengrep/opengrep/releases/tag/v1.30.0",
+  "platforms": {
+    "win32-x64": {
+      "url": "https://github.com/opengrep/opengrep/releases/download/v1.30.0/opengrep_windows_x86.exe",
+      "sha256": "b5cf4f8fe9f44e030aab2d579d96bd395c139db1f1ba66633676ff4d5ebc7c39",
+      "archive": "none",
+      "bin": "opengrep.exe"
+    },
+    "linux-x64": {
+      "url": "https://github.com/opengrep/opengrep/releases/download/v1.30.0/opengrep_manylinux_x86",
+      "sha256": "35779bdd72e92129c8df2a77f0c55e8c08356801ea92591ef32108d6b28d564c",
+      "archive": "none",
+      "bin": "opengrep"
+    }
+  },
+  "verify": {
+    "args": [
+      "--version"
+    ],
+    "expect": "1.30.0"
+  },
+  "timeoutSec": 900
+}

package/dist/security-runtime/tools/registry/osv-scanner.json

@@ -0,0 +1,14 @@
+{
+  "name": "osv-scanner",
+  "version": "2.6.0",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/google/osv-scanner",
+  "releaseUrl": "https://github.com/google/osv-scanner/releases/tag/v2.6.0",
+  "checksumsUrl": "https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_SHA256SUMS",
+  "platforms": {
+    "win32-x64": { "url": "https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_windows_amd64.exe", "sha256": "e0ed7644118b717b028c249ee9d3515024e55e8510747ca08906eb96765354d6", "archive": "none", "bin": "osv-scanner.exe" },
+    "linux-x64": { "url": "https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_linux_amd64", "sha256": "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108", "archive": "none", "bin": "osv-scanner" }
+  },
+  "verify": { "args": ["--version"], "expect": "2.6.0" },
+  "timeoutSec": 300
+}

package/dist/security-runtime/tools/registry/semgrep-rules.json

@@ -0,0 +1,21 @@
+{
+  "name": "semgrep-rules",
+  "version": "a84ff9cc2453ca91d581380de4b8b3f272f6f4be",
+  "license": "Semgrep Rules License v1.0 (internal use)",
+  "homepage": "https://github.com/semgrep/semgrep-rules",
+  "releaseUrl": "https://github.com/semgrep/semgrep-rules/tree/a84ff9cc2453ca91d581380de4b8b3f272f6f4be",
+  "platforms": {
+    "win32-x64": {
+      "url": "https://codeload.github.com/semgrep/semgrep-rules/tar.gz/a84ff9cc2453ca91d581380de4b8b3f272f6f4be",
+      "sha256": "b227c2d234ffd9c84c4dbd6619a5897a7192637c141baeace3bfc37b0715a887",
+      "archive": "tar.gz",
+      "bin": "semgrep-rules-a84ff9cc2453ca91d581380de4b8b3f272f6f4be/README.md"
+    },
+    "linux-x64": {
+      "url": "https://codeload.github.com/semgrep/semgrep-rules/tar.gz/a84ff9cc2453ca91d581380de4b8b3f272f6f4be",
+      "sha256": "b227c2d234ffd9c84c4dbd6619a5897a7192637c141baeace3bfc37b0715a887",
+      "archive": "tar.gz",
+      "bin": "semgrep-rules-a84ff9cc2453ca91d581380de4b8b3f272f6f4be/README.md"
+    }
+  }
+}