nsauditor-ai 0.1.91 → 0.1.92

package/README.md

@@ -17,8 +17,9 @@ 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.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.
@@ -486,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"
       }
     }
   }
@@ -503,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
@@ -512,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/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.91",
+  "version": "0.1.92",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,

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 };
+}