nsauditor-ai 0.1.0

package/plugins/ping_checker.mjs

@@ -0,0 +1,271 @@
+// plugins/ping_checker.mjs
+// Ping Checker — ICMP ping, TTL-based OS guess, ARP assist for local targets,
+// and ICMP/TCP fallback probes when Echo Request gets no reply.
+// Uses ONLY ctx.lookupVendor / ctx.probableOsFromVendor (if provided).
+
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+import net from "node:net";
+import { isPrivateLike } from '../utils/net_validation.mjs';
+
+const execFileP = promisify(execFile);
+const isWin = process.platform === "win32";
+const DEBUG = /^(1|true|yes|on)$/i.test(String(process.env.DEBUG_MODE || process.env.PING_DEBUG || ""));
+const FALLBACK_ENABLED = !/^(0|false|no|off)$/i.test(String(process.env.PING_FALLBACK ?? "true"));
+const FALLBACK_TIMEOUT = Number(process.env.PING_FALLBACK_TIMEOUT) || 3000;
+
+function dlog(...a) { if (DEBUG) console.log("[ping-checker]", ...a); }
+
+/** Validate host string to prevent command injection. */
+function isValidHost(h) {
+  if (!h || typeof h !== "string") return false;
+  // Allow IPv4, IPv6, and hostnames only — no shell metacharacters
+  return /^[a-zA-Z0-9.:_\-\[\]%]+$/.test(h);
+}
+
+/**
+ * Try ICMP Timestamp Request (Type 13) via nping or hping3.
+ * Returns true if the host responded, false otherwise.
+ */
+async function tryIcmpTimestamp(host, timeoutMs) {
+  if (!isValidHost(host)) return { alive: false, info: "Invalid host" };
+
+  // Try nping first (from nmap suite)
+  try {
+    const { stdout } = await execFileP(
+      "nping",
+      ["--icmp", "--icmp-type", "timestamp", "-c", "1", "--delay", "0", host],
+      { windowsHide: true, timeout: timeoutMs + 500 }
+    );
+    dlog("nping timestamp output:", stdout);
+    const ok = /RCVD|completed/i.test(stdout) && !/0 received/i.test(stdout);
+    if (ok) return { alive: true, info: "ICMP Timestamp reply via nping" };
+    return { alive: false, info: "ICMP Timestamp — no reply (nping)" };
+  } catch {
+    dlog("nping not available or failed");
+  }
+
+  // Try hping3 as second option
+  try {
+    const { stdout } = await execFileP(
+      "hping3",
+      ["-1", "--icmptype", "13", "-c", "1", host],
+      { windowsHide: true, timeout: timeoutMs + 500 }
+    );
+    dlog("hping3 timestamp output:", stdout);
+    const ok = /flags=/.test(stdout) || /len=/.test(stdout);
+    if (ok) return { alive: true, info: "ICMP Timestamp reply via hping3" };
+    return { alive: false, info: "ICMP Timestamp — no reply (hping3)" };
+  } catch {
+    dlog("hping3 not available or failed");
+  }
+
+  return { alive: false, info: "ICMP Timestamp — nping/hping3 not available" };
+}
+
+/**
+ * TCP ACK probe on common ports (80, 443).
+ * A successful connect OR ECONNREFUSED (RST) both mean the host is up.
+ * Returns { alive, port, info }.
+ */
+function tryTcpAckProbe(host, port, timeoutMs) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    socket.setTimeout(timeoutMs);
+
+    const cleanup = () => { try { socket.destroy(); } catch {} };
+
+    socket.on("connect", () => {
+      cleanup();
+      resolve({ alive: true, port, info: `TCP connect to port ${port} — host up` });
+    });
+
+    socket.on("error", (err) => {
+      cleanup();
+      if (err.code === "ECONNREFUSED") {
+        // RST received — host is alive
+        resolve({ alive: true, port, info: `TCP RST on port ${port} — host up` });
+      } else {
+        resolve({ alive: false, port, info: `TCP probe port ${port} — ${err.code || err.message}` });
+      }
+    });
+
+    socket.on("timeout", () => {
+      cleanup();
+      resolve({ alive: false, port, info: `TCP probe port ${port} — timeout` });
+    });
+
+    socket.connect(port, host);
+  });
+}
+
+async function getMacViaArp(ip, iface = null) {
+  const cmd = "arp";
+  const args = isWin ? ["-a", ip] : ["-n", ip];
+  if (iface && !isWin) {
+    args.push("-i", iface);
+  }
+  try {
+    const { stdout } = await execFileP(cmd, args, { windowsHide: true, timeout: 5000 });
+    // Log raw output for debugging
+    dlog("Raw ARP output:", stdout);
+    // Compact regex: catches colon or dash formats, 1 or 2 hex digits
+    const macRe = /([0-9a-f]{1,2}(?:[:-][0-9a-f]{1,2}){5})/i;
+    const line = stdout.split(/\r?\n/).find(l => l.includes(ip) || l.includes(`(${ip})`));
+    const m = (line && line.match(macRe)) || stdout.match(macRe);
+    if (m) {
+      let mac = m[1].replace(/-/g, ":").toUpperCase();
+      mac = mac.split(":").map(part => part.padStart(2, "0")).join(":");
+      dlog(`Parsed MAC for IP ${ip}: ${mac}`);
+      return mac;
+    }
+    dlog("No MAC found in output");
+    return null;
+  } catch (e) {
+    dlog("arp exec failed:", e?.message || e);
+    return null;
+  }
+}
+
+function osFromTtl(initial) {
+  if (!initial) return null;
+  if (initial >= 61 && initial <= 64) return "Linux/Unix/macOS or RTOS";
+  if (initial >= 125 && initial <= 128) return "Windows";
+  if (initial >= 254 && initial <= 255) return "Cisco/Solaris or RTOS/IoT";
+  if (initial >= 30 && initial <= 32) return "Older system or custom embedded";
+  return `Custom/Proprietary (TTL=${initial})`;
+}
+
+export default {
+  id: "001",
+  name: "Ping Checker",
+  description: "Checks ICMP reachability, infers OS from TTL, and leverages ARP (local only) with vendor hints from ctx.",
+  priority: 10,
+  requirements: {},
+  protocols: ["icmp"],
+  ports: [],
+  dependencies: [],
+
+  async run(host, _port, opts = {}) {
+    if (!isValidHost(host)) {
+      return { up: false, os: null, probeMethod: "none", data: [{ probe_protocol: "icmp", probe_port: 0, probe_info: "Invalid host", response_banner: null }] };
+    }
+    const timeoutMs = Number(opts.timeoutMs ?? process.env.NSA_PING_TIMEOUT_MS ?? 5000);
+    const fallbackEnabled = opts.fallback ?? FALLBACK_ENABLED;
+    const fallbackTimeout = Number(opts.fallbackTimeout ?? FALLBACK_TIMEOUT);
+    const cmd = "ping";
+    const args = isWin
+      ? ["-n", "1", "-w", String(timeoutMs), host]
+      : ["-c", "1", "-W", String(Math.ceil(timeoutMs / 1000)), host];
+
+    const data = [];
+    let up = false;
+    let os = null;
+    let probeMethod = "none";
+
+    // 1) ICMP Echo Request (Type 8)
+    try {
+      const { stdout } = await execFileP(cmd, args, { windowsHide: true, timeout: timeoutMs + 1000 });
+      dlog("Raw ping output:", stdout);
+      const ok = /ttl=|TTL=|bytes from|time=|Antwort von|Reply from/i.test(stdout);
+      const ttlMatch = stdout.match(/ttl=(\d+)|TTL=(\d+)/i);
+      const ttl = ttlMatch ? parseInt(ttlMatch[1] || ttlMatch[2], 10) : null;
+      const initialTTL = ttl ? ttl + 1 : null;
+      const icmpOs = osFromTtl(initialTTL);
+
+      data.push({
+        probe_protocol: "icmp",
+        probe_port: 0,
+        probe_info: ok
+          ? `Ping OK — ttl=${ttl ?? "N/A"} (inferred base ${initialTTL ?? "N/A"})`
+          : "Ping did not confirm host up",
+        response_banner: ttl ? `ttl=${ttl}` : null
+      });
+
+      if (ok) {
+        up = true;
+        probeMethod = "echo";
+        if (icmpOs) os = icmpOs;
+      }
+    } catch (e) {
+      dlog("ICMP probe error:", e?.message || e);
+      data.push({ probe_protocol: "icmp", probe_port: 0, probe_info: "Ping failed", response_banner: null });
+    }
+
+    // 2) Fallback probes — only when echo failed and fallback is enabled
+    if (!up && fallbackEnabled) {
+      dlog("Echo failed, attempting fallback probes");
+
+      // Fallback 1: ICMP Timestamp Request (Type 13)
+      const tsResult = await tryIcmpTimestamp(host, fallbackTimeout);
+      data.push({
+        probe_protocol: "icmp-timestamp",
+        probe_port: 0,
+        probe_info: tsResult.info,
+        response_banner: null
+      });
+
+      if (tsResult.alive) {
+        up = true;
+        probeMethod = "timestamp";
+      }
+
+      // Fallback 2: TCP ACK probe on ports 80 and 443
+      if (!up) {
+        const tcpPorts = [80, 443];
+        for (const port of tcpPorts) {
+          const tcpResult = await tryTcpAckProbe(host, port, fallbackTimeout);
+          data.push({
+            probe_protocol: "tcp-ack",
+            probe_port: port,
+            probe_info: tcpResult.info,
+            response_banner: null
+          });
+
+          if (tcpResult.alive) {
+            up = true;
+            probeMethod = "tcp-ack";
+            // Propagate confirmed port to shared context so downstream
+            // plugins gated on tcp_open (HTTP Probe, Webapp Detector, etc.)
+            // can run without waiting for a full port scan.
+            const ctx = opts?.context;
+            if (ctx?.tcpOpen && typeof ctx.tcpOpen.add === "function") {
+              ctx.tcpOpen.add(port);
+            }
+            break; // No need to probe further
+          }
+        }
+      }
+    }
+
+    // 3) ARP (local only)
+    if (isPrivateLike(host)) {
+      const interfaces = isWin ? [null] : [null, "en0"];
+      let mac = null;
+      for (const iface of interfaces) {
+        mac = await getMacViaArp(host, iface);
+        if (mac) break;
+      }
+
+      if (mac) {
+        up = true; // ARP reachability implies L2 presence
+
+        // Only use ctx helpers (no OUI loading here)
+        const ctx = opts?.context || {};
+        const vendorRaw = typeof ctx.lookupVendor === "function" ? (ctx.lookupVendor(mac) || null) : null;
+        const vendor = vendorRaw ? vendorRaw.replace(/[\r\n]+/g, ' ').trim() : null;
+        const info = vendor ? `ARP entry found — vendor: ${vendor}` : "ARP entry found";
+
+        // If OS not set from TTL, try ctx vendor heuristic
+        if (!os && typeof ctx.probableOsFromVendor === "function") {
+          const guess = ctx.probableOsFromVendor(vendor);
+          if (guess && guess !== "Unknown") os = guess;
+        }
+
+        data.push({ probe_protocol: "arp", probe_port: 0, probe_info: info, response_banner: mac });
+      }
+    }
+
+    return { up, os, probeMethod, data };
+  }
+};

