nsauditor-ai 0.1.0

package/plugins/tls_scanner.mjs

@@ -0,0 +1,225 @@
+// plugins/tls_scanner.mjs
+// TLS Scanner — detects which TLS protocol versions a host supports on common TLS ports.
+// Plug-and-play: includes conclude() so the Result Concluder auto-consumes it.
+//
+// Env vars:
+//   TLS_SCANNER_TIMEOUT_MS   default 8000
+//   TLS_SCANNER_VERSIONS     CSV (e.g., "TLSv1,TLSv1.1,TLSv1.2,TLSv1.3")
+//   TLS_SCANNER_PORTS        CSV of ports to scan (defaults to common TLS ports below)
+//   TLS_SCANNER_DEBUG        "1"/"true" to include per-version errors in data rows
+//   TLS_SCANNER_SNI          optional explicit SNI/hostname for handshake
+//   TLS_SCANNER_TLS_MODULE   module id/url for TLS API (for tests), default 'node:tls'
+//
+// Notes:
+// - We do not rejectUnauthorized to allow protocol negotiation without CA trust.
+// - We set minVersion==maxVersion to force a specific handshake version.
+// - We capture the agreed protocol (e.g., "TLSv1.2") and a representative cipher name.
+
+import dns from 'node:dns/promises';
+
+// Lazy TLS import — test injection allowed in non-production environments only.
+// In production (NODE_ENV=production) only 'node:tls' is accepted.
+const _rawTlsEnv = process.env.TLS_SCANNER_TLS_MODULE;
+const TLS_MODULE_ID = (() => {
+  if (!_rawTlsEnv) return 'node:tls';
+  if (process.env.NODE_ENV === 'production') {
+    console.warn('[tls_scanner] TLS_SCANNER_TLS_MODULE is ignored in production');
+    return 'node:tls';
+  }
+  // In non-production (test/dev): allow any value for stub injection
+  return _rawTlsEnv;
+})();
+let __tlsMod;
+async function loadTls() {
+  if (!__tlsMod) {
+    const m = await import(TLS_MODULE_ID);
+    __tlsMod = m.default ?? m; // support default/named exports
+  }
+  return __tlsMod;
+}
+
+const DEFAULT_PORTS = {
+  443: 'https',
+  465: 'smtps',
+  563: 'nntps',
+  993: 'imaps',
+  995: 'pop3s'
+};
+
+function parseCsvEnv(name, fallback) {
+  const v = process.env[name];
+  if (!v) return fallback;
+  const arr = String(v).split(',').map(s => s.trim()).filter(Boolean);
+  return arr.length ? arr : fallback;
+}
+
+function parsePortsEnv(name, fallback) {
+  const v = process.env[name];
+  if (!v) return fallback;
+  const out = {};
+  for (const tok of String(v).split(',').map(s => s.trim()).filter(Boolean)) {
+    const [p, svc] = tok.split(':').map(s => s.trim());
+    const n = Number(p);
+    if (Number.isFinite(n)) out[n] = svc || (DEFAULT_PORTS[n] || `tcp-${n}`);
+  }
+  return Object.keys(out).length ? out : fallback;
+}
+
+async function reverseHostname(ip) {
+  try {
+    const names = await dns.reverse(ip);
+    return Array.isArray(names) && names.length ? names[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+export default {
+  id: "011",
+  name: "TLS Scanner",
+  description: "Detects supported TLS protocol versions and ciphers on common TLS ports.",
+  priority: 350,
+  requirements: {},
+
+  async run(host, _port, opts = {}) {
+    const timeoutMs = Number(process.env.TLS_SCANNER_TIMEOUT_MS || 8000);
+    const versions = parseCsvEnv('TLS_SCANNER_VERSIONS', ['TLSv1', 'TLSv1.1', 'TLSv1.2', 'TLSv1.3']);
+    const portsMap = parsePortsEnv('TLS_SCANNER_PORTS', { ...DEFAULT_PORTS });
+    const debug = /^(1|true|yes|on)$/i.test(String(process.env.TLS_SCANNER_DEBUG || ''));
+    const sni = process.env.TLS_SCANNER_SNI || null;
+    const hostname = sni || (await reverseHostname(host)) || host;
+    const tlsApi = await loadTls();
+
+    async function checkOnePort(port, service) {
+      const result = {
+        ip: host,
+        port,
+        service,
+        supportedVersions: [],
+        ciphers: {},
+        errors: [],
+        isTLSService: false,
+        supportsOld: false,
+        hostname: hostname || null
+      };
+
+      const check = (version) => new Promise((resolve) => {
+        let settled = false;
+        const options = {
+          host,
+          port,
+          servername: hostname,
+          rejectUnauthorized: false,
+          minVersion: version,
+          maxVersion: version
+        };
+        const socket = tlsApi.connect(options, () => {
+          if (settled) return;
+          settled = true;
+          const protocol = socket.getProtocol?.();
+          const cipher = socket.getCipher?.();
+          try { socket.end?.(); } catch {}
+          resolve({ success: true, protocol, cipher: cipher ? cipher.name : 'Unknown' });
+        });
+        socket.setTimeout?.(timeoutMs);
+        socket.on?.('timeout', () => {
+          if (settled) return;
+          settled = true;
+          try { socket.destroy?.(); } catch {}
+          resolve({ success: false, error: 'timeout' });
+        });
+        socket.on?.('error', (err) => {
+          if (settled) return;
+          settled = true;
+          resolve({ success: false, error: err && err.message ? err.message : 'error' });
+        });
+      });
+
+      for (const v of versions) {
+        const res = await check(v);
+        if (res.success) {
+          const proto = res.protocol || v;
+          result.supportedVersions.push(proto);
+          result.ciphers[proto] = res.cipher;
+        }
+        if (debug) {
+          result.errors.push({ version: v, success: !!res.success, error: res.success ? 'none' : res.error });
+        }
+      }
+
+      result.isTLSService = result.supportedVersions.length > 0;
+      result.supportsOld = result.supportedVersions.some(v => v === 'TLSv1' || v === 'TLSv1.1');
+
+      return result;
+    }
+
+    const perPort = [];
+    for (const [pStr, svc] of Object.entries(portsMap)) {
+      const p = Number(pStr);
+      try {
+        const r = await checkOnePort(p, svc);
+        perPort.push(r);
+      } catch (e) {
+        if (debug) perPort.push({ ip: host, port: p, service: svc, supportedVersions: [], ciphers: {}, errors: [{ error: String(e.message || e) }] });
+      }
+    }
+
+    // Build raw result.data rows for Evidence + Concluder
+    const data = perPort.map(r => {
+      const infoBits = [];
+      if (r.supportedVersions.length) infoBits.push(`TLS: ${r.supportedVersions.join(', ')}`);
+      if (r.supportsOld) infoBits.push('OLD: yes');
+      if (r.hostname && r.hostname !== r.ip) infoBits.push(`SNI: ${r.hostname}`);
+      const probe_info = infoBits.join(' | ') || 'No TLS supported';
+      const bannerObj = { ciphers: r.ciphers, debug: debug ? r.errors : undefined };
+      return {
+        probe_protocol: 'tcp',
+        probe_port: r.port,
+        probe_service: r.service,
+        probe_info,
+        response_banner: JSON.stringify(bannerObj)
+      };
+    });
+
+    const up = perPort.some(r => r.isTLSService);
+
+    return {
+      up,
+      program: 'TLS',
+      version: null,
+      data
+    };
+  }
+};
+
+// ---------------- Plug-and-Play concluder adapter ----------------
+import { statusFrom } from '../utils/conclusion_utils.mjs';
+
+export async function conclude({ host, result }) {
+  const rows = Array.isArray(result?.data) ? result.data : [];
+  const items = [];
+  for (const r of rows) {
+    const port = Number(r?.probe_port);
+    if (!Number.isFinite(port)) continue;
+    const svc = r?.probe_service || ({ 443:'https', 465:'smtps', 563:'nntps', 993:'imaps', 995:'pop3s' }[port]) || 'tls';
+    const info = r?.probe_info || null;
+    const banner = r?.response_banner || null;
+    const status = /TLS: /.test(String(info||'')) ? 'open' : 'closed';
+    items.push({
+      port,
+      protocol: 'tcp',
+      service: svc,
+      program: 'TLS',
+      version: null,
+      status,
+      info,
+      banner,
+      source: 'tls-scanner',
+      evidence: [r],
+      authoritative: true
+    });
+  }
+  return items;
+}
+
+export const authoritativePorts = new Set(['tcp:443','tcp:465','tcp:563','tcp:993','tcp:995']);

package/plugins/upnp_scanner.mjs

@@ -0,0 +1,441 @@
+// plugins/upnp_scanner.mjs
+// Enhanced UPnP Scanner — discovers UPnP devices/services in the subnet with comprehensive SSDP analysis
+// Performs active M-SEARCH queries, detailed header analysis, and improved error handling
+// Filters results to include only devices matching the target host IP by default.
+// Set UPNP_INCLUDE_NON_MATCHED=1 to keep all discovered devices.
+
+import upnp from 'node-upnp-utils';
+import { isPrivateLike } from '../utils/net_validation.mjs';
+
+const DEBUG = /^(1|true|yes|on)$/i.test(String(process.env.DEBUG_MODE || process.env.UPNP_DEBUG || ""));
+function dlog(...a) { if (DEBUG) console.log("[upnp-scanner]", ...a); }
+
+// Active M-SEARCH targets for comprehensive discovery
+const SEARCH_TARGETS = [
+  'ssdp:all',
+  'upnp:rootdevice',
+  'urn:schemas-upnp-org:device:MediaRenderer:1',
+  'urn:schemas-upnp-org:device:MediaServer:1',
+  'urn:schemas-upnp-org:service:ContentDirectory:1',
+  'urn:schemas-upnp-org:service:ConnectionManager:1',
+  'urn:schemas-wifialliance-org:device:WFADevice:1'
+];
+
+function ipMatches(target, address) {
+  const t = String(target || "").trim();
+  const a = String(address || "").trim();
+  return t === a;
+}
+
+function extractOsFromServer(server) {
+  if (!server) return { os: null, version: null };
+  const s = String(server).toLowerCase();
+
+  // Check for POSIX
+  if (/posix/i.test(s)) {
+    return { os: "POSIX", version: null };
+  }
+
+  // Check for Linux with version
+  const linuxMatch = s.match(/linux\s*\/?\s*([\d.]+)\b/i);
+  if (linuxMatch && linuxMatch[1]) {
+    return { os: "Linux", version: linuxMatch[1] };
+  }
+
+  // Check for Windows
+  const windowsMatch = s.match(/windows\s*\/?\s*([\d.]+)\b/i);
+  if (windowsMatch && windowsMatch[1]) {
+    return { os: "Windows", version: windowsMatch[1] };
+  }
+
+  // Check for other OS patterns
+  if (/android/i.test(s)) {
+    const androidMatch = s.match(/android\s*([\d.]+)/i);
+    return { os: "Android", version: androidMatch?.[1] || null };
+  }
+
+  if (/darwin|macos|mac\s*os/i.test(s)) {
+    const macMatch = s.match(/darwin\s*([\d.]+)|mac\s*os\s*([\d.]+)/i);
+    return { os: "macOS", version: macMatch?.[1] || macMatch?.[2] || null };
+  }
+
+  return { os: null, version: null };
+}
+
+function analyzeSsdpHeaders(headers, rinfo) {
+  const analysis = {
+    timestamp: new Date().toISOString(),
+    sourceIP: rinfo?.address,
+    sourcePort: rinfo?.port,
+    searchTarget: headers.ST,
+    notificationType: headers.NT,
+    uniqueServiceName: headers.USN,
+    server: headers.SERVER,
+    location: headers.LOCATION,
+    cacheControl: headers['CACHE-CONTROL'],
+    maxAge: null,
+    bootId: headers['BOOTID.UPNP.ORG'],
+    configId: headers['CONFIGID.UPNP.ORG'],
+    date: headers.DATE,
+    ext: headers.EXT,
+    opt: headers.OPT
+  };
+
+  // Extract max-age from cache-control
+  if (analysis.cacheControl) {
+    const maxAgeMatch = analysis.cacheControl.match(/max-age\s*=\s*(\d+)/i);
+    if (maxAgeMatch) {
+      analysis.maxAge = parseInt(maxAgeMatch[1], 10);
+    }
+  }
+
+  return analysis;
+}
+
+function extractDeviceInfo(device, deviceXml) {
+  const info = {
+    friendlyName: null,
+    manufacturer: null,
+    manufacturerURL: null,
+    modelName: null,
+    modelNumber: null,
+    modelDescription: null,
+    serialNumber: null,
+    UDN: null,
+    deviceType: null,
+    services: []
+  };
+
+  // Extract from device object if available
+  if (device?.description?.device) {
+    const desc = device.description.device;
+    info.friendlyName = desc.friendlyName;
+    info.manufacturer = desc.manufacturer;
+    info.manufacturerURL = desc.manufacturerURL;
+    info.modelName = desc.modelName;
+    info.modelNumber = desc.modelNumber;
+    info.modelDescription = desc.modelDescription;
+    info.serialNumber = desc.serialNumber;
+    info.UDN = desc.UDN;
+    info.deviceType = desc.deviceType;
+
+    // Extract services
+    if (desc.serviceList?.service) {
+      const services = Array.isArray(desc.serviceList.service) ? 
+        desc.serviceList.service : [desc.serviceList.service];
+      info.services = services.map(svc => ({
+        serviceType: svc.serviceType,
+        serviceId: svc.serviceId,
+        controlURL: svc.controlURL,
+        eventSubURL: svc.eventSubURL,
+        SCPDURL: svc.SCPDURL
+      }));
+    }
+  }
+
+  return info;
+}
+
+async function fetchDeviceDescription(location, timeout = 5000) {
+  if (!location) return null;
+  
+  try {
+    const { default: fetch } = await import('node-fetch');
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    
+    const response = await fetch(location, { 
+      signal: controller.signal,
+      headers: {
+        'User-Agent': 'UPnP-Scanner/1.0'
+      }
+    });
+    
+    clearTimeout(timeoutId);
+    
+    if (response.ok) {
+      return await response.text();
+    } else {
+      dlog(`HTTP ${response.status} when fetching ${location}`);
+      return null;
+    }
+  } catch (e) {
+    if (e.name === 'AbortError') {
+      dlog("Fetch timeout for device description:", location);
+    } else {
+      dlog("Failed to fetch device description:", e?.message || e);
+    }
+    return null;
+  }
+}
+
+function deduplicateDevices(devices) {
+  // Use Map to track unique devices by USN base (before ::)
+  const seen = new Map();
+  
+  for (const device of devices) {
+    const headers = device.headers || {};
+    const usn = headers.USN || '';
+    const baseUsn = usn.split('::')[0]; // Get base USN without service type
+    const address = device.address || '';
+    
+    // Create unique device signature
+    const signature = `${baseUsn}|${address}`;
+    
+    if (!seen.has(signature)) {
+      // Store first occurrence
+      seen.set(signature, {
+        device,
+        searchTargets: new Set([headers.ST].filter(Boolean))
+      });
+    } else {
+      // Add search target to existing device
+      const existing = seen.get(signature);
+      if (headers.ST) {
+        existing.searchTargets.add(headers.ST);
+      }
+      // Merge any additional device info
+      if (device.description && !existing.device.description) {
+        existing.device.description = device.description;
+      }
+      dlog(`Deduplicated device: ${signature} (ST: ${headers.ST})`);
+    }
+  }
+
+  // Return deduplicated devices with aggregated search targets
+  return Array.from(seen.values()).map(entry => {
+    const device = {...entry.device};
+    device.searchTargets = Array.from(entry.searchTargets);
+    return device;
+  });
+}
+
+async function runWithUpnp(targetHost, timeoutMs, opts) {
+  let upnp;
+  if (process.env.UPNP_TEST_FAKE && globalThis.__upnpFakeFactory) {
+    upnp = globalThis.__upnpFakeFactory();
+  } else {
+    const { default: upnpModule } = await import('node-upnp-utils');
+    upnp = upnpModule;
+  }
+
+  const allDevices = [];
+  let matched = false;
+  const includeNonMatched = /^(1|true|yes|on)$/i.test(String(process.env.UPNP_INCLUDE_NON_MATCHED || ""));
+
+  try {
+    // Perform discovery with multiple search targets
+    for (const searchTarget of SEARCH_TARGETS) {
+      try {
+        dlog(`Searching for ${searchTarget}`);
+        const devices = await upnp.discover({ 
+          timeout: Math.floor(timeoutMs / SEARCH_TARGETS.length),
+          st: searchTarget 
+        });
+        allDevices.push(...devices);
+        dlog(`Found ${devices.length} devices for ${searchTarget}`);
+      } catch (e) {
+        dlog(`Error searching for ${searchTarget}:`, e?.message || e);
+      }
+    }
+
+    // Deduplicate devices
+    const uniqueDevices = deduplicateDevices(allDevices);
+    dlog(`Total unique devices discovered: ${uniqueDevices.length}`);
+
+    const rows = [];
+    
+    for (const device of uniqueDevices) {
+      const address = device.address;
+      const ipHit = ipMatches(targetHost, address);
+      const keepRow = ipHit || includeNonMatched;
+
+      if (!keepRow) continue;
+
+      const headers = device.headers || {};
+      const usn = headers.USN || 'unknown';
+      const location = headers.LOCATION || '';
+      const server = headers.SERVER || '';
+      const st = headers.ST || 'upnp:rootdevice';
+      
+      // Enhanced OS detection
+      const { os, version } = extractOsFromServer(server);
+      
+      // Enhanced SSDP analysis
+      const ssdpAnalysis = analyzeSsdpHeaders(headers, { address, port: 1900 });
+      
+      // Fetch and parse device description if available
+      let deviceXml = null;
+      if (location) {
+        deviceXml = await fetchDeviceDescription(location, 3000);
+      }
+      
+      // Extract detailed device information
+      const deviceInfo = extractDeviceInfo(device, deviceXml);
+      
+      // Build comprehensive info string
+      const infoParts = [];
+      infoParts.push(`type=${st}`);
+      
+      if (deviceInfo.friendlyName) {
+        infoParts.push(`name="${deviceInfo.friendlyName}"`);
+      }
+      if (deviceInfo.manufacturer) {
+        infoParts.push(`manufacturer="${deviceInfo.manufacturer}"`);
+      }
+      if (deviceInfo.modelName) {
+        infoParts.push(`model="${deviceInfo.modelName}"`);
+      }
+      if (deviceInfo.modelNumber) {
+        infoParts.push(`modelNumber="${deviceInfo.modelNumber}"`);
+      }
+      if (os) {
+        infoParts.push(`os="${os}${version ? ` ${version}` : ''}"`);
+      }
+      if (ssdpAnalysis.maxAge) {
+        infoParts.push(`maxAge=${ssdpAnalysis.maxAge}s`);
+      }
+      
+      infoParts.push(`address=${address}`);
+      if (location) {
+        infoParts.push(`location=${location}`);
+      }
+
+      // Enhanced banner with comprehensive data
+      const bannerObj = {
+        address,
+        headers: {
+          USN: usn,
+          SERVER: server,
+          ST: st,
+          LOCATION: location,
+          'CACHE-CONTROL': headers['CACHE-CONTROL'],
+          DATE: headers.DATE,
+          EXT: headers.EXT
+        },
+        ssdpAnalysis,
+        deviceInfo,
+        descriptionXML: deviceXml ? deviceXml.substring(0, 2000) : null, // Limit XML size
+        xmlTruncated: deviceXml && deviceXml.length > 2000
+      };
+
+      const row = {
+        probe_protocol: "upnp",
+        probe_port: 1900,
+        probe_info: (ipHit ? "Matched host — " : "Discovered — ") + infoParts.join(" "),
+        response_banner: JSON.stringify(bannerObj),
+        os,
+        osVersion: version,
+        ssdpHeaders: ssdpAnalysis,
+        deviceDetails: deviceInfo
+      };
+      
+      rows.push(row);
+
+      if (ipHit) {
+        matched = true;
+        dlog(`Match detected for host ${targetHost} with device ${address}`);
+      }
+    }
+
+    return { rows, matched };
+    
+  } catch (e) {
+    dlog("UPnP discovery error:", e?.message || e);
+    return { rows: [], matched: false };
+  }
+}
+
+export default {
+  id: "028",
+  name: "Enhanced UPnP Scanner",
+  description: "Comprehensive UPnP/SSDP discovery with active M-SEARCH probing, detailed header analysis, and enhanced device fingerprinting. Returns only instances matching the target host IP by default.",
+  priority: 346,
+  requirements: {},
+  protocols: ["upnp", "ssdp"],
+  ports: [1900],
+  runStrategy: "single",
+
+  async run(host, _port = 1900, opts = {}) {
+    const timeoutMs = Number(opts.timeoutMs ?? process.env.NSA_UPNP_TIMEOUT_MS ?? 15000); // Increased timeout
+    const data = [];
+
+    if (!isPrivateLike(host)) {
+      data.push({
+        probe_protocol: "upnp",
+        probe_port: 1900,
+        probe_info: "Non-local target — UPnP/SSDP not attempted (requires local network)",
+        response_banner: null
+      });
+      return {
+        up: false,
+        program: "UPnP/SSDP",
+        version: "Unknown",
+        os: null,
+        type: "upnp",
+        data
+      };
+    }
+
+    const { rows, matched } = await runWithUpnp(host, timeoutMs, opts);
+    dlog(`Discovery complete: matched=${matched}, rows.length=${rows.length}`);
+
+    if (rows.length === 0) {
+      data.push({
+        probe_protocol: "upnp",
+        probe_port: 1900,
+        probe_info: "No UPnP/SSDP devices relevant to target IP discovered within timeout window",
+        response_banner: JSON.stringify({
+          searchTargets: SEARCH_TARGETS,
+          timeout: timeoutMs,
+          reason: "No responses received"
+        })
+      });
+    } else {
+      // Sort rows by relevance (matched first, then by device type)
+      rows.sort((a, b) => {
+        if (a.probe_info.includes("Matched host") && !b.probe_info.includes("Matched host")) return -1;
+        if (!a.probe_info.includes("Matched host") && b.probe_info.includes("Matched host")) return 1;
+        return 0;
+      });
+      
+      data.push(...rows);
+    }
+
+    // Add summary row for matched devices
+    if (matched) {
+      const matchedRows = rows.filter(r => r.probe_info.includes("Matched host"));
+      const uniqueDeviceTypes = [...new Set(matchedRows.map(r => {
+        const match = r.probe_info.match(/type=([^\s]+)/);
+        return match ? match[1] : 'unknown';
+      }))];
+      
+      const summaryRow = {
+        probe_protocol: "upnp",
+        probe_port: 1900,
+        probe_info: `Host ${host} confirmed via UPnP/SSDP - ${matchedRows.length} device(s) found: ${uniqueDeviceTypes.join(', ')}`,
+        response_banner: JSON.stringify({
+          summary: true,
+          matchedDevices: matchedRows.length,
+          deviceTypes: uniqueDeviceTypes,
+          discoveredAt: new Date().toISOString()
+        })
+      };
+      
+      data.unshift(summaryRow); // Add at beginning
+      dlog(`Added summary row for ${matchedRows.length} matched devices`);
+    }
+
+    return {
+      up: matched,
+      program: "UPnP/SSDP",
+      version: "1.1-Enhanced",
+      os: matched ? rows.find(r => r.os)?.os || null : null,
+      osVersion: matched ? rows.find(r => r.osVersion)?.osVersion || null : null,
+      type: "upnp",
+      deviceCount: rows.length,
+      searchTargets: SEARCH_TARGETS,
+      data
+    };
+  }
+};