nsauditor-ai 0.1.91 → 0.1.93

package/README.md

@@ -17,8 +17,10 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
-**Latest: CE 0.1.91 + Enterprise 0.16.0** (May 2026)
+**Latest: CE 0.1.93 + Enterprise 0.16.2** (May 2026)
 
+- ☁️ **MCP `scan_cloud` tool: audit cloud accounts directly** (CE 0.1.93 — paired EE 0.16.2) — *(Enterprise)* a dedicated MCP tool so you can say *"Audit my AWS account"* or *"Audit my AWS and Azure accounts"* in Claude Desktop / Claude Code, with **no network host** — the server scopes the run to only the requested clouds' EE plugins. The MCP analog of the CLI `--host aws --plugins all` scoping. Enterprise-gated (`enterpriseMCP`) with plugin-layer defense-in-depth, and **anti-false-clean reporting** — a cloud is reported "audited" only if a plugin actually ran; a missing-credential / skipped cloud is surfaced as an explicit note + `audited:false` (R-HIGH caught + folded by the `audit-cloud-plugin-false-negatives` review). Plugin count UNCHANGED at 28; all six matrices UNCHANGED.
+- 🔌 **MCP `NSA_ENV_FILE`: per-environment `.env` for the MCP server** (CE 0.1.92 — paired EE 0.16.1) — the MCP analog of 0.16.0's CLI `--env`. Point the MCP server at a specific account/cloud by setting **`NSA_ENV_FILE`** to a dotenv path in your Claude Desktop / Claude Code config instead of inlining every credential; the server loads that environment's cloud credentials + `CLOUD_PROVIDER` at startup. Loaded **after** the MCP auth gate + license (scan-target vars only; the auth key + license are ignored if present in the file), **fail-fast** on a missing / INI / set-but-empty path, and treated as the **authoritative scan target** — leftover ambient provider credentials the file doesn't set are cleared, closing a false-clean (a partial file could otherwise silently scan a leftover account) caught + folded by the `audit-cloud-plugin-false-negatives` review. Plugin count UNCHANGED at 28; all six matrices UNCHANGED.
 - 🎯 **Per-account scanning: `--env` / `--aws-profile` + sentinel-host plugin scoping** (CE 0.1.91 — paired EE 0.16.0) — audit many cloud accounts one at a time without shell-export juggling. **`--env <path>`** loads a per-scan dotenv credentials file (override-on; fail-fast on a missing file; an INI/`~/.aws/credentials` file is detected and redirected to `--aws-profile`). **`--aws-profile <name>`** uses a named profile from the OS-default `~/.aws/credentials` (clears stale explicit keys, sets `AWS_SDK_LOAD_CONFIG=1`, implies `CLOUD_PROVIDER=aws`). On a cloud-sentinel host, **`--host aws|gcp|azure` + `--plugins all` auto-scopes** to only that cloud's plugins (other clouds + non-cloud plugins are skipped and logged); explicit `--plugins` lists are unaffected. A host↔`CLOUD_PROVIDER` conflict fails fast (no silent empty "clean" report), and a zero-match sentinel scope warns loudly. EE 0.16.0 adds a declarative `cloudProvider` field to all 27 cloud plugins. Plugin count UNCHANGED at 28; all six matrices UNCHANGED.
 - 🛡️ **Cross-cloud scope hotfix** (CE 0.1.90 — paired EE 0.15.9) — EE 0.15.9 moves the AWS-plugin `CLOUD_PROVIDER` gate from `preflight()` to `run()`: the 0.15.8 gate was placed where the scan orchestrator never calls it, so the cross-cloud bleed persisted; it's now on the load-bearing `run()` path (a `CLOUD_PROVIDER=gcp|azure` scan with AWS creds present no longer bleeds AWS resources into the GCP/Azure packs), validated via a run()-path test + a real-creds local proof. CE is a paired no-op bump. Plugin count UNCHANGED at 28; all six matrices UNCHANGED.
 - 🛡️ **Cloud-plugin scoping fixes** (CE 0.1.89 — paired EE 0.15.8) — EE 0.15.8 closes two issues surfaced by the 0.15.7 full multi-cloud smoke: the AWS plugins now gate on `CLOUD_PROVIDER` (a `CLOUD_PROVIDER=gcp|azure` scan with AWS creds present no longer bleeds AWS resources into the GCP/Azure attestation packs), and the GCP IAM/storage auditor now surfaces an evidence-gap instead of a false-clean PASS when a policy can't be read. CE is a paired no-op bump (no CE code change). Plugin count UNCHANGED at 28; all six coverage matrices UNCHANGED.
