nsauditor-ai 0.1.0

package/utils/attack_map.mjs

@@ -0,0 +1,180 @@
+// utils/attack_map.mjs
+// MITRE ATT&CK mapping for network security audit findings.
+// Maps service types, CVEs, and scan findings to ATT&CK technique IDs.
+
+/**
+ * Technique definition: { techniqueId, name }
+ */
+const T = (techniqueId, name) => ({ techniqueId, name });
+
+/**
+ * Mapping from finding/service patterns to ATT&CK techniques.
+ */
+export const SERVICE_TECHNIQUE_MAP = {
+  ssh_cve:              [T('T1021.004', 'Remote Services: SSH')],
+  smb_cve:              [T('T1021.002', 'Remote Services: SMB/Windows Admin Shares')],
+  ftp_anonymous:        [T('T1078', 'Valid Accounts'), T('T1530', 'Data from Cloud Storage Object')],
+  dns_zone_transfer:    [T('T1590.002', 'Gather Victim Network Information: DNS')],
+  snmp_default:         [T('T1078', 'Valid Accounts'), T('T1040', 'Network Sniffing')],
+  http_dangerous:       [T('T1190', 'Exploit Public-Facing Application')],
+  privesc_cve:          [T('T1068', 'Exploitation for Privilege Escalation')],
+  default_credentials:  [T('T1110', 'Brute Force')],
+  tls_weakness:         [T('T1557', 'Adversary-in-the-Middle')],
+  rdp_exposure:         [T('T1021.001', 'Remote Services: RDP')],
+  mdns_llmnr_exposure:  [T('T1557.001', 'LLMNR/NBT-NS Poisoning')],
+};
+
+/**
+ * Convert a technique ID to a MITRE ATT&CK URL.
+ * Sub-techniques use dot notation (T1021.004) which maps to slash paths (/T1021/004/).
+ * @param {string} techniqueId - e.g. "T1021.004" or "T1190"
+ * @returns {string} Full URL
+ */
+export function attackUrl(techniqueId) {
+  const path = String(techniqueId).replace(/\./g, '/');
+  return `https://attack.mitre.org/techniques/${path}/`;
+}
+
+/**
+ * Map a service record to matching ATT&CK techniques.
+ * Inspects service type and boolean/array fields to identify relevant techniques.
+ *
+ * @param {object} service - Service record from scan conclusion
+ * @returns {Array<{ techniqueId: string, name: string, url: string }>}
+ */
+export function mapServiceToAttack(service) {
+  if (!service || typeof service !== 'object') return [];
+
+  const techniques = [];
+  const svcName = String(service.service || '').toLowerCase();
+
+  // FTP anonymous login
+  if (service.anonymousLogin === true) {
+    techniques.push(...SERVICE_TECHNIQUE_MAP.ftp_anonymous);
+  }
+
+  // DNS zone transfer
+  if (service.axfrAllowed === true) {
+    techniques.push(...SERVICE_TECHNIQUE_MAP.dns_zone_transfer);
+  }
+
+  // SNMP default community string
+  if (service.community === 'public' || service.community === 'private') {
+    techniques.push(...SERVICE_TECHNIQUE_MAP.snmp_default);
+  }
+
+  // HTTP dangerous methods
+  if (Array.isArray(service.dangerousMethods) && service.dangerousMethods.length > 0) {
+    techniques.push(...SERVICE_TECHNIQUE_MAP.http_dangerous);
+  }
+
+  // TLS/SSL weaknesses
+  if (
+    (Array.isArray(service.weakAlgorithms) && service.weakAlgorithms.length > 0) ||
+    (Array.isArray(service.weakCiphers) && service.weakCiphers.length > 0) ||
+    (Array.isArray(service.weakProtocols) && service.weakProtocols.length > 0)
+  ) {
+    techniques.push(...SERVICE_TECHNIQUE_MAP.tls_weakness);
+  }
+
+  // RDP exposure
+  if (svcName === 'rdp' || svcName === 'ms-wbt-server') {
+    techniques.push(...SERVICE_TECHNIQUE_MAP.rdp_exposure);
+  }
+
+  // mDNS / LLMNR exposure
+  if (svcName === 'mdns' || svcName === 'llmnr') {
+    techniques.push(...SERVICE_TECHNIQUE_MAP.mdns_llmnr_exposure);
+  }
+
+  // Default/weak credentials (generic flag)
+  if (service.defaultCredentials === true || service.weakCredentials === true) {
+    techniques.push(...SERVICE_TECHNIQUE_MAP.default_credentials);
+  }
+
+  // CVE-based mappings
+  const cves = service.cves || service.cve || [];
+  if (Array.isArray(cves)) {
+    for (const cve of cves) {
+      const cveId = typeof cve === 'string' ? cve : (cve?.id || cve?.cveId || '');
+      if (cveId) {
+        techniques.push(...mapCveToAttack(cveId, svcName));
+      }
+    }
+  }
+
+  return dedup(techniques).map(t => ({ ...t, url: attackUrl(t.techniqueId) }));
+}
+
+/**
+ * Map a CVE + service context to ATT&CK technique(s).
+ * Uses the service type to determine the most relevant technique category.
+ *
+ * @param {string} cveId - e.g. "CVE-2023-12345"
+ * @param {string} [serviceType] - e.g. "ssh", "smb", "http"
+ * @returns {Array<{ techniqueId: string, name: string }>}
+ */
+export function mapCveToAttack(cveId, serviceType) {
+  if (!cveId) return [];
+
+  const svc = String(serviceType || '').toLowerCase();
+  const id = String(cveId).toUpperCase();
+
+  // Service-specific CVE mapping
+  if (svc === 'ssh' || svc === 'openssh') {
+    return [...SERVICE_TECHNIQUE_MAP.ssh_cve];
+  }
+  if (svc === 'smb' || svc === 'microsoft-ds' || svc === 'netbios-ssn') {
+    return [...SERVICE_TECHNIQUE_MAP.smb_cve];
+  }
+  if (svc === 'rdp' || svc === 'ms-wbt-server') {
+    return [...SERVICE_TECHNIQUE_MAP.rdp_exposure];
+  }
+  if (svc === 'http' || svc === 'https' || svc === 'http-proxy') {
+    return [...SERVICE_TECHNIQUE_MAP.http_dangerous];
+  }
+  if (svc === 'ftp') {
+    return [...SERVICE_TECHNIQUE_MAP.http_dangerous]; // T1190: exploiting a public-facing service
+  }
+  if (svc === 'dns' || svc === 'domain') {
+    return [...SERVICE_TECHNIQUE_MAP.dns_zone_transfer];
+  }
+
+  // No service context — cannot reliably map to a specific ATT&CK technique
+
+  return [];
+}
+
+/**
+ * Collect all ATT&CK techniques across all services in a scan conclusion.
+ * Returns deduplicated list.
+ *
+ * @param {object} conclusion - Full scan conclusion: { result: { services: [...] } }
+ * @returns {Array<{ techniqueId: string, name: string, url: string }>}
+ */
+export function getAllTechniques(conclusion) {
+  const services = conclusion?.result?.services ?? [];
+  if (!Array.isArray(services) || services.length === 0) return [];
+
+  const all = [];
+  for (const svc of services) {
+    all.push(...mapServiceToAttack(svc));
+  }
+
+  return dedup(all).map(t => t.url ? t : { ...t, url: attackUrl(t.techniqueId) });
+}
+
+/**
+ * Deduplicate techniques by techniqueId.
+ * @param {Array<{ techniqueId: string, name: string }>} techniques
+ * @returns {Array<{ techniqueId: string, name: string }>}
+ */
+function dedup(techniques) {
+  const seen = new Map();
+  for (const t of techniques) {
+    if (!seen.has(t.techniqueId)) {
+      seen.set(t.techniqueId, { techniqueId: t.techniqueId, name: t.name });
+    }
+  }
+  return [...seen.values()];
+}

