nsauditor-ai 0.2.22 → 0.2.23

package/README.md

@@ -17,7 +17,7 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
-**Latest: CE 0.2.22 + Enterprise 0.31.8** (July 2026) — paired bump for the Enterprise "GAP-1 positive-substrate polish — framework-aware PCI Req 10.5.1 caveat restoration + SOC 2 GRC-push hygiene" cycle. No new framework, no new plugins (still 28), all seven coverage matrices unchanged; no CE engine change. Requires CE 0.2.8+. Full detail in **[CHANGELOG.md](./CHANGELOG.md)**.
+**Latest: CE 0.2.23 + Enterprise 0.31.9** (July 2026) — **operator bug-fix cycle (real CE engine/CLI/MCP change).** Fixes three operator-reported bugs from a live test: **(BUG2b) cloud-scan scope integrity** — cloud auditor plugins ran during a `--host 192.168.1.1` **network** scan; a cloud auditor now runs **only** on its own cloud sentinel (`aws`/`gcp`/`azure`), never on a network host, never via credentials-in-env, and never via an explicit `--plugins`/MCP `probe_service` selection (`--host` is the sole cloud-intent signal); **(BUG1) AI-conclusion robustness** — the AI conclusion no longer aborts on cloud-scale payloads (payload-scaled timeout, 120s→600s, `NSA_AI_TIMEOUT_MS`-overridable) and writes a **visible** `scan_response_ai.txt` stub on failure instead of failing quiet; **(BUG2a)** the AI bail message names the unresolved API key instead of misreporting "AI_ENABLED=false". Externally reviewed across multiple rounds → 🟢 PASS. Paired **Enterprise 0.31.9** (GAP-1 #3 RoC positive-substrate render-site parity). No new framework, no new plugins (still 28), all seven coverage matrices unchanged. Requires CE 0.2.8+. Full detail in **[CHANGELOG.md](./CHANGELOG.md)**.
 
 → See a sample EE scan output: **[walk-through with synthetic Acme Corp AWS account](https://www.nsauditor.com/ai/docs/sample-scan/)** (no signup required)
 
@@ -66,6 +66,16 @@ If you're heading into a **SOC 2, HIPAA, NIST CSF 2.0, PCI DSS, ISO 27001, CIS C
 → **[See sample EE scan output](https://www.nsauditor.com/ai/docs/sample-scan/)** — full evidence pack against synthetic Acme Corp AWS account (no signup required)
 → **[Buy NSAuditor AI Enterprise Edition](https://www.nsauditor.com/ai/pricing/)** — $2k / $5k / $10k+ per year for 5 / 25 / unlimited seats + custom SLA. Onboarding call included.
 
+### Prefer to buy through AWS Marketplace?
+
+Enterprise Edition is also available as an **[AWS Marketplace container listing](https://aws.amazon.com/marketplace/pp?sku=etar8knc8dx7bshizrrnnjbzi)** — same product, same local ES256 license key, billed through your AWS account (consolidated billing / EDP drawdown, procurement-friendly; custom Enterprise terms via AWS Private Offers). *Launching now in limited availability — if the listing shows "not available," it hasn't gone fully public yet: [contact us](https://www.nsauditor.com/support.html) for immediate access via a Private Offer.*
+
+How Marketplace fulfillment works (ZDE and air-gap preserved — no runtime AWS dependency at scan time):
+
+1. **Subscribe** on the listing (tiers `base` / `growth` / `scale` mirror the 5 / 25 / unlimited-seat plans).
+2. **Register** your email + AWS account ID at the URL shown in the listing's usage instructions — your **ES256 license key arrives by email**.
+3. **Pull and run** the Docker image from the Marketplace registry (commands in the listing's usage instructions and your license email) with `NSAUDITOR_LICENSE_KEY=<your key>`. One tier-agnostic image — upgrades are just a new license key, never a new image. The container runs fully offline after that; billing lives in AWS, enforcement is your local key.
+
 ### Feature comparison
 
 | | Community (Free) | Pro ($49/mo) | Enterprise ($2k+/yr) |

package/cli.mjs

@@ -18,6 +18,7 @@ import { buildSarifLog } from './utils/sarif.mjs';
 import { buildCsv } from './utils/export_csv.mjs';
 import { buildMarkdownReport } from './utils/report_md.mjs';
 import { recordScan, getLastScan, computeDiff, formatDiffReport, pruneForCE, HISTORY_FILE } from './utils/scan_history.mjs';
+import { aiBailMessage, computeAiTimeoutMs, aiFailureStubText, aiSummaryLine } from './utils/ai_stage.mjs';
 import { getTierFromEnv, loadLicense } from './utils/license.mjs';
 import { resolveCapabilities, hasCapability, inferRequiredTier } from './utils/capabilities.mjs';
 import { createScheduler } from './utils/scheduler.mjs';
@@ -185,7 +186,8 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
     console.warn('[OpenAI] No conclusion.summary available; skipping.');
     return {
       file_paths: { folder: outDir, plain: null, ai_json: null, raw_json: null, html: null, admin_html: null },
-      ai_conclusion: null
+      ai_conclusion: null,
+      ai_status: 'no_summary',
     };
   }
 
@@ -306,10 +308,13 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
   // --- Bail out early if sending disabled -----------------------------------
   const providerLabel = aiProvider === 'claude' ? 'Claude' : aiProvider === 'ollama' ? 'Ollama' : 'OpenAI';
   if (!sendEnabled || !key) {
-    console.log(`[${providerLabel}] AI_ENABLED=false; not sending. Model=${model}`);
+    // BUG2(a): distinguish "AI disabled" from "AI enabled but key unresolved" —
+    // the old single message misdiagnosed a keychain/env key miss as AI_ENABLED=false.
+    console.log(aiBailMessage({ sendEnabled, key, aiProvider, model }));
     return {
       file_paths: { folder: outDir, plain: null, ai_json: null, raw_json: adminRawPath, html: null, admin_html: adminHtmlPath },
-      ai_conclusion: null
+      ai_conclusion: null,
+      ai_status: sendEnabled ? 'key_unresolved' : 'skipped',
     };
   }
 
@@ -335,14 +340,32 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
 
   // --- Send to AI provider ---------------------------------------------------
   let aiConclusionText = null;
+  // review fold 8: contain the serialization — hoisting userContent above the
+  // try (so the catch can name the timeout) must not let a JSON.stringify throw
+  // (e.g. a circular payload) escape maybeSendToOpenAI uncaught. (payloadForAI is
+  // already serialized once at the aiPayloadPath write above, so this is
+  // defensive; the fallback keeps the timeout math + stub path alive.)
+  let userContent;
+  try {
+    userContent = `Scan payload:\n${JSON.stringify(payloadForAI, null, 2)}`;
+  } catch (e) {
+    console.warn(`[${providerLabel}] Failed to serialize AI payload:`, e?.message || e);
+    userContent = `Scan payload:\n${String(payloadForAI?.summary ?? '(unserializable payload)')}`;
+  }
+  // AbortController timeout — prevents the pipeline hanging on a stalled AI provider.
+  // BUG1: scale with payload size (cloud-scale 28-40KB payloads exceeded the old
+  // flat 120s default and aborted); an explicit NSA_AI_TIMEOUT_MS still wins.
+  // Hoisted above the try so the catch's fail-visible stub can name the timeout.
+  const AI_TIMEOUT_MS = computeAiTimeoutMs({
+    payloadBytes: Buffer.byteLength(userContent, 'utf8'), // optional fold: UTF-8 bytes, not UTF-16 units
+    host,
+    envOverride: process.env.NSA_AI_TIMEOUT_MS,
+  });
   try {
     console.log(`[${providerLabel}] Sending summary, model:`, model);
 
     let resp;
-    const userContent = `Scan payload:\n${JSON.stringify(payloadForAI, null, 2)}`;
 
-    // AbortController timeout — prevents the pipeline hanging on a stalled AI provider.
-    const AI_TIMEOUT_MS = Number(process.env.NSA_AI_TIMEOUT_MS) || 120_000; // 2 min default
     const ac = new AbortController();
     const aiTimer = setTimeout(() => ac.abort(), AI_TIMEOUT_MS);
 
@@ -350,7 +373,9 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
       if (aiProvider === 'claude') {
         // --- Claude (Anthropic) ---
         const { default: Anthropic } = await import('@anthropic-ai/sdk');
-        const client = new Anthropic({ apiKey: key });
+        // R-3: maxRetries:0 so the outer AbortController/timeout can't race the
+        // SDK's own internal retry loop (which would multiply the wall-clock).
+        const client = new Anthropic({ apiKey: key, maxRetries: 0 });
 
         resp = await client.messages.create({
           model,
@@ -359,7 +384,7 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
           messages: [
             { role: 'user', content: userContent }
           ]
-        }, { signal: ac.signal });
+        }, { signal: ac.signal, timeout: AI_TIMEOUT_MS });
 
         console.log(`[${providerLabel}] Response id:`, resp?.id ?? '(unknown)');
 
@@ -373,7 +398,7 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
         // --- Ollama (OpenAI-compatible API) ---
         const { default: OpenAI } = await import('openai');
         const ollamaBase = process.env.OLLAMA_BASE_URL || 'http://localhost:11434/v1';
-        const client = new OpenAI({ baseURL: ollamaBase, apiKey: key });
+        const client = new OpenAI({ baseURL: ollamaBase, apiKey: key, maxRetries: 0 }); // R-3
 
         resp = await client.chat.completions.create({
           model,
@@ -381,7 +406,7 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
             { role: 'system', content: promptText },
             { role: 'user', content: userContent }
           ]
-        }, { signal: ac.signal });
+        }, { signal: ac.signal, timeout: AI_TIMEOUT_MS });
 
         console.log(`[${providerLabel}] Response id:`, resp?.id ?? '(unknown)');
 
@@ -389,7 +414,7 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
       } else {
         // --- OpenAI ---
         const { default: OpenAI } = await import('openai');
-        const client = new OpenAI({ apiKey: key });
+        const client = new OpenAI({ apiKey: key, maxRetries: 0 }); // R-3
 
         if (client.responses?.create) {
           resp = await client.responses.create({
@@ -398,7 +423,7 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
               { role: 'system', content: promptText },
               { role: 'user', content: userContent }
             ]
-          }, { signal: ac.signal });
+          }, { signal: ac.signal, timeout: AI_TIMEOUT_MS });
         } else if (client.chat?.completions?.create) {
           resp = await client.chat.completions.create({
             model,
@@ -406,7 +431,7 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
               { role: 'system', content: promptText },
               { role: 'user', content: userContent }
             ]
-          }, { signal: ac.signal });
+          }, { signal: ac.signal, timeout: AI_TIMEOUT_MS });
         } else {
           throw new Error('OpenAI SDK: neither responses.create nor chat.completions.create is available.');
         }
