nsauditor-ai 0.1.0

package/plugins/result_concluder.mjs

@@ -0,0 +1,274 @@
+// plugins/result_concluder.mjs — plug-and-play dispatcher with full metadata and evidence
+import { normalizeService, upsertService, keyOf } from '../utils/conclusion_utils.mjs';
+
+function pickResultsFromArgs(args) {
+  if (Array.isArray(args[0])) return args[0];
+  if (args.length >= 3 && args[2] && Array.isArray(args[2].results)) return args[2].results;
+  if (args.length === 1 && args[0] && Array.isArray(args[0].results)) return args[0].results;
+  return [];
+}
+
+// Stable slug from plugin name, falling back to IDs
+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);
+}
+
+function scoreOsLabel(label) {
+  const s = String(label||'').toLowerCase();
+  if (!s || s === 'unknown') return 0;
+  if (/red\s*hat|centos|rhel/.test(s)) return 120;
+  if (/ubuntu|debian/.test(s)) return 110;
+  if (/suse|opensuse|alpine/.test(s)) return 105;
+  if (/freebsd|openbsd|netbsd/.test(s)) return 104;
+  if (/solaris|aix|hp-ux/.test(s)) return 103;
+  if (/windows/.test(s)) return 100;
+  if (/macos|os\s*x|ios|apple/.test(s)) return 95;
+  if (/linux/.test(s)) return 20;
+  return 10;
+}
+
+function pickOs(currentOs, currentVersion, candidateOs, candidateVersion, source, curSource) {
+  if (!candidateOs || candidateOs === 'Unknown') return { os: currentOs, osVersion: currentVersion, source: curSource };
+  if (!currentOs || currentOs === 'Unknown') return { os: candidateOs, osVersion: candidateVersion, source };
+  const cScore = scoreOsLabel(currentOs);
+  const nScore = scoreOsLabel(candidateOs);
+  if (nScore > cScore) return { os: candidateOs, osVersion: candidateVersion, source };
+  if (nScore === cScore) {
+    if (String(candidateOs).length > String(currentOs).length) return { os: candidateOs, osVersion: candidateVersion, source };
+    const candIsDetector = /(^013$)|os\s*detector/i.test(String(source||''));
+    const curIsDetector  = /(^013$)|os\s*detector/i.test(String(curSource||''));
+    if (candIsDetector && !curIsDetector) return { os: candidateOs, osVersion: candidateVersion, source };
+  }
+  return { os: currentOs, osVersion: currentVersion, source: curSource };
+}
+
+// Generic fallback when a plugin provides no adapter
+function fallbackRecord(pluginName, result) {
+  const rows = Array.isArray(result?.data) ? result.data : [];
+  const row = rows.find(Boolean) || {};
+  const proto = row?.probe_protocol || result?.protocol || 'tcp';
+  const port = Number(row?.probe_port ?? (
+    /ftp/i.test(pluginName) ? 21 :
+    /ssh/i.test(pluginName) ? 22 :
+    /dns/i.test(pluginName) ? 53 :
+    /snmp/i.test(pluginName) ? 161 :
+    result?.port ?? 0
+  ));
+  let status = result?.up ? 'open' : 'unknown';
+
+  // Re-label ECONNREFUSED as closed (requested feature)
+  if (row?.probe_info && /refused|ECONNREFUSED/i.test(String(row.probe_info))) {
+    status = 'closed';
+  }
+
+  return [{
+    port, protocol: proto, service: (pluginName || 'unknown').toLowerCase().split(/\s+/)[0],
+    program: result?.program || 'Unknown', version: result?.version || 'Unknown',
+    status,
+    info: row?.probe_info || null, banner: row?.response_banner || null,
+    source: (pluginName || 'plugin').toLowerCase().split(/\s+/)[0],
+    evidence: rows
+  }];
+}
+
+function extractHostNameFromUpnp(result) {
+  const rows = Array.isArray(result?.data) ? result.data : [];
+  for (const row of rows) {
+    const banner = row?.response_banner;
+    if (banner) {
+      try {
+        const obj = JSON.parse(banner);
+        const xml = obj?.descriptionXML || '';
+        const match = xml.match(/<friendlyName>(.*?)<\/friendlyName>/);
+        if (match && match[1]) {
+          return match[1];
+        }
+      } catch {}
+    }
+  }
+  return null;
+}
+
+function extractHostNameFromMdns(result) {
+  const rows = Array.isArray(result?.data) ? result.data : [];
+  for (const row of rows) {
+    let name = null;
+    const banner = row?.response_banner;
+    if (banner) {
+      try {
+        const obj = JSON.parse(banner);
+        // 1. Prefer txt.fn (friendly name)
+        if (obj?.txt?.fn) return obj.txt.fn;
+        // 2. Fallback to txt.md (model description)
+        if (obj?.txt?.md) return obj.txt.md;
+        // 3. Fallback to name field in banner JSON
+        if (obj?.name) return obj.name;
+        // 4. Fallback to fullname
+        const fullname = obj?.fullname || '';
+        const nameMatch = fullname.match(/[^._]+/);
+        if (nameMatch && nameMatch[0]) return nameMatch[0];
+      } catch (e) {
+        // ignore JSON parse error
+      }
+    }
+    // 5. Always check probe_info for name="..." if not found above
+    if (row?.probe_info) {
+      const m = row.probe_info.match(/name="([^"]+)"/);
+      if (m && m[1]) return m[1];
+    }
+  }
+  return null;
+}
+
+export default {
+  id: "008",
+  name: "Result Concluder",
+  description: "Aggregates plugin results and produces a unified summary, host OS, and per-service findings.",
+  priority: 100000,
+  requirements: {},
+  runStrategy: "single",
+
+  async run(...args) {
+    const results = pickResultsFromArgs(args);
+    const services = [];
+    const evidence = [];
+    let os = null;
+    let osVersion = null;
+    let osSource = null;
+    let hostName = null;
+
+    const pushEvidence = (from, rows) => {
+      const max = Number(process.env.CONCLUDER_EVIDENCE_MAX || 200);
+      for (const d of (Array.isArray(rows) ? rows : [])) {
+        if (evidence.length >= max) break;
+        const piece = {
+          from: from || 'plugin',
+          protocol: d?.probe_protocol ?? null,
+          port: d?.probe_port ?? null,
+          status: d?.status ?? null,
+          info: d?.probe_info ?? null,
+        };
+        const banner = d?.response_banner;
+        if (banner) {
+          const s = String(banner);
+          piece.banner = s.length > 800 ? s.slice(0, 800) + '…' : s;
+        }
+        evidence.push(piece);
+      }
+    };
+
+    for (const r of results) {
+      const name = r?.name || r?.id || 'plugin';
+      const slug = slugify(name, r?.id);
+      const modPath = `./${slug}.mjs`;
+
+      // Prefer OS and osVersion provided by plugins, but pick the most specific; OS Detector wins ties
+      if (r?.result?.os) {
+        const picked = pickOs(os, osVersion, r.result.os, r.result.osVersion, String(r?.id || r?.name), osSource);
+        os = picked.os;
+        osVersion = picked.osVersion;
+        osSource = picked.source;
+      }
+
+      // Extract host name from UPnP Scanner if available
+      if (slug === 'upnp_scanner') {
+        hostName = extractHostNameFromUpnp(r?.result) || hostName;
+      }
+
+      // Extract host name from mDNS Scanner if available
+      if (slug === 'mdns_scanner') {
+        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 });
+          }
+          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 });
+      }
+      if (r?.result?.data) pushEvidence(name, r.result.data);
+    }
+
+    for (const svc of services) delete svc.__authoritative;
+
+    services.sort((a,b)=> (a.port - b.port) || String(a.protocol).localeCompare(String(b.protocol)) );
+
+    // Separate meta/non-service entries from real services
+    const META_PROTOCOLS = new Set(['assessment', 'icmp', 'os-detector', 'arp']);
+    const PORT_ZERO_META_PROTOCOLS = new Set(['api', 'tcp', 'udp']);
+    const isMetaEntry = (s) => {
+      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 realServices = services.filter(s => !isMetaEntry(s));
+
+    // Move meta entries into evidence only
+    for (const m of metaEntries) {
+      evidence.push({
+        from: m.source || 'meta',
+        protocol: m.protocol,
+        port: m.port,
+        status: m.status,
+        info: m.info,
+        ...(m.banner ? { banner: m.banner } : {}),
+      });
+    }
+
+    // Replace services array contents with real services only
+    services.length = 0;
+    services.push(...realServices);
+
+    if (!os) {
+      const banners = services.flatMap(s => [s.banner, s.info, s.program]).filter(Boolean).join(' ').toLowerCase();
+      if (/vsftpd|pure-?ftpd|bftpd/.test(banners)) os = 'Linux';
+      else if (/filezilla|windows/.test(banners)) os = 'Windows';
+      else if (/apple|macos|mac\s*os|os\s*x/.test(banners)) os = 'macOS';
+      else os = null;
+    }
+
+    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');
+    if (os) parts.push(`OS: ${os}`);
+    if (osVersion) parts.push(`Version: ${osVersion}`);
+    if (open.length) {
+      const top = open.slice(0, 3).map(s => `${s.service}/${s.port}`).join(', ');
+      const more = open.length > 3 ? ` (+${open.length - 3} more open)` : '';
+      parts.push(`Open: ${top}${more}`);
+    } else {
+      parts.push('No open services detected');
+    }
+
+    return {
+      summary: parts.join(' — '),
+      host: { up: hostUp, os, osVersion, name: hostName },
+      services,
+      evidence,
+      source_count: results.length,
+      os_source: osSource || null
+    };
+  }
+};