package/utils/capabilities.mjs

@@ -0,0 +1,53 @@
+// utils/capabilities.mjs
+
+export const CAPABILITIES = {
+  // CE (always available)
+  coreScanning:       { tier: 'ce' },
+  aiAnalysis:         { tier: 'ce' },  // Any provider (OpenAI/Claude/Ollama), basic prompts
+  basicCTEM:          { tier: 'ce' },
+  basicRedaction:     { tier: 'ce' },
+  basicMCP:           { tier: 'ce' },
+  findingQueue:       { tier: 'ce' },
+
+  // Pro
+  intelligenceEngine: { tier: 'pro' },
+  riskScoring:        { tier: 'pro' },
+  proAI:              { tier: 'pro' },
+  analysisAgents:     { tier: 'pro' },
+  verificationEngine: { tier: 'pro' },
+  advancedCTEM:       { tier: 'pro' },
+  enhancedRedaction:  { tier: 'pro' },
+  proMCP:             { tier: 'pro' },
+  pdfExport:          { tier: 'pro' },
+  brandedReports:     { tier: 'pro' },
+
+  // Enterprise
+  cloudScanners:      { tier: 'enterprise' },
+  zeroTrust:          { tier: 'enterprise' },
+  complianceEngine:   { tier: 'enterprise' },
+  zdePolicyEngine:    { tier: 'enterprise' },
+  enterpriseCTEM:     { tier: 'enterprise' },
+  enterpriseMCP:      { tier: 'enterprise' },
+  usageMetering:      { tier: 'enterprise' },
+  airGapped:          { tier: 'enterprise' },
+  dockerIsolation:    { tier: 'enterprise' },
+};
+
+const TIER_CAPS = {
+  ce:         new Set(['ce']),
+  pro:        new Set(['ce', 'pro']),
+  enterprise: new Set(['ce', 'pro', 'enterprise']),
+};
+
+export function resolveCapabilities(tier = 'ce') {
+  const allowed = TIER_CAPS[tier] ?? TIER_CAPS.ce;
+  const caps = {};
+  for (const [key, def] of Object.entries(CAPABILITIES)) {
+    caps[key] = allowed.has(def.tier);
+  }
+  return caps;
+}
+
+export function hasCapability(capabilities, cap) {
+  return Boolean(capabilities?.[cap]);
+}