@@ -491,13 +516,17 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
         html: aiHtmlPath,
         admin_html: adminHtmlPath
       },
-      ai_conclusion: aiConclusionText
+      ai_conclusion: aiConclusionText,
+      // review fold D: a 200 with no extractable text is NOT "ok" — the
+      // end-of-scan summary must not read "OK" when there is no conclusion.
+      ai_status: (typeof aiConclusionText === 'string' && aiConclusionText.trim()) ? 'ok' : 'empty',
     };
   } catch (err) {
-    console.error(`[${providerLabel}] Send failed:`, err?.stack || err?.message || String(err));
+    const errMsg = String(err?.message || err);
+    console.error(`[${providerLabel}] Send failed:`, err?.stack || errMsg);
     try {
       await fsp.writeFile(aiErrPath, JSON.stringify({
-        error: String(err?.message || err),
+        error: errMsg,
         stack: err?.stack || null,
         provider: aiProvider,
         model
@@ -507,16 +536,38 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
       console.warn(`[${providerLabel}] Also failed to write error file:`, e?.message || e);
     }
 
+    // BUG1 (fail-VISIBLE): also write a human-readable scan_response_ai.txt stub
+    // so the operator sees WHY there is no AI conclusion (the JSON error file +
+    // the console.error above both scroll away in a 3-cloud run). Names the error
+    // and, on a timeout/abort, the NSA_AI_TIMEOUT_MS remedy.
+    let aiFailureStubPath = null;
+    try {
+      await fsp.writeFile(aiTxtPath, aiFailureStubText({
+        host, model, providerLabel, errorMessage: errMsg,
+        timeoutMs: AI_TIMEOUT_MS, whenIso: new Date().toISOString(),
+      }), 'utf8');
+      aiFailureStubPath = aiTxtPath;
+      console.log(`[${providerLabel}] Wrote AI failure stub:`, aiTxtPath);
+    } catch (e) {
+      console.warn(`[${providerLabel}] Also failed to write AI failure stub:`, e?.message || e);
+    }
+
     return {
       file_paths: {
         folder: outDir,
+        // review fold 16: keep `plain` NULL on failure — a downstream consumer
+        // uses `plain != null` as an AI-success proxy. The visible stub is
+        // surfaced on its own `ai_failure_stub` key + via ai_status/ai_error.
         plain: null,
         ai_json: null,
+        ai_failure_stub: aiFailureStubPath,
         raw_json: adminRawPath,
         html: null,
         admin_html: adminHtmlPath
       },
-      ai_conclusion: null
+      ai_conclusion: null,
+      ai_status: 'failed',
+      ai_error: errMsg,
     };
   }
 }
@@ -705,14 +756,17 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
     }
   } catch { /* EE not installed — CE proceeds unchanged */ }
 
