nsauditor-ai 0.1.0

package/utils/scan_history.mjs

@@ -0,0 +1,248 @@
+// utils/scan_history.mjs
+// Scan history persistence and comparison utilities.
+// Uses JSONL (one JSON object per line) for append-friendly storage.
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+export const HISTORY_FILE = 'scan_history.jsonl';
+
+/**
+ * Build a service key for comparison (port + protocol).
+ * @param {object} svc
+ * @returns {string}
+ */
+function serviceKey(svc) {
+  return `${svc.port ?? ''}/${svc.protocol ?? 'tcp'}`;
+}
+
+/**
+ * Append a scan summary as a single JSON line to scan_history.jsonl.
+ * @param {string} outputDir - root output directory
+ * @param {object} summary  - scan summary object
+ * @returns {Promise<string>} path to the history file
+ */
+export async function recordScan(outputDir, summary) {
+  const filePath = path.join(outputDir, HISTORY_FILE);
+  const entry = {
+    timestamp: summary.timestamp ?? new Date().toISOString(),
+    host: summary.host ?? null,
+    servicesCount: summary.servicesCount ?? 0,
+    openPorts: Array.isArray(summary.openPorts) ? summary.openPorts : [],
+    os: summary.os ?? null,
+    findingsCount: summary.findingsCount ?? 0,
+    services: Array.isArray(summary.services) ? summary.services.map((s) => ({
+      port: s.port ?? null,
+      protocol: s.protocol ?? 'tcp',
+      service: s.service ?? null,
+      version: s.version ?? null,
+    })) : [],
+  };
+  const line = JSON.stringify(entry) + '\n';
+  await fsp.mkdir(outputDir, { recursive: true });
+  await fsp.appendFile(filePath, line, 'utf8');
+  return filePath;
+}
+
+/**
+ * Read scan_history.jsonl and return the most recent entry for the given host.
+ * @param {string} outputDir
+ * @param {string} host
+ * @returns {Promise<object|null>}
+ */
+export async function getLastScan(outputDir, host) {
+  const filePath = path.join(outputDir, HISTORY_FILE);
+  let content;
+  try {
+    content = await fsp.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+
+  const lines = content.trim().split('\n').filter(Boolean);
+  let latest = null;
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (entry.host === host) {
+        if (!latest || entry.timestamp > latest.timestamp) {
+          latest = entry;
+        }
+      }
+    } catch {
+      // skip malformed lines
+    }
+  }
+
+  return latest;
+}
+
+/**
+ * Compare two scan summaries and return a structured diff.
+ * @param {object} current  - current scan summary
+ * @param {object|null} previous - previous scan summary (null for first scan)
+ * @returns {object} diff object
+ */
+export function computeDiff(current, previous) {
+  if (!previous) {
+    return {
+      newServices: [],
+      removedServices: [],
+      changedServices: [],
+      newFindings: current?.findingsCount ?? 0,
+      summary: 'No previous scan for comparison.',
+    };
+  }
+
+  const currentServices = Array.isArray(current?.services) ? current.services : [];
+  const previousServices = Array.isArray(previous?.services) ? previous.services : [];
+
+  const prevMap = new Map();
+  for (const svc of previousServices) {
+    prevMap.set(serviceKey(svc), svc);
+  }
+
+  const currMap = new Map();
+  for (const svc of currentServices) {
+    currMap.set(serviceKey(svc), svc);
+  }
+
+  const newServices = [];
+  const changedServices = [];
+
+  for (const [key, svc] of currMap) {
+    const prev = prevMap.get(key);
+    if (!prev) {
+      newServices.push(svc);
+    } else if (prev.service !== svc.service || prev.version !== svc.version) {
+      changedServices.push({
+        port: svc.port,
+        protocol: svc.protocol,
+        previousService: prev.service,
+        previousVersion: prev.version,
+        currentService: svc.service,
+        currentVersion: svc.version,
+      });
+    }
+  }
+
+  const removedServices = [];
+  for (const [key, svc] of prevMap) {
+    if (!currMap.has(key)) {
+      removedServices.push(svc);
+    }
+  }
+
+  const findingsDelta = (current?.findingsCount ?? 0) - (previous?.findingsCount ?? 0);
+
+  // Build human-readable summary
+  const parts = [];
+  if (newServices.length) {
+    parts.push(`${newServices.length} new service(s) detected`);
+  }
+  if (removedServices.length) {
+    parts.push(`${removedServices.length} service(s) removed`);
+  }
+  if (changedServices.length) {
+    parts.push(`${changedServices.length} service(s) changed`);
+  }
+  if (findingsDelta !== 0) {
+    const sign = findingsDelta > 0 ? '+' : '';
+    parts.push(`findings delta: ${sign}${findingsDelta}`);
+  }
+
+  const summary = parts.length > 0
+    ? parts.join(', ') + '.'
+    : 'No changes detected since last scan.';
+
+  return {
+    newServices,
+    removedServices,
+    changedServices,
+    newFindings: findingsDelta,
+    summary,
+  };
+}
+
+const CE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/**
+ * Remove JSONL entries older than 7 days from the given history file.
+ * CE-only — call after each scan for CE tier. Pro/Enterprise: unlimited retention.
+ * Unparseable lines are preserved to avoid data loss.
+ *
+ * @param {string} filePath - absolute path to the JSONL history file
+ * @returns {Promise<void>}
+ */
+export async function pruneForCE(filePath) {
+  let raw;
+  try {
+    raw = await fsp.readFile(filePath, 'utf8');
+  } catch {
+    return; // file doesn't exist yet — nothing to prune
+  }
+  const cutoff = Date.now() - CE_RETENTION_MS;
+  const kept = raw.split('\n').filter(line => {
+    if (!line.trim()) return false;
+    try {
+      const entry = JSON.parse(line);
+      const rawTs = entry.timestamp;
+      if (rawTs == null || rawTs === '') return true; // missing/null timestamp — preserve
+      const ts = new Date(rawTs).getTime();
+      if (isNaN(ts)) return true; // non-parseable string — preserve to avoid data loss
+      return ts >= cutoff;
+    } catch {
+      return true; // keep unparseable lines rather than lose data
+    }
+  });
+  await fsp.writeFile(filePath, kept.join('\n') + (kept.length ? '\n' : ''));
+}
+
+/**
+ * Format a diff object into markdown-like text lines.
+ * @param {object} diff - output from computeDiff()
+ * @returns {string}
+ */
+export function formatDiffReport(diff) {
+  if (!diff) return '';
+
+  const lines = [];
+  lines.push('## Scan Comparison');
+  lines.push('');
+  lines.push(diff.summary);
+  lines.push('');
+
+  if (diff.newServices.length) {
+    lines.push('### New Services');
+    for (const svc of diff.newServices) {
+      lines.push(`- ${svc.port}/${svc.protocol}: ${svc.service ?? 'unknown'} (${svc.version ?? 'unknown'})`);
+    }
+    lines.push('');
+  }
+
+  if (diff.removedServices.length) {
+    lines.push('### Removed Services');
+    for (const svc of diff.removedServices) {
+      lines.push(`- ${svc.port}/${svc.protocol}: ${svc.service ?? 'unknown'} (${svc.version ?? 'unknown'})`);
+    }
+    lines.push('');
+  }
+
+  if (diff.changedServices.length) {
+    lines.push('### Changed Services');
+    for (const ch of diff.changedServices) {
+      lines.push(`- ${ch.port}/${ch.protocol}: ${ch.previousService ?? 'unknown'} ${ch.previousVersion ?? ''} -> ${ch.currentService ?? 'unknown'} ${ch.currentVersion ?? ''}`);
+    }
+    lines.push('');
+  }
+
+  if (diff.newFindings !== 0) {
+    const sign = diff.newFindings > 0 ? '+' : '';
+    lines.push(`**Findings delta:** ${sign}${diff.newFindings}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/utils/scheduler.mjs

@@ -0,0 +1,157 @@
+// utils/scheduler.mjs
+// Continuous scan scheduler with concurrency control.
+
+/**
+ * Create a scheduler that runs periodic scan cycles across a set of hosts.
+ * @param {object} opts
+ * @param {number} opts.intervalMs - interval between scan cycles in ms
+ * @param {string[]} opts.hosts - hosts to scan each cycle
+ * @param {number} [opts.parallel=1] - max concurrent scans
+ * @param {function} opts.scanFn - async (host) => result — performs the scan
+ * @param {function} [opts.onScanComplete] - (host, result, diff) => void
+ * @param {function} [opts.onCycleComplete] - (results) => void
+ * @returns {object} scheduler instance
+ */
+export function createScheduler(opts) {
+  const {
+    intervalMs,
+    hosts,
+    parallel = 1,
+    scanFn,
+    onScanComplete,
+    onCycleComplete,
+  } = opts;
+
+  if (!intervalMs || intervalMs <= 0) throw new Error('intervalMs must be a positive number');
+  if (!Array.isArray(hosts) || hosts.length === 0) throw new Error('hosts must be a non-empty array');
+  if (typeof scanFn !== 'function') throw new Error('scanFn must be a function');
+
+  let _running = false;
+  let _timer = null;
+  let _cycleInProgress = false;
+  let _stopRequested = false;
+  let _cyclePromise = null;
+
+  /**
+   * Run scans for all hosts with concurrency control (semaphore pattern).
+   * @returns {Promise<Map<string, object>>} host → result map
+   */
+  async function runCycle() {
+    _cycleInProgress = true;
+    const results = new Map();
+    const concurrency = Math.max(1, parallel);
+    let running = 0;
+    let idx = 0;
+
+    await new Promise((resolve) => {
+      if (hosts.length === 0) return resolve();
+
+      const tryNext = () => {
+        while (running < concurrency && idx < hosts.length) {
+          if (_stopRequested) {
+            // Don't start new scans, but let in-progress ones finish
+            if (running === 0) return resolve();
+            return;
+          }
+          const h = hosts[idx++];
+          running++;
+          scanFn(h)
+            .then((result) => {
+              results.set(h, result);
+              if (typeof onScanComplete === 'function') {
+                try { onScanComplete(h, result, null); } catch { /* swallow callback errors */ }
+              }
+            })
+            .catch((err) => {
+              const errResult = { error: err?.message || String(err) };
+              results.set(h, errResult);
+              if (typeof onScanComplete === 'function') {
+                try { onScanComplete(h, errResult, null); } catch { /* swallow */ }
+              }
+            })
+            .finally(() => {
+              running--;
+              if (results.size === hosts.length) return resolve();
+              tryNext();
+            });
+        }
+        // If stop was requested and nothing is running, resolve
+        if (_stopRequested && running === 0) return resolve();
+      };
+      tryNext();
+    });
+
+    if (typeof onCycleComplete === 'function') {
+      try { await onCycleComplete(results); } catch (err) { console.error('[scheduler] onCycleComplete error:', err?.message || err); }
+    }
+
+    _cycleInProgress = false;
+    return results;
+  }
+
+  const scheduler = {
+    /**
+     * Begin periodic scanning.
+     */
+    start() {
+      if (_running) return;
+      _running = true;
+      _stopRequested = false;
+
+      // Run first cycle immediately, then schedule subsequent ones
+      const kick = async () => {
+        if (_stopRequested) return;
+        _cyclePromise = runCycle();
+        await _cyclePromise;
+        _cyclePromise = null;
+      };
+
+      kick(); // fire-and-forget first cycle
+      _timer = setInterval(() => {
+        if (!_cycleInProgress && !_stopRequested) {
+          kick();
+        }
+      }, intervalMs);
+    },
+
+    /**
+     * Stop scheduling. Waits for any in-progress cycle to finish.
+     * @returns {Promise<void>}
+     */
+    async stop() {
+      if (!_running) return;
+      _stopRequested = true;
+
+      if (_timer !== null) {
+        clearInterval(_timer);
+        _timer = null;
+      }
+
+      // Wait for in-progress cycle to complete
+      if (_cyclePromise) {
+        await _cyclePromise;
+      }
+
+      _running = false;
+      _stopRequested = false;
+      _cycleInProgress = false;
+    },
+
+    /**
+     * @returns {boolean} whether the scheduler is running
+     */
+    isRunning() {
+      return _running;
+    },
+
+    /**
+     * Run a single scan cycle immediately (independent of the interval timer).
+     * @returns {Promise<Map<string, object>>}
+     */
+    async runOnce() {
+      return runCycle();
+    },
+  };
+
+  return scheduler;
+}

package/utils/webhook.mjs

@@ -0,0 +1,177 @@
+// utils/webhook.mjs
+// Webhook notification utilities — pure Node.js, no external deps.
+
+import http from 'node:http';
+import https from 'node:https';
+import { isBlockedIp, resolveAndValidate } from './net_validation.mjs';
+
+/**
+ * Validate that a URL is http or https.
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isValidWebhookUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate that a webhook URL is safe for external use (blocks SSRF targets).
+ * Apply this at the CLI/user-input boundary, not inside sendWebhook itself.
+ * Performs DNS resolution to defeat rebinding / encoded-IP bypasses.
+ * @param {string} url
+ * @returns {Promise<boolean>}
+ */
+export async function isSafeWebhookUrl(url) {
+  if (!isValidWebhookUrl(url)) return false;
+  const host = new URL(url).hostname.toLowerCase();
+  // Fast-path: block obvious loopback, link-local, cloud metadata, and private ranges
+  if (/^(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[0-1])\.|169\.254\.|0\.|localhost$|metadata\.google)/i.test(host)) {
+    return false;
+  }
+  if (host === '::1' || host === '[::1]' || /^fe80:/i.test(host)) return false;
+
+  // DNS resolution check — catches rebinding, decimal/octal IPs, IPv6-mapped addrs
+  try {
+    await resolveAndValidate(host);
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+// Injectable SSRF checker — overridable in tests only (see _setWebhookSafeChecker).
+let _safeChecker = isSafeWebhookUrl;
+
+/**
+ * Override the SSRF checker used by sendWebhook. Test-only — throws in production.
+ * @internal
+ */
+export function _setWebhookSafeChecker(fn) {
+  if (process.env.NODE_ENV === 'production') throw new Error('_setWebhookSafeChecker is not available in production');
+  _safeChecker = fn ?? isSafeWebhookUrl;
+}
+
+/**
+ * Send a JSON payload to a webhook URL via HTTP POST.
+ * @param {string} url - webhook endpoint (http or https)
+ * @param {object} payload - JSON-serializable data
+ * @param {object} [opts]
+ * @param {number} [opts.timeout=10000] - request timeout in ms
+ * @param {number} [opts.retries=2] - retry count on failure
+ * @param {number} [opts.retryDelayMs=1000] - delay between retries in ms
+ * @returns {Promise<{ success: boolean, statusCode: number, error?: string }>}
+ */
+export async function sendWebhook(url, payload, opts = {}) {
+  // Enforce SSRF safety at the function level — covers scheduler, programmatic,
+  // and any other callers that bypass CLI parseArgs validation.
+  const safe = await _safeChecker(url);
+  if (!safe) {
+    return { success: false, statusCode: 0, error: 'URL rejected by SSRF guard' };
+  }
+
+  const timeout = opts.timeout ?? 10000;
+  const retries = opts.retries ?? 2;
+  const retryDelayMs = opts.retryDelayMs ?? 1000;
+
+  const body = JSON.stringify(payload);
+  const parsed = new URL(url);
+  const transport = parsed.protocol === 'https:' ? https : http;
+
+  const requestOptions = {
+    method: 'POST',
+    hostname: parsed.hostname,
+    port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+    path: parsed.pathname + parsed.search,
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+    },
+    timeout,
+  };
+
+  let lastError = null;
+  const maxAttempts = 1 + retries;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (attempt > 0 && retryDelayMs > 0) {
+      await new Promise((r) => setTimeout(r, retryDelayMs));
+    }
+
+    try {
+      const result = await new Promise((resolve, reject) => {
+        const req = transport.request(requestOptions, (res) => {
+          // Consume response body to free socket
+          const chunks = [];
+          res.on('data', (c) => chunks.push(c));
+          res.on('end', () => {
+            const statusCode = res.statusCode;
+            const success = statusCode >= 200 && statusCode < 300;
+            resolve({ success, statusCode });
+          });
+        });
+
+        req.on('timeout', () => {
+          req.destroy();
+          reject(new Error('Request timed out'));
+        });
+
+        req.on('error', (err) => {
+          reject(err);
+        });
+
+        req.write(body);
+        req.end();
+      });
+
+      if (result.success) return result;
+      // 4xx = client error, won't succeed on retry
+      if (result.statusCode >= 400 && result.statusCode < 500) {
+        return { success: false, statusCode: result.statusCode, error: `HTTP ${result.statusCode}` };
+      }
+      // 5xx or other: retry
+      lastError = `HTTP ${result.statusCode}`;
+      if (attempt === maxAttempts - 1) {
+        return { success: false, statusCode: result.statusCode, error: lastError };
+      }
+    } catch (err) {
+      lastError = err?.message || String(err);
+      if (attempt === maxAttempts - 1) {
+        return { success: false, statusCode: 0, error: lastError };
+      }
+    }
+  }
+
+  // Should not reach here, but safety net
+  return { success: false, statusCode: 0, error: lastError || 'Unknown error' };
+}
+
+/**
+ * Build a standardised alert payload for webhook delivery.
+ * @param {string} host - scanned host
+ * @param {object[]} findings - array of finding objects
+ * @param {string} [severity='high'] - alert severity level
+ * @returns {object} alert payload
+ */
+export function buildAlertPayload(host, findings, severity = 'high') {
+  const items = Array.isArray(findings) ? findings : [];
+
+  return {
+    timestamp: new Date().toISOString(),
+    host,
+    severity,
+    findingsCount: items.length,
+    summary: `${items.length} finding(s) detected on ${host} at severity ${severity} or above`,
+    details: items.map((f) => ({
+      port: f.port ?? null,
+      protocol: f.protocol ?? 'tcp',
+      service: f.service ?? null,
+      description: f.description ?? f.summary ?? null,
+      severity: f.severity ?? severity,
+    })),
+  };
+}