package/utils/conclusion_utils.mjs

@@ -0,0 +1,70 @@
+// utils/conclusion_utils.mjs
+// Shared helpers for normalizing plugin findings into service records.
+
+import { generateCpe } from './cpe.mjs';
+
+export const keyOf = (svc) => `${(svc.protocol || 'tcp').toLowerCase()}:${Number(svc.port)}`;
+
+export const firstDataRow = (res) =>
+  Array.isArray(res?.data) ? res.data.find(Boolean) : null;
+
+export function statusFrom({ info, banner, fallbackUp }) {
+  const s = `${info || ''} ${banner || ''}`.toLowerCase();
+  if (/connection refused|closed/.test(s)) return 'closed';
+  if (/filtered|no route|host unreachable/.test(s)) return 'filtered';
+  if (/\bopen\b|\bready\b|^220(?:-| )/m.test(s)) return 'open';
+  if (typeof fallbackUp === 'boolean') return fallbackUp ? 'open' : 'unknown';
+  return 'unknown';
+}
+
+export function normalizeService(svc) {
+  return {
+    port: Number(svc.port),
+    protocol: (svc.protocol || 'tcp').toLowerCase(),
+    service: String(svc.service || 'unknown').toLowerCase(),
+    program: svc.program ?? null,
+    version: svc.version ?? null,
+    cpe: svc.program ? generateCpe(svc.program, svc.version) : null,
+    status: svc.status || 'unknown',
+    info: svc.info ?? null,
+    banner: svc.banner ?? null,
+    source: svc.source || 'unknown',
+    evidence: Array.isArray(svc.evidence) ? svc.evidence : []
+  };
+}
+
+// Merge by protocol:port with basic authority precedence.
+// If 'authoritative' flag is true on a record, it wins over non-authoritative.
+export function upsertService(services, next, { authoritative = false } = {}) {
+  const key = keyOf(next);
+  const i = services.findIndex(s => keyOf(s) === key);
+  if (i === -1) {
+    services.push({ ...next, __authoritative: !!authoritative });
+    return;
+  }
+  const cur = services[i];
+  // Authority precedence
+  if (authoritative && !cur.__authoritative) {
+    services[i] = { ...cur, ...next, __authoritative: true };
+    return;
+  }
+  if (!authoritative && cur.__authoritative) {
+    // keep current authoritative, but allow filling blanks
+    services[i] = {
+      ...cur,
+      program: cur.program || next.program || null,
+      version: cur.version || next.version || null,
+      info: cur.info || next.info || null,
+      banner: cur.banner || next.banner || null,
+      evidence: (cur.evidence || []).concat(next.evidence || [])
+    };
+    return;
+  }
+  // Same authority level: last-write-wins while preserving non-null fields
+  services[i] = {
+    ...cur,
+    ...next,
+    evidence: (cur.evidence || []).concat(next.evidence || []),
+    __authoritative: cur.__authoritative || authoritative
+  };
+}

