nsauditor-ai 0.1.90 → 0.1.92

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.90 + Enterprise 0.15.9** (May 2026)
+**Latest: CE 0.1.92 + Enterprise 0.16.1** (May 2026)
 
+- 🔌 **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.
 - ☁️ **GCP SDK refresh** (CE 0.1.88 — paired EE 0.15.7) — EE 0.15.7 re-applies the GCP SDK major bump (`@google-cloud/compute` ^6 / `@google-cloud/iam` ^2 / `googleapis` ^173) on the pure-ADC credential path, validated live against a test-infra GCP project (first live GCP audit: 3 CRITICAL firewall findings on compute@6). Compute-client SA-impersonation is explicitly unsupported on compute@6 (documented in-code + gated to plan-later); pure-ADC and key-file paths are fully supported. Also folds the plugin-1021 project-resolution fix. CE is a paired no-op bump (no CE code change). Plugin count UNCHANGED at 28; all six coverage matrices UNCHANGED.
@@ -485,10 +487,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"
       }
     }
   }
@@ -502,6 +503,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
@@ -511,6 +538,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/bin/nsauditor-ai.mjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-import '../cli.mjs';
+import { main } from '../cli.mjs';
+main().catch((err) => { console.error(err?.stack || err); process.exit(1); });

package/cli.mjs

@@ -5,6 +5,7 @@ import { buildHtmlReport } from './utils/report_html.mjs';
 import fsp from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -522,7 +523,7 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
 
 /* ------------------------------- CLI ----------------------------------- */
 
