nsauditor-ai 0.2.55 → 0.2.57

package/mcp_server.mjs

@@ -12,11 +12,12 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
+import { responseDigest, RECEIPT_MARKER } from './utils/mcp_call_digest.mjs';
 import { appendFile, mkdir, chmod } from 'node:fs/promises';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { resolveAndValidate } from './utils/net_validation.mjs';
+import { resolveAndValidate, classifyAddress, canonicalIp, allowAllHosts } from './utils/net_validation.mjs';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
   CallToolRequestSchema,
@@ -175,10 +176,11 @@ export function buildScanCloudRegionIntent(regions) {
 //   1. Embedded in the response text (Claude cannot omit; it's the payload)
 //   2. Persisted to ~/.nsauditor/mcp-calls.log (append-only, mode 0600)
 //
-// Customer verification: paste the UUID from Claude into
-//   nsauditor-ai mcp verify-call <uuid>
-// If it appears in the local log → real call. If not → hallucinated.
-// (See cli.mjs `verify-call` subcommand.)
+// Customer verification: save the response (footer included) and run
+//   nsauditor-ai mcp verify-call <uuid> --response <file>
+// The id alone proves only that this server issued it once — an AI client that has seen an earlier response can paste
+// a real id under a fabricated one. So the server also logs a digest of each response BODY (utils/mcp_call_digest.mjs),
+// and verify-call recomputes it from the saved text (1.3.0 (s6)). See cli.mjs `verify-call`.
 const MCP_CALL_LOG_PATH = join(homedir(), '.nsauditor', 'mcp-calls.log');
 
 async function recordToolCall(toolName) {
@@ -200,11 +202,20 @@ async function recordToolCall(toolName) {
 }
 
 function appendCallSentinel(text, callId) {
+  // The digest of the BODY — the text the receipt is appended to — is what binds this response to its id. It is
+  // logged, never printed: a digest in the footer would replay together with the id. Best-effort like the id line: a
+  // failed write leaves the call verifiable only as "issued", never as a false ✓.
+  try {
+    _nodeFs.appendFileSync(MCP_CALL_LOG_PATH, JSON.stringify({ call_id: callId, digest: responseDigest(text) }) + '\n', { encoding: 'utf8' });
+  } catch (err) {
+    process.stderr.write(`[nsauditor-mcp] call-log digest write failed: ${err.message}\n`);
+  }
   return (
-    `${text}\n\n── Verified MCP call ──\n` +
+    `${text}\n\n${RECEIPT_MARKER}\n` +
     `call_id: ${callId}\n` +
-    `Verify (proves Claude actually called this server, not hallucinated):\n` +
-    `  nsauditor-ai mcp verify-call ${callId}`
+    `To check that this exact response came from this server, save the whole response (footer included)\n` +
+    `to a file and run:\n` +
+    `  nsauditor-ai mcp verify-call ${callId} --response <file>`
   );
 }
 
@@ -244,7 +255,23 @@ export const TOOLS = [
   {
     name: 'scan_host',
     description:
-      'Run a full plugin scan on a target host and return structured results including service detection, OS fingerprinting, and security findings.',
+      'Run a full plugin scan on a target host and return structured results: service detection, OS fingerprinting, and'
+      + ' the flags the service checks leave on each service record — weak SSH algorithms, SNMP default community, weak '
+      + 'TLS protocols / ciphers and a self-signed certificate, the MCP server checks, and anonymous FTP login and DNS '
+      + 'zone transfer only when the server\'s environment enables them (FTP_CHECK_ANON; DNS_CHECK_AXFR with '
+      + 'DNS_AXFR_DOMAIN — both off by default). The records also carry the HTTP probe\'s methods (006, dangerousMethods; '
+      + 'methodsTested false is not tested, never "none"), the NetBIOS/SMB null-session check (014, nullSessionAllowed; '
+      + 'opt-in, SMB_NULL_SESSION) and the TLS-certificate (040, certAudit) and debug-endpoint (050, tribeHealth) audits. For a domain-name target the DNS-security audit (060, dnsSecurity) lands '
+      + 'on a 53/udp record if the scan found one, else in the conclusion\'s evidence; an IP-address target is DECLINED '
+      + '(manifest: skipped, with the reason; markdown: NOT TESTED), so DNS posture is unknown, not clean. Opt-in checks carry '
+      + 'axfrTested / anonymousLoginTested / nullSessionTested; a null result is NOT TESTED, never "refused". Enterprise\'s '
+      + 'zero-trust assessment (1023) reaches the conclusion only as one score line in its evidence, not its '
+      + 'per-dimension findings. It does NOT look up '
+      + 'CVEs and does NOT run the Enterprise analysis agents or exploit intelligence — so zero findings here is NOT a '
+      + 'statement that the host has no known vulnerabilities. For CVEs, call get_vulnerabilities (Pro) with each '
+      + 'service\'s cpe where it names a concrete version; a service whose cpe is null gets no lookup, so its CVE coverage'
+      + ' is unknown, not clean. The CLI scan (Enterprise package, Pro or Enterprise licence) runs the CVE mapper, the '
+      + 'analysis agents and, with a KEV / EPSS store, exploit intelligence.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -335,7 +362,7 @@ export const TOOLS = [
         },
         pluginName: {
           type: 'string',
-          description: 'Plugin name or ID to run (e.g. "ssh_scanner" or "002")',
+          description: 'Plugin ID (e.g. "002") or its full name as list_plugins returns it, in any case (e.g. "SSH Scanner")',
         },
       },
       required: ['host', 'port', 'pluginName'],
@@ -379,38 +406,48 @@ export const TOOLS = [
 
 /**
  * Validate host to prevent SSRF via loopback, link-local, or cloud metadata.
- * Performs DNS resolution to defeat rebinding / encoded-IP bypasses.
+ *
+ * A literal is classified by VALUE in any spelling (net_validation.classifyAddress); a name is
+ * resolved and EVERY answer is classified — in both arms of NSA_ALLOW_ALL_HOSTS. Allow-all admits
+ * private ranges only: loopback, unspecified, link-local and metadata stay refused, by literal or
+ * by answer. A name that does not resolve is refused in both arms.
+ *
+ * ⚠️ LIMIT (stated, 1.3.0): this does NOT pin the resolved address. It returns the NAME, and each
+ * plugin resolves it again when it connects, so a name whose answer changes between this check
+ * and the scan (DNS rebinding) is not caught. Pinning is boarded for a later release; it is not in 1.3.0.
+ * Before 1.3.0 this comment said the resolution "defeats rebinding"; it never did.
  * @param {string} host
  * @returns {Promise<string>} normalised hostname
  */
 export async function validateHost(host) {
   const h = String(host).trim().toLowerCase();
   if (!h) throw new Error('Empty host');
-  // Fast-path: reject decimal-encoded loopback IPs (127.0.0.0/8).
-  // Other private/link-local ranges (RFC 1918, 169.254.x.x) are caught by the regex below
-  // and by the DNS resolveAndValidate() layer for all encoding forms.
+  const notAllowed = () => new Error('Scanning loopback, link-local, or metadata addresses is not allowed via MCP');
+  // Cheap pre-check for the obvious spellings; the classifier below is the authority.
   const _isAllDigits = /^\d+$/.test(h);
   const _n = _isAllDigits && h.length <= 10 ? Number(h) : -1;
   const isDecimalLoopback = _n >= 0x7F000000 && _n <= 0x7FFFFFFF;
   if (isDecimalLoopback || /^(localhost|127\.|0\.|::1|0\.0\.0\.0|169\.254\.|fe80:|metadata\.google)/i.test(h)) {
-    throw new Error('Scanning loopback, link-local, or metadata addresses is not allowed via MCP');
+    throw notAllowed();
   }
 
   // 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).
+  // They are never resolved (dns.lookup('aws') would be ENOTFOUND).
   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) {
-    try {
-      await resolveAndValidate(h);
-    } catch (err) {
-      throw new Error('Scanning loopback, link-local, or metadata addresses is not allowed via MCP');
-    }
+  // NSA_ALLOW_ALL_HOSTS (1/true/yes/on only) admits PRIVATE ranges for local-network auditing.
+  const allowPrivate = allowAllHosts();
+  const cls = classifyAddress(h);
+  if (cls === 'always' || (cls === 'private' && !allowPrivate)) throw notAllowed();
+  if (canonicalIp(h)) return h;   // a permitted literal — nothing to resolve
+
+  try {
+    await resolveAndValidate(h, { allowPrivate });
+  } catch (err) {
+    if (/blocked/.test(String(err && err.message))) throw notAllowed();
+    throw new Error(`Host could not be resolved via MCP: ${h}`);
   }
   return h;
 }
@@ -456,6 +493,8 @@ export async function handleScanHost(args) {
         host: output.host,
         conclusion: output.conclusion,
         toolVersion: TOOL_VERSION,
+        // Build 4 (Gate 3-A F-1): the manifest, so an audit that did not run — 060's decline of an IP address — is said.
+        manifest: output.manifest ?? [],
       });
     }
   } catch { /* swallow — markdown is best-effort */ }