package/utils/cpe.mjs

@@ -0,0 +1,74 @@
+// utils/cpe.mjs
+// CPE 2.3 string generator for known service programs.
+
+export const CPE_MAP = {
+  'nginx':        { vendor: 'nginx',       product: 'nginx' },
+  'openssh':      { vendor: 'openbsd',     product: 'openssh' },
+  'apache':       { vendor: 'apache',      product: 'http_server' },
+  'proftpd':      { vendor: 'proftpd',     product: 'proftpd' },
+  'pure-ftpd':    { vendor: 'pureftpd',    product: 'pure-ftpd' },
+  'bftpd':        { vendor: 'bftpd',       product: 'bftpd' },
+  'isc bind':     { vendor: 'isc',         product: 'bind' },
+  'bind':         { vendor: 'isc',         product: 'bind' },
+  'microsoft-iis':{ vendor: 'microsoft',   product: 'internet_information_services' },
+  'iis':          { vendor: 'microsoft',   product: 'internet_information_services' },
+  'lighttpd':     { vendor: 'lighttpd',    product: 'lighttpd' },
+  'tomcat':       { vendor: 'apache',      product: 'tomcat' },
+  'mysql':        { vendor: 'oracle',      product: 'mysql' },
+  'postgresql':   { vendor: 'postgresql',  product: 'postgresql' },
+  'mongodb':      { vendor: 'mongodb',     product: 'mongodb' },
+  'redis':        { vendor: 'redis',       product: 'redis' },
+  'opensearch':   { vendor: 'amazon',      product: 'opensearch' },
+  'elasticsearch':{ vendor: 'elastic',     product: 'elasticsearch' },
+  'vsftpd':       { vendor: 'beasts',      product: 'vsftpd' },
+  'dropbear':     { vendor: 'dropbear_ssh_project', product: 'dropbear_ssh' },
+  'exim':         { vendor: 'exim',        product: 'exim' },
+  'postfix':      { vendor: 'postfix',     product: 'postfix' },
+  'dovecot':      { vendor: 'dovecot',     product: 'dovecot' },
+  'openssl':      { vendor: 'openssl',     product: 'openssl' },
+};
+
+/**
+ * Escape special characters in a CPE 2.3 component value.
+ * Colons, backslashes, asterisks, and question marks must be escaped.
+ */
+export function escapeCpeComponent(s) {
+  return String(s).replace(/([:\\*?])/g, '\\$1');
+}
+
+/**
+ * Split a version string like "8.2p1" into { version, update }.
+ * Handles dash/underscore separators (e.g. "9.0-rc1", "2.4.57-2").
+ * If no update suffix is found, update defaults to '*'.
+ */
+export function parseVersion(versionString) {
+  if (!versionString) return { version: '*', update: '*' };
+
+  // Match version (digits and dots) followed by optional separator and update suffix.
+  // Supports: "8.2p1", "9.0-rc1", "2.4.57-2", "1.25.0_beta"
+  const m = versionString.match(/^(\d[\d.]*)(?:[-_]([a-zA-Z0-9]\w*)|([a-zA-Z]\w*))?$/);
+  if (!m) return { version: versionString, update: '*' };
+
+  return {
+    version: m[1],
+    update: m[2] || m[3] || '*',
+  };
+}
+
+/**
+ * Generate a CPE 2.3 formatted string for a known program/version.
+ * Returns null when the program is not in CPE_MAP.
+ */
+export function generateCpe(program, version) {
+  if (!program) return null;
+
+  const key = String(program).toLowerCase();
+  const entry = CPE_MAP[key];
+  if (!entry) return null;
+
+  const { version: ver, update } = parseVersion(version || null);
+
+  const safeVer = ver === '*' ? '*' : escapeCpeComponent(ver);
+  const safeUpd = update === '*' ? '*' : escapeCpeComponent(update);
+  return `cpe:2.3:a:${entry.vendor}:${entry.product}:${safeVer}:${safeUpd}:*:*:*:*:*:*`;
+}

