nsauditor-ai 0.1.12 → 0.1.21

package/utils/report_md.mjs

@@ -0,0 +1,308 @@
+// utils/report_md.mjs
+// Render scan conclusion as GitHub-flavored Markdown.
+//
+// Used by:
+//   - CLI --output-format md → writes scan_report.md alongside other formats
+//   - MCP scan_host tool → returns ready-to-quote markdown block in the tool response
+//
+// Pure synchronous renderer — no I/O, no network. Empty-conclusion inputs produce a
+// minimal report (header + "no services detected") rather than throwing, so callers
+// don't need to guard before invocation.
+
+const SEVERITIES = ['Critical', 'High', 'Medium', 'Low', 'Info'];
+
+/**
+ * Escape Markdown special characters that would break table cell rendering.
+ * Pipes break tables; backticks break inline code; newlines break row layout.
+ */
+function escapeCell(value) {
+  if (value == null) return '';
+  return String(value)
+    .replace(/\|/g, '\\|')
+    .replace(/`/g, '\\`')
+    .replace(/[\r\n]+/g, ' ');
+}
+
+/**
+ * Trim a value for table display; '' if null/undefined/'Unknown'.
+ */
+function cell(value) {
+  if (value == null) return '';
+  const s = String(value).trim();
+  if (!s || s === 'Unknown') return '';
+  return escapeCell(s);
+}
+
+/**
+ * Extract security findings from per-service fields.
+ * Mirrors the per-service finding extraction used by sarif.mjs and export_csv.mjs:
+ * findings are derived from service flags (anonymousLogin, weakAlgorithms, cves, etc.),
+ * not from a separate findings array on the conclusion (which doesn't exist today).
+ *
+ * @param {object[]} services
+ * @param {string} host
+ * @returns {Array<{ severity: string, title: string, target: string, evidence: string|null }>}
+ */
+function extractFindings(services, host) {
+  const findings = [];
+
+  for (const svc of services) {
+    const target = `${host}:${svc.port}/${svc.protocol || 'tcp'}`;
+
+    if (svc.anonymousLogin === true) {
+      findings.push({
+        severity: 'Critical',
+        title: 'FTP anonymous login enabled',
+        target,
+        evidence: `${svc.service || 'ftp'} on ${target} accepts anonymous authentication.`,
+      });
+    }
+
+    if (svc.axfrAllowed === true) {
+      findings.push({
+        severity: 'Critical',
+        title: 'DNS zone transfer (AXFR) allowed',
+        target,
+        evidence: `Zone transfer permitted on ${target}; entire zone may be enumerated.`,
+      });
+    }
+
+    if (svc.community && (svc.community === 'public' || svc.community === 'private')) {
+      findings.push({
+        severity: 'High',
+        title: `SNMP default community string: ${svc.community}`,
+        target,
+        evidence: `SNMP responds to community "${svc.community}" on ${target}.`,
+      });
+    }
+
+    if (Array.isArray(svc.weakAlgorithms) && svc.weakAlgorithms.length > 0) {
+      const algos = svc.weakAlgorithms
+        .map((a) => (typeof a === 'string' ? a : a?.algorithm || a?.name || ''))
+        .filter(Boolean);
+      findings.push({
+        severity: 'Medium',
+        title: `Weak algorithm(s) supported: ${algos.join(', ')}`,
+        target,
+        evidence: null,
+      });
+    }
+
+    if (Array.isArray(svc.weakProtocols) && svc.weakProtocols.length > 0) {
+      findings.push({
+        severity: 'Medium',
+        title: `Weak protocol(s) enabled: ${svc.weakProtocols.join(', ')}`,
+        target,
+        evidence: null,
+      });
+    }
+
+    if (Array.isArray(svc.weakCiphers) && svc.weakCiphers.length > 0) {
+      findings.push({
+        severity: 'Medium',
+        title: `Weak cipher(s) supported: ${svc.weakCiphers.length} cipher(s)`,
+        target,
+        evidence: svc.weakCiphers.slice(0, 5).join(', '),
+      });
+    }
+
+    if (Array.isArray(svc.dangerousMethods) && svc.dangerousMethods.length > 0) {
+      findings.push({
+        severity: 'Medium',
+        title: `Dangerous HTTP method(s) allowed: ${svc.dangerousMethods.join(', ')}`,
+        target,
+        evidence: null,
+      });
+    }
+
+    const cves = svc.cves || svc.cve || [];
+    if (Array.isArray(cves)) {
+      for (const cve of cves) {
+        const cveId = typeof cve === 'string' ? cve : (cve?.id || cve?.cveId || '');
+        if (!cveId) continue;
+        const sev = (typeof cve === 'object' && cve?.severity) ? String(cve.severity) : 'High';
+        findings.push({
+          severity: normalizeSeverity(sev),
+          title: `${cveId} — ${svc.program || svc.service || 'service'}${svc.version && svc.version !== 'Unknown' ? ' ' + svc.version : ''}`,
+          target,
+          evidence: `See https://nvd.nist.gov/vuln/detail/${cveId}`,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function normalizeSeverity(sev) {
+  if (!sev) return 'Info';
+  const s = String(sev).trim().toLowerCase();
+  if (s.startsWith('crit')) return 'Critical';
+  if (s.startsWith('hi'))   return 'High';
+  if (s.startsWith('med'))  return 'Medium';
+  if (s.startsWith('lo'))   return 'Low';
+  return 'Info';
+}
+
+function severityRank(sev) {
+  // Lower index → higher priority for sorting
+  const idx = SEVERITIES.indexOf(sev);
+  return idx === -1 ? SEVERITIES.length : idx;
+}
+
+/**
+ * Compute a fenced-code-block delimiter that's guaranteed not to be closed
+ * prematurely by backtick runs inside the content. Per CommonMark §4.5, the
+ * closing fence must contain at least as many backticks as the opening fence,
+ * so we pick (longest internal run + 1), with a floor of 3 (the standard).
+ *
+ * Defensive against Markdown injection when evidence contains user-supplied
+ * data (banner snippets, probe responses) that may include literal ``` runs.
+ *
+ * @param {*} content - The content that will be wrapped in the fenced block.
+ * @returns {string} Backtick string of appropriate length (length >= 3).
+ */
+function safeFenceFor(content) {
+  const matches = String(content ?? '').match(/`+/g) || [];
+  let longestRun = 0;
+  for (const m of matches) {
+    if (m.length > longestRun) longestRun = m.length;
+  }
+  const fenceLen = Math.max(3, longestRun + 1);
+  return '`'.repeat(fenceLen);
+}
+
+/**
+ * Build a GitHub-flavored Markdown scan report.
+ *
+ * @param {object} scanData
+ * @param {string} scanData.host - Target host (IP or hostname)
+ * @param {object} scanData.conclusion - Concluder output: { result: { services }, summary, host }
+ * @param {string} [scanData.aiAnalysis] - Optional AI-generated analysis text (Markdown or plain)
+ * @param {string} [scanData.toolVersion] - Tool version string (e.g. "0.1.15")
+ * @param {string|Date} [scanData.scanTime] - Scan timestamp (defaults to now in ISO format)
+ * @returns {string} Markdown report
+ */
+export function buildMarkdownReport(scanData) {
+  if (!scanData || typeof scanData !== 'object') {
+    throw new TypeError('scanData required');
+  }
+
+  const host = scanData.host ?? '(unknown host)';
+  const conclusion = scanData.conclusion ?? {};
+  const services = conclusion?.result?.services ?? [];
+  const hostInfo = conclusion?.host ?? {};
+  const summaryText = conclusion?.summary ?? '';
+  const toolVersion = scanData.toolVersion ?? '';
+  const scanTime = scanData.scanTime instanceof Date
+    ? scanData.scanTime.toISOString()
+    : (scanData.scanTime ?? new Date().toISOString());
+
+  const lines = [];
+
+  // ---- Header ----
+  lines.push(`# NSAuditor AI Scan Report`);
+  lines.push('');
+  const headerRows = [
+    ['Host', host],
+    ['Scan time', scanTime],
+  ];
+  if (toolVersion) headerRows.push(['Tool version', toolVersion]);
+  if (hostInfo.os) headerRows.push(['OS', `${hostInfo.os}${hostInfo.osVersion ? ' ' + hostInfo.osVersion : ''}`]);
+  if (hostInfo.name && hostInfo.name !== host) headerRows.push(['Hostname', hostInfo.name]);
+  for (const [k, v] of headerRows) {
+    lines.push(`- **${k}:** ${escapeCell(v)}`);
+  }
+  lines.push('');
+
+  // ---- Summary ----
+  lines.push(`## Summary`);
+  lines.push('');
+  if (summaryText) {
+    lines.push(escapeCell(summaryText));
+    lines.push('');
+  }
+  lines.push(`- **Services detected:** ${services.length}`);
+
+  const findings = extractFindings(services, host);
+  if (findings.length > 0) {
+    const counts = {};
+    for (const sev of SEVERITIES) counts[sev] = 0;
+    for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
+    const sevSummary = SEVERITIES
+      .filter((s) => counts[s] > 0)
+      .map((s) => `${s}: ${counts[s]}`)
+      .join(', ');
+    lines.push(`- **Security findings:** ${findings.length} (${sevSummary})`);
+  } else {
+    lines.push(`- **Security findings:** 0`);
+  }
+  lines.push('');
+
+  // ---- Services table ----
+  lines.push(`## Services`);
+  lines.push('');
+  if (services.length === 0) {
+    lines.push('_No services detected._');
+    lines.push('');
+  } else {
+    lines.push('| Port | Protocol | Service | Program | Version | Status |');
+    lines.push('|------|----------|---------|---------|---------|--------|');
+    for (const svc of services) {
+      lines.push([
+        '',
+        cell(svc.port),
+        cell(svc.protocol || 'tcp'),
+        cell(svc.service),
+        cell(svc.program),
+        cell(svc.version),
+        cell(svc.status),
+        '',
+      ].join(' | ').trim());
+    }
+    lines.push('');
+  }
+
+  // ---- Findings ----
+  lines.push(`## Findings`);
+  lines.push('');
+  if (findings.length === 0) {
+    lines.push('_No security findings._');
+    lines.push('');
+  } else {
+    findings.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+    for (const f of findings) {
+      lines.push(`### [${f.severity}] ${f.title}`);
+      lines.push('');
+      lines.push(`- **Target:** ${escapeCell(f.target)}`);
+      if (f.evidence) {
+        lines.push('- **Evidence:**');
+        lines.push('');
+        const fence = safeFenceFor(f.evidence);
+        lines.push('  ' + fence);
+        lines.push('  ' + String(f.evidence).split(/\r?\n/).join('\n  '));
+        lines.push('  ' + fence);
+      }
+      lines.push('');
+    }
+  }
+
+  // ---- AI Analysis (optional) ----
+  if (scanData.aiAnalysis && String(scanData.aiAnalysis).trim()) {
+    lines.push(`## AI Analysis`);
+    lines.push('');
+    lines.push(String(scanData.aiAnalysis).trim());
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// Internal helpers exported for testing.
+export const _internals = {
+  extractFindings,
+  normalizeSeverity,
+  severityRank,
+  escapeCell,
+  safeFenceFor,
+};

package/utils/tool_version.mjs

@@ -0,0 +1,30 @@
+// utils/tool_version.mjs
+//
+// Single source of truth for the nsauditor-ai package version, resolved at
+// module-load time from package.json via createRequire.
+//
+// Why a dedicated module:
+//   - process.env.npm_package_version is ONLY set when invoked via `npm run`.
+//     When users invoke through the bin shim (the normal install path) it's
+//     undefined, which silently produced empty version fields in rendered
+//     reports prior to v0.1.16 (see Task N.15 / N.6 review).
+//   - Centralizing the resolution avoids each consumer reinventing the
+//     pattern (or inventing a broken version of it).
+
+import { createRequire } from 'node:module';
+
+const _require = createRequire(import.meta.url);
+const _pkg = _require('../package.json');
+
+/**
+ * The nsauditor-ai package version, e.g. "0.1.16".
+ * Resolved from package.json — independent of how the process was invoked.
+ * @type {string}
+ */
+export const TOOL_VERSION = _pkg.version;
+
+/**
+ * The nsauditor-ai package name, e.g. "nsauditor-ai".
+ * @type {string}
+ */
+export const TOOL_NAME = _pkg.name;

package/utils/validate.mjs

@@ -0,0 +1,293 @@
+// utils/validate.mjs
+//
+// Pre-flight environment validation for the `nsauditor-ai validate` CLI command.
+// Verifies that the runtime environment is correctly configured WITHOUT running
+// a scan: plugins load, license JWT is valid (if set), at least one AI provider
+// is configured, output dir is writable with adequate free space, and DNS
+// resolution works.
+//
+// Designed to:
+//   - Complete in <2s end-to-end (each check has its own timeout)
+//   - Run hermetically in CI (no real network required — uses 'localhost')
+//   - Be Docker HEALTHCHECK friendly (exit code 0/1/2)
+//   - Support both human-readable and JSON output modes (CLI handles formatting)
+//
+// Each check returns a CheckResult: { name, status, message, details? }
+//   status:  'ok' | 'warn' | 'error' | 'skip'
+//
+// Dependencies are injectable via opts so tests can substitute fakes.
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import dnsP from 'node:dns/promises';
+import { fileURLToPath } from 'node:url';
+import { resolveBaseOutDir } from './output_dir.mjs';
+
+// Package root — derived from THIS file's location (utils/validate.mjs) by
+// going up one directory. Used as the default plugin-discovery base so that
+// `nsauditor-ai validate` finds the plugins shipped with the package, NOT
+// whatever happens to be in the user's cwd. Fixed in v0.1.21 (Task N.25).
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const STATUSES = Object.freeze({
+  OK:    'ok',
+  WARN:  'warn',
+  ERROR: 'error',
+  SKIP:  'skip',
+});
+
+const FREE_SPACE_WARN_MB = 100;
+const DEFAULT_NETWORK_TIMEOUT_MS = 1500;
+const DEFAULT_NETWORK_HOST = 'localhost'; // hermetic — no external dependency
+
+/**
+ * Verify all installed plugins load without error.
+ *
+ * Discovery base is the **package root** (derived from this file's location),
+ * not `process.cwd()`. Critical: when the bin shim is invoked from anywhere
+ * other than the install dir, `process.cwd()` is the user's working
+ * directory — which has no plugins. v0.1.20 had this bug; fixed in v0.1.21.
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.discover] - Override for testing.
+ * @param {string}   [opts.pkgRoot]  - Override package root path (test injection).
+ */
+export async function checkPlugins({ discover, pkgRoot = PKG_ROOT } = {}) {
+  try {
+    const fn = discover || (await import('./plugin_discovery.mjs')).discoverPlugins;
+    const result = await fn(pkgRoot);
+    const plugins = Array.isArray(result) ? result : (result?.plugins ?? []);
+    return {
+      name: 'plugins',
+      status: STATUSES.OK,
+      message: `${plugins.length} plugin${plugins.length === 1 ? '' : 's'} loaded`,
+      details: { count: plugins.length, basePath: pkgRoot },
+    };
+  } catch (err) {
+    return {
+      name: 'plugins',
+      status: STATUSES.ERROR,
+      message: `Plugin discovery failed: ${err.message}`,
+      details: { error: err.message, basePath: pkgRoot },
+    };
+  }
+}
+
+/**
+ * If NSAUDITOR_LICENSE_KEY is set, verify the JWT and report the resolved tier.
+ * Otherwise, skip (CE works fine without a license).
+ */
+export async function checkLicense({ loadFn, env = process.env } = {}) {
+  const key = env.NSAUDITOR_LICENSE_KEY;
+  if (!key) {
+    return {
+      name: 'license',
+      status: STATUSES.SKIP,
+      message: 'No license key set — running as Community Edition',
+      details: { tier: 'ce' },
+    };
+  }
+  try {
+    const fn = loadFn || (await import('./license.mjs')).loadLicense;
+    const result = await fn(key);
+    if (!result.valid) {
+      return {
+        name: 'license',
+        status: STATUSES.ERROR,
+        message: `License invalid: ${result.reason || 'unknown reason'}`,
+        details: { tier: result.tier ?? 'ce', reason: result.reason },
+      };
+    }
+    // Warn if expiring within 7 days
+    const days = Number(result.daysUntilExpiry);
+    if (Number.isFinite(days) && days <= 7) {
+      return {
+        name: 'license',
+        status: STATUSES.WARN,
+        message: `License valid (${result.tier}) but expires in ${days} day${days === 1 ? '' : 's'}`,
+        details: { tier: result.tier, daysUntilExpiry: days, expiresAt: result.expiresAt },
+      };
+    }
+    return {
+      name: 'license',
+      status: STATUSES.OK,
+      message: `License valid (${result.tier}, ${result.org || 'unknown org'})`,
+      details: { tier: result.tier, org: result.org, expiresAt: result.expiresAt },
+    };
+  } catch (err) {
+    return {
+      name: 'license',
+      status: STATUSES.ERROR,
+      message: `License verification threw: ${err.message}`,
+      details: { error: err.message },
+    };
+  }
+}
+
+/**
+ * Verify at least one AI provider is configured. Warn if none — AI is optional
+ * but most users want it.
+ */
+export function checkAiProviders({ env = process.env } = {}) {
+  const providers = [];
+  if (env.OPENAI_API_KEY)    providers.push('openai');
+  if (env.ANTHROPIC_API_KEY) providers.push('claude');
+  // Ollama is host-based, not key-based — presence of OLLAMA_HOST or default localhost both count
+  if (env.OLLAMA_HOST || env.AI_PROVIDER === 'ollama') providers.push('ollama');
+
+  if (providers.length === 0) {
+    return {
+      name: 'ai_providers',
+      status: STATUSES.WARN,
+      message: 'No AI provider configured — AI analysis will be skipped (set OPENAI_API_KEY, ANTHROPIC_API_KEY, or AI_PROVIDER=ollama)',
+      details: { providers: [] },
+    };
+  }
+  return {
+    name: 'ai_providers',
+    status: STATUSES.OK,
+    message: `${providers.length} provider${providers.length === 1 ? '' : 's'} configured: ${providers.join(', ')}`,
+    details: { providers },
+  };
+}
+
+/**
+ * Verify the resolved output directory is writable. Warn if free space is below
+ * the configured threshold (100 MB by default).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - Override resolved dir for testing.
+ * @param {object} [opts.fsApi] - Override fsp for testing.
+ */
+export async function checkOutputDir({ dir, fsApi = fsp, freeSpaceWarnMB = FREE_SPACE_WARN_MB } = {}) {
+  const target = dir ?? resolveBaseOutDir();
+  try {
+    await fsApi.mkdir(target, { recursive: true });
+    // Round-trip a tiny file to prove writability
+    const probe = path.join(target, `.nsauditor-validate-${process.pid}`);
+    await fsApi.writeFile(probe, 'ok', 'utf8');
+    await fsApi.unlink(probe);
+  } catch (err) {
+    return {
+      name: 'output_dir',
+      status: STATUSES.ERROR,
+      message: `Output dir not writable (${target}): ${err.message}`,
+      details: { dir: target, error: err.message },
+    };
+  }
+  // Free-space check — fs.promises.statfs is Node 19+ (project requires Node 20+).
+  // If the API throws (rare; some filesystems don't support it), surface as a warn,
+  // not an error — writability already proved.
+  let freeBytes = null;
+  try {
+    if (typeof fsApi.statfs === 'function') {
+      const st = await fsApi.statfs(target);
+      // bavail is blocks available to non-root user; bsize is block size
+      freeBytes = Number(st.bavail) * Number(st.bsize);
+    }
+  } catch { /* statfs unsupported — skip the free-space portion */ }
+
+  if (freeBytes != null) {
+    const freeMB = Math.floor(freeBytes / (1024 * 1024));
+    if (freeMB < freeSpaceWarnMB) {
+      return {
+        name: 'output_dir',
+        status: STATUSES.WARN,
+        message: `Output dir writable (${target}) but only ${freeMB} MB free (threshold ${freeSpaceWarnMB} MB)`,
+        details: { dir: target, freeMB, threshold: freeSpaceWarnMB },
+      };
+    }
+    return {
+      name: 'output_dir',
+      status: STATUSES.OK,
+      message: `Output dir writable (${target}), ${freeMB} MB free`,
+      details: { dir: target, freeMB },
+    };
+  }
+  return {
+    name: 'output_dir',
+    status: STATUSES.OK,
+    message: `Output dir writable (${target})`,
+    details: { dir: target },
+  };
+}
+
+/**
+ * Verify DNS resolution works. Defaults to 'localhost' for hermetic CI runs;
+ * override via `host` for environments where the user wants to test external
+ * resolution.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.host] - Hostname to resolve.
+ * @param {number} [opts.timeoutMs]
+ * @param {Function} [opts.lookup] - Override dnsP.lookup for testing.
+ */
+export async function checkNetwork({
+  host = DEFAULT_NETWORK_HOST,
+  timeoutMs = DEFAULT_NETWORK_TIMEOUT_MS,
+  lookup = dnsP.lookup,
+} = {}) {
+  let timer;
+  const lookupP = lookup(host).then((res) => {
+    // dns.lookup returns { address, family }
+    return res?.address || (Array.isArray(res) ? res[0]?.address : null);
+  });
+  const timeoutP = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`DNS timeout after ${timeoutMs}ms`)), timeoutMs);
+  });
+  try {
+    const address = await Promise.race([lookupP, timeoutP]);
+    return {
+      name: 'network',
+      status: STATUSES.OK,
+      message: `DNS resolution OK (${host} → ${address})`,
+      details: { host, address },
+    };
+  } catch (err) {
+    return {
+      name: 'network',
+      status: STATUSES.WARN,
+      message: `DNS resolution failed (${host}): ${err.message}`,
+      details: { host, error: err.message },
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Run all validation checks in parallel and aggregate results.
+ *
+ * Exit-code mapping (computed here for the CLI):
+ *   - any 'error' → exit 2
+ *   - any 'warn'  → exit 1
+ *   - else        → exit 0
+ *
+ * @param {object} [opts] - Forwarded to individual check functions for testability.
+ * @returns {Promise<{ overall: 'ok'|'warn'|'error', checks: object[], exitCode: 0|1|2 }>}
+ */
+export async function runValidation(opts = {}) {
+  const checks = await Promise.all([
+    checkPlugins(opts.plugins ?? {}),
+    checkLicense(opts.license ?? {}),
+    Promise.resolve(checkAiProviders(opts.ai ?? {})),
+    checkOutputDir(opts.outputDir ?? {}),
+    checkNetwork(opts.network ?? {}),
+  ]);
+
+  let overall = STATUSES.OK;
+  for (const c of checks) {
+    if (c.status === STATUSES.ERROR) { overall = STATUSES.ERROR; break; }
+    if (c.status === STATUSES.WARN && overall !== STATUSES.ERROR) overall = STATUSES.WARN;
+  }
+  const exitCode = overall === STATUSES.ERROR ? 2 : overall === STATUSES.WARN ? 1 : 0;
+  return { overall, checks, exitCode };
+}
+
+// Internal constants exposed for testing.
+export const _internals = {
+  FREE_SPACE_WARN_MB,
+  DEFAULT_NETWORK_TIMEOUT_MS,
+  DEFAULT_NETWORK_HOST,
+  PKG_ROOT,
+};