@@ -464,7 +503,9 @@ export async function handleScanHost(args) {
     host: output.host,
     conclusion: output.conclusion ?? null,
     manifest: output.manifest ?? [],
-    pluginsRan: output.results?.length ?? 0,
+    // Plugins that RAN, from the manifest — not output.results, which holds one wrapped run per port plus
+    // error / timeout / gate-skip envelopes. Same count scan_cloud reports.
+    pluginsRan: (output.manifest || []).filter((m) => m.status === 'ran').length,
     markdown,
   };
 }
@@ -657,7 +698,7 @@ export async function handleProbeService(args) {
     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}".`,
+      `'${s}' cloud sentinel. Use a network host or IP address, or a cloud auditor with host: "${s}".`,
     );
   }
   const hostKind = isCloudSentinelHost(host) ? `cloud:${String(host).trim().toLowerCase()}` : 'network';
@@ -862,10 +903,9 @@ export function createServer() {
       };
     }
 
-    // CE 0.1.36 (Thread L Phase 2): mint a per-call sentinel UUID and
-    // log it BEFORE the Pro-gate so even denials prove the call hit
-    // the server. Fabricated responses cannot include a UUID that
-    // exists in the customer's local log file.
+    // CE 0.1.36 (Thread L Phase 2): mint a per-call UUID and log it BEFORE the Pro-gate, so even a denial shows the
+    // call hit the server. The id alone does NOT authenticate a response — a fabricated response can carry a real id
+    // copied from an earlier one — so the receipt also logs a digest of the body (appendCallSentinel, 1.3.0 (s6)).
     const callId = await recordToolCall(name);
 
     // Gate Pro-tier tools at the MCP dispatch layer