@@ -412,6 +414,7 @@ npx nsauditor-ai-mcp
 
 | Tool | Purpose |
 |---|---|
+| `scan_cloud` | Audit one or more cloud accounts (AWS / GCP / Azure) using server-configured credentials; no network host. "Audit my AWS account" / "Audit my AWS and Azure accounts". |
 | `start_assessment` | Multi-host orchestrated assessment workflow |
 | `prioritize_risks` | Cross-host risk prioritization |
 | `compliance_check` | Compliance mapping with gap analysis |
@@ -486,10 +489,9 @@ Then add this to your `claude_desktop_config.json` (Settings → Developer → E
       "command": "nsauditor-ai-mcp",
       "env": {
         "NSA_MCP_AUTH_KEY": "keychain:NSA_MCP_AUTH_KEY",
+        "NSA_ENV_FILE": "~/envs/prod-aws.env",
         "AI_PROVIDER": "claude",
-        "ANTHROPIC_API_KEY": "keychain:ANTHROPIC_API_KEY",
-        "NSA_ALLOW_ALL_HOSTS": "1",
-        "PLUGIN_TIMEOUT_MS": "5000"
+        "ANTHROPIC_API_KEY": "keychain:ANTHROPIC_API_KEY"
       }
     }
   }
@@ -503,6 +505,32 @@ The exact `NSA_MCP_AUTH_KEY` value to paste is printed by `nsauditor-ai mcp inst
 - `PLUGIN_TIMEOUT_MS=5000` — reduces per-plugin timeout to 5s so the full scan completes within Claude Desktop's 60s MCP limit
 - `AI_PROVIDER` and API key — optional, enables AI-powered analysis of scan results
 
+#### `NSA_ENV_FILE` — point the MCP server at an environment file
+
+Instead of inlining every scan variable in the config above, set **`NSA_ENV_FILE`** to a
+dotenv file and keep the cloud credentials, `CLOUD_PROVIDER`, and scan tuning there. To scan
+a different account or cloud, change the one path (or swap the file) and restart Claude Desktop —
+no JSON editing.
+
+```bash
+# ~/envs/prod-aws.env   (chmod 600 — this holds credentials)
+CLOUD_PROVIDER=aws
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=...
+NSA_ALLOW_ALL_HOSTS=1
+PLUGIN_TIMEOUT_MS=5000
+```
+
+- The file is loaded at server startup; values in it **override** the same keys in the config `env` block.
+- **Fail-fast:** if the path is missing or points at an AWS credentials/INI file, the server refuses
+  to start (it will not silently fall back to ambient credentials and scan the wrong account). The
+  error is written to the MCP server's stderr log.
+- **The file is the authoritative scan target:** ambient provider credentials (e.g. an old account's
+  `AWS_*` keys still in the config `env` block) that the file does **not** set are cleared, so a partial
+  file can't silently scan a leftover account. Instance-role / ADC identity is untouched.
+- `NSA_MCP_AUTH_KEY` and `NSAUDITOR_LICENSE_KEY` are resolved **before** the file and must stay
+  inline (or in `~/.nsauditor/.env`); if present in `NSA_ENV_FILE` they are ignored.
+
 ### Claude Code Setup
 
 ```bash
