nsauditor-ai 0.1.90 → 0.1.91

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.90 + Enterprise 0.15.9** (May 2026)
+**Latest: CE 0.1.91 + Enterprise 0.16.0** (May 2026)
 
+- 🎯 **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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.1.90",
+  "version": "0.1.91",
   "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/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 };
+}