nsauditor-ai 0.2.57 → 1.1.0

package/cli.mjs

@@ -25,9 +25,10 @@ import { resolveCapabilities, hasCapability, inferRequiredTier, CAPABILITIES } f
 import { createScheduler } from './utils/scheduler.mjs';
 import { watchCycle } from './utils/watch_cycle.mjs';
 import { redactSetCookieLines } from './utils/cookie_redaction.mjs';
-import { sendWebhook, buildAlertPayload, isSafeWebhookUrl } from './utils/webhook.mjs';
+import { sendWebhook, buildAlertPayload, isSafeWebhookUrl, ALERT_PAYLOADS, NOTIFY_FORMATS, NOTIFY_PAYLOADS, NOTIFY_SEVERITIES } from './utils/webhook.mjs';
 import { scrubByKey } from './utils/redact.mjs';
-import { isBlockedIp, resolveAndValidate, allowAllHosts, canonicalIp } from './utils/net_validation.mjs';
+import { isBlockedIp, resolveAndValidateAll, allowAllHosts, canonicalIp } from './utils/net_validation.mjs';
+import { runPinned } from './utils/scan_pin.mjs';
 import { getAllTechniques } from './utils/attack_map.mjs';
 import { TOOL_VERSION } from './utils/tool_version.mjs';
 import { resolveBaseOutDir, createHostOutDir, safeHost } from './utils/output_dir.mjs';