@@ -512,6 +540,15 @@ claude mcp add nsauditor-ai \
   -- npx nsauditor-ai-mcp
 ```
 
+To target an environment via the file, add it as an env value:
+
+```bash
+claude mcp add nsauditor-ai \
+  --env NSA_MCP_AUTH_KEY=keychain:NSA_MCP_AUTH_KEY \
+  --env NSA_ENV_FILE=~/envs/prod-aws.env \
+  -- npx nsauditor-ai-mcp
+```
+
 (On Linux/Windows, replace the `keychain:NSA_MCP_AUTH_KEY` placeholder with the literal key printed by `install-key`.)
 
 ### Troubleshooting MCP authentication

package/mcp_server.mjs

@@ -54,6 +54,12 @@ export function _requireProCapability(toolName) {
   return requireProCapability(toolName);
 }
 
+/** @internal Test-only. Returns the Enterprise-gate denial object (or null if allowed). */
+export function _requireEnterpriseCapability(toolName) {
+  if (process.env.NODE_ENV === 'production') throw new Error('_requireEnterpriseCapability is test-only and disabled in production');
+  return requireEnterpriseCapability(toolName);
+}
+
 function requireProCapability(toolName) {
   if (_capabilities.proMCP) return null; // Pro/Enterprise: allow
   return {
@@ -65,6 +71,17 @@ function requireProCapability(toolName) {
   };
 }
 
+function requireEnterpriseCapability(toolName) {
+  if (_capabilities.enterpriseMCP) return null; // Enterprise: allow
+  return {
+    content: [{
+      type: 'text',
+      text: `🔒 **${toolName}** (cloud account auditing) requires an Enterprise license.\n\nView Enterprise pricing at https://www.nsauditor.com/ai/pricing/\n\n**CE tools available:** scan_host, list_plugins`,
+    }],
+    isError: true,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Lazy singletons — initialised on first use, overridable for tests
 // ---------------------------------------------------------------------------
@@ -176,6 +193,22 @@ const TOOLS = [
       required: ['host'],
     },
   },
+  {
+    name: 'scan_cloud',
+    description:
+      'Audit one or more cloud accounts (AWS / GCP / Azure) for security & compliance posture using the credentials configured in the server environment. No network host required. Requires an Enterprise license. Use for "audit my AWS account" / "audit my AWS and Azure accounts".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        providers: {
+          type: 'array',
+          items: { type: 'string', enum: ['aws', 'gcp', 'azure'] },
+          description: 'Which cloud(s) to audit. Omit to audit all clouds the server is configured for.',
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: 'probe_service',
     description:
@@ -313,6 +346,80 @@ export async function handleScanHost(args) {
   };
 }
 
