nsauditor-ai 0.2.56 → 0.2.57

package/plugins/port_scanner.mjs

@@ -8,6 +8,7 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { mapLimit } from "../utils/concurrency.mjs";
+import { parsePortsSpec, uniqInts } from "../utils/ports_spec.mjs";
 
 /* ------------------------------ helpers ------------------------------ */
 
@@ -16,48 +17,9 @@ const toInt = (v, d) => {
   return Number.isFinite(n) && n >= 0 ? n : d;
 };
 
-function uniqInts(arr = []) {
-  return [...new Set((arr || []).map((x) => Number(x)).filter(Number.isFinite))];
-}
-
-/**
- * Parse a CLI-style ports spec string into TCP/UDP port arrays.
- *
- * Accepted formats (entries comma-separated, whitespace tolerated):
- *   "8090"                   → { tcp: [8090],          udp: [] }
- *   "8090,9090"              → { tcp: [8090, 9090],    udp: [] }
- *   "8090/tcp"               → { tcp: [8090],          udp: [] }
- *   "8090/udp"               → { tcp: [],              udp: [8090] }
- *   "8090,9090/udp"          → { tcp: [8090],          udp: [9090] }
- *   "8090/tcp,9090/udp"      → { tcp: [8090],          udp: [9090] }
- *
- * Default protocol when not specified: TCP.
- *
- * Malformed entries (non-numeric, out-of-range 1–65535, empty, unknown
- * protocol suffix) are silently skipped — defensive for sloppy CLI input.
- *
- * @param {string} spec
- * @returns {{ tcp: number[], udp: number[] }}
- */
-export function parsePortsSpec(spec) {
-  const out = { tcp: [], udp: [] };
-  if (typeof spec !== 'string') return out;
-  const entries = spec.split(',').map(s => s.trim()).filter(Boolean);
-  for (const entry of entries) {
-    // Reject entries with more than one '/' separator (e.g. "8090/tcp/extra")
-    const parts = entry.split('/');
-    if (parts.length > 2) continue;
-    const portStr = parts[0];
-    const proto   = (parts[1] || 'tcp').toLowerCase();
-    if (proto !== 'tcp' && proto !== 'udp') continue;
-    const port = Number(portStr);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) continue;
-    out[proto].push(port);
-  }
-  out.tcp = uniqInts(out.tcp);
-  out.udp = uniqInts(out.udp);
-  return out;
-}
+// parsePortsSpec lives in utils/ports_spec.mjs (1.3.0 item 12: the webapp detector parses --ports the same way) and is
+// re-exported here, where the CLI flag's tests and the build-5 text leg import it.
+export { parsePortsSpec };
 
 /**
  * ⚠️ THE PACKAGE'S OWN DATA IS FOUND RELATIVE TO THE PACKAGE, NOT TO THE CALLER.
@@ -122,9 +84,14 @@ async function readPortSet(fp) {
  * purpose must not silently get the full set back.
  */
 export async function loadConfigPortsFromServicesJson(cwd = process.cwd(), pkgRoot = PKG_ROOT) {
-  const override = await readPortSet(path.join(cwd, "config", "services.json"));
+  const overridePath = path.join(cwd, "config", "services.json");
+  const override = await readPortSet(overridePath);
   if (override.tcp.length || override.udp.length) return { ...override, source: "override" };
-  return { ...(await readPortSet(path.join(pkgRoot, "config", "services.json"))), source: "package" };
+  const floor = { ...(await readPortSet(path.join(pkgRoot, "config", "services.json"))), source: "package" };
+  // B6-4j (1.3.0): a cwd file that EXISTS and yields nothing is ignored OUT LOUD (run() warns), named by its RELATIVE path —
+  // the working directory's absolute path is the operator's layout, which does not travel in a log.
+  const present = await fsp.access(overridePath).then(() => true, () => false);
+  return present ? { ...floor, overrideIgnored: path.join("config", "services.json") } : floor;
 }
 
 function classifyTcpError(err) {
@@ -249,7 +216,12 @@ export default {
   priority: 30,
   protocols: ["tcp", "udp"],
   ports: [],
-  requirements: { host: "up" },
+  // 1.3.0 lane 1 F, ruling (ii): NOT gated on `host: "up"`. The port scan is the measurement that
+  // decides liveness, so it does not wait for a liveness guess: with no discovery evidence it still
+  // runs, and its own `up` (a port answered) opens every `host: "up"` gate downstream. Gated, a host
+  // that drops ping and the common ports lost its port scan and read "Host appears DOWN" over an
+  // open uncommon port (driven through the CLI: `003 skipped "host not up"`).
+  requirements: {},
 
   // run(host, _portIgnored, opts)
   async run(host, _port = 0, opts = {}) {
@@ -287,6 +259,10 @@ export default {
           + `the surface cannot be measured, not that nothing is listening. Check that the file is `
           + `readable (it ships mode 0644), or pass the ports explicitly.`);
       }
+      if (cfg.overrideIgnored) {
+        console.warn(`[port_scanner] WARNING: ${cfg.overrideIgnored} in the working directory yields no ports — it lists none in `
+          + `the forms read here (a "services" array, or "tcp" / "udp" arrays) — so the package's default port set is scanned instead.`);
+      }
     }
 
     // Additive merge of CLI --ports flag (string spec)
@@ -334,12 +310,16 @@ export default {
     const udpClosed     = data.filter(d => d.probe_protocol === "udp" && d.status === "closed").map(d => d.probe_port); // typically empty
     const udpNoResponse = data.filter(d => d.probe_protocol === "udp" && d.status === "no-response").map(d => d.probe_port);
 
-    // Consider host "up" if we saw any TCP evidence (open/closed/filtered) OR any UDP open.
-    const anyTcpEvidence = tcpOpen.length > 0 || tcpClosed.length > 0 || tcpFiltered.length > 0;
-    const anyUdpOpen     = udpOpen.length > 0;
+    // `up` means a port answered — open or refused; a timeout, an unreachable or a socket error is
+    // not an answer. (1.3.0 lane 1 F: 'filtered' — every timeout, EHOSTUNREACH, ENETUNREACH and other
+    // socket error, classifyTcpError — used to count too, so a host that answered nothing read UP from
+    // its own timeouts; driven against a silent 127.0.0.2: `up: true, tcpFiltered: [22, 8443]`.
+    // Ungated, that would read every silent host UP and open every downstream gate.)
+    const anyTcpAnswer = tcpOpen.length > 0 || tcpClosed.length > 0;
+    const anyUdpOpen   = udpOpen.length > 0;
 
     return {
-      up: anyTcpEvidence || anyUdpOpen,
+      up: anyTcpAnswer || anyUdpOpen,
       program: "Unknown",
       version: "Unknown",
       os: null,

package/plugins/result_concluder.mjs

@@ -1,4 +1,7 @@
 // plugins/result_concluder.mjs — plug-and-play dispatcher with full metadata and evidence
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { normalizeService, upsertService, keyOf } from '../utils/conclusion_utils.mjs';
 
 function pickResultsFromArgs(args) {
@@ -8,15 +11,79 @@ function pickResultsFromArgs(args) {
   return [];
 }
 
-// Stable slug from plugin name, falling back to IDs. Exported so tests/concluder_drops_honesty.test.mjs derives the
-// adapter census with THIS rule rather than a copy of it.
-export function slugify(name, id) {
-  const base = String(name || '').toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
-  if (base) return base;
-  const map = { '001':'ping_checker','002':'ssh_scanner','003':'port_scanner','004':'ftp_banner_check','005':'host_up_check','006':'http_probe','007':'snmp_scanner','009':'dns_scanner','010':'webapp_detector','011':'tls_scanner','012':'opensearch_scanner','013':'os_detector','014':'netbios__smb_scanner','015':'sunrpc_scanner','024':'syn_scanner','025':'db_scanner','026':'arp_scanner','027':'mdns_scanner','028':'upnp_scanner' };
-  return map[String(id)] || String(id);
+// The second argument (or opts.adapters in the (host, port, { results }) form) may carry the PluginManager's adapter
+// registry: a Map (or plain object) from plugin id to { conclude, authoritativePorts, cloudProvider }.
+function pickOptsFromArgs(args) {
+  if (Array.isArray(args[0]) && args[1] && typeof args[1] === 'object') return args[1];
+  if (args.length >= 3 && args[2] && typeof args[2] === 'object') return args[2];
+  if (args.length === 1 && args[0] && typeof args[0] === 'object' && !Array.isArray(args[0])) return args[0];
+  return {};
 }
 
+// A plugin name as a label — the default `source` of an adapter record that names none. It no longer RESOLVES
+// anything: until 1.3.0 the concluder imported `./<this slug>.mjs` and read only a named `conclude`, so 014 and 024
+// (slug ≠ file name) and 040 / 050 / 060 (conclude on the default object) were never reached.
+function nameSlug(name) {
+  return String(name || 'plugin').toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'plugin';
+}
+
+/** One adapter-registry entry from a plugin module: `conclude` named or on the default object, by plugin ID. */
+function adapterEntry(mod) {
+  const p = mod?.default;
+  if (!p || typeof p !== 'object' || p.id == null) return null;
+  const conclude = typeof mod.conclude === 'function' ? mod.conclude
+    : (typeof p.conclude === 'function' ? p.conclude.bind(p) : null);
+  return {
+    id: String(p.id),
+    name: typeof p.name === 'string' ? p.name : null,
+    conclude,
+    authoritativePorts: mod.authoritativePorts ?? p.authoritativePorts ?? null,
+    cloudProvider: p.cloudProvider ?? null,
+  };
+}
+
+// The concluder's own directory as a registry, built once — used for any id the caller's registry does not carry
+// (a direct concluder.run, or a test manager with injected plugins).
+const SELF = fileURLToPath(import.meta.url);
+let ownRegistry = null;
+function ownDirectoryAdapters() {
+  ownRegistry ??= (async () => {
+    const map = new Map();
+    let names = [];
+    try { names = (await readdir(path.dirname(SELF))).filter((f) => f.endsWith('.mjs')).sort(); } catch { return map; }
+    for (const f of names) {
+      if (f === path.basename(SELF)) continue;
+      try {
+        const e = adapterEntry(await import(pathToFileURL(path.join(path.dirname(SELF), f)).href));
+        if (e && !map.has(e.id)) map.set(e.id, e);
+      } catch { /* a plugin that fails to load has no adapter here */ }
+    }
+    return map;
+  })();
+  return ownRegistry;
+}
+
+function toRegistry(adapters) {
+  if (adapters instanceof Map) return adapters;
+  if (adapters && typeof adapters === 'object') return new Map(Object.entries(adapters));
+  return new Map();
+}
+
+// A result with NO id (some callers pass names only) resolves by the plugin's DECLARED name — never by a file name
+// derived from it, which is what left 014 / 024 unreached.
+function byDeclaredName(registry) {
+  const out = new Map();
+  for (const e of registry.values()) {
+    const n = typeof e?.name === 'string' ? e.name.trim().toLowerCase() : '';
+    if (n && !out.has(n)) out.set(n, e);
+  }
+  return out;
+}
+
+// Adapter payloads that travel under a namespace. A record without a positive port is evidence, not a service row,
+// and these ride along onto its evidence entry so moving it there loses nothing.
+export const ADAPTER_PAYLOAD_KEYS = ['certAudit', 'tribeHealth', 'dnsSecurity'];
+
 function scoreOsLabel(label) {
   const s = String(label||'').toLowerCase();
   if (!s || s === 'unknown') return 0;
@@ -134,6 +201,9 @@ export default {
 
   async run(...args) {
     const results = pickResultsFromArgs(args);
+    const supplied = toRegistry(pickOptsFromArgs(args).adapters);
+    const own = await ownDirectoryAdapters();
+    const pendingAttach = [];
     const services = [];
     const evidence = [];
     let os = null;
@@ -163,8 +233,8 @@ export default {
 
     for (const r of results) {
       const name = r?.name || r?.id || 'plugin';
-      const slug = slugify(name, r?.id);
-      const modPath = `./${slug}.mjs`;
+      const id = String(r?.id ?? '');
+      const slug = nameSlug(name);
 
       // Prefer OS and osVersion provided by plugins, but pick the most specific; OS Detector wins ties
       if (r?.result?.os) {
@@ -174,33 +244,43 @@ export default {
         osSource = picked.source;
       }
 
-      // Extract host name from UPnP Scanner if available
-      if (slug === 'upnp_scanner') {
+      // Host names by plugin ID (they keyed on a name slug, and the UPnP one never matched: the plugin is named
+      // "Enhanced UPnP Scanner").
+      if (id === '028') {
         hostName = extractHostNameFromUpnp(r?.result) || hostName;
       }
-
-      // Extract host name from mDNS Scanner if available
-      if (slug === 'mdns_scanner') {
+      if (id === '027') {
         hostName = extractHostNameFromMdns(r?.result) || hostName;
       }
 
-      let recs = null;
-      try {
-        const mod = await import(modPath);
-        if (typeof mod.conclude === 'function') {
-          recs = await mod.conclude({ host: typeof args[0] === 'string' ? args[0] : undefined, result: r?.result });
-          const authSet = mod?.authoritativePorts instanceof Set ? mod.authoritativePorts : null;
-          for (const item of (recs || [])) {
-            const rec = normalizeService({ ...item, source: item.source || slug });
-            const key = keyOf(rec);
-            const authoritative = (authSet && authSet.has(key)) || !!item.authoritative;
-            upsertService(services, rec, { authoritative });
+      // Resolve the adapter by ID: the caller's registry first, then this directory. A cloudProvider plugin is
+      // EXEMPT — its findings travel raw (cloud_finding_summary / harvestCloudFindings), and through a service-record
+      // adapter they carry no port and collapse into one fabricated row.
+      const entry = id
+        ? (supplied.get(id) ?? own.get(id))
+        : (byDeclaredName(supplied).get(String(name).trim().toLowerCase())
+          ?? byDeclaredName(own).get(String(name).trim().toLowerCase()));
+      if (entry && typeof entry.conclude === 'function' && !entry.cloudProvider) {
+        let recs = null;
+        try {
+          recs = await entry.conclude({ host: typeof args[0] === 'string' ? args[0] : undefined, result: r?.result });
+        } catch {
+          recs = null; // an adapter that throws falls through to the fallback record, as before
+        }
+        if (recs) {
+          const authSet = entry.authoritativePorts instanceof Set ? entry.authoritativePorts : null;
+          for (const item of recs) {
+            const { attachOnly, ...rest } = item || {};
+            const rec = normalizeService({ ...rest, source: rest.source || slug });
+            const authoritative = (authSet && authSet.has(keyOf(rec))) || !!rest.authoritative;
+            // An attach-only record (060's domain DNS-posture audit) lands only on a service a port-level probe
+            // found; decided after every result is in, so result order does not matter.
+            if (attachOnly) pendingAttach.push(rec);
+            else upsertService(services, rec, { authoritative });
           }
           if (r?.result?.data) pushEvidence(name, r.result.data);
           continue;
         }
-      } catch {
-        // no adapter -> fall through
       }
       for (const item of fallbackRecord(name, r?.result)) {
         upsertService(services, normalizeService(item), { authoritative: false });
@@ -208,6 +288,12 @@ export default {
       if (r?.result?.data) pushEvidence(name, r.result.data);
     }
 
+    const unattached = [];
+    for (const rec of pendingAttach) {
+      if (services.some((s) => keyOf(s) === keyOf(rec))) upsertService(services, rec, { authoritative: false });
+      else unattached.push(rec);
+    }
+
     for (const svc of services) delete svc.__authoritative;
 
     services.sort((a,b)=> (a.port - b.port) || String(a.protocol).localeCompare(String(b.protocol)) );
@@ -216,24 +302,28 @@ export default {
     const META_PROTOCOLS = new Set(['assessment', 'icmp', 'os-detector', 'arp']);
     const PORT_ZERO_META_PROTOCOLS = new Set(['api', 'tcp', 'udp']);
     const isMetaEntry = (s) => {
+      // A service has a port. A record without a positive integer one (no port at all keys to `<proto>:NaN`) is
+      // evidence — 040's "no TLS found", 060's per-domain findings — never a service row with port null.
+      if (!(Number.isInteger(s.port) && s.port > 0)) return true;
       if (META_PROTOCOLS.has(s.protocol)) return true;
       if (s.port === 0 && PORT_ZERO_META_PROTOCOLS.has(s.protocol)) return true;
       if (s.info && /Skipped:/i.test(String(s.info))) return true;
       return false;
     };
 
-    const metaEntries = services.filter(isMetaEntry);
+    const metaEntries = services.filter(isMetaEntry).concat(unattached);
     const realServices = services.filter(s => !isMetaEntry(s));
 
-    // Move meta entries into evidence only
+    // Move meta entries into evidence only — with any namespaced adapter payload, so nothing is lost on the way
     for (const m of metaEntries) {
       evidence.push({
         from: m.source || 'meta',
         protocol: m.protocol,
-        port: m.port,
+        port: Number.isFinite(m.port) ? m.port : null,
         status: m.status,
         info: m.info,
         ...(m.banner ? { banner: m.banner } : {}),
+        ...Object.fromEntries(ADAPTER_PAYLOAD_KEYS.filter((k) => m[k] != null).map((k) => [k, m[k]])),
       });
     }
 
@@ -252,7 +342,8 @@ export default {
     const hostUp = results.some(r => r?.result?.up === true) || services.some(s => s.status === 'open');
     const open = services.filter(s => s.status === 'open');
     const parts = [];
-    parts.push(hostUp ? `Host${hostName ? ` (${hostName})` : ''} is UP` : 'Host appears DOWN');
+    // Not UP means no probe got an answer — no evidence either way, never "DOWN" (1.3.0 lane 1 F).
+    parts.push(hostUp ? `Host${hostName ? ` (${hostName})` : ''} is UP` : 'No evidence the host is up');
     if (os) parts.push(`OS: ${os}`);
     if (osVersion) parts.push(`Version: ${osVersion}`);
     if (open.length) {

package/plugins/snmp_scanner.mjs

@@ -4,6 +4,10 @@
 // Returns { up: boolean, program: string, version: string, os: string|null, type: string, data: [{ probe_protocol, probe_port, probe_info, response_banner }], serialNumber: string, hardwareVersion: string, firmwareVersion: string, ip6: string|null, deviceWebPage: string|null, deviceWebPageInstruction: string }.
 
 export const DEFAULT_COMMUNITIES = ['public', 'private'];
+// ⚠️ A COMMUNITY STRING THE OPERATOR SUPPLIED (SNMP_COMMUNITY) IS A CREDENTIAL — it authenticates to their devices — so
+// it is never written into a result, a record or an evidence row. Only a DEFAULT community is recorded by name, because
+// a default community answering IS the finding; any other string is recorded as the word 'custom'.
+export const communityLabel = (comm) => (DEFAULT_COMMUNITIES.includes(comm) ? comm : 'custom');
 export const snmpCommunities = process.env.SNMP_COMMUNITY
   ? String(process.env.SNMP_COMMUNITY).split(',').map(s => s.trim()).filter(Boolean)
   : DEFAULT_COMMUNITIES;
@@ -124,6 +128,7 @@ export default {
     let deviceWebPageInstruction = '';
     let deviceFullName = null;
     let community = null;
+    let communityCustom = false; // a custom (operator-supplied) string ANSWERED — not a finding, and not "not tested"
     const communitiesTried = [];
     const data = [];
 
@@ -137,7 +142,7 @@ export default {
       const useOid = options.oid ? options.oid.split('.').map(Number) : oidTable.default;
 
       for (const comm of snmpCommunities) {
-        communitiesTried.push(comm);
+        communitiesTried.push(communityLabel(comm));
         const s = new Session({ host, community: comm, timeouts: [5000] });
 
         try {
@@ -157,7 +162,7 @@ export default {
           const val = String(vbs?.[0]?.value || '');
           if (val) {
             up = true;
-            community = comm;
+            if (DEFAULT_COMMUNITIES.includes(comm)) community = comm; else communityCustom = true;
             const parsed = fromSysDescr(val);
             program = parsed.family || 'Unknown';
             version = parsed.version || 'Unknown';
@@ -168,7 +173,7 @@ export default {
             else if (/microsoft|windows|linux|unix/i.test(program)) type = 'server';
 
             let probeInfo = `SNMP response received: ${program} ${version}${os ? ` (OS: ${os})` : ''} (Type: ${type})`;
-            if (comm === 'public' || comm === 'private') {
+            if (DEFAULT_COMMUNITIES.includes(comm)) {
               probeInfo += ` WARNING: Default SNMP community string '${comm}' accepted — misconfiguration`;
             }
 
@@ -220,7 +225,7 @@ export default {
             if (hardwareVersion) infoPieces.push(`HW Ver: ${hardwareVersion}`);
             if (firmwareVersion) infoPieces.push(`FW Ver: ${firmwareVersion}`);
             infoPieces.push(')');
-            if (comm === 'public' || comm === 'private') {
+            if (DEFAULT_COMMUNITIES.includes(comm)) {
               infoPieces.push(` WARNING: Default SNMP community string '${comm}' accepted — misconfiguration`);
             }
             data[0].probe_info = infoPieces.join(', ');
@@ -240,7 +245,7 @@ export default {
             data.push({
               probe_protocol: 'udp',
               probe_port: 161,
-              probe_info: `No SNMP response for community "${comm}"`,
+              probe_info: `No SNMP response for community "${communityLabel(comm)}"`,
               response_banner: null
             });
           }
@@ -257,7 +262,7 @@ export default {
       });
     }
 
-    return { up, program, version, os, type, serialNumber, hardwareVersion, firmwareVersion, ip6, deviceWebPage, deviceWebPageInstruction, community, communitiesTried, data };
+    return { up, program, version, os, type, serialNumber, hardwareVersion, firmwareVersion, ip6, deviceWebPage, deviceWebPageInstruction, community, communityCustom, communitiesTried, data };
   }
 };
 
@@ -265,14 +270,21 @@ export async function conclude({ host, result }) {
   const rows = Array.isArray(result?.data) ? result.data : [];
   const row = rows[0] || null;
   const isDefault = DEFAULT_COMMUNITIES.includes(result?.community);
-  const communityInfo = result?.community ? ` [community=${isDefault ? result.community : 'custom'}]` : '';
+  // A result written by an earlier release carries a custom string in `community`; the field is masked here as well.
+  // (Its evidence rows are carried as they were written — this adapter does not rewrite another release's evidence.)
+  const custom = result?.communityCustom === true || (result?.community != null && !isDefault);
+  const communityInfo = isDefault ? ` [community=${result.community}]` : custom ? ' [community=custom]' : '';
   return [{
     port: 161, protocol: 'udp', service: 'snmp',
     program: result?.program || 'Unknown', version: result?.version || 'Unknown',
     status: result?.up ? 'open' : 'no response',
     info: row?.probe_info ? `${row.probe_info}${communityInfo}` : communityInfo || null,
     banner: row?.response_banner ? `${row.response_banner}${communityInfo}` : null,
-    community: result?.community || null,
+    community: isDefault ? result.community : null,
+    ...(custom ? { communityCustom: true } : {}),
+    // 1.3.0 (s1) B: what was TRIED, as labels — a default community is MEASURED only where it was tried. Re-labelled here,
+    // so a raw result an earlier release wrote (which carried the strings themselves) never puts one on the record.
+    communitiesTried: Array.isArray(result?.communitiesTried) ? result.communitiesTried.map(communityLabel) : null,
     source: 'snmp', evidence: rows, authoritative: true
   }];
 }

package/plugins/syn_scanner.mjs

@@ -299,7 +299,8 @@ export async function conclude({ host, result }) {
       port,
       protocol: proto,
       service: r?.service || "unknown",
-      program: result?.program || "nmap",
+      // nmap is the tool that saw the port, not the program listening on it (1.3.0).
+      program: "Unknown",
       version: r?.response_banner || "Unknown",
       status,
       info: r?.probe_info || null,