-async function parseArgs(argv) {
+export async function parseArgs(argv) {
   const args = { cmd: 'scan', host: undefined, plugins: 'all', insecureHttps: false };
   const a = argv.slice(2);
   // Help: bare `--help`/`-h`/`help` or completely empty invocation.
@@ -604,6 +605,15 @@ async function parseArgs(argv) {
   const complianceScopeVal = get('compliance-scope') || get('compliance_scope');
   args.complianceScope = (complianceScopeVal && complianceScopeVal !== true) ? complianceScopeVal : null;
 
+  // Per-scan account selection (EE 0.16.x). `--env <path>` loads a dotenv
+  // (override-on) for this scan; `--aws-profile <name>` selects a named profile
+  // from ~/.aws/credentials. Both are wired into main() via resolveScanEnv().
+  // get() returns undefined (absent), true (value-less flag), or the string value.
+  const envVal = get('env');
+  args.env = envVal === undefined ? undefined : envVal; // string path, or true if value-less
+  const awsProfileVal = get('aws-profile');
+  args.awsProfile = awsProfileVal === undefined ? undefined : awsProfileVal;
+
   return args;
 }
 
@@ -804,8 +814,9 @@ function maxSeverityInConclusion(conclusion) {
   return max;
 }
 
-async function main() {
-  const { cmd, host, plugins, insecureHttps, hostFile, parallel, failOn, outputFormat, watch, intervalMinutes, webhookUrl, alertSeverity, ports, compliance, complianceScope } = await parseArgs(process.argv);
+export async function main() {
+  const args = await parseArgs(process.argv);
+  const { cmd, host, plugins, insecureHttps, hostFile, parallel, failOn, outputFormat, watch, intervalMinutes, webhookUrl, alertSeverity, ports, compliance, complianceScope } = 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
@@ -833,6 +844,10 @@ Usage:
 Scan options:
   --host, --ip, --target <h>   Target host, IP, or CIDR
   --host-file <path>           File with one host per line
+  --env <path>                 Load a dotenv (KEY=value) file for this scan (per-account
+                               credentials). Override-on; missing file = hard error.
+  --aws-profile <name>         Use a named profile from the OS-default ~/.aws/credentials.
+                               Implies CLOUD_PROVIDER=aws; overrides explicit AWS_* keys.
   --plugins <list|all>         Plugins to run (e.g. 001,003,020 or "all"; default: all)
   --ports <range>              Override port list (e.g. 22,80,443 or 1-1000)
   --out <dir>                  Output directory for scan artifacts
@@ -890,10 +905,15 @@ Environment:
 Cloud-scan hosts:
   --host aws | gcp | azure       Sentinel literals (case-insensitive). These are not
                                  DNS-resolved; they route the scan to the matching
-                                 cloud-scanner plugin via the provider's control-plane
-                                 API. Pair with --plugins 020,030 (or similar) — using
-                                 --plugins all on a sentinel host produces noisy
-                                 unreachable-host findings from non-cloud plugins.
+                                 cloud-scanner plugins via the provider's control-plane
+                                 API, and imply CLOUD_PROVIDER=<host> when unset. With
+                                 --plugins all the scan AUTO-SCOPES to only that cloud's
+                                 plugins (other clouds + non-cloud plugins are skipped and
+                                 the skip is logged) — so --plugins all is safe here.
+                                 Note: the composite zero-trust checker (1023) has no
+                                 single cloud and is therefore skipped under this
+                                 auto-scope; to run it, select it explicitly
+                                 (--plugins 023,...) or scan a network host/CIDR.
 
 Examples:
   nsauditor-ai scan --host 10.0.0.1 --plugins all
@@ -907,6 +927,37 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     process.exit(0);
   }
 
+  // Per-scan environment selection (--env / --aws-profile) + sentinel-host
+  // implied CLOUD_PROVIDER. The eager `import 'dotenv/config'` at the top of
+  // this file already loaded the default cwd `.env` (override-off) for
+  // import-time consumers; this layers the explicitly-selected env ON TOP
+  // (override-on) before license + dispatch.
+  if (args.env === true) {
+    console.error('Error: --env requires a file path (e.g. --env ~/envs/prod.env)');
+    process.exit(2);
+  }
+  if (args.awsProfile === true) {
+    console.error('Error: --aws-profile requires a profile name (e.g. --aws-profile prod)');
+    process.exit(2);
+  }
+  try {
+    const { resolveScanEnv } = await import('./utils/env_loader.mjs');
+    const fsm = await import('node:fs');
+    const patch = resolveScanEnv({
+      envPath: typeof args.env === 'string' ? args.env : undefined,
+      awsProfile: typeof args.awsProfile === 'string' ? args.awsProfile : undefined,
+      host,
+      env: process.env,
+      fileExists: (p) => fsm.existsSync(p),
+      readFile: (p) => fsm.readFileSync(p, 'utf8'),
+    });
+    Object.assign(process.env, patch.set);          // override-on
+    for (const k of patch.unset) delete process.env[k];
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
   // Verify license JWT at startup (~5ms for ES256). Populates _verifiedTier
   // so all subsequent getTierFromEnv() calls return the cryptographically
   // validated tier instead of relying on prefix detection alone.
@@ -2004,7 +2055,18 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
   }
 }
 
-main().catch((err) => {
-  console.error(err?.stack || err);
-  process.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 = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+})();
+if (_isEntrypoint) {
+  main().catch((err) => {
+    console.error(err?.stack || err);
+    process.exit(1);
+  });
+}

package/mcp_server.mjs

@@ -592,6 +592,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.90",
+  "version": "0.1.92",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,

package/plugin_manager.mjs

@@ -20,6 +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';
 
 const __filename = fileURLToPath(import.meta.url);
 
@@ -749,15 +750,38 @@ export class PluginManager {
     let selection;
     let opts;
 
+    let rawSpec;
     if (specOrOptions && typeof specOrOptions === "object" && !Array.isArray(specOrOptions)) {
       const { plugins = "all", ...rest } = specOrOptions;
+      rawSpec = plugins;
       selection = this._resolveSelection(plugins);
       opts = rest;
     } else {
+      rawSpec = specOrOptions;
       selection = this._resolveSelection(specOrOptions);
       opts = maybeOpts || {};
     }
 
+    // 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);
+    if (scope.scoped) {
+      selection = scope.selected;
+      if (scope.selected.length === 0) {
+        console.error(
+          `WARNING: --host '${scope.provider}' matched 0 ${scope.provider.toUpperCase()} plugins — ` +
+          `NOTHING was audited. Ensure the ${scope.provider.toUpperCase()} plugins are installed and ` +
+          `licensed (an empty result is NOT a clean pass).`,
+        );
+      } else if (scope.skipped.length) {
+        console.error(
+          `Cloud host '${scope.provider}' → running ${scope.selected.length} ` +
+          `${scope.provider.toUpperCase()} plugin(s); skipping ${scope.skipped.length} ` +
+          `non-${scope.provider} plugin(s) (other clouds + non-cloud).`,
+        );
+      }
+    }
+
     // Decide execution mode
     const anyOrchestratedSignals = selection.some((p) => p?.priority != null || p?.requirements != null);
     const orchestrate = opts.orchestrate !== false && anyOrchestratedSignals;

package/utils/env_loader.mjs

@@ -0,0 +1,113 @@
+// utils/env_loader.mjs
+//
+// Pure resolver for the per-scan environment selection flags (--env / --aws-profile)
+// and the sentinel-host implied CLOUD_PROVIDER. Returns an env "patch"
+// ({ set, unset }) that the CLI applies to process.env. Fail-fast: throws on a
+// missing --env file or an INI/credentials file mistakenly passed to --env.
+//
+// fs is injected (readFile/fileExists) so the precedence + error rules unit-test
+// without a real filesystem.
+
+import os from 'node:os';
+import path from 'node:path';
+import dotenv from 'dotenv';
+
+const CLOUD_SENTINELS = new Set(['aws', 'gcp', 'azure']);
+const AWS_EXPLICIT_KEYS = ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN'];
+
+function expandTilde(p) {
+  if (typeof p !== 'string') return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+// INI signature: a [section] header line, OR no KEY=value line at all.
+function looksLikeIni(content) {
+  const hasSection = /^\s*\[[^\]]+\]\s*$/m.test(content);
+  const hasKeyValue = /^\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=/m.test(content);
+  return hasSection || !hasKeyValue;
+}
+
+function providerAlreadySet(set, env) {
+  const v = set.CLOUD_PROVIDER ?? env.CLOUD_PROVIDER;
+  return v != null && String(v).trim() !== '';
+}
+
+// The effective CLOUD_PROVIDER after merging the --env file (set) + shell env.
+function effectiveProvider(set, env) {
+  const v = set.CLOUD_PROVIDER ?? env.CLOUD_PROVIDER;
+  return v == null ? '' : String(v).trim().toLowerCase();
+}
+
+// Lenient match (mirrors awsScanSkipReason CSV semantics): the effective provider
+// matches the host if it equals the host OR is a CSV that includes the host.
+function providerMatchesHost(effective, hostProvider) {
+  if (!effective) return true; // unset → no contradiction
+  const tokens = effective.split(',').map((t) => t.trim()).filter(Boolean);
+  return tokens.includes(hostProvider);
+}
+
+/**
+ * @param {object} args
+ * @param {string} [args.envPath]     value of --env
+ * @param {string} [args.awsProfile]  value of --aws-profile
+ * @param {string} [args.host]        --host value (for sentinel CLOUD_PROVIDER implication)
+ * @param {object} args.env           snapshot of current process.env (read-only)
+ * @param {(p:string)=>boolean} args.fileExists
+ * @param {(p:string)=>string}  args.readFile
+ * @returns {{set: Record<string,string>, unset: string[]}}
+ */
+export function resolveScanEnv({ envPath, awsProfile, host, env = {}, fileExists, readFile }) {
+  const set = {};
+  const unset = [];
+
+  // 1. --env dotenv file (override-on applied by caller via Object.assign).
+  if (typeof envPath === 'string' && envPath.length) {
+    const resolved = path.resolve(expandTilde(envPath));
+    if (!fileExists(resolved)) {
+      throw new Error(`--env file not found: ${resolved} (fail-fast: refusing to fall back to ambient credentials)`);
+    }
+    const content = readFile(resolved);
+    if (looksLikeIni(content)) {
+      throw new Error(
+        `${resolved} looks like an AWS credentials / INI file (has [section] headers / no KEY=value lines), ` +
+        `not a dotenv file. Use --aws-profile <name> instead (with AWS_SHARED_CREDENTIALS_FILE in an --env file ` +
+        `if the path is non-default).`,
+      );
+    }
+    Object.assign(set, dotenv.parse(content));
+  }
+
+  // 2. --aws-profile: AWS_PROFILE wins; clear explicit keys; load ~/.aws/config; imply aws.
+  if (typeof awsProfile === 'string' && awsProfile.length) {
+    set.AWS_PROFILE = awsProfile;
+    set.AWS_SDK_LOAD_CONFIG = '1';
+    for (const k of AWS_EXPLICIT_KEYS) {
+      delete set[k];      // a key from the --env file must not survive the profile
+      unset.push(k);
+    }
+    if (!providerAlreadySet(set, env)) set.CLOUD_PROVIDER = 'aws';
+  }
+
+  // 3. Sentinel host implies its provider when CLOUD_PROVIDER is still unset.
+  //    Fail-fast on a host vs CLOUD_PROVIDER contradiction: if the effective
+  //    provider (--env file + shell env) is set to a cloud that does NOT match
+  //    the host, scoping would select host-plugins that then all self-skip on
+  //    the awsScanSkipReason gate → ZERO plugins run → a silent "clean" report.
+  if (typeof host === 'string' && CLOUD_SENTINELS.has(host.trim().toLowerCase())) {
+    const hostProvider = host.trim().toLowerCase();
+    const effective = effectiveProvider(set, env);
+    if (effective && !providerMatchesHost(effective, hostProvider)) {
+      throw new Error(
+        `--host '${hostProvider}' conflicts with CLOUD_PROVIDER='${effective}': the host and the ` +
+        `effective cloud provider do not match, which would silently skip every plugin (an empty ` +
+        `"clean" report). Resolve by dropping the conflicting CLOUD_PROVIDER, or scan the matching host ` +
+        `(--host ${effective.split(',')[0].trim()}).`,
+      );
+    }
+    if (!providerAlreadySet(set, env)) set.CLOUD_PROVIDER = hostProvider;
+  }
+
+  return { set, unset };
+}

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

@@ -0,0 +1,42 @@
+// utils/sentinel_scope.mjs
+//
+// Sentinel-host plugin scoping. When the scan target is a cloud-sentinel host
+// (`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.
+
+export const CLOUD_SENTINEL_HOSTS = new Set(['aws', 'gcp', 'azure']);
+
+export function isCloudSentinelHost(host) {
+  return typeof host === 'string' && CLOUD_SENTINEL_HOSTS.has(host.trim().toLowerCase());
+}
+
+// spec is the ORIGINAL plugin spec ('all' | undefined | null → implicit;
+// array or CSV string → explicit). Only the implicit case is scoped.
+function isImplicitAll(spec) {
+  if (spec == null) return true;
+  if (typeof spec === 'string') return spec.trim().toLowerCase() === 'all';
+  return false; // arrays are always explicit
+}
+
+/**
+ * @param {Array<object>} selection  resolved plugin objects (each may have .cloudProvider)
+ * @param {string} host
+ * @param {string|string[]} spec      original selection spec
+ * @returns {{selected: object[], skipped: object[], scoped: boolean, provider: string|null}}
+ */
+export function scopeSelectionForHost(selection, host, spec) {
+  if (!isCloudSentinelHost(host) || !isImplicitAll(spec)) {
+    return { selected: selection, skipped: [], scoped: false, provider: null };
+  }
+  const provider = host.trim().toLowerCase();
+  const selected = [];
+  const skipped = [];
+  for (const p of selection) {
+    if (p && p.cloudProvider === provider) selected.push(p);
+    else skipped.push(p);
+  }
+  return { selected, skipped, scoped: true, provider };
+}