+const VALID_PROVIDERS = ['aws', 'gcp', 'azure'];
+
+export async function handleScanCloud(args) {
+  // Validate providers; default → all three.
+  let providers = VALID_PROVIDERS.slice();
+  if (args && args.providers != null) {
+    if (!Array.isArray(args.providers)) {
+      throw new Error('providers must be an array of "aws" | "gcp" | "azure"');
+    }
+    const requested = args.providers.map((p) => String(p).trim().toLowerCase());
+    for (const p of requested) {
+      if (!VALID_PROVIDERS.includes(p)) {
+        throw new Error(`unknown provider '${p}' (valid: ${VALID_PROVIDERS.join(', ')})`);
+      }
+    }
+    if (requested.length > 0) providers = requested;
+  }
+
+  const pm = await getPluginManager();
+
+  // Save/set/restore CLOUD_PROVIDER so the per-plugin .includes() gates pass and
+  // the cross-cloud bleed gate is satisfied — restored in finally so the tool
+  // never leaves the long-lived server's env mutated for the next call.
+  const savedProvider = process.env.CLOUD_PROVIDER;
+  let output;
+  try {
+    process.env.CLOUD_PROVIDER = providers.join(',');
+    output = await pm.runCloud(providers);
+  } finally {
+    if (savedProvider === undefined) delete process.env.CLOUD_PROVIDER;
+    else process.env.CLOUD_PROVIDER = savedProvider;
+  }
+
+  // Render a Markdown summary (best-effort, same as scan_host).
+  let markdown = null;
+  try {
+    if (output.conclusion) {
+      markdown = buildMarkdownReport({ host: output.host, conclusion: output.conclusion, toolVersion: TOOL_VERSION });
+    }
+  } catch { /* swallow — markdown is best-effort */ }
+
+  // Anti-false-clean: a requested cloud is "audited" ONLY if >=1 of its plugins
+  // actually completed (manifest status 'ran'). Surface every NOT-effectively-
+  // audited provider with a specific reason — never a silent empty "clean".
+  const providerStatus = output.providerStatus || {};
+  const auditedProviders = output.auditedProviders || [];
+  const notes = [];
+  for (const p of providers) {
+    const s = providerStatus[p] || { available: 0, ran: 0, skipped: 0, errored: 0 };
+    if (s.ran > 0) continue; // effectively audited (clean or not)
+    if (s.available === 0) {
+      notes.push(`${p}: no cloud plugins available — Enterprise EE plugins not installed (an empty result is NOT a clean pass)`);
+    } else if (s.errored > 0) {
+      notes.push(`${p}: ${s.errored} plugin(s) ran but errored (e.g. credentials not configured) — NOT audited (an empty result is NOT a clean pass)`);
+    } else {
+      notes.push(`${p}: ${s.skipped} plugin(s) present but skipped (requirements/capability not met) — NOT audited`);
+    }
+  }
+
+  // Honest count: completed audits, NOT error/skip envelopes.
+  const pluginsRan = (output.manifest || []).filter((m) => m.status === 'ran').length;
+
+  return {
+    providers,
+    audited: auditedProviders.length > 0,
+    auditedProviders,
+    conclusion: output.conclusion ?? null,
+    manifest: output.manifest ?? [],
+    pluginsRan,
+    markdown,
+    ...(notes.length ? { notes } : {}),
+  };
+}
+
 export async function handleProbeService(args) {
   if (!args?.host || typeof args.host !== 'string') {
     throw new Error('Missing required parameter: host');
@@ -371,6 +478,7 @@ export async function handleListPlugins() {
 /** Map tool name to handler. Exported for testing. */
 export const toolHandlers = {
   scan_host: handleScanHost,
+  scan_cloud: handleScanCloud,
   probe_service: handleProbeService,
   get_vulnerabilities: handleGetVulnerabilities,
   list_plugins: handleListPlugins,
@@ -429,6 +537,19 @@ export function createServer() {
       }
     }
 
+    // Gate the Enterprise cloud-audit tool at the MCP dispatch layer.
+    if (name === 'scan_cloud') {
+      const denied = requireEnterpriseCapability(name);
+      if (denied) {
+        return {
+          ...denied,
+          content: denied.content.map((c) =>
+            c.type === 'text' ? { ...c, text: appendCallSentinel(c.text, callId) } : c,
+          ),
+        };
+      }
+    }
+
     try {
       const result = await handler(args ?? {});
 
@@ -592,6 +713,27 @@ export async function startStdioServer() {
   _tier = getTierFromEnv();
   _capabilities = resolveCapabilities(_tier);
 
+  // NSA_ENV_FILE: load the per-environment dotenv file AFTER auth + license
+  // (so it carries scan-target vars only and can alter neither) and BEFORE
+  // createServer()/connect. plugin_manager.mjs captures PLUGIN_TIMEOUT_MS in a
+  // module-level const at import (first tool call), so the file MUST be applied
+  // before any tool call can import it. Fail-fast: a missing / INI file refuses
+  // startup rather than silently scanning ambient credentials (wrong-account →
+  // a false "clean"). stdout is JSON-RPC, so diagnostics go to stderr.
+  try {
+    const fsm = await import('node:fs');
+    const { applyScanEnvFile } = await import('./utils/mcp_env_file.mjs');
+    applyScanEnvFile({
+      env: process.env,
+      fileExists: (p) => fsm.existsSync(p),
+      readFile: (p) => fsm.readFileSync(p, 'utf8'),
+      log: (m) => process.stderr.write(`[nsauditor-mcp] ${m}\n`),
+    });
+  } catch (err) {
+    process.stderr.write(`✗ NSA_ENV_FILE: ${err.message}\n`);
+    process.exit(1);
+  }
+
   const server = createServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.1.91",
+  "version": "0.1.93",
   "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 } from './utils/sentinel_scope.mjs';
+import { scopeSelectionForHost, scopeSelectionForProviders } from './utils/sentinel_scope.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 
@@ -852,6 +852,59 @@ export class PluginManager {
       ai_out_path: null,
     };
   }
+
+  /**
+   * Cloud-account audit: scope the plugin run to the union of the given cloud
+   * providers (by each plugin's `cloudProvider` field), with no network host.
+   * Sibling of run() that scopes by provider-set instead of by sentinel host,
+   * then reuses the same orchestrate + conclude path. Returns the run()-shaped
+   * output. The cloud plugins ignore `host`; the synthetic label just identifies
+   * the report. An empty selection returns an empty result (surfaced as a note
+   * by the caller) rather than a silent clean.
+   *
+   * @param {string[]} providers  e.g. ['aws'] or ['aws','azure']
+   * @param {object} [opts]
+   */
+  async runCloud(providers, opts = {}) {
+    const reqProviders = (providers || []).map((p) => String(p).trim().toLowerCase());
+    const host = `cloud:${reqProviders.join('+') || 'none'}`;
+    const all = this.plugins.slice();
+    const { selected } = scopeSelectionForProviders(all, reqProviders);
+
+    // Seed per-provider accounting for EVERY requested provider, so a provider
+    // with zero plugins is visible (available:0), not just silently absent.
+    const providerStatus = {};
+    for (const p of reqProviders) providerStatus[p] = { available: 0, ran: 0, skipped: 0, errored: 0 };
+
+    if (selected.length === 0) {
+      // Parity with the sentinel-host path in run(): an empty scope is NOT a clean pass.
+      console.error(
+        `WARNING: scan_cloud scope [${reqProviders.join(', ') || '(none)'}] matched 0 cloud plugins — ` +
+        `NOTHING was audited (an empty result is NOT a clean pass).`,
+      );
+      return { host, results: [], conclusion: null, manifest: [], providerStatus, auditedProviders: [],
+               ai: null, ai_meta: null, ai_error: null, ai_out_path: null };
+    }
+
+    const orch = await this._runOrchestrated(host, selected, opts);
+    const conclusion = await this.runConcluder(orch.results);
+
+    // Per-provider effectiveness from the manifest (ids match the selected set).
+    const manifestById = new Map((orch.manifest || []).map((m) => [String(m.id), m]));
+    for (const p of selected) {
+      const prov = p.cloudProvider;
+      if (!providerStatus[prov]) providerStatus[prov] = { available: 0, ran: 0, skipped: 0, errored: 0 };
+      providerStatus[prov].available++;
+      const m = manifestById.get(String(p.id));
+      if (m && m.status === 'ran') providerStatus[prov].ran++;
+      else if (m && m.status === 'skipped') providerStatus[prov].skipped++;
+      else providerStatus[prov].errored++;
+    }
+    const auditedProviders = Object.keys(providerStatus).filter((p) => providerStatus[p].ran > 0);
+
+    return { host, results: orch.results, conclusion, manifest: orch.manifest, providerStatus, auditedProviders,
+             ai: null, ai_meta: null, ai_error: null, ai_out_path: null };
+  }
 }
 
 export default PluginManager;

package/utils/mcp_env_file.mjs

@@ -0,0 +1,89 @@
+// utils/mcp_env_file.mjs
+//
+// Loads the per-environment dotenv file named by NSA_ENV_FILE into env for the
+// MCP server, reusing the CLI's resolveScanEnv() (same dotenv parse, tilde-
+// expansion, INI-detection, fail-fast). Called from startStdioServer() AFTER
+// auth + license are resolved, so the file carries SCAN-TARGET vars only (cloud
+// creds / CLOUD_PROVIDER / scan tuning) and can neither bypass the auth gate nor
+// escalate the license tier. NSA_MCP_AUTH_KEY / NSAUDITOR_LICENSE_KEY in the file
+// are intentionally ignored (they resolve before the file is read).
+//
+// The file is the AUTHORITATIVE scan-target selector: any explicit provider
+// credential present in the ambient env but NOT set by the file is "leftover"
+// (e.g. a previous account's keys still in the Claude Desktop env block) and is
+// CLEARED — otherwise a partial file would let the scan silently run against the
+// wrong account and report "clean" (the worst outcome an audit tool can produce).
+// Instance-role / ADC identity (which has no env var) is untouched. This mirrors
+// how the CLI --aws-profile path already clears the explicit AWS keys.
+
+import { resolveScanEnv } from './env_loader.mjs';
+
+// Resolved before NSA_ENV_FILE loads → stripped if present in the file.
+const RESERVED_KEYS = new Set(['NSA_MCP_AUTH_KEY', 'NSAUDITOR_LICENSE_KEY']);
+
+// Explicit per-provider credential env vars. Cleared if the file does not set them.
+const PROVIDER_CRED_KEYS = [
+  'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN', 'AWS_PROFILE',
+  'GOOGLE_APPLICATION_CREDENTIALS', 'GOOGLE_CLOUD_PROJECT', 'GOOGLE_CLOUD_PROJECT_ID', 'GCLOUD_PROJECT',
+  'AZURE_CLIENT_ID', 'AZURE_TENANT_ID', 'AZURE_CLIENT_SECRET', 'AZURE_SUBSCRIPTION_ID',
+];
+
+/**
+ * @param {object} a
+ * @param {Record<string,string>} a.env  process.env (mutated in place; file wins)
+ * @param {(p:string)=>boolean} a.fileExists
+ * @param {(p:string)=>string}  a.readFile
+ * @param {(m:string)=>void}    [a.log]  stderr sink — key NAMES only, never values
+ * @returns {{applied: string[], ignored: string[], cleared: string[]}}
+ * @throws if NSA_ENV_FILE is set-but-empty, or points at a missing/INI file
+ */
+export function applyScanEnvFile({ env, fileExists, readFile, log = () => {} }) {
+  const envPath = env.NSA_ENV_FILE;
+  if (envPath == null) return { applied: [], ignored: [], cleared: [] }; // truly unset → no-op
+  if (typeof envPath !== 'string' || envPath.trim() === '') {
+    // set-but-empty (e.g. an unresolved config-template var): the operator
+    // clearly intended a file. Fail-fast rather than silently scan ambient creds.
+    throw new Error(
+      'NSA_ENV_FILE is set but empty — refusing to start; unset it or give a real path ' +
+      '(an empty value would silently scan ambient credentials)',
+    );
+  }
+
+  // Only envPath is set → resolveScanEnv reduces to: resolve + tilde-expand →
+  // fail-fast if missing → reject INI → dotenv.parse → { set, unset: [] }.
+  const { set } = resolveScanEnv({ envPath, env, fileExists, readFile });
+
+  const ignored = Object.keys(set).filter((k) => RESERVED_KEYS.has(k));
+  for (const k of ignored) delete set[k];
+
+  const applied = Object.keys(set);
+  Object.assign(env, set); // override-on — the file is the environment selector
+
+  // Anti-false-clean: clear leftover ambient provider creds the file did NOT set.
+  const cleared = [];
+  for (const k of PROVIDER_CRED_KEYS) {
+    if (!(k in set) && env[k] != null && env[k] !== '') {
+      delete env[k];
+      cleared.push(k);
+    }
+  }
+
+  if (ignored.length) {
+    log(
+      `ignored ${ignored.join(', ')} from NSA_ENV_FILE — auth/license resolve ` +
+      `before the file; set them inline or in ~/.nsauditor/.env`,
+    );
+  }
+  if (cleared.length) {
+    log(
+      `cleared ambient ${cleared.join(', ')} not set by NSA_ENV_FILE ` +
+      `(the file is the authoritative scan target — refusing to use leftover credentials)`,
+    );
+  }
+  log(
+    `Loaded scan environment from ${envPath} ` +
+    `(${applied.length} keys: ${applied.join(', ') || 'none'})`,
+  );
+
+  return { applied, ignored, cleared };
+}

package/utils/sentinel_scope.mjs

@@ -40,3 +40,24 @@ export function scopeSelectionForHost(selection, host, spec) {
   }
   return { selected, skipped, scoped: true, provider };
 }
+
+/**
+ * Multi-cloud generalization of scopeSelectionForHost: scope a resolved plugin
+ * selection to the union of the given providers (by each plugin's cloudProvider
+ * field). Used by pluginManager.runCloud() / the MCP scan_cloud tool. Network
+ * plugins (no cloudProvider) and non-requested clouds land in `skipped`.
+ *
+ * @param {Array<object>} selection  resolved plugin objects (each may have .cloudProvider)
+ * @param {string[]} providers       e.g. ['aws'] or ['aws','azure']
+ * @returns {{selected: object[], skipped: object[], providers: string[]}}
+ */
+export function scopeSelectionForProviders(selection, providers) {
+  const set = new Set((providers || []).map((p) => String(p).trim().toLowerCase()));
+  const selected = [];
+  const skipped = [];
+  for (const p of selection) {
+    if (p && p.cloudProvider && set.has(p.cloudProvider)) selected.push(p);
+    else skipped.push(p);
+  }
+  return { selected, skipped, providers: [...set] };
+}