package/utils/cve_validator.mjs

@@ -0,0 +1,64 @@
+// utils/cve_validator.mjs
+// Post-processes LLM output to validate CVE IDs against NVD.
+
+import { createNvdClient } from './nvd_client.mjs';
+
+const CVE_RE = /\bCVE-\d{4}-\d{4,}\b/g;
+
+/**
+ * Extract deduplicated CVE IDs from text.
+ * @param {string} text — LLM response text (markdown, plain, etc.)
+ * @returns {string[]}
+ */
+export function extractCveIds(text) {
+  if (!text) return [];
+  const matches = String(text).match(CVE_RE);
+  if (!matches) return [];
+  return [...new Set(matches)];
+}
+
+/**
+ * Validate an array of CVE IDs against NVD.
+ * @param {string[]} cveIds
+ * @param {{ apiKey?: string, cacheDir?: string }} [options]
+ * @returns {Promise<Map<string, { exists: boolean|null, cvssScore?: number, severity?: string }>>}
+ */
+export async function validateCves(cveIds, options) {
+  const client = options?.client ?? createNvdClient(options);
+  const results = new Map();
+
+  for (const id of cveIds) {
+    try {
+      const res = await client.validateCveId(id);
+      results.set(id, {
+        exists: res.exists,
+        ...(res.cvssScore != null && { cvssScore: res.cvssScore }),
+        ...(res.severity != null && { severity: res.severity }),
+      });
+    } catch {
+      // NVD unreachable — mark as unknown
+      results.set(id, { exists: null });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Annotate CVE IDs in text with verification markers.
+ * - Verified:   {{CVE_VERIFIED:CVE-XXXX-XXXXX}}
+ * - Unverified: {{CVE_UNVERIFIED:CVE-XXXX-XXXXX}}
+ * - Unknown (exists: null): left as-is
+ * @param {string} text
+ * @param {Map<string, { exists: boolean|null }>} validationMap
+ * @returns {string}
+ */
+export function annotateCveText(text, validationMap) {
+  if (!text) return text;
+  return String(text).replace(CVE_RE, (match) => {
+    const info = validationMap.get(match);
+    if (!info || info.exists === null) return match;
+    if (info.exists) return `{{CVE_VERIFIED:${match}}}`;
+    return `{{CVE_UNVERIFIED:${match}}}`;
+  });
+}

package/utils/cvss.mjs

@@ -0,0 +1,129 @@
+// utils/cvss.mjs
+// CVSS v3.1 base score calculator following the FIRST.org specification.
+// Pure implementation — no external dependencies.
+
+const METRIC_WEIGHTS = {
+  AV: { N: 0.85, A: 0.62, L: 0.55, P: 0.20 },
+  AC: { L: 0.77, H: 0.44 },
+  PR: {
+    U: { N: 0.85, L: 0.62, H: 0.27 },
+    C: { N: 0.85, L: 0.68, H: 0.50 },
+  },
+  UI: { N: 0.85, R: 0.62 },
+  C:  { H: 0.56, L: 0.22, N: 0 },
+  I:  { H: 0.56, L: 0.22, N: 0 },
+  A:  { H: 0.56, L: 0.22, N: 0 },
+};
+
+const VALID_VALUES = {
+  AV: ['N', 'A', 'L', 'P'],
+  AC: ['L', 'H'],
+  PR: ['N', 'L', 'H'],
+  UI: ['N', 'R'],
+  S:  ['U', 'C'],
+  C:  ['H', 'L', 'N'],
+  I:  ['H', 'L', 'N'],
+  A:  ['H', 'L', 'N'],
+};
+
+const REQUIRED_METRICS = ['AV', 'AC', 'PR', 'UI', 'S', 'C', 'I', 'A'];
+
+function roundUp(val) {
+  return Math.ceil(val * 10) / 10;
+}
+
+/**
+ * Parse a CVSS v3.1 vector string into a metrics object.
+ * @param {string} vectorString — e.g. "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"
+ * @returns {{ AV: string, AC: string, PR: string, UI: string, S: string, C: string, I: string, A: string }}
+ */
+export function parseCvssVector(vectorString) {
+  if (typeof vectorString !== 'string') {
+    throw new Error('CVSS vector must be a string');
+  }
+
+  const trimmed = vectorString.trim();
+  if (!trimmed.startsWith('CVSS:3.1/')) {
+    throw new Error(`Invalid CVSS v3.1 vector prefix: "${trimmed}"`);
+  }
+
+  const parts = trimmed.slice('CVSS:3.1/'.length).split('/');
+  const metrics = {};
+
+  for (const part of parts) {
+    const [key, value] = part.split(':');
+    if (!key || value === undefined) {
+      throw new Error(`Malformed metric component: "${part}"`);
+    }
+    if (!VALID_VALUES[key]) {
+      throw new Error(`Unknown metric key: "${key}"`);
+    }
+    if (!VALID_VALUES[key].includes(value)) {
+      throw new Error(`Invalid value "${value}" for metric "${key}". Valid: ${VALID_VALUES[key].join(', ')}`);
+    }
+    metrics[key] = value;
+  }
+
+  for (const req of REQUIRED_METRICS) {
+    if (!metrics[req]) {
+      throw new Error(`Missing required metric: "${req}"`);
+    }
+  }
+
+  return metrics;
+}
+
+/**
+ * Calculate the CVSS v3.1 base score from a metrics object.
+ * @param {{ AV: string, AC: string, PR: string, UI: string, S: string, C: string, I: string, A: string }} metrics
+ * @returns {number} Base score 0.0–10.0
+ */
+export function calculateBaseScore(metrics) {
+  const scopeChanged = metrics.S === 'C';
+
+  const cWeight = METRIC_WEIGHTS.C[metrics.C];
+  const iWeight = METRIC_WEIGHTS.I[metrics.I];
+  const aWeight = METRIC_WEIGHTS.A[metrics.A];
+
+  const iss = 1 - ((1 - cWeight) * (1 - iWeight) * (1 - aWeight));
+
+  let impact;
+  if (scopeChanged) {
+    impact = 7.52 * (iss - 0.029) - 3.25 * Math.pow(iss - 0.02, 15);
+  } else {
+    impact = 6.42 * iss;
+  }
+
+  if (impact <= 0) return 0.0;
+
+  const avWeight = METRIC_WEIGHTS.AV[metrics.AV];
+  const acWeight = METRIC_WEIGHTS.AC[metrics.AC];
+  const prWeight = scopeChanged
+    ? METRIC_WEIGHTS.PR.C[metrics.PR]
+    : METRIC_WEIGHTS.PR.U[metrics.PR];
+  const uiWeight = METRIC_WEIGHTS.UI[metrics.UI];
+
+  const exploitability = 8.22 * avWeight * acWeight * prWeight * uiWeight;
+
+  let baseScore;
+  if (scopeChanged) {
+    baseScore = roundUp(Math.min(1.08 * (impact + exploitability), 10));
+  } else {
+    baseScore = roundUp(Math.min(impact + exploitability, 10));
+  }
+
+  return baseScore;
+}
+
+/**
+ * Map a numeric CVSS score to its severity label per CVSS v3.1 spec.
+ * @param {number} score — 0.0–10.0
+ * @returns {"None"|"Low"|"Medium"|"High"|"Critical"}
+ */
+export function severityFromScore(score) {
+  if (score === 0.0) return 'None';
+  if (score <= 3.9) return 'Low';
+  if (score <= 6.9) return 'Medium';
+  if (score <= 8.9) return 'High';
+  return 'Critical';
+}

package/utils/delta_reporter.mjs

@@ -0,0 +1,110 @@
+// utils/delta_reporter.mjs
+// Delta reporting: compare two full scan cycles across multiple hosts.
+
+import { computeDiff } from './scan_history.mjs';
+
+/**
+ * Compare two full scan cycle results and produce a delta report.
+ * @param {Map<string, object>|object} currentResults  - host → scan result (Map or plain object)
+ * @param {Map<string, object>|object|null} previousResults - host → scan result from prior cycle
+ * @returns {{ newHosts: string[], removedHosts: string[], hostDiffs: Map<string, object> }}
+ */
+export function buildDeltaReport(currentResults, previousResults) {
+  const currMap = currentResults instanceof Map
+    ? currentResults
+    : new Map(Object.entries(currentResults || {}));
+  const prevMap = previousResults instanceof Map
+    ? previousResults
+    : new Map(Object.entries(previousResults || {}));
+
+  const currentHosts = new Set(currMap.keys());
+  const previousHosts = new Set(prevMap.keys());
+
+  const newHosts = [];
+  for (const h of currentHosts) {
+    if (!previousHosts.has(h)) newHosts.push(h);
+  }
+
+  const removedHosts = [];
+  for (const h of previousHosts) {
+    if (!currentHosts.has(h)) removedHosts.push(h);
+  }
+
+  const hostDiffs = new Map();
+  for (const h of currentHosts) {
+    const curr = currMap.get(h);
+    const prev = prevMap.has(h) ? prevMap.get(h) : null;
+    hostDiffs.set(h, computeDiff(curr, prev));
+  }
+
+  return { newHosts, removedHosts, hostDiffs };
+}
+
+/**
+ * Format a delta report into a human-readable summary string.
+ * @param {{ newHosts: string[], removedHosts: string[], hostDiffs: Map<string, object> }} deltaReport
+ * @returns {string}
+ */
+export function formatDeltaSummary(deltaReport) {
+  if (!deltaReport) return '';
+
+  const lines = [];
+  lines.push('=== Delta Report ===');
+  lines.push('');
+
+  if (deltaReport.newHosts.length) {
+    lines.push(`New hosts (${deltaReport.newHosts.length}): ${deltaReport.newHosts.join(', ')}`);
+  }
+  if (deltaReport.removedHosts.length) {
+    lines.push(`Removed hosts (${deltaReport.removedHosts.length}): ${deltaReport.removedHosts.join(', ')}`);
+  }
+
+  if (deltaReport.hostDiffs && deltaReport.hostDiffs.size > 0) {
+    lines.push('');
+    lines.push('Per-host changes:');
+    for (const [host, diff] of deltaReport.hostDiffs) {
+      lines.push(`  ${host}: ${diff.summary}`);
+    }
+  }
+
+  if (!deltaReport.newHosts.length && !deltaReport.removedHosts.length) {
+    let anyChange = false;
+    if (deltaReport.hostDiffs) {
+      for (const diff of deltaReport.hostDiffs.values()) {
+        if (diff.newServices?.length || diff.removedServices?.length || diff.changedServices?.length || diff.newFindings) {
+          anyChange = true;
+          break;
+        }
+      }
+    }
+    if (!anyChange) {
+      lines.push('No significant changes detected.');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Determine whether a delta report contains significant changes.
+ * Returns true if any new/removed hosts exist, or if any host has service changes.
+ * @param {{ newHosts: string[], removedHosts: string[], hostDiffs: Map<string, object> }} deltaReport
+ * @returns {boolean}
+ */
+export function hasSignificantChanges(deltaReport) {
+  if (!deltaReport) return false;
+
+  if (deltaReport.newHosts.length > 0) return true;
+  if (deltaReport.removedHosts.length > 0) return true;
+
+  if (deltaReport.hostDiffs) {
+    for (const diff of deltaReport.hostDiffs.values()) {
+      if (diff.newServices?.length > 0) return true;
+      if (diff.removedServices?.length > 0) return true;
+      if (diff.changedServices?.length > 0) return true;
+      if (diff.newFindings && diff.newFindings !== 0) return true;
+    }
+  }
+
+  return false;
+}