-  const { file_paths: ai_file_paths, ai_conclusion } = await maybeSendToOpenAI({ host, results, conclusion, promptMode, outDir });
+  const { file_paths: ai_file_paths, ai_conclusion, ai_status, ai_error } = await maybeSendToOpenAI({ host, results, conclusion, promptMode, outDir });
+  // BUG1 (fail-VISIBLE): a one-line end-of-scan AI status so a failed/aborted AI
+  // conclusion is not silently swallowed under the per-stage logs.
+  console.log(aiSummaryLine({ host, ai_status, ai_error }));
 
   // --- Scan history: record & compare ---
   let scanDiff = null;
   try {
     const outRoot = toCleanPath(process.env.SCAN_OUT_PATH || process.env.OPENAI_OUT_PATH || 'out').replace(/\.[^/.]+$/, '') || 'out';
     const services = conclusion?.result?.services ?? [];
-    const findingsCount = services.reduce((n, svc) => {
+    const serviceFindingsCount = services.reduce((n, svc) => {
       if (svc.anonymousLogin === true) n++;
       if (svc.axfrAllowed === true) n++;
       if (Array.isArray(svc.weakAlgorithms)) n += svc.weakAlgorithms.length;
@@ -721,6 +775,15 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
       if (Array.isArray(cves)) n += cves.length;
       return n;
     }, 0);
+    // review fold R-1: cloud plugins emit findings on `results[].result.findings`,
+    // NOT as service-level attrs — so a cloud (--host aws) scan recorded
+    // findingsCount:0 in scan_history over a 201-finding scan (a false-clean
+    // history channel). Roll cloud findings into findingsCount + surface the split.
+    const cloudFindingsCount = (results || []).reduce((n, r) => {
+      const f = r?.result?.findings;
+      return n + (Array.isArray(f) ? f.length : 0);
+    }, 0);
+    const findingsCount = serviceFindingsCount + cloudFindingsCount;
 
     const scanSummary = {
       timestamp: new Date().toISOString(),
@@ -729,6 +792,7 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
       openPorts: services.filter((s) => s.status === 'open').map((s) => s.port),
       os: conclusion?.result?.host?.os ?? null,
       findingsCount,
+      cloudFindingsCount,
       services: services.map((s) => ({
         port: s.port, protocol: s.protocol ?? 'tcp',
         service: s.service ?? null, version: s.version ?? null,
@@ -755,7 +819,7 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
     console.warn('[ScanHistory] Failed to record/compare scan:', err?.message || err);
   }
 
-  return { host, results, conclusion, ai_file_paths, ai_conclusion, scanDiff };
+  return { host, results, conclusion, ai_file_paths, ai_conclusion, ai_status, ai_error, scanDiff };
 }
 
 /* -------------------- CI/CD severity threshold helpers ------------------- */
@@ -930,6 +994,13 @@ Cloud-scan hosts:
                                  single cloud and is therefore skipped under this
                                  auto-scope; to run it, select it explicitly
                                  (--plugins 023,...) or scan a network host/CIDR.
+                                 INVERSE (cloud scope integrity): a cloud auditor runs
+                                 ONLY on its own sentinel host. On a NETWORK host (IP /
+                                 CIDR / hostname) the cloud-scanner plugins NEVER run —
+                                 not via --plugins all, not via an explicit --plugins
+                                 1020, and not because cloud credentials are present in
+                                 the environment. '--host' is the sole cloud-scan
+                                 trigger; credentials are a capability, not intent.
 
 Examples:
   nsauditor-ai scan --host 10.0.0.1 --plugins all

package/mcp_server.mjs

@@ -23,6 +23,7 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { buildRegionIntent } from './utils/region_intent.mjs';
+import { excludeMismatchedCloudPlugins, isCloudSentinelHost } from './utils/sentinel_scope.mjs';
 import { getTierFromEnv, loadLicense } from './utils/license.mjs';
 import { resolveCapabilities } from './utils/capabilities.mjs';
 import { buildMarkdownReport } from './utils/report_md.mjs';
@@ -343,6 +344,13 @@ export async function validateHost(host) {
     throw new Error('Scanning loopback, link-local, or metadata addresses is not allowed via MCP');
   }
 
+  // Cloud-sentinel hosts (aws/gcp/azure) are scoping tokens, NOT DNS names — they
+  // route to the cloud-scanner plugins (probe_service enforces the cloud-intent
+  // gate downstream; the CLI whitelists them the same way in scanSingleHost).
+  // Skip the SSRF DNS resolution for them so the sentinel path is reachable
+  // (otherwise dns.lookup('aws') ENOTFOUND is misread as a blocked address).
+  if (isCloudSentinelHost(h)) return h;
+
   // DNS resolution check — catches rebinding, decimal/octal IPs, IPv6-mapped addrs.
   // NSA_ALLOW_ALL_HOSTS=1 bypasses RFC 1918 checks for local network auditing.
   if (!process.env.NSA_ALLOW_ALL_HOSTS) {
@@ -564,7 +572,36 @@ export async function handleProbeService(args) {
     throw new Error(`Unknown plugin: ${args.pluginName}`);
   }
 
-  const result = await pm._runOne(plugin, host, args.port);
+  // M-1 (BUG2b): probe_service is the LIVE MCP single-plugin route (dispatches
+  // via _runOne). It must honor the same cloud-intent contract as run()/runByName
+  // — a cloud auditor runs IFF the host is ITS sentinel; a network host (or the
+  // wrong cloud) must NEVER trigger it, even with cloud creds in the env.
+  const gate = excludeMismatchedCloudPlugins([plugin], host);
+  if (gate.skipped.length) {
+    const need = plugin.cloudProvider;
+    throw new Error(
+      `Plugin ${plugin.id} (${plugin.name}) is a ${need} cloud auditor — it does not run against ` +
+      `${gate.sentinel ? `the '${gate.sentinel}' cloud` : `network host '${host}'`}. ` +
+      `For a cloud audit use the scan_cloud tool (providers: ["${need}"]), or call probe_service ` +
+      `with host: "${need}". Cloud auditors run only on their own cloud; credentials in the ` +
+      `environment are a capability, not an intent signal.`,
+    );
+  }
+  // M1-SSRF (fold): validateHost whitelists the cloud-sentinel literals past the
+  // SSRF DNS check. That is safe ONLY because a sentinel host must reach a CLOUD
+  // plugin (which ignores `host`). A NETWORK plugin (no cloudProvider) routed a
+  // sentinel host would socket.connect(port, 'aws') without SSRF re-validation —
+  // a bypass if the literal resolves internally. Reject it, restoring the
+  // invariant that scopeSelectionForHost enforces on the pm.run() path.
+  if (isCloudSentinelHost(host) && !plugin.cloudProvider) {
+    const s = String(host).trim().toLowerCase();
+    throw new Error(
+      `Plugin ${plugin.id} (${plugin.name}) is a network plugin — it does not run against the ` +
+      `'${s}' cloud sentinel. Use a network host/IP/CIDR, or a cloud auditor with host: "${s}".`,
+    );
+  }
+  const hostKind = isCloudSentinelHost(host) ? `cloud:${String(host).trim().toLowerCase()}` : 'network';
+  const result = await pm._runOne(plugin, host, args.port, { hostKind });
   return result;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,

package/plugin_manager.mjs

@@ -20,7 +20,7 @@ import { pathToFileURL, fileURLToPath } from "url";
 import { discoverPlugins } from './utils/plugin_discovery.mjs';
 import { getTierFromEnv } from './utils/license.mjs';
 import { resolveCapabilities } from './utils/capabilities.mjs';
-import { scopeSelectionForHost, scopeSelectionForProviders } from './utils/sentinel_scope.mjs';
+import { scopeSelectionForHost, scopeSelectionForProviders, excludeMismatchedCloudPlugins, isCloudSentinelHost } from './utils/sentinel_scope.mjs';
 import { mapLimit } from './utils/concurrency.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -588,7 +588,25 @@ export class PluginManager {
       return await this.runConcluder(resultsArg);
     }
 
-    const arr = await this._runAcrossPorts(plugin, host, opts);
+    // BUG2(b): runByName (a public PluginManager entry) honors the same
+    // cloud-intent contract as run() — a cloud auditor runs ONLY on its own
+    // sentinel host — and threads opts.hostKind. Defense-in-depth for direct
+    // library consumers; the LIVE MCP single-plugin route (probe_service →
+    // _runOne) is guarded at its own call site in mcp_server.handleProbeService.
+    const rb = excludeMismatchedCloudPlugins([plugin], host);
+    if (rb.skipped.length) {
+      const need = plugin.cloudProvider;
+      console.error(
+        `Plugin ${plugin.id} (${plugin.name}) is a ${need} cloud auditor — it runs only on --host ${need} ` +
+        `(host '${host}' is ${rb.sentinel ? `the '${rb.sentinel}' cloud` : 'a network target'}). Skipping.`,
+      );
+      return { id: plugin.id, name: plugin.name, result: { up: false, skipped: true, data: [] } };
+    }
+    const rbOpts = {
+      ...opts,
+      hostKind: isCloudSentinelHost(host) ? `cloud:${String(host).trim().toLowerCase()}` : 'network',
+    };
+    const arr = await this._runAcrossPorts(plugin, host, rbOpts);
     const filtered = arr.filter(Boolean);
     if (filtered.length === 0) return { id: plugin.id, name: plugin.name, result: { up: false, data: [] } };
     if (filtered.length === 1) return filtered[0];
@@ -769,6 +787,17 @@ export class PluginManager {
       opts = maybeOpts || {};
     }
 
+    // BUG2(b): tag the host kind so plugins + the EE cloud gate can honor the
+    // "--host is the sole cloud-intent signal" contract as defense-in-depth
+    // (alongside the network-host exclusion below). Cloned so the caller's opts
+    // object — shared across concurrent hosts in the CLI multi-host path — is
+    // never mutated; hostKind stays a scalar string so the shallow opts spread
+    // in callPlugin (:152) / _runOne (:517) forwards it verbatim to every plugin.
+    opts = {
+      ...opts,
+      hostKind: isCloudSentinelHost(host) ? `cloud:${String(host).trim().toLowerCase()}` : 'network',
+    };
+
     // Sentinel-host scoping: on --host aws|gcp|azure with the implicit `all`,
     // run only that cloud's plugins; skip other clouds + non-cloud plugins.
     const scope = scopeSelectionForHost(selection, host, rawSpec);
@@ -790,16 +819,70 @@ export class PluginManager {
       }
     }
 
+    // BUG2(b): a cloud auditor (any plugin with a `cloudProvider` tag) runs IFF
+    // the host is ITS sentinel — the symmetric inverse of the sentinel scoping
+    // above. Fires for the implicit `all` AND an explicit `--plugins 1020`
+    // selection: a network scan must NEVER audit a cloud estate (even with cloud
+    // creds in the env), and a `--host gcp` scan must not run an explicitly-listed
+    // AWS auditor. '--host' is the sole cloud-intent signal — no escape hatch.
+    const netScope = excludeMismatchedCloudPlugins(selection, host);
+    // review fold R-5: excluded cloud plugins are removed from `selection` before
+    // dispatch, so without a manifest entry they leave no machine-readable trace
+    // in pm.run()'s result. (The requirements/capability skip classes DO push a
+    // manifest entry; the sentinel-scope skip at :812 does not — a separate
+    // pre-existing gap, not addressed here.) A `skipped` entry surfaces the
+    // exclusion to MCP scan_host responses + pm.run() library consumers (the CLI
+    // does not currently render the manifest). One entry per excluded plugin.
+    const cloudSkipManifest = netScope.skipped.map((p) => ({
+      id: String(p?.id || ''),
+      name: p?.name || 'Plugin',
+      status: 'skipped',
+      reason: `${p?.cloudProvider || 'cloud'} cloud auditor requires --host ${p?.cloudProvider || 'aws|gcp|azure'} ` +
+        `(host '${host}' is ${netScope.sentinel ? `the '${netScope.sentinel}' cloud` : 'a network target'})`,
+      duration_ms: 0,
+    }));
+    if (netScope.excludedCloud && netScope.skipped.length) {
+      selection = netScope.selected;
+      const ids = netScope.skipped.map((p) => p?.id ?? '?').join(', ');
+      if (netScope.sentinel) {
+        // foreign-cloud plugin explicitly selected on a mismatched sentinel host
+        const foreign = [...new Set(netScope.skipped.map((p) => p?.cloudProvider).filter(Boolean))].join('/');
+        console.error(
+          `Host '${host}' is the '${netScope.sentinel}' cloud → skipping ${netScope.skipped.length} ` +
+          `non-${netScope.sentinel} cloud auditor(s) [${ids}] (${foreign} auditors require --host ${foreign}). ` +
+          `A cloud auditor runs only on its own sentinel host — '--host' is the sole cloud-scan trigger.`,
+        );
+      } else {
+        console.error(
+          `Host '${host}' is a network target → skipping ${netScope.skipped.length} cloud auditor(s) ` +
+          `[${ids}]: cloud plugins require a cloud sentinel host (--host aws|gcp|azure). ` +
+          `Credentials in the environment are a capability, not an intent signal — '--host' is the ` +
+          `sole cloud-scan trigger. (To audit a cloud, run e.g. \`--host aws\`.)`,
+        );
+      }
+      // review fold 4: if the exclusion emptied the selection, say so loudly — an
+      // empty result is NOT a clean pass (mirrors the sentinel zero-match warning).
+      if (selection.length === 0) {
+        console.error(
+          `WARNING: after excluding cloud auditors for host '${host}', ZERO plugins remain — ` +
+          `NOTHING was audited (an empty result is NOT a clean pass). To audit a cloud, use --host aws|gcp|azure.`,
+        );
+      }
+    }
+
     // Decide execution mode
     const anyOrchestratedSignals = selection.some((p) => p?.priority != null || p?.requirements != null);
     const orchestrate = opts.orchestrate !== false && anyOrchestratedSignals;
 
     let results = [];
     let manifest = [];
+    // R-5: surface excluded cloud auditors as skipped manifest entries (before
+    // the dispatched plugins), so the exclusion is machine-visible, not stderr-only.
+    if (cloudSkipManifest.length) manifest.push(...cloudSkipManifest);
     if (orchestrate) {
       const orch = await this._runOrchestrated(host, selection, opts);
       results = orch.results;
-      manifest = orch.manifest;
+      manifest = manifest.concat(orch.manifest);
     } else {
       // Legacy path: simple run across ports for each plugin (except concluder)
       const toRun = selection.filter((p) => !isConcluder(p));
@@ -884,7 +967,11 @@ export class PluginManager {
           return { manifest: { id: String(mod.id || ''), name: mod.name || 'Plugin', status: 'skipped', reason: `missing capabilities: ${(mod.requiredCapabilities || []).join(',')}`, duration_ms: 0 }, outputs: [] };
         }
         const startMs = Date.now();
-        const wrappedRuns = await callPlugin(mod, host, ctx, [], { ...opts, timeoutMs });
+        // BUG2(b) fold B: thread hostKind on the MCP/cloud-parallel path too, so
+        // the defense-in-depth signal is present on EVERY cloud dispatch route
+        // (selection here is already scoped to each plugin's cloudProvider).
+        const cloudHostKind = mod.cloudProvider ? `cloud:${mod.cloudProvider}` : opts.hostKind;
+        const wrappedRuns = await callPlugin(mod, host, ctx, [], { ...opts, timeoutMs, hostKind: cloudHostKind });
         const duration_ms = Date.now() - startMs;
         let status = 'ran';
         let reason = null;

package/utils/ai_stage.mjs

@@ -0,0 +1,129 @@
+// utils/ai_stage.mjs
+//
+// Pure, testable helpers for the CLI AI-conclusion stage (cli.mjs
+// maybeSendToOpenAI). Extracted so the BUG1 (payload-scaled timeout +
+// fail-visible failure) and BUG2(a) (disabled-vs-key bail message) logic can be
+// unit-tested without importing the CLI entrypoint. No I/O, no side effects.
+
+/** Display label for an AI provider id. */
+export function aiProviderLabel(aiProvider) {
+  return aiProvider === 'claude' ? 'Claude' : aiProvider === 'ollama' ? 'Ollama' : 'OpenAI';
+}
+
+/** The env var an operator sets for a provider's key (null for keyless ollama). */
+export function aiKeyEnvVar(aiProvider) {
+  if (aiProvider === 'claude') return 'ANTHROPIC_API_KEY';
+  if (aiProvider === 'ollama') return null;
+  return 'OPENAI_API_KEY';
+}
+
+/**
+ * BUG2(a): the AI-stage bail message. The old code printed a single
+ * "AI_ENABLED=false; not sending" for BOTH `!sendEnabled` and `!key`, so an
+ * operator who set AI_ENABLED=true but whose key failed to resolve (unset env or
+ * a missing `keychain:<label>` entry) was told AI was disabled — a misdiagnosis.
+ * This distinguishes the two, and on a key miss names the provider-specific env
+ * var + the keychain-reference possibility.
+ *
+ * @returns {string} the log line to print at the bail site.
+ */
+export function aiBailMessage({ sendEnabled, key, aiProvider, model }) {
+  const label = aiProviderLabel(aiProvider);
+  if (!sendEnabled) {
+    return `[${label}] AI_ENABLED is not set to true — skipping AI conclusion. Model=${model}`;
+  }
+  // sendEnabled === true but the key did not resolve.
+  const envVar = aiKeyEnvVar(aiProvider);
+  const ref = envVar
+    ? `\`${envVar}\` is unset/empty, or its \`keychain:<label>\` reference did not resolve`
+    : 'the provider key did not resolve';
+  return `[${label}] AI_ENABLED=true but the API key could not be resolved — ${ref}. Skipping AI conclusion. Model=${model}`;
+}
+
+/**
+ * BUG1: scale the AI-call timeout with the payload size. The fixed 120s
+ * AbortController aborted cloud-scale scans (AWS 28KB / Azure 40KB payloads with
+ * 200+ findings) whose 16k-token conclusions take longer than 2 min to generate,
+ * while a small 4-5KB network-host payload finished well inside 120s. An explicit
+ * NSA_AI_TIMEOUT_MS (envOverride) always wins. Otherwise: floor 120s (preserves
+ * network-host behavior), +15s per KB of payload, ceiling 600s (10 min).
+ *
+ * @param {{payloadBytes?: number, host?: string, envOverride?: string|number}} o
+ * @returns {number} timeout in ms.
+ */
+export function computeAiTimeoutMs({ payloadBytes = 0, host = '', envOverride } = {}) {
+  const explicit = Number(envOverride);
+  // optional fold: an explicit override wins, truncated to an integer ms (a
+  // fractional value would otherwise be passed verbatim to setTimeout/the SDK).
+  if (Number.isFinite(explicit) && explicit > 0) return Math.trunc(explicit);
+  const FLOOR_MS = 120_000; // 2 min — unchanged for small network-host payloads
+  const CEIL_MS = 600_000;  // 10 min hard cap
+  const MS_PER_KB = 15_000;
+  const kb = Math.max(0, Number(payloadBytes) || 0) / 1024;
+  const scaled = FLOOR_MS + Math.round(kb * MS_PER_KB);
+  return Math.min(CEIL_MS, Math.max(FLOOR_MS, scaled));
+}
+
+/**
+ * BUG1 (fail-VISIBLE): on an AI failure the pipeline used to write only a JSON
+ * error file + a console.error that scrolls away in a 3-cloud run, so the
+ * operator just saw "no AI conclusion". This produces a human-readable
+ * scan_response_ai.txt body that names the error and — when it looks like a
+ * timeout/abort — the NSA_AI_TIMEOUT_MS remedy.
+ *
+ * @returns {string} the scan_response_ai.txt body for the failure case.
+ */
+export function aiFailureStubText({ host, model, providerLabel, errorMessage, timeoutMs, whenIso }) {
+  // review fold 9 + R-3: match the local AbortController abort ("Request was
+  // aborted.") AND the SDK request-timeout ("Request timed out." — the
+  // APIConnectionTimeoutError the SDK `timeout` option raises, racing the
+  // AbortController per fold-10) — both cases NSA_AI_TIMEOUT_MS addresses. We do
+  // NOT match the raw undici "Connect Timeout Error" / socket ETIMEDOUT strings
+  // (raising the local timeout is the wrong remedy for a TCP-connect failure).
+  // Caveat: the Anthropic SDK reclassifies a connect-timeout as "Request timed
+  // out." — so on the Claude path a connect failure may still surface the remedy;
+  // that is acceptable (a wrapped SDK timeout is plausibly the local window).
+  const aborted = /\babort|request timed out/i.test(String(errorMessage || ''));
+  const lines = [
+    `Model: ${model}`,
+    `Provider: ${providerLabel}`,
+    `When: ${whenIso}`,
+    `Host: ${host}`,
+    ``,
+    `==== ${providerLabel} Conclusion: FAILED ====`,
+    `The AI conclusion could NOT be generated for this scan.`,
+    `Error: ${errorMessage}`,
+  ];
+  if (aborted) {
+    const secs = Math.round((Number(timeoutMs) || 0) / 1000);
+    lines.push(
+      ``,
+      `This looks like a TIMEOUT — the request was aborted${secs ? ` after ~${secs}s` : ''}. Large`,
+      `cloud-scan payloads can exceed the AI timeout. Re-run with a longer timeout, e.g.:`,
+      `  NSA_AI_TIMEOUT_MS=600000 nsauditor-ai --host <target> ...`,
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * One-line end-of-scan summary so an AI failure/skip is visible without scrolling
+ * the per-stage logs. `ai_status` covers EVERY value maybeSendToOpenAI returns:
+ *   'ok'            — a conclusion was generated
+ *   'empty'         — provider returned 200 but no extractable text (NOT ok)
+ *   'skipped'       — AI disabled (AI_ENABLED not true)
+ *   'key_unresolved'— AI enabled but the API key did not resolve
+ *   'no_summary'    — no scan summary to send
+ *   'failed'        — the provider call threw (carries ai_error as the cause)
+ * Any unknown status falls to the FAILED branch (fail-visible default).
+ */
+export function aiSummaryLine({ host, ai_status, ai_error }) {
+  switch (ai_status) {
+    case 'ok':             return `AI conclusion: OK (${host})`;
+    case 'empty':          return `AI conclusion: EMPTY — provider returned no text (${host})`;
+    case 'skipped':        return `AI conclusion: SKIPPED — AI_ENABLED not set (${host})`;
+    case 'key_unresolved': return `AI conclusion: SKIPPED — API key could not be resolved (${host})`;
+    case 'no_summary':     return `AI conclusion: SKIPPED — no scan summary to send (${host})`;
+    default:               return `AI conclusion: FAILED (${host})${ai_error ? ` — ${ai_error}` : ''}`;
+  }
+}

package/utils/scan_history.mjs

@@ -31,6 +31,10 @@ export async function recordScan(outputDir, summary) {
     openPorts: Array.isArray(summary.openPorts) ? summary.openPorts : [],
     os: summary.os ?? null,
     findingsCount: summary.findingsCount ?? 0,
+    // review re-fold R-1: persist the cloud/service split so a cloud (--host aws)
+    // scan's findings are machine-visible in history (findingsCount already
+    // includes them; this surfaces how many came from cloud auditors).
+    cloudFindingsCount: summary.cloudFindingsCount ?? 0,
     services: Array.isArray(summary.services) ? summary.services.map((s) => ({
       port: s.port ?? null,
       protocol: s.protocol ?? 'tcp',

package/utils/sentinel_scope.mjs

@@ -4,8 +4,14 @@
 // (`aws`/`gcp`/`azure`) and the plugin selection is the IMPLICIT `all`, run only
 // the plugins tagged with that provider (`plugin.cloudProvider`), skipping the
 // other clouds + the non-cloud network plugins (which would otherwise probe the
-// literal string "aws" and emit unreachable-host noise). Explicit plugin
-// selections are always honored as-is.
+// literal string "aws" and emit unreachable-host noise).
+//
+// scopeSelectionForHost honors an EXPLICIT plugin selection as-is (it only scopes
+// the implicit `all`). The CLOUD-INTENT contract itself, however, is NOT waivable
+// by explicit selection: excludeMismatchedCloudPlugins (BUG2b) strips any cloud
+// auditor whose cloudProvider does not match the host's sentinel — including an
+// explicitly-listed foreign-cloud plugin and every cloud plugin on a network host.
+// '--host' is the sole cloud-scan trigger; credentials/selection are not intent.
 
 export const CLOUD_SENTINEL_HOSTS = new Set(['aws', 'gcp', 'azure']);
 
@@ -41,6 +47,39 @@ export function scopeSelectionForHost(selection, host, spec) {
   return { selected, skipped, scoped: true, provider };
 }
 
+/**
+ * BUG2(b) (operator-confirmed contract 2026-07-03): the INVERSE of
+ * scopeSelectionForHost — a cloud auditor plugin runs IF AND ONLY IF the host is
+ * ITS OWN cloud sentinel. `--host` is the sole cloud-intent signal; credentials
+ * in the environment are a capability, never intent; there is NO escape hatch
+ * (not the implicit `all`, not an explicit `--plugins 1020` selection).
+ *
+ * Strips every cloud-tagged plugin whose `cloudProvider` does NOT match the
+ * host's sentinel:
+ *   - NETWORK host (IP / CIDR / hostname → sentinel === null): ALL cloud plugins
+ *     are foreign → all stripped (the reported router-scan bug).
+ *   - SENTINEL host P (aws/gcp/azure): a foreign-cloud plugin (e.g. an AWS
+ *     auditor explicitly selected on `--host gcp`) is stripped; P's own plugins
+ *     and non-cloud plugins are kept. (Complements scopeSelectionForHost, which
+ *     only scopes the implicit `all` — this also covers explicit selections.)
+ *
+ * @param {Array<object>} selection  resolved plugin objects (each may have .cloudProvider)
+ * @param {string} host
+ * @returns {{selected: object[], skipped: object[], sentinel: string|null, excludedCloud: boolean}}
+ */
+export function excludeMismatchedCloudPlugins(selection, host) {
+  const sentinel = isCloudSentinelHost(host) ? String(host).trim().toLowerCase() : null;
+  const selected = [];
+  const skipped = [];
+  for (const p of selection) {
+    // non-cloud plugins (no cloudProvider) always survive; a cloud plugin
+    // survives only when the host IS its sentinel.
+    if (p && p.cloudProvider && p.cloudProvider !== sentinel) skipped.push(p);
+    else selected.push(p);
+  }
+  return { selected, skipped, sentinel, excludedCloud: skipped.length > 0 };
+}
+
 /**
  * Multi-cloud generalization of scopeSelectionForHost: scope a resolved plugin
  * selection to the union of the given providers (by each plugin's cloudProvider