package/package.json

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

package/plugin_manager.mjs

@@ -274,6 +274,16 @@ async function callPlugin(mod, host, ctx, priorOutputs = null, cliOpts = {}) {
   });
 }
 
+// A UDP row opens its port only when it ANSWERED (1.3.0, B6-4c). The row's own `status` decides when it carries one (the
+// port scanner's 'open' / 'no-response'); otherwise only POSITIVE text counts, never a negative that CONTAINS a positive
+// phrase: "No UDP response" matched `udp response` and "No SNMP response for community …" matched `snmp response`, so a
+// plugin gated on `udp_open` read 'ran' over a silent port.
+const UDP_NEGATIVE = /^no\b|no response|\berror\b/;
+function udpRowAnswered(d, info) {
+  if (d?.status != null) return String(d.status).toLowerCase() === "open";
+  return !UDP_NEGATIVE.test(info) && /udp response|snmp response|sysdescr|pdu/.test(info);
+}
+
 // Heuristics to update context from any plugin's result
 function updateContextFromResult(mod, result, ctx) {
   try {
@@ -336,9 +346,9 @@ function updateContextFromResult(mod, result, ctx) {
         }
       }
 
-      // UDP hints (rare)
+      // UDP hints (rare) — only a row that ANSWERED opens its port (B6-4c, `udpRowAnswered`).
       if (proto === "udp" && Number.isFinite(port)) {
-        if (/udp response|snmp response|sysdescr|pdu/.test(info)) {
+        if (udpRowAnswered(d, info)) {
           ctx.udpOpen.add(port);
         }
       }
@@ -373,7 +383,8 @@ function updateContextFromResult(mod, result, ctx) {
     }
     if (id === "007" || name.includes("snmp")) {
       const first = rows[0];
-      if (/snmp response/.test(safeLower(first?.probe_info || "")) && Number.isFinite(first?.probe_port)) {
+      const firstInfo = safeLower(first?.probe_info || "");
+      if (udpRowAnswered(first, firstInfo) && /snmp response/.test(firstInfo) && Number.isFinite(first?.probe_port)) {
         ctx.udpOpen.add(Number(first.probe_port));
       }
     }
@@ -390,7 +401,8 @@ function updateContextFromResult(mod, result, ctx) {
  */
 export function describeSkipReason(mod, ctx) {
   const req = mod?.requirements || {};
-  if (req.host === 'up' && !ctx.hostUp) return 'host not up';
+  // No probe answered, which is no evidence either way — never "down" (1.3.0 lane 1 F).
+  if (req.host === 'up' && !ctx.hostUp) return 'no evidence the host is up';
   if (req.host === 'down' && ctx.hostUp) return 'host is up (requires down)';
   if (Array.isArray(req.tcp_open) && req.tcp_open.length) {
     const missing = req.tcp_open.filter(p => !ctx.tcpOpen.has(p));
@@ -690,6 +702,30 @@ export class PluginManager {
     return mergeResultObjects(plugin, filtered);
   }
 
+  /**
+   * The adapter registry handed to the concluder, by plugin ID (1.3.0): every loaded plugin's `conclude` — named or on
+   * its default object, as discovery attaches it — with its authoritativePorts and cloudProvider. Ids are a
+   * correctness key here, so a built-in wins: CE over EE over a custom NSAUDITOR_PLUGIN_PATH plugin that reuses an id
+   * (which would otherwise capture that plugin's records).
+   */
+  _concluderAdapters() {
+    const RANK = { ce: 0, ee: 1, custom: 2 };
+    const map = new Map();
+    for (const p of this.plugins || []) {
+      if (isConcluder(p) || typeof p?.conclude !== 'function') continue;
+      const id = String(p.id);
+      const rank = RANK[p._source] ?? 1;
+      const prev = map.get(id);
+      if (prev && prev.rank <= rank) {
+        if (prev.rank < rank) vlog(`plugin id ${id} from ${p._source} ignored for the concluder: a ${prev.source} plugin owns it`);
+        continue;
+      }
+      map.set(id, { rank, source: p._source ?? null, name: p.name ?? null, conclude: p.conclude.bind(p),
+        authoritativePorts: p.authoritativePorts ?? null, cloudProvider: p.cloudProvider ?? null });
+    }
+    return map;
+  }
+
   async runConcluder(resultsArray) {
     const concluder =
       this.plugins.find((p) => p.id === "008") ||
@@ -702,16 +738,17 @@ export class PluginManager {
     }
 
     try {
+      const adapters = this._concluderAdapters();
       // Support both signatures:
-      //  1) run(pluginResults)
-      //  2) run(host, port, { results })
+      //  1) run(pluginResults, { adapters })
+      //  2) run(host, port, { results, adapters })
       let conclusion;
       if (concluder.run.length >= 3) {
         vlog("Running Result Concluder with plugin results (opts.results signature):", JSON.stringify(resultsArray, null, 2));
-        conclusion = await concluder.run(null, 0, { results: resultsArray, context: withBaseContext({}) });
+        conclusion = await concluder.run(null, 0, { results: resultsArray, context: withBaseContext({}), adapters });
       } else {
         vlog("Running Result Concluder with plugin results (single-arg signature):", JSON.stringify(resultsArray, null, 2));
-        conclusion = await concluder.run(resultsArray);
+        conclusion = await concluder.run(resultsArray, { adapters });
       }
 
       vlog("Result Concluder raw output:", JSON.stringify(conclusion, null, 2));
@@ -795,6 +832,9 @@ export class PluginManager {
           reason: describeSkipReason(mod, ctx),
           duration_ms: 0,
         });
+        // Requested and NOT measured: the same three-state map the run path writes below, so a
+        // late consumer cannot read a gated-out upstream as one nobody requested (D26-3).
+        ctx.pluginRunStatus.set(String(mod.id || ''), 'skipped');
         continue;
       }
 
@@ -807,6 +847,7 @@ export class PluginManager {
           reason: `missing capabilities: ${(mod.requiredCapabilities || []).join(',')}`,
           duration_ms: 0,
         });
+        ctx.pluginRunStatus.set(String(mod.id || ''), 'skipped');
         continue;
       }