package/plugins/port_scanner.mjs

@@ -0,0 +1,250 @@
+// plugins/port_scanner.mjs
+// Fast TCP/UDP port sampler with banner sniffing and clear CLOSED/FILTERED mapping.
+// Output shape matches earlier examples (tcpOpen/tcpClosed/tcpFiltered, etc.).
+
+import net from "node:net";
+import dgram from "node:dgram";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+/* ------------------------------ helpers ------------------------------ */
+
+const toInt = (v, d) => {
+  const n = Number(v);
+  return Number.isFinite(n) && n >= 0 ? n : d;
+};
+
+function uniqInts(arr = []) {
+  return [...new Set((arr || []).map((x) => Number(x)).filter(Number.isFinite))];
+}
+
+async function loadConfigPortsFromServicesJson(cwd = process.cwd()) {
+  // Supports the "array schema" used by tests:
+  // { "services": [ { port, protocol }, ... ] }
+  // and a fallback object schema: { tcp: [...], udp: [...] }
+  const out = { tcp: [], udp: [] };
+  try {
+    const fp = path.join(cwd, "config", "services.json");
+    const raw = await fsp.readFile(fp, "utf8");
+    const cfg = JSON.parse(raw);
+
+    if (Array.isArray(cfg?.services)) {
+      for (const s of cfg.services) {
+        const p = Number(s?.port);
+        const proto = String(s?.protocol || "").toLowerCase();
+        if (!Number.isFinite(p)) continue;
+        if (proto === "udp") out.udp.push(p);
+        else out.tcp.push(p); // default to TCP when not specified
+      }
+    } else {
+      if (Array.isArray(cfg?.tcp)) out.tcp.push(...cfg.tcp);
+      if (Array.isArray(cfg?.udp)) out.udp.push(...cfg.udp);
+    }
+  } catch {
+    // no config, ignore
+  }
+  out.tcp = uniqInts(out.tcp);
+  out.udp = uniqInts(out.udp);
+  return out;
+}
+
+function classifyTcpError(err) {
+  const code = err?.code || "";
+  const msg = err?.message || String(err) || "";
+  // Treat ANY "refused" (code OR message) as closed, and ensure info contains 'refused'
+  if (code === "ECONNREFUSED" || /ECONNREFUSED|refused/i.test(msg)) {
+    const suffix = code ? ` (${code})` : "";
+    return { status: "closed", info: `Connect refused${suffix}` };
+  }
+  if (code === "ETIMEDOUT" || /timed?\s*out/i.test(msg)) return { status: "filtered", info: "Timeout" };
+  if (code === "EHOSTUNREACH" || code === "ENETUNREACH") return { status: "filtered", info: "Unreachable" };
+  return { status: "filtered", info: code || "Socket error" };
+}
+
+/* ------------------------------ TCP scan ------------------------------ */
+
+async function scanTcpPort(host, port, { timeoutMs, bannerTimeoutMs, maxBannerBytes }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const socket = new net.Socket();
+    let banner = Buffer.alloc(0);
+    let done = false;
+    let bannerTimer = null;
+
+    const finish = (status, info, extra = {}) => {
+      if (done) return;
+      done = true;
+      clearTimeout(bannerTimer);
+      try { socket.destroy(); } catch {}
+      resolve({
+        probe_protocol: "tcp",
+        probe_port: port,
+        status,
+        probe_info: info || null,
+        response_banner: banner.length ? banner.toString("utf8", 0, Math.min(maxBannerBytes, banner.length)).trim() : null,
+        rtt_ms: Date.now() - started,
+        error: extra.error || null,
+      });
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.setNoDelay?.(true);
+
+    socket.once("connect", () => {
+      // Give services a short opportunity to greet with a banner.
+      bannerTimer = setTimeout(() => finish("open", "TCP connect success (peer closed)"), bannerTimeoutMs);
+    });
+
+    socket.on("data", (chunk) => {
+      banner = Buffer.concat([banner, chunk]);
+      if (banner.length >= maxBannerBytes) {
+        finish("open", "TCP connect success (banner captured)");
+      }
+    });
+
+    socket.once("timeout", () => finish("filtered", "Timeout"));
+
+    socket.once("error", (e) => {
+      const cls = classifyTcpError(e);
+      finish(cls.status, cls.info, { error: e?.code || String(e) });
+    });
+
+    try {
+      socket.connect(port, host);
+    } catch (e) {
+      const cls = classifyTcpError(e);
+      finish(cls.status, cls.info, { error: e?.code || String(e) });
+    }
+  });
+}
+
+/* ------------------------------ UDP scan ------------------------------ */
+
+async function scanUdpPort(host, port, { timeoutMs, udpPayload }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const sock = dgram.createSocket("udp4");
+    let done = false;
+
+    const finish = (status, info) => {
+      if (done) return;
+      done = true;
+      try { sock.close(); } catch {}
+      resolve({
+        probe_protocol: "udp",
+        probe_port: port,
+        status,
+        probe_info: info || null,
+        response_banner: null,
+        rtt_ms: Date.now() - started,
+      });
+    };
+
+    const t = setTimeout(() => finish("no-response", "No UDP response"), timeoutMs);
+
+    sock.once("error", () => {
+      clearTimeout(t);
+      finish("no-response", "UDP error/no response"); // conservative default for generic UDP ping
+    });
+
+    sock.once("message", () => {
+      clearTimeout(t);
+      finish("open", "UDP response");
+    });
+
+    try {
+      sock.send(udpPayload, port, host);
+    } catch {
+      clearTimeout(t);
+      finish("no-response", "UDP send error");
+    }
+  });
+}
+
+/* ------------------------------- runner ------------------------------- */
+
+export default {
+  id: "003",
+  name: "Port Scanner",
+  description: "Lightweight TCP/UDP sampler with banner sniffing. Classifies ECONNREFUSED as closed.",
+  priority: 30,
+  protocols: ["tcp", "udp"],
+  ports: [],
+  requirements: { host: "up" },
+
+  // run(host, _portIgnored, opts)
+  async run(host, _port = 0, opts = {}) {
+    const timeoutMs       = toInt(opts.timeoutMs ?? process.env.TCP_CONNECT_TIMEOUT_MS, 1200);
+    const bannerTimeoutMs = toInt(opts.bannerTimeoutMs ?? process.env.TCP_BANNER_TIMEOUT_MS, 250);
+    const maxBannerBytes  = toInt(process.env.TCP_BANNER_MAX_BYTES, 350);
+    const udpPayload      = Buffer.from("hi");
+
+    // Port sources: opts first, else config/services.json, else empty (tests supply what they need)
+    let tcpPorts = Array.isArray(opts.tcpPorts) ? uniqInts(opts.tcpPorts) : [];
+    let udpPorts = Array.isArray(opts.udpPorts) ? uniqInts(opts.udpPorts) : [];
+
+    if (!tcpPorts.length && !udpPorts.length) {
+      const cfg = await loadConfigPortsFromServicesJson();
+      tcpPorts = cfg.tcp;
+      udpPorts = cfg.udp;
+    }
+
+    // If still nothing, just return empty structure
+    if (!tcpPorts.length && !udpPorts.length) {
+      return {
+        up: false,
+        program: "Unknown",
+        version: "Unknown",
+        os: null,
+        type: "port-scan",
+        tcpOpen: [],
+        tcpClosed: [],
+        tcpFiltered: [],
+        udpOpen: [],
+        udpClosed: [],
+        udpNoResponse: [],
+        data: [],
+      };
+    }
+
+    const data = [];
+
+    // TCP scans
+    for (const p of tcpPorts) {
+      data.push(await scanTcpPort(host, p, { timeoutMs, bannerTimeoutMs, maxBannerBytes }));
+    }
+
+    // UDP scans
+    for (const p of udpPorts) {
+      data.push(await scanUdpPort(host, p, { timeoutMs, udpPayload }));
+    }
+
+    // Buckets
+    const tcpOpen      = data.filter(d => d.probe_protocol === "tcp" && d.status === "open").map(d => d.probe_port);
+    const tcpClosed    = data.filter(d => d.probe_protocol === "tcp" && d.status === "closed").map(d => d.probe_port);
+    const tcpFiltered  = data.filter(d => d.probe_protocol === "tcp" && d.status === "filtered").map(d => d.probe_port);
+
+    const udpOpen       = data.filter(d => d.probe_protocol === "udp" && d.status === "open").map(d => d.probe_port);
+    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;
+
+    return {
+      up: anyTcpEvidence || anyUdpOpen,
+      program: "Unknown",
+      version: "Unknown",
+      os: null,
+      type: "port-scan",
+      tcpOpen,
+      tcpClosed,
+      tcpFiltered,
+      udpOpen,
+      udpClosed,
+      udpNoResponse,
+      data,
+    };
+  },
+};