@@ -88,6 +89,34 @@ export function scrubIPv4KeepingProductIds(str, replaceAddress) {
  * to compare a raw against its payload, which needs the real function rather than a re-spelling
  * of its rules. `tests/redact_product_ids.test.mjs` is that census.
  */
+// ── AWS ACCOUNT IDs AND BARE 12-DIGIT IDS (EE 2.0.0) ──────────────────────────────────────────────────────────────────
+// Marketing task #204's real AWS run measured the account ID 20 times in one payload — bare, in bucket names, an SQS URL,
+// six SNS ARNs and an IAM user ARN — and the operator ruled "State it now, fix in 2.0.0". TWO PASSES, as the architect
+// seat ruled: (1) an ID found in a CERTAIN context — an ARN's account field in any partition, the account segment of an
+// `amazonaws.com/<12 digits>` URL — is an account, and every literal occurrence of it is masked as [ACCOUNT_ID], inside
+// resource names too (the names stay: remediation text that cannot name the bucket is useless to the customer); (2) any
+// OTHER bare 12-digit run is masked with a NEUTRAL label, [REDACTED_ID] — a 12-digit number in a router banner is not an AWS
+// account, so masking it is the safe direction and naming it would mislead the model and the auditor reading the payload.
+// tests/redact_aws_account_ids.test.mjs; the false-positive census is tests/redact_product_ids.test.mjs.
+export const ACCOUNT_ID_MASK = '[ACCOUNT_ID]';
+export const BARE_ID_MASK = '[REDACTED_ID]';
+const ARN_ACCOUNT_RE = /\barn:aws(?:-[a-z]+)*:[a-z0-9-]*:[a-z0-9-]*:(\d{12})(?=:)/gi;
+const URL_ACCOUNT_RE = /\bamazonaws\.com(?:\.cn)?\/(\d{12})(?!\d)/gi;
+const BARE_12_DIGIT_RE = /\b\d{12}\b/g;
+/** The AWS account IDs a payload carries in a CERTAIN context — ARN account fields and AWS URL segments, anywhere in it. */
+export function awsAccountIdsIn(input) {
+  const ids = new Set();
+  const visit = (v) => {
+    if (typeof v === 'string') {
+      for (const m of v.matchAll(ARN_ACCOUNT_RE)) ids.add(m[1]);
+      for (const m of v.matchAll(URL_ACCOUNT_RE)) ids.add(m[1]);
+    } else if (Array.isArray(v)) v.forEach(visit);
+    else if (v && typeof v === 'object') Object.values(v).forEach(visit);
+  };
+  visit(input);
+  return ids;
+}
+
 export function redactSensitiveForAI(input, targetHost) {
   const DROP_KEYS = new Set([
     'ip6', 'deviceWebPage', 'deviceWebPageInstruction',
@@ -99,8 +128,11 @@ export function redactSensitiveForAI(input, targetHost) {
     /^172\.(1[6-9]|2\d|3[0-1])\./.test(ip) ||
     /^192\.168\./.test(ip);
 
+  const accountIds = [...awsAccountIdsIn(input)];
+
   const scrubString = (str) => {
     let s = String(str);
+    for (const id of accountIds) s = s.split(id).join(ACCOUNT_ID_MASK);
     s = s.replace(/\bSerial\s*[:=]\s*[A-Za-z0-9._-]+/gi, 'Serial=[REDACTED_HIDDEN]');
     s = s.replace(/\b(?:[0-9a-f]{2}:){5}[0-9a-f]{2}\b/gi, '[MAC]'); // MAC
     s = s.replace(/\bfe80::[0-9a-f:]+\b/gi, '[FE80::/64]');         // IPv6 link-local
@@ -110,6 +142,8 @@ export function redactSensitiveForAI(input, targetHost) {
     // A scanned service's Set-Cookie VALUE is its session token: redacted here whatever a producer kept (1.3.0, both
     // seams ruled — the webapp detector still reflects its headers into the result).
     s = redactSetCookieLines(s);
+    // LAST, so every rule above sees the input it always saw (a `Serial: <12 digits>` stays the serial rule's).
+    s = s.replace(BARE_12_DIGIT_RE, BARE_ID_MASK);
     return s;
   };
 
@@ -131,18 +165,117 @@ export function redactSensitiveForAI(input, targetHost) {
   return walk(input);
 }
 
+/**
+ * The payload the AI stage writes to scan_response_ai_payload.json and sends: every redaction step, in order, in ONE function
+ * that maybeSendToOpenAI calls, so the file IS this function's output and docs/openai.md's list is driven through the real
+ * pipeline (EE 2.0.0, the architect seat's S1 — a test that composed the rules with a policy spelled in the TEST proved the
+ * rules, never the call site).
+ */
+export function buildAIPayload({ host, hostOsHint = null, summary, results, conclusion, detectedSerial = null, redact = true, env = process.env }) {
+  let payloadForAI = {
+    host,
+    host_os_hint: hostOsHint,
+    summary, // include full; redactor will mask
+    services: conclusion?.result?.services ?? [],
+    evidence: conclusion?.result?.evidence ?? [],
+    _meta: {
+      resultsCount: Array.isArray(results) ? results.length : (results ? 1 : 0),
+      serialFound: !!detectedSerial
+    }
+  };
+
+  if (redact) {
+    // `_meta.redactor` names what ran: 'builtin', Community's redactor, the same at every tier. Until EE 2.0.0 a Pro-tier
+    // branch here deferred to a `globalThis.redactSensitiveForAI` hook that neither package installs, and the record started
+    // as 'fallback' and stayed there, so every normal run said "fallback" (marketing task #204, finding 3). The branch is
+    // deleted (the architect seat's ruling), and so is its retry: the redactor builds a new object and never modifies its
+    // input, so a second call on the same input throws again. A throw propagates to maybeSendToOpenAI, which has then written
+    // and sent nothing.
+    const used = 'builtin';
+    payloadForAI = redactSensitiveForAI(payloadForAI, host);
+
+    // additional key-based scrubbing (CONFIDENTIAL_KEYWORDS=serial,password,token)
+    const keywords = String(env.CONFIDENTIAL_KEYWORDS || '')
+      .split(',')
+      .map((s) => s.trim().toLowerCase())
+      .filter(Boolean);
+    if (keywords.length) payloadForAI = scrubByKey(payloadForAI, keywords, '[REDACTED_HIDDEN]');
+
+    // Redact top-level host field (private IPs survive scrubString)
+    if (typeof payloadForAI.host === 'string') {
+      payloadForAI.host = '[REDACTED_HOST]';
+    }
+
+    // Redact any remaining IP addresses in the summary field
+    if (typeof payloadForAI.summary === 'string') {
+      // ⚠️ THE SAME RULE, A DIFFERENT POLICY: every address goes, private ones included. It
+      // carried its own copy of the address regex — the copy that was NOT fixed when the
+      // identifier defect was found in the redactor, which is exactly how the second instance
+      // of a class arrives. Measured at the time: neither live payload's summary carries an
+      // `EE-` token, so this was a latent duplicate rather than a live defect.
+      payloadForAI.summary = scrubIPv4KeepingProductIds(payloadForAI.summary, () => '[REDACTED_HOST]');
+    }
+
+    // Also redact private IPs in nested service/evidence strings
+    const privateIpRe = /\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b/g;
+    function scrubPrivateIps(obj) {
+      if (typeof obj === 'string') return obj.replace(privateIpRe, '[REDACTED_IP]');
+      if (Array.isArray(obj)) return obj.map(scrubPrivateIps);
+      if (obj && typeof obj === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) out[k] = scrubPrivateIps(v);
+        return out;
+      }
+      return obj;
+    }
+    payloadForAI.services = scrubPrivateIps(payloadForAI.services);
+    payloadForAI.evidence = scrubPrivateIps(payloadForAI.evidence);
+
+    payloadForAI = { ...payloadForAI, _meta: { ...(payloadForAI?._meta || {}), wasRedacted: true, redactor: used } };
+  } else {
+    payloadForAI = { ...payloadForAI, _meta: { ...(payloadForAI?._meta || {}), wasRedacted: false } };
+  }
+
+  // Ensure placeholder only if a serial was detected
+  if (payloadForAI?._meta?.serialFound && detectedSerial) {
+    const s = String(payloadForAI.summary ?? '').trim();
+    if (!/\bSerial\s*[:=]/i.test(s)) {
+      payloadForAI.summary = `${s}  Serial: [REDACTED_HIDDEN]`;
+    } else {
+      payloadForAI.summary = s.replace(/\bSerial\s*[:=]\s*([A-Za-z0-9._-]+)/i, 'Serial: [REDACTED_HIDDEN]');
+    }
+  }
+
+  return payloadForAI;
+}
+
 /* ------------------------- OpenAI & reporting -------------------------- */
 
+/**
+ * The OpenAI model used when OPENAI_MODEL is unset (EE 2.0.0, marketing task #203 — the small model it named until then was a generation stale). Chosen on
+ * 2026-10-11 against OpenAI's own pages, read raw: https://developers.openai.com/api/docs/models lists `gpt-6-luna` as
+ * "Our most efficient model for focused, high-volume tasks" ($0.10 / $0.50 per MTok, 128K max output, 1.05M context), and
+ * https://developers.openai.com/api/docs/deprecations maps the previous small model (`gpt-5.4-nano`) to it. The request
+ * sends only `model` and `input`, so no parameter a newer model refuses rides with it.
+ */
+export const DEFAULT_OPENAI_MODEL = 'gpt-6-luna';
+
+/** The model the AI step asks for: the provider's own variable, or its default. */
+export function aiModelFor(env = process.env) {
+  const aiProvider = (env.AI_PROVIDER || 'openai').toLowerCase().trim();
+  return aiProvider === 'claude'
+    ? toCleanPath(env.ANTHROPIC_MODEL || 'claude-sonnet-4-6')
+    : aiProvider === 'ollama'
+    ? toCleanPath(env.OLLAMA_MODEL || 'llama3')
+    : toCleanPath(env.OPENAI_MODEL || DEFAULT_OPENAI_MODEL);
+}
+
 async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basic', outDir: presetOutDir = null, runId = null, pluginStatus = [] }) {
   // --- env & opts -----------------------------------------------------------
   const sendEnabled   = parseBool(process.env.AI_ENABLED);
   const redactEnabled = parseBool(process.env.OPENAI_REDACT, true);
   const aiProvider    = (process.env.AI_PROVIDER || 'openai').toLowerCase().trim();
-  const model         = aiProvider === 'claude'
-    ? toCleanPath(process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-6')
-    : aiProvider === 'ollama'
-    ? toCleanPath(process.env.OLLAMA_MODEL || 'llama3')
-    : toCleanPath(process.env.OPENAI_MODEL || 'gpt-4o-mini');
+  const model         = aiModelFor(process.env);
   const { resolveSecret } = await import('./utils/keychain.mjs');
   const keyRaw        = aiProvider === 'claude'
     ? await resolveSecret(process.env.ANTHROPIC_API_KEY)
@@ -163,6 +296,7 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
   const adminRawPath   = path.join(outDir, 'scan_conclusion_raw.json');
   const adminHtmlPath  = path.join(outDir, 'scan_conclusion_raw.html');
   const aiPayloadPath  = path.join(outDir, 'scan_response_ai_payload.json');
+  const aiSystemPromptPath = path.join(outDir, 'scan_response_ai_system_prompt.txt');
   const aiResponsePath = path.join(outDir, 'scan_response_ai.json');
   const aiTxtPath      = path.join(outDir, 'scan_response_ai.txt');
   const aiHtmlPath     = path.join(outDir, 'scan_response_ai.html');
@@ -260,91 +394,8 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
   }
 
   // --- Build sanitized payload for AI ---------------------------------------
-  let payloadForAI = {
-    host,
-    host_os_hint: hostOsHint,
-    summary: summaryWithFullSerial, // include full; redactor will mask
-    services: conclusion?.result?.services ?? [],
-    evidence: conclusion?.result?.evidence ?? [],
-    _meta: {
-      resultsCount: Array.isArray(results) ? results.length : (results ? 1 : 0),
-      serialFound: !!detectedSerial
-    }
-  };
-
-  if (redactEnabled) {
-    let used = 'fallback';
-    try {
-      // Only allow external redaction override for Pro/Enterprise tiers.
-      // CE always uses the built-in redact pipeline to preserve the ZDE guarantee.
-      const redactCaps = resolveCapabilities(getTierFromEnv());
-      if (hasCapability(redactCaps, 'enhancedRedaction') && typeof globalThis.redactSensitiveForAI === 'function') {
-        let out = globalThis.redactSensitiveForAI(payloadForAI);
-        if (out && typeof out.then === 'function') out = await out;
-        if (typeof out === 'string') out = JSON.parse(out);
-        if (!out || typeof out !== 'object') throw new Error('external redactor returned non-object');
-        payloadForAI = out;
-        used = 'external';
-      } else {
-        payloadForAI = redactSensitiveForAI(payloadForAI, host);
-      }
-    } catch (e) {
-      console.warn('[OpenAI] Redaction failed, using fallback:', e?.message || e);
-      payloadForAI = redactSensitiveForAI(payloadForAI, host);
-      used = 'fallback';
-    }
-
-    // additional key-based scrubbing (CONFIDENTIAL_KEYWORDS=serial,password,token)
-    const keywords = String(process.env.CONFIDENTIAL_KEYWORDS || '')
-      .split(',')
-      .map((s) => s.trim().toLowerCase())
-      .filter(Boolean);
-    if (keywords.length) payloadForAI = scrubByKey(payloadForAI, keywords, '[REDACTED_HIDDEN]');
-
-    // Redact top-level host field (private IPs survive scrubString)
-    if (typeof payloadForAI.host === 'string') {
-      payloadForAI.host = '[REDACTED_HOST]';
-    }
-
-    // Redact any remaining IP addresses in the summary field
-    if (typeof payloadForAI.summary === 'string') {
-      // ⚠️ THE SAME RULE, A DIFFERENT POLICY: every address goes, private ones included. It
-      // carried its own copy of the address regex — the copy that was NOT fixed when the
-      // identifier defect was found in the redactor, which is exactly how the second instance
-      // of a class arrives. Measured at the time: neither live payload's summary carries an
-      // `EE-` token, so this was a latent duplicate rather than a live defect.
-      payloadForAI.summary = scrubIPv4KeepingProductIds(payloadForAI.summary, () => '[REDACTED_HOST]');
-    }
-
-    // Also redact private IPs in nested service/evidence strings
-    const privateIpRe = /\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b/g;
-    function scrubPrivateIps(obj) {
-      if (typeof obj === 'string') return obj.replace(privateIpRe, '[REDACTED_IP]');
-      if (Array.isArray(obj)) return obj.map(scrubPrivateIps);
-      if (obj && typeof obj === 'object') {
-        const out = {};
-        for (const [k, v] of Object.entries(obj)) out[k] = scrubPrivateIps(v);
-        return out;
-      }
-      return obj;
-    }
-    payloadForAI.services = scrubPrivateIps(payloadForAI.services);
-    payloadForAI.evidence = scrubPrivateIps(payloadForAI.evidence);
-
-    payloadForAI = { ...payloadForAI, _meta: { ...(payloadForAI?._meta || {}), wasRedacted: true, redactor: used } };
-  } else {
-    payloadForAI = { ...payloadForAI, _meta: { ...(payloadForAI?._meta || {}), wasRedacted: false } };
-  }
-
-  // Ensure placeholder only if a serial was detected
-  if (payloadForAI?._meta?.serialFound && detectedSerial) {
-    const s = String(payloadForAI.summary ?? '').trim();
-    if (!/\bSerial\s*[:=]/i.test(s)) {
-      payloadForAI.summary = `${s}  Serial: [REDACTED_HIDDEN]`;
-    } else {
-      payloadForAI.summary = s.replace(/\bSerial\s*[:=]\s*([A-Za-z0-9._-]+)/i, 'Serial: [REDACTED_HIDDEN]');
-    }
-  }
+  const payloadForAI = buildAIPayload({ host, hostOsHint, summary: summaryWithFullSerial, results, conclusion, detectedSerial,
+    redact: redactEnabled });
 
   // --- Bail out early if sending disabled -----------------------------------
   const providerLabel = aiProvider === 'claude' ? 'Claude' : aiProvider === 'ollama' ? 'Ollama' : 'OpenAI';
@@ -379,6 +430,17 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
   const eeBlock = conclusion?.result?.eeEnrichment?.enrichedPrompt;
   if (eeBlock) promptText = eeBlock + '\n\n---\n\n' + promptText;
 
+  // --- Write the SYSTEM PROMPT we plan to send, beside the payload (EE 2.0.0, marketing task #204 finding 2) ---
+  // On Pro and Enterprise the intelligence block above travels here, not in the payload, so the payload file alone was not
+  // the record of what left the machine. Written BEFORE the request, as the payload is: the two files together are the
+  // request's content (the model name and the key are the rest).
+  try {
+    await fsp.writeFile(aiSystemPromptPath, promptText, 'utf8');
+    console.log(`[${providerLabel}] Wrote AI system prompt:`, aiSystemPromptPath);
+  } catch (e) {
+    console.warn(`[${providerLabel}] Failed to write AI system prompt:`, e?.message || e);
+  }
+
   // --- Send to AI provider ---------------------------------------------------
   let aiConclusionText = null;
   // review fold 8: contain the serialization — hoisting userContent above the
@@ -615,6 +677,18 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
 
 /* ------------------------------- CLI ----------------------------------- */
 
+/**
+ * Why a webhook URL flag's value is refused before any address is looked at, or null: it is not a URL, or its scheme is
+ * not one the flag takes. The value itself is never repeated — a Slack or Teams webhook URL carries its own credential.
+ * @param {string} flag @param {unknown} value @param {string[]} schemes e.g. ['https:'] or ['http:', 'https:']
+ */
+function webhookSchemeRefusal(flag, value, schemes) {
+  const wanted = schemes.length === 1 ? `an ${schemes[0].replace(':', '')} URL` : `an ${schemes.map((x) => x.replace(':', '')).join(' or ')} URL`;
+  let protocol;
+  try { protocol = new URL(String(value)).protocol; } catch { return `${flag} must be ${wanted}; the value given is not a URL`; }
+  return schemes.includes(protocol) ? null : `${flag} must be ${wanted}; got ${protocol}`;
+}
+
 export async function parseArgs(argv) {
   const args = { cmd: 'scan', host: undefined, plugins: 'all', insecureHttps: false };
   const a = argv.slice(2);
@@ -711,21 +785,81 @@ export async function parseArgs(argv) {
   args.watch = !!(get('watch'));
   const intervalVal = get('interval');
   args.intervalMinutes = (intervalVal && intervalVal !== true) ? Math.max(1, parseInt(intervalVal, 10) || 60) : 60;
+  // Every refusal from here on THROWS with code EFLAGVALUE (mapped to exit 2 at the entry point), never `process.exit`:
+  // parseArgs is exported and driven in-process by the suite, and an exit here kills the runner mid-file (the EFLAGSHAPE
+  // lesson — `--webhook-url` exited here until the next Community release after 1.0.0).
+  const flagValue = (msg) => Object.assign(new Error(msg), { code: 'EFLAGVALUE' });
   const whUrl = get('webhook-url') || get('webhook_url') || null;
   if (whUrl && whUrl !== true) {
+    // Not a URL, or a scheme other than http(s), is named as that — never as an internal address.
+    const schemeRefusal = webhookSchemeRefusal('--webhook-url', whUrl, ['http:', 'https:']);
+    if (schemeRefusal) throw flagValue(schemeRefusal);
     if (!(await isSafeWebhookUrl(whUrl))) {
-      console.error(`[ERROR] Webhook URL rejected: private/loopback/metadata addresses are not allowed.`);
-      process.exit(2);
+      throw flagValue('Webhook URL rejected: private/loopback/metadata addresses are not allowed.');
+    }
+    // A plain-http alert URL is accepted (documented; whether to refuse it is a MAJOR-shaped decision, boarded), and the
+    // operator is told once what it costs. The URL itself is never printed — it carries its own credential.
+    if (new URL(whUrl).protocol === 'http:') {
+      console.warn('[WARN] --webhook-url is a plain http URL: findings leave in the clear over plaintext HTTP on every '
+        + 'watch alert sent to it — use an https URL');
     }
     args.webhookUrl = whUrl;
   } else {
     args.webhookUrl = null;
   }
-  const alertSev = get('alert-severity') || get('alert_severity') || null;
-  args.alertSeverity = (alertSev && alertSev !== true) ? alertSev.toLowerCase() : 'high';
+  // The accepted values are the alert path's own rank table (SEVERITY_RANK), in any case. An unrecognised one used to
+  // become `high` in silence — the rank fallback — while the alert echoed the typo; it is refused like every value flag.
+  const alertSev = get('alert-severity') ?? get('alert_severity');
+  const ALERT_SEVERITIES = Object.keys(SEVERITY_RANK);
+  if (alertSev === undefined || alertSev === null) args.alertSeverity = 'high';
+  else if (alertSev === true || !ALERT_SEVERITIES.includes(String(alertSev).toLowerCase())) {
+    throw flagValue(`--alert-severity must be one of ${ALERT_SEVERITIES.join(' | ')}`);
+  } else args.alertSeverity = String(alertSev).toLowerCase();
   // R4: by default a watch cycle alerts only hosts whose scan CHANGED; this restores an alert on every cycle.
   args.alertEveryCycle = !!(get('alert-every-cycle') || get('alert_every_cycle'));
 
+  // ── EE 2.0.0 (cargo 3, D3/D5): the drift notification and the watch alert's payload mode ─────────────────────────
+  const oneOf = (flag, allowed, dflt) => {
+    const v = get(flag);
+    if (v === undefined) return dflt;
+    if (v === true || !allowed.includes(String(v).toLowerCase())) throw flagValue(`--${flag} must be one of ${allowed.join(' | ')}`);
+    return String(v).toLowerCase();
+  };
+  const notifyUrl = get('notify-webhook');
+  if (notifyUrl === true) throw flagValue('--notify-webhook requires a URL');
+  args.notifyFormat = oneOf('notify-format', NOTIFY_FORMATS, null);
+  args.notifySeverity = oneOf('notify-severity', NOTIFY_SEVERITIES, null);
+  args.notifyPayload = oneOf('notify-payload', NOTIFY_PAYLOADS, null);
+  if (notifyUrl === undefined) {
+    const stray = [['notify-format', args.notifyFormat], ['notify-severity', args.notifySeverity], ['notify-payload', args.notifyPayload]]
+      .filter(([, v]) => v !== null).map(([f]) => `--${f}`);
+    if (stray.length) throw flagValue(`${stray.join(', ')} configure the drift notification and need --notify-webhook <url>`);
+    args.notifyWebhook = null;
+  } else {
+    if (args.watch) {
+      throw flagValue('--notify-webhook sends the drift file of a ONE-SHOT scan, and --watch writes none; '
+        + 'watch-mode alerts use --webhook-url');
+    }
+    // https ONLY (the architect seat's read, F3): the URL is a credential and the body is scan content, so neither
+    // crosses the network in the clear. --webhook-url is unchanged.
+    let notifyProtocol = null;
+    try { notifyProtocol = new URL(notifyUrl).protocol; } catch { /* not a URL — named just below */ }
+    if (notifyProtocol === 'http:') {
+      throw flagValue('--notify-webhook must be an https URL: it carries its own credential, and the drift it sends is scan content');
+    }
+    const notifySchemeRefusal = webhookSchemeRefusal('--notify-webhook', notifyUrl, ['https:']);
+    if (notifySchemeRefusal) throw flagValue(notifySchemeRefusal);
+    // The SAME boundary check --webhook-url gets: public destinations only, DNS-resolved.
+    if (!(await isSafeWebhookUrl(notifyUrl))) {
+      throw flagValue('--notify-webhook rejected: private/loopback/metadata addresses are not allowed');
+    }
+    args.notifyWebhook = notifyUrl;
+  }
+  args.alertPayload = oneOf('alert-payload', ALERT_PAYLOADS, 'full');
+  if (get('alert-payload') !== undefined && !args.webhookUrl) {
+    throw flagValue('--alert-payload shapes the --watch webhook alert and needs --webhook-url <url>');
+  }
+
   // Compliance: framework selector + scope file. Forwarded to EE's
   // runCompliancePhase via enrichScan(). No-op without an EE Enterprise license.
   const complianceVal = get('compliance');
@@ -865,6 +999,16 @@ export async function parseArgs(argv) {
  * @param {{ cmd?: string, host?: string|true, hostFile?: string }} args  parseArgs' result
  * @returns {{ message: string, code: number }|null}
  */
+/**
+ * EE 2.0.0: --notify-webhook sends the drift of a COMPLIANCE scan, so a run with no framework — from --compliance or
+ * from COMPLIANCE_FRAMEWORKS, which --env may have loaded — would accept the flag and send nothing, ever. Refused.
+ */
+export function notifyRefusal({ notifyWebhook, compliance, envCompliance } = {}) {
+  if (!notifyWebhook || compliance || envCompliance) return null;
+  return { code: 2, message: 'Fatal: --notify-webhook sends the drift file of a compliance scan; name a framework '
+    + 'with --compliance (or COMPLIANCE_FRAMEWORKS)' };
+}
+
 export function scanTargetRefusal({ cmd, host, hostFile } = {}) {
   if (cmd !== 'scan') return { message: `Unknown command: ${cmd}`, code: 2 };
   if (!hostFile && !host) return { message: 'Fatal: --host or --host-file is required', code: 2 };
@@ -894,34 +1038,59 @@ const CLOUD_SENTINEL_HOSTS = new Set(['aws', 'gcp', 'azure']);
  * that is not a literal is resolved with EVERY answer checked. Before 1.3.0 a digits-and-dots string
  * skipped resolution (/^[\\d.:[\\]]+$/), so '6425673729' — which the OS reads as 127.0.0.1 — was
  * scanned unchecked.
+ *
+ * PINNED SINCE EE 2.0.0 (R1b — the operator's ruling "CLI pins too"): it RETURNS the answer set it resolved, and
+ * scanSingleHost runs the plugins inside `runPinned` with it, so the scan connects to the addresses this check looked at.
+ * NSA_ALLOW_ALL_HOSTS relaxes WHICH answers are admitted, never whether one may change between the check and the connect:
+ * under it the name is resolved WITHOUT a refusal and still pinned; a name that does not resolve is refused
+ * (ETARGETUNRESOLVED) under it as without it — until the Community release after 1.0.0 it scanned unpinned.
  * @param {string} host
  * @param {Record<string,string|undefined>} [env]
+ * @returns {Promise<Array<{ address: string, family: 4|6 }> | null>} the answers to pin; null for a literal or a sentinel
  */
 export async function assertScanTargetAllowed(host, env = process.env) {
+  // A refusal is an operator error, coded so the entry point names it and exits 2 rather than printing a stack.
+  const refuse = (msg) => Object.assign(new Error(msg), { code: 'ETARGETREFUSED' });
+  // A name that does not resolve was not refused by the guard — it cannot be scanned at all, because a scan connects only
+  // to the addresses its check resolved. Its own code and its own sentence, with or without NSA_ALLOW_ALL_HOSTS (which
+  // admits every address range, never an unresolved name). MCP refuses it the same way.
+  const unresolved = (err) => Object.assign(new Error(`Host could not be resolved: ${host} (${err?.code ?? 'no answer'}) — `
+    + 'a scan connects only to the addresses its host check resolved, so a target that does not resolve is not scanned'),
+  { code: 'ETARGETUNRESOLVED' });
+  const BLOCKED_ANSWER = 'Host resolves to blocked IP range';
   const isCloudSentinel = typeof host === 'string' && CLOUD_SENTINEL_HOSTS.has(host.toLowerCase());
-  if (isCloudSentinel || allowAllHosts(env)) return;
+  if (isCloudSentinel) return null;
+  if (allowAllHosts(env)) {
+    if (canonicalIp(host)) return null;
+    try { return await resolveAndValidateAll(host, { checkAnswers: false }); } catch (err) { throw unresolved(err); }
+  }
   if (isBlockedIp(host)) {
-    throw new Error(`Scanning blocked address range is not allowed: ${host}`);
+    throw refuse(`Scanning blocked address range is not allowed: ${host}`);
   }
   if (!canonicalIp(host)) {
     try {
-      await resolveAndValidate(host);
+      return await resolveAndValidateAll(host);
     } catch (err) {
-      throw new Error(`Host rejected by SSRF guard: ${err.message}`);
+      if (err?.message === BLOCKED_ANSWER) throw refuse(`Host rejected by SSRF guard: ${err.message}`);
+      throw unresolved(err);
     }
   }
+  return null;
 }
 
 export async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   // SSRF guard — block loopback, private ranges, cloud metadata endpoints.
-  // Set NSA_ALLOW_ALL_HOSTS=1 to scan RFC 1918 / private ranges (local network auditing).
+  // NSA_ALLOW_ALL_HOSTS=1 lifts this whole guard for local network auditing — loopback and metadata included (the MCP
+  // server's guard admits private ranges only).
   // Cloud-sentinel hosts (see CLOUD_SENTINEL_HOSTS above) skip the guard.
-  await assertScanTargetAllowed(host);
+  const answers = await assertScanTargetAllowed(host);
 
   // `manifest` classifies every selected plugin as ran|skipped|timeout|error with a reason.
   // Discarding it is what makes "no findings" ambiguous between a clean estate and one whose
   // plugins never loaded — see utils/run_record.mjs.
-  const { results, conclusion, manifest: pluginStatus = [] } = await pm.run(host, plugins || 'all', opts);
+  // R1b: the plugins connect to the addresses the check resolved (utils/scan_pin.mjs), never to a second answer.
+  const { results, conclusion, manifest: pluginStatus = [] } = await runPinned(answers ? { [host]: answers } : null,
+    () => pm.run(host, plugins || 'all', opts));
 
   // Enrich conclusion with MITRE ATT&CK technique mapping
   const techniques = getAllTechniques(conclusion);
@@ -1012,6 +1181,18 @@ export async function scanSingleHost(pm, host, plugins, opts, promptMode) {
       // delta as findings RESOLVED — measured on a live run, three such rows.
       pluginStatus,
       onWarn: (msg) => console.warn(`[EE] ${msg}`),
+      // EE 2.0.0 (the drift file). The run id and the root the run records are written under (the SAME resolver
+      // `appendHostWritten` below uses), so EE compares with the run `report --since prior` names; and `watch`, true
+      // only from the watch loop, where EE writes no drift file. Pinned by tests/ee_drift_forwarding.test.mjs.
+      runId: opts?.runId ?? null,
+      runRecordRoot: resolveBaseOutDir(),
+      watch: opts?.watch === true,
+      // EE 2.0.0 (cargo 3, D3/D4): the opt-in drift notification, forwarded verbatim; EE validates every value again
+      // and sends only on a compared drift that crossed a trigger. Pinned by tests/cli_notify_flags.test.mjs.
+      notifyWebhook: opts?.notifyWebhook ?? null,
+      notifyFormat: opts?.notifyFormat ?? null,
+      notifySeverity: opts?.notifySeverity ?? null,
+      notifyPayload: opts?.notifyPayload ?? null,
     }) : null;
     hostScopeScanned = eeEnrichment?.scopeScanned ?? null;
     // ⚠️ Read from `exploitIntel.stores`, NOT a top-level `exploit` key — measured against
@@ -1634,7 +1815,7 @@ export async function runReport(args, caps) {
 
 export async function main(testHooks = {}) {
   const args = await parseArgs(process.argv);
-  const { cmd, host, plugins, insecureHttps, hostFile, parallel, failOn, outputFormat, watch, intervalMinutes, webhookUrl, alertSeverity, alertEveryCycle, ports, compliance, complianceScope, complianceHistory, slaPolicy, attestWindow, framework, awsRegion, approvalArgs, feedArgs } = args;
+  const { cmd, host, plugins, insecureHttps, hostFile, parallel, failOn, outputFormat, watch, intervalMinutes, webhookUrl, alertSeverity, alertEveryCycle, alertPayload, notifyWebhook, notifyFormat, notifySeverity, notifyPayload, ports, compliance, complianceScope, complianceHistory, slaPolicy, attestWindow, framework, awsRegion, approvalArgs, feedArgs } = args;
 
   // Version: handled before license verification so it works without a key.
   // CE-0.1.30.1 — closes the discovery-flag UX gap where pre-fix
@@ -1673,7 +1854,7 @@ Scan options:
                                region-scoped checks use AWS_REGION, else one region (with an
                                incomplete-coverage notice); CloudTrail trail discovery,
                                GuardDuty/Inspector and EC2 instances attempt every region.
-  --plugins <list|all>         Plugins to run (e.g. 001,003,020 or "all"; default: all)
+  --plugins <list|all>         Plugins to run (e.g. 001,003,011 or "all"; default: all)
   --ports <list>               Ports ADDED to the default set (e.g. 22,80,443 or 161/udp;
                                a range such as 1-1000 is not parsed and adds nothing)
   --out <dir>                  Output directory for scan artifacts
@@ -1685,11 +1866,11 @@ Scan options:
                                040 / 050 / 060 audits (060: the domain's SPF / DMARC /
                                NS), and Dangerous HTTP methods (medium) only where an
                                Allow header was read. Anonymous FTP / zone transfer /
-                               null session only with FTP_CHECK_ANON / DNS_CHECK_AXFR /
-                               SMB_NULL_SESSION set; not tested never trips it; any
-                               concluded scan is info. Not CVEs or agent findings —
-                               exit 0 is not a clean host. Exit 2: unknown severity or
-                               no conclusion.
+                               null session only with FTP_CHECK_ANON / DNS_CHECK_AXFR
+                               or DNS_AUDIT_AXFR_CHECK (060) / SMB_NULL_SESSION set;
+                               not tested never trips it; any concluded scan is info.
+                               Not CVEs or agent findings — exit 0 is not a clean host.
+                               Exit 2: unknown severity or no conclusion.
   --output-format <fmt>        Additional report format: sarif | csv | md
   --insecure-https             Skip TLS validation on probed HTTPS targets
   --watch                      CTEM continuous ALERTING mode: re-scan on --interval and
@@ -1709,10 +1890,21 @@ Scan options:
                                one-shot --host X,X scans X twice.
   --interval <minutes>         Watch interval (default 60)
   --webhook-url <url>          Send --watch alerts (must be public; private/loopback blocked)
-  --alert-severity <sev>       Min severity to alert on (default: high)
+  --alert-severity <sev>       Min severity to alert on: critical|high|medium|low|info (default: high)
   --alert-every-cycle          Alert every host with a finding at or above --alert-severity
                                on every --watch cycle, the first included (default: only
                                hosts whose scan changed)
+  --alert-payload <mode>       full (default) | minimal — minimal drops the host, service and
+                               description from each --watch alert
+  --notify-webhook <url>       Enterprise, one-shot scans with --compliance only (never --watch):
+                               POST the scan's drift (scan_drift_<fw>.json) when a control goes
+                               to fail, a control loses measurement, or a new violation is at or
+                               above --notify-severity. Public https URLs only; off by default
+  --notify-format <fmt>        generic (default) | slack | teams (a Teams Workflows webhook)
+  --notify-severity <sev>      critical | high (default) | medium | low | info — for new
+                               violations only
+  --notify-payload <mode>      minimal (default: no hostnames, resources, account ids or
+                               finding text) | full
   --compliance <framework>     Map findings to controls. 'all' = all 8 frameworks, or a CSV of
                                soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr,nist-800-171
                                (aliases nist/pci/iso/cis, and 800-171 or cmmc for nist-800-171 --
@@ -1821,7 +2013,9 @@ Environment:
   NSA_MCP_AUTH_KEY               MCP server auth key — read by mcp_server at startup;
                                  client supplies via Claude Desktop config env block
   NSA_MCP_AUTH_DISABLE=1         Skip MCP auth check (CI/dev escape hatch — emits warn)
-  NSA_ALLOW_ALL_HOSTS=1          Permit RFC1918 / loopback (local-network auditing)
+  NSA_ALLOW_ALL_HOSTS=1          Local-network auditing. CLI: lifts the whole scan-entry
+                                 guard, loopback and metadata included. MCP server:
+                                 admits RFC 1918 / CGNAT / fc00::/7 only
   CLOUD_PROVIDER=aws|gcp|azure   Required for cloud scanner plugins (020/021/022/023/030)
   AI_PROVIDER=openai|claude|ollama   AI provider for report generation
   NSAUDITOR_TSA_URL              RFC 3161 timestamp authority for compliance attestation.
@@ -2709,11 +2903,19 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       const { readFile, stat } = await import('node:fs/promises');
       const { join: _join } = await import('node:path');
       const { homedir: _homedir } = await import('node:os');
-      const { responseDigest, bodyOf } = await import('./utils/mcp_call_digest.mjs');
+      const { responseDigest, requestDigest, bodyOf } = await import('./utils/mcp_call_digest.mjs');
       const logPath = _join(_homedir(), '.nsauditor', 'mcp-calls.log');
       const uuid = rawArgs[2];
       const respAt = rawArgs.indexOf('--response');
       const respPath = respAt > 0 ? rawArgs[respAt + 1] : null;
+      // B63 (2.1.0): the request saved beside the response (<call_id>.request.json), checked against the digest the
+      // server logged of that file's bytes. Optional; absent, every output below is what it was.
+      const reqAt = rawArgs.indexOf('--request');
+      const reqPath = reqAt > 0 ? rawArgs[reqAt + 1] : null;
+      if (reqAt > 0 && !reqPath) {
+        console.error('Usage: nsauditor-ai mcp verify-call <uuid> --response <file|-> --request <file>');
+        process.exit(2);
+      }
       if (!uuid || (respAt > 0 && !respPath)) {
         console.error('Usage: nsauditor-ai mcp verify-call <uuid> --response <file|->');
         console.error('  Save the whole tool response (footer included) to a file, or pipe it in with --response -.');
@@ -2740,6 +2942,13 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
           process.exit(2);
         }
       }
+      let reqBytes = null;
+      if (reqPath) {
+        try { reqBytes = await readFile(reqPath); } catch (err) {
+          console.error(`✗ Could not read the request from ${reqPath}: ${err.message}`);
+          process.exit(2);
+        }
+      }
       let logExists = false;
       try { await stat(logPath); logExists = true; } catch { /* missing */ }
       if (!logExists) {
@@ -2774,28 +2983,48 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       })();
       const issuedLine = `${issued.tool ?? 'an unrecorded tool'}, issued ${ago} (${issued.ts ?? 'no timestamp'})`;
       const digests = entries.map((e) => e.digest).filter((d) => typeof d === 'string');
+      // With --request, the request is checked after the response and the exit is the worse of the two: any refutation
+      // is 1, otherwise anything indeterminate is 3. Without it, each exit below is exactly what it was.
+      const finish = (code) => {
+        if (reqBytes == null) process.exit(code);
+        const recorded = entries.map((e) => e.request_digest).filter((d) => typeof d === 'string');
+        let reqCode;
+        if (recorded.length === 0) {
+          console.log(`? The request is not bound: this server recorded no request digest for call_id ${uuid}.`);
+          console.log('  The call was not saved with NSA_MCP_RESPONSE_DIR set, or it predates request binding.');
+          reqCode = 3;
+        } else if (recorded.includes(requestDigest(reqBytes))) {
+          console.log(`✓ This request is the one the server recorded for that call — ${issuedLine}.`);
+          reqCode = 0;
+        } else {
+          console.log(`✗ The request does not match what this server recorded for that call (${issuedLine}).`);
+          console.log('  It was changed after the server wrote it, or it belongs to another call.');
+          reqCode = 1;
+        }
+        process.exit(code === 1 || reqCode === 1 ? 1 : (code === 3 || reqCode === 3 ? 3 : 0));
+      };
       if (digests.length === 0) {
         console.log(`? call_id ${uuid} was issued by this server for ${issued.tool ?? 'an unrecorded tool'} ${ago} (${issued.ts ?? 'no timestamp'}).`);
         console.log('  This call predates response binding: no digest of its response was recorded, so the text');
         console.log('  cannot be bound to it. The id alone does not verify a response.');
-        process.exit(3);
+        finish(3);
       }
       if (responseText == null) {
         console.log(`? call_id ${uuid} was issued by this server for ${issued.tool ?? 'an unrecorded tool'} ${ago} (${issued.ts ?? 'no timestamp'}).`);
         console.log('  That alone does not verify the text you are reading: an id from an earlier response can be');
         console.log('  pasted under a fabricated one. Save the raw tool response and run:');
         console.log(`    nsauditor-ai mcp verify-call ${uuid} --response <file>`);
-        process.exit(3);
+        finish(3);
       }
       if (digests.includes(responseDigest(bodyOf(responseText)))) {
         console.log(`✓ This response text was produced by this server for that call — ${issuedLine}.`);
         console.log(`  log: ${logPath}`);
-        process.exit(0);
+        finish(0);
       }
       console.log(`✗ The text does not match what this server sent for that call (${issuedLine}).`);
       console.log('  Either it was altered after copying (rendering, re-wrapping) or it was not produced by this');
       console.log('  call — re-copy the RAW tool output and verify again.');
-      process.exit(1);
+      finish(1);
     } else {
       console.log('Usage:');
       console.log('  nsauditor-ai mcp install-key            Generate a new key, persist, print Claude config');
@@ -2805,6 +3034,7 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       console.log('  nsauditor-ai mcp status                 Show storage source without revealing the key');
       console.log('  nsauditor-ai mcp tier                   Print actual MCP server tier (ground truth, bypasses Claude AI synthesis)');
       console.log('  nsauditor-ai mcp verify-call <uuid> --response <file|->   Check that a saved tool response is the text this server produced for that call');
+      console.log('      [--request <file>]   …and that a saved request (<call_id>.request.json) is the one it recorded');
       console.log('');
       console.log('Environment variables:');
       console.log(`  ${MCP_AUTH_ENV_VAR}        Read by mcp_server.mjs at startup; client supplies via Claude config`);
@@ -3234,15 +3464,29 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     opts.complianceTrackSla = true;
   }
   if (awsRegionIntent) opts.awsRegionIntent = awsRegionIntent;
+  // EE 2.0.0: the drift notification needs a framework to drift — refused here, where --env has already loaded.
+  const notifyRefused = notifyRefusal({ notifyWebhook, compliance, envCompliance: process.env.COMPLIANCE_FRAMEWORKS });
+  if (notifyRefused) {
+    console.error(notifyRefused.message);
+    process.exit(notifyRefused.code);
+  }
+  if (notifyWebhook) Object.assign(opts, { notifyWebhook, notifyFormat, notifySeverity, notifyPayload });
   const pm = await PluginManager.create(`${__dirname}/plugins`);
+  // Before the watch loop, the run record or any host: a --plugins list that names no plugin is refused by name.
+  const selectionRefused = pluginSelectionRefusal(plugins, pm);
+  if (selectionRefused) throw selectionRefused;
   const promptMode = String(process.env.OPENAI_PROMPT_MODE || 'basic').toLowerCase().trim();
 
   // --- CTEM: continuous watch mode ---
   if (watch) {
     const intervalMs = intervalMinutes * 60 * 1000;
     let previousCycleResults = null;
+    // EE 2.0.0: every scan in this loop tells Enterprise it is a watch cycle, so no drift file is written per cycle (the
+    // drift file is the one-shot path's; the operator's ruling). `opts.runId` is already unset here.
+    opts.watch = true;
 
-    const scheduler = createScheduler({
+    // `testHooks._createScheduler`: a test seam, absent in every real invocation — it lets a leg run one watch cycle.
+    const scheduler = (testHooks?._createScheduler ?? createScheduler)({
       intervalMs,
       hosts,
       parallel,
@@ -3262,8 +3506,9 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
         console.log(text ?? '[CTEM] First cycle complete — it establishes the baseline. Delta reporting begins on the next cycle.');
         if (webhookUrl) {
           for (const { host: h, findings } of alerts) {
-            const payload = buildAlertPayload(h, findings, alertSeverity);
-            const webhookResult = await sendWebhook(webhookUrl, payload, { retries: 2, retryDelayMs: 1000 });
+            const payload = buildAlertPayload(h, findings, alertSeverity, { payload: alertPayload });
+            // `testHooks._sendWebhook`: a test seam, absent in every real invocation.
+            const webhookResult = await (testHooks?._sendWebhook ?? sendWebhook)(webhookUrl, payload, { retries: 2, retryDelayMs: 1000 });
             if (webhookResult.success) {
               console.log(`[CTEM] Webhook alert sent for ${h}`);
             } else {
@@ -3290,7 +3535,8 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     const dropped = scheduler.duplicatesDropped
       ? ` (${scheduler.duplicatesDropped} duplicate host(s) dropped — watch mode scans each host once per cycle)` : '';
     console.log(`[CTEM] Watch mode enabled. Interval: ${intervalMinutes}m, Concurrency: ${parallel}, Hosts: ${scheduler.hosts.length}${dropped}`);
-    if (webhookUrl) console.log(`[CTEM] Webhook URL: ${webhookUrl}, Alert severity: ${alertSeverity}, alerting `
+    // The HOST only: a Slack or Teams webhook URL carries its own credential in the path or the query (EE 2.0.0).
+    if (webhookUrl) console.log(`[CTEM] Webhook: ${new URL(webhookUrl).host}, Alert severity: ${alertSeverity}, alerting `
       + (alertEveryCycle ? 'every host with such a finding, every cycle' : 'hosts whose scan changed (the first cycle sets the baseline)'));
 
     scheduler.start();
@@ -3537,6 +3783,48 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
   }
 }
 
+/**
+ * An explicit --plugins list, resolved against the loaded plugins before anything is scanned or written: a token that names
+ * no plugin is refused BY NAME, and so is a list that names none. Until 1.0.0 both were dropped without a word, and a list
+ * that resolved to nothing ran ZERO plugins — exit 0, "Security findings: 0", and with --compliance every in-scope control
+ * PASS at zero evidence. `all` must stand alone: inside a list it was dropped too, silently running only the rest.
+ * Returns an EFLAGVALUE error (exit 2 through exitOnMainRejection), or null when the selection stands.
+ * @param {string[]|string|undefined} plugins  parseArgs' `plugins`: 'all', or the list's trimmed tokens
+ * @param {{ findPlugin(name: string): object|null }} pm
+ */
+export function pluginSelectionRefusal(plugins, pm) {
+  if (!Array.isArray(plugins)) return null;
+  const refuse = (msg) => Object.assign(new Error(msg), { code: 'EFLAGVALUE' });
+  if (plugins.length === 0) return refuse('--plugins named no plugin — give plugin ids or names, or all');
+  const quote = (t) => JSON.stringify(t);
+  const withAll = plugins.some((t) => t.toLowerCase() === 'all');
+  const unknown = plugins.filter((t) => t.toLowerCase() !== 'all' && !pm.findPlugin(t));
+  if (unknown.length) {
+    return refuse(`--plugins: no plugin matches ${unknown.map(quote).join(', ')}${withAll ? '; "all" must be given alone' : ''}`
+      + ' — name each plugin by its id or name (nsauditor-ai license --plugins lists them)');
+  }
+  if (withAll) return refuse('--plugins: "all" must be given alone — it already selects every plugin');
+  return null;
+}
+
+/**
+ * What a rejected main() exits with — the ONE copy of this mapping. Both entry points call it: the block below when
+ * cli.mjs is run directly, and bin/nsauditor-ai.mjs, the command npm installs (which imports main(), so cli.mjs is never
+ * the entry point for an installed user). A flag refusal is an operator error, not a crash: name it and exit 2, this
+ * CLI's "could not do what you asked" code. Everything else keeps the stack and exit 1. `error` and `exit` are seams for
+ * the suite (tests/cli_bin_entrypoint.test.mjs).
+ */
+export function exitOnMainRejection(err, { error = console.error, exit = process.exit } = {}) {
+  // A refused scan target (ETARGETREFUSED) is the same class: the operator asked for something the guard does not allow —
+  // and so is one that does not resolve (ETARGETUNRESOLVED): nothing can be scanned at a name with no address.
+  if (err?.code === 'EFLAGSHAPE' || err?.code === 'EFLAGVALUE' || err?.code === 'ETARGETREFUSED' || err?.code === 'ETARGETUNRESOLVED') {
+    error(`[ERROR] ${err.message}`);
+    return exit(2);
+  }
+  error(err?.stack || err);
+  return exit(1);
+}
+
 // Only auto-run main() when this file is the process entrypoint. Importing
 // cli.mjs (e.g. unit tests pulling in `parseArgs`) must NOT trigger a scan.
 const _isEntrypoint = (() => {
@@ -3547,14 +3835,5 @@ const _isEntrypoint = (() => {
   }
 })();
 if (_isEntrypoint) {
-  main().catch((err) => {
-    // A flag-shape refusal is an operator error, not a crash: name it and exit 2, this CLI's
-    // "could not do what you asked" code. Everything else keeps the stack and exit 1.
-    if (err?.code === 'EFLAGSHAPE') {
-      console.error(`[ERROR] ${err.message}`);
-      process.exit(2);
-    }
-    console.error(err?.stack || err);
-    process.exit(1);
-  });
+  main().catch((err) => exitOnMainRejection(err));
 }