package/plugins/snmp_scanner.mjs

@@ -0,0 +1,278 @@
+// plugins/snmp_scanner.mjs
+// Plugin to probe SNMP (UDP port 161) to detect device types (e.g., printers, routers) via sysDescr OID.
+// Uses 'snmp-native' npm package, declared in dependencies.
+// 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'];
+export const snmpCommunities = process.env.SNMP_COMMUNITY
+  ? String(process.env.SNMP_COMMUNITY).split(',').map(s => s.trim()).filter(Boolean)
+  : DEFAULT_COMMUNITIES;
+const oidTable = {
+  default: [1, 3, 6, 1, 2, 1, 1, 1, 0], // sysDescr 
+  epsonShortName: [1, 3, 6, 1, 2, 1, 1, 5, 0], // sysDescr EPSON6768F4 '1.3.6.1.2.1.1.5.0'
+  epsonModel: [1, 3, 6, 1, 4, 1, 1248, 1, 1, 3, 1, 29, 3, 1, 45, 0], // Epson model OID
+  epsonSerial: [1, 3, 6, 1, 4, 1, 1248, 1, 2, 2, 1, 1, 1, 4, 1], // Epson serial number
+  epsonVersions: [1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 1], // Hardware and firmware versions
+  epsonIPv6: [1, 3, 6, 1, 4, 1, 1248, 1, 1, 3, 1, 4, 46, 1, 2, 2], // IPv6 address in URL
+  epsonName: [1, 3, 6, 1, 4, 1, 1248, 1, 1, 3, 1, 26, 2, 1, 3, 1], // Epson device full name
+  epsonVersion: [1, 3, 6, 1, 4, 1, 1248, 1, 1, 3, 1, 21, 1, 1, 2, 5], // Epson device version
+  epsonFirmware: null
+};
+
+/** Clamp helper: keep first N chars (used for Epson S/N = 10 chars) */
+const clampSerial = (sn, n = 10) => (sn && sn.length > n ? sn.slice(0, n) : sn);
+
+/**
+ * Parse an SNMP sysDescr for OS/family/version hints.
+ */
+function fromSysDescr(v) {
+  const s = (v || '').toLowerCase();
+
+  if (s.includes('epson')) {
+    return { family: 'Epson', os: 'Embedded Linux', version: '' };
+  }
+  if (s.includes('cisco')) {
+    const iosMatch = s.match(/version\s+([0-9.]+)/);
+    return { family: 'Cisco', os: 'Cisco IOS', version: iosMatch ? iosMatch[1] : '' };
+  }
+  if (s.includes('palo alto')) {
+    const paMatch = s.match(/pa-([0-9]+)/);
+    return { family: 'Palo Alto Networks', os: 'PAN-OS', version: paMatch ? paMatch[1] : '' };
+  }
+  if (s.includes('synology')) {
+    const modelMatch = s.match(/diskstation\s+([a-z0-9+]+)/);
+    return { family: 'Synology', os: 'DiskStation Manager (DSM)', version: modelMatch ? modelMatch[1] : '' };
+  }
+  if (s.includes('windows')) {
+    const versionMatch = s.match(/version\s+([0-9.]+)/);
+    return { family: 'Microsoft', os: 'Windows', version: versionMatch ? versionMatch[1] : '' };
+  }
+  if (s.includes('linux')) {
+    const versionMatch = s.match(/linux\s+.*?([0-9.]+\S*)/);
+    return { family: 'Linux', os: 'Linux/Unix', version: versionMatch ? versionMatch[1] : '' };
+  }
+  if (s.includes('unix')) {
+    return { family: 'Unix', os: 'Linux/Unix', version: '' };
+  }
+  return { family: null, os: null, version: '' };
+}
+
+/** Parse "EEPS2 Hard Ver.1.00 Firm Ver.0.23" */
+function parseVersions(versionString) {
+  const regex = /hard\s+ver\.(\d+\.\d+)\s+firm\s+ver\.(\d+\.\d+)/i;
+  const m = String(versionString || '').match(regex);
+  if (m && m.length === 3) {
+    return { hardwareVersion: m[1], firmwareVersion: m[2] };
+  }
+  return { hardwareVersion: null, firmwareVersion: null };
+}
+
+/**
+ * Extract a printer serial number from an SNMP VarBind.
+ */
+function parseSerialNumber(snmpResponse) {
+  let raw = '';
+  if (snmpResponse && Buffer.isBuffer(snmpResponse.valueRaw)) {
+    raw = snmpResponse.valueRaw.toString('latin1');
+  } else if (snmpResponse && typeof snmpResponse.value === 'string') {
+    raw = snmpResponse.value;
+  } else {
+    return { serialNumber: '' };
+  }
+
+  const asciiStr = raw.replace(/[^\x20-\x7E]/g, ' ').replace(/\s+/g, ' ').trim();
+
+  const BLOCKLIST = new Set([ 'UNKNOWN', 'BDC', 'ST2', 'HTTP', 'IPP', 'EPSON', 'ET', 'SERIES', 'PRINT', 'SERVER' ]);
+
+  const candidates = [];
+  const re = /\b([A-Z0-9]{10,14})\b/g;
+  for (const m of asciiStr.matchAll(re)) {
+    const tok = m[1];
+    if (BLOCKLIST.has(tok)) continue;
+    const letters = (tok.match(/[A-Z]/g) || []).length;
+    const digits  = (tok.match(/\d/g)  || []).length;
+    if (letters >= 2 && digits >= 2) {
+      candidates.push({ tok, idx: m.index });
+    }
+  }
+  if (!candidates.length) return { serialNumber: '' };
+  candidates.sort((a, b) => (b.tok.length - a.tok.length) || (b.idx - a.idx));
+  return { serialNumber: candidates[0].tok };
+}
+
+export default {
+  id: '007',
+  name: 'SNMP Scanner',
+  description: 'Probes SNMP (UDP 161) to detect device types via sysDescr and Epson OIDs.',
+  priority: 70,
+  requirements: { host: "up", udp_open: [161] },
+  protocols: ['udp'],
+  ports: [161],
+  dependencies: ['snmp-native'],
+  async run(host, port, opts = {}) {
+    const options = opts; // drop-in rename; SNMP always uses port 161 (UDP)
+    let up = false;
+    let program = 'Unknown';
+    let version = 'Unknown';
+    let os = null;
+    let type = 'unknown';
+    let serialNumber = '';
+    let hardwareVersion = '';
+    let firmwareVersion = '';
+    let ip6 = null;
+    let deviceWebPage = null;
+    let deviceWebPageInstruction = '';
+    let deviceFullName = null;
+    let community = null;
+    const communitiesTried = [];
+    const data = [];
+
+    try {
+      const snmp = await import('snmp-native').catch(() => null);
+      if (!snmp?.default?.Session && !snmp?.Session) {
+        throw new Error('snmp-native package not properly loaded');
+      }
+      const Session = snmp.default?.Session || snmp.Session;
+
+      const useOid = options.oid ? options.oid.split('.').map(Number) : oidTable.default;
+
+      for (const comm of snmpCommunities) {
+        communitiesTried.push(comm);
+        const s = new Session({ host, community: comm, timeouts: [5000] });
+
+        try {
+          const vbs = await new Promise((resolve) => {
+            let settled = false;
+            const timer = setTimeout(() => { if (!settled) resolve([]); }, 2000);
+            try {
+              s.get({ oid: useOid }, (err, vb) => {
+                if (settled) return;
+                clearTimeout(timer);
+                settled = true;
+                resolve(err ? [] : (vb || []));
+              });
+            } catch { clearTimeout(timer); if (!settled) { settled = true; resolve([]); } }
+          });
+
+          const val = String(vbs?.[0]?.value || '');
+          if (val) {
+            up = true;
+            community = comm;
+            const parsed = fromSysDescr(val);
+            program = parsed.family || 'Unknown';
+            version = parsed.version || 'Unknown';
+            os = parsed.os;
+
+            if (/cisco|palo alto/i.test(program) || /router|switch/i.test(val)) type = 'router';
+            else if (/synology|epson|printer/i.test(program + ' ' + val)) type = 'printer';
+            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') {
+              probeInfo += ` WARNING: Default SNMP community string '${comm}' accepted — misconfiguration`;
+            }
+
+            data.push({
+              probe_protocol: 'udp',
+              probe_port: 161,
+              probe_info: probeInfo,
+              response_banner: val || null
+            });
+
+            // Epson extras
+            const isEpson = /epson/i.test(program + ' ' + val);
+            if (isEpson) {
+              const get = (oid) => new Promise((resolve) => {
+                let settled = false;
+                const timer = setTimeout(() => { if (!settled) { settled = true; resolve([]); } }, 2000);
+                try {
+                  s.get({ oid }, (err, vb) => {
+                    clearTimeout(timer);
+                    if (!settled) { settled = true; resolve(err ? [] : (vb || [])); }
+                  });
+                } catch { clearTimeout(timer); if (!settled) { settled = true; resolve([]); } }
+              });
+
+              const serialVbs = await get(oidTable.epsonSerial);
+              const { serialNumber: sn } = parseSerialNumber(serialVbs?.[0] || '');
+              if (sn) serialNumber = clampSerial(sn, 10);
+
+              const versionsVbs = await get(oidTable.epsonVersions);
+              const { hardwareVersion: hw, firmwareVersion: fw } = parseVersions(versionsVbs?.[0]?.value || '');
+              if (hw) hardwareVersion = hw;
+              if (fw) firmwareVersion = fw;
+
+              const nameVbs = await get(oidTable.epsonName);
+              const nameVal = String(nameVbs?.[0]?.value || '');
+              if (nameVal) {
+                program = nameVal;
+                deviceFullName = nameVal;
+              }
+
+              const versionVbs = await get(oidTable.epsonVersion);
+              const versionVal = String(versionVbs?.[0]?.value || '');
+              if (versionVal) version = versionVal;
+            }
+
+            // Only add 'Serial:' when a real serial exists
+            const infoPieces = [`SNMP response received: ${program} ${version}${os ? ` (OS: ${os})` : ''} (Type: ${type}`];
+            if (serialNumber) infoPieces.push(`Serial: ${serialNumber}`);
+            if (hardwareVersion) infoPieces.push(`HW Ver: ${hardwareVersion}`);
+            if (firmwareVersion) infoPieces.push(`FW Ver: ${firmwareVersion}`);
+            infoPieces.push(')');
+            if (comm === 'public' || comm === 'private') {
+              infoPieces.push(` WARNING: Default SNMP community string '${comm}' accepted — misconfiguration`);
+            }
+            data[0].probe_info = infoPieces.join(', ');
+
+            const bannerExtras = [];
+            if (serialNumber) bannerExtras.push(`Serial=${serialNumber}`);
+            if (hardwareVersion) bannerExtras.push(`HW=${hardwareVersion}`);
+            if (firmwareVersion) bannerExtras.push(`FW=${firmwareVersion}`);
+            if (bannerExtras.length) {
+              data[0].response_banner = `${val}\nAdditional Info: ${bannerExtras.join(', ')}`;
+            } else {
+              data[0].response_banner = val;
+            }
+
+            break;
+          } else {
+            data.push({
+              probe_protocol: 'udp',
+              probe_port: 161,
+              probe_info: `No SNMP response for community "${comm}"`,
+              response_banner: null
+            });
+          }
+        } finally {
+          try { s.close(); } catch {}
+        }
+      }
+    } catch (err) {
+      data.push({
+        probe_protocol: 'udp',
+        probe_port: 161,
+        probe_info: `Error: ${err.message}`,
+        response_banner: null
+      });
+    }
+
+    return { up, program, version, os, type, serialNumber, hardwareVersion, firmwareVersion, ip6, deviceWebPage, deviceWebPageInstruction, community, communitiesTried, data };
+  }
+};
+
+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'}]` : '';
+  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,
+    source: 'snmp', evidence: rows, authoritative: true
+  }];
+}