nsauditor-ai 0.1.0

package/utils/export_csv.mjs

@@ -0,0 +1,82 @@
+// utils/export_csv.mjs
+// Export scan results as CSV.
+
+/**
+ * Escape a CSV field value.
+ * - Wrap in double quotes if contains comma, newline, or double quote
+ * - Escape double quotes by doubling them
+ * @param {*} value
+ * @returns {string}
+ */
+export function escapeCsvField(value) {
+  if (value == null) return '';
+  let str = String(value);
+  // Defend against CSV formula injection in spreadsheets
+  if (/^[=+\-@\t\r]/.test(str)) {
+    str = "'" + str;
+  }
+  if (/[",\r\n]/.test(str)) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+const COLUMNS = ['host', 'port', 'protocol', 'service', 'program', 'version', 'status', 'cpe', 'security_findings'];
+
+/**
+ * Build a security_findings string from a service record.
+ * @param {object} svc
+ * @returns {string}
+ */
+function buildFindings(svc) {
+  const parts = [];
+
+  if (Array.isArray(svc.weakAlgorithms) && svc.weakAlgorithms.length) {
+    parts.push(`weak_algorithms:${svc.weakAlgorithms.length}`);
+  }
+  if (svc.anonymousLogin) {
+    parts.push('anonymous_login');
+  }
+  if (svc.axfrAllowed) {
+    parts.push('axfr_allowed');
+  }
+  if (Array.isArray(svc.dangerousMethods) && svc.dangerousMethods.length) {
+    parts.push(`dangerous_methods:${svc.dangerousMethods.join(';')}`);
+  }
+  if (svc.community) {
+    parts.push(`default_community:${svc.community}`);
+  }
+
+  return parts.join(',');
+}
+
+/**
+ * Build CSV string from scan conclusion.
+ * Columns: host, port, protocol, service, program, version, status, cpe, security_findings
+ *
+ * @param {{ host: string, conclusion: object }} scanData
+ * @returns {string} CSV content with header row
+ */
+export function buildCsv(scanData) {
+  const { host, conclusion } = scanData;
+  const services = conclusion?.result?.services ?? [];
+
+  const header = COLUMNS.join(',');
+  const rows = services.map((svc) => {
+    const findings = buildFindings(svc);
+    const fields = [
+      host,
+      svc.port ?? '',
+      svc.protocol ?? '',
+      svc.service ?? '',
+      svc.program ?? '',
+      svc.version ?? '',
+      svc.status ?? '',
+      svc.cpe ?? '',
+      findings,
+    ];
+    return fields.map(escapeCsvField).join(',');
+  });
+
+  return [header, ...rows].join('\r\n') + '\r\n';
+}

package/utils/finding_queue.mjs

@@ -0,0 +1,64 @@
+// utils/finding_queue.mjs
+
+import { validateFinding, generateFindingId } from './finding_schema.mjs';
+
+const SEVERITY_SCORE = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, INFO: 0 };
+
+export class FindingQueue {
+  constructor() {
+    this.findings = [];
+  }
+
+  add(finding) {
+    const errors = validateFinding(finding);
+    if (errors.length > 0) throw new Error(`Invalid finding: ${errors.join(', ')}`);
+    const id = finding.id || generateFindingId();
+    this.findings.push({ ...finding, id });
+    return id;
+  }
+
+  getByCategory(cat) {
+    return this.findings.filter(f => f.category === cat);
+  }
+
+  getByStatus(status) {
+    return this.findings.filter(f => f.status === status);
+  }
+
+  getUnverified() {
+    return this.getByStatus('UNVERIFIED');
+  }
+
+  markVerified(id, verification) {
+    const f = this._find(id);
+    f.status = 'VERIFIED';
+    f.evidence = { ...(f.evidence ?? {}), verification };
+  }
+
+  markFalsePositive(id, reason) {
+    const f = this._find(id);
+    f.status = 'FALSE_POSITIVE';
+    f.falsePositiveReason = reason;
+  }
+
+  prioritize() {
+    this.findings.sort(
+      (a, b) => (SEVERITY_SCORE[b.severity] ?? 0) - (SEVERITY_SCORE[a.severity] ?? 0)
+    );
+    return this;
+  }
+
+  toJSON() {
+    return JSON.parse(JSON.stringify(this.findings));
+  }
+
+  get size() {
+    return this.findings.length;
+  }
+
+  _find(id) {
+    const f = this.findings.find(f => f.id === id);
+    if (!f) throw new Error(`Finding not found: ${id}`);
+    return f;
+  }
+}

package/utils/finding_schema.mjs

@@ -0,0 +1,36 @@
+// utils/finding_schema.mjs
+import { v4 as uuidv4 } from 'uuid';
+
+export const FINDING_CATEGORIES = ['AUTH', 'CRYPTO', 'CONFIG', 'SERVICE', 'EXPOSURE', 'CVE'];
+export const FINDING_STATUSES   = ['UNVERIFIED', 'VERIFIED', 'POTENTIAL', 'FALSE_POSITIVE'];
+export const FINDING_SEVERITIES = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
+export const FINDING_EFFORTS    = ['LOW', 'MEDIUM', 'HIGH'];
+
+/**
+ * Validate a finding object against the schema.
+ * @param {object} f
+ * @returns {string[]} Array of error messages; empty = valid
+ */
+export function validateFinding(f) {
+  const errors = [];
+  if (!FINDING_CATEGORIES.includes(f?.category))
+    errors.push(`invalid category: ${f?.category}`);
+  if (!FINDING_STATUSES.includes(f?.status))
+    errors.push(`invalid status: ${f?.status}`);
+  if (!FINDING_SEVERITIES.includes(f?.severity))
+    errors.push(`invalid severity: ${f?.severity}`);
+  if (!f?.title || typeof f.title !== 'string')
+    errors.push('title required');
+  if (!f?.target?.host)
+    errors.push('target.host required');
+  return errors;
+}
+
+/**
+ * Generate a globally unique finding ID.
+ * Format: F-<uuid-v4> (e.g. F-3d7e4b2a-91f0-4c3e-b8a6-7f2d5e9c1a04)
+ * UUID-based — no counter to reset, no collision risk across restarts.
+ */
+export function generateFindingId() {
+  return `F-${uuidv4()}`;
+}

package/utils/host_iterator.mjs

@@ -0,0 +1,166 @@
+// utils/host_iterator.mjs
+// Expand host specifications: single IP, CIDR notation, or host file paths.
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Parse a dotted-quad IPv4 string into a 32-bit unsigned integer.
+ * Throws on invalid format.
+ */
+function ipToUint32(ip) {
+  const parts = ip.split('.');
+  if (parts.length !== 4) throw new Error(`Invalid IPv4 address: ${ip}`);
+  let num = 0;
+  for (let i = 0; i < 4; i++) {
+    const octet = Number(parts[i]);
+    if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
+      throw new Error(`Invalid IPv4 address: ${ip}`);
+    }
+    num = (num * 256) + octet;
+  }
+  return num >>> 0; // ensure unsigned
+}
+
+/**
+ * Convert a 32-bit unsigned integer back to dotted-quad string.
+ */
+function uint32ToIp(num) {
+  return [
+    (num >>> 24) & 0xFF,
+    (num >>> 16) & 0xFF,
+    (num >>> 8) & 0xFF,
+    num & 0xFF
+  ].join('.');
+}
+
+/**
+ * Expand a CIDR notation string to an array of host IPs.
+ * Example: '192.168.1.0/30' → ['192.168.1.1', '192.168.1.2']
+ * Excludes network address and broadcast address for /31 and larger.
+ * For /32 returns the single IP. For /31 returns both IPs (point-to-point).
+ */
+export function expandCidr(cidr) {
+  const parts = cidr.split('/');
+  if (parts.length !== 2) throw new Error(`Invalid CIDR notation: ${cidr}`);
+
+  const ip = parts[0];
+  const prefix = Number(parts[1]);
+
+  if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) {
+    throw new Error(`Invalid prefix length: ${parts[1]} (must be 0-32)`);
+  }
+  if (prefix < 16) {
+    throw new Error(`Prefix /${prefix} too large (max 65534 hosts). Minimum prefix is /16.`);
+  }
+
+  const ipNum = ipToUint32(ip); // validates IP format
+
+  if (prefix === 32) {
+    return [ip];
+  }
+
+  if (prefix === 31) {
+    // RFC 3021 point-to-point: return both IPs
+    const mask = (0xFFFFFFFF << (32 - prefix)) >>> 0;
+    const network = (ipNum & mask) >>> 0;
+    return [uint32ToIp(network), uint32ToIp((network + 1) >>> 0)];
+  }
+
+  // Standard subnets: exclude network and broadcast
+  const mask = (0xFFFFFFFF << (32 - prefix)) >>> 0;
+  const network = (ipNum & mask) >>> 0;
+  const broadcast = (network | (~mask >>> 0)) >>> 0;
+  const hosts = [];
+  for (let addr = network + 1; addr < broadcast; addr++) {
+    hosts.push(uint32ToIp(addr >>> 0));
+  }
+  return hosts;
+}
+
+/**
+ * Read a host file (one host per line, # comments, blank lines ignored).
+ */
+const HOST_LINE_RE = /^[\w.:\/\-]+$/;
+
+export async function parseHostFile(filePath) {
+  const content = await fsp.readFile(filePath, 'utf8');
+  return content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'))
+    .filter((line) => {
+      if (!HOST_LINE_RE.test(line)) {
+        console.warn(`[host-file] Ignoring suspicious line: ${line.slice(0, 50)}`);
+        return false;
+      }
+      return true;
+    });
+}
+
+/**
+ * Expand a dash-range notation to an array of IPs.
+ * Example: '192.168.1.1-50' → ['192.168.1.1', '192.168.1.2', ..., '192.168.1.50']
+ * Also supports full IP ranges: '192.168.1.1-192.168.1.50'
+ */
+export function expandRange(range) {
+  // Full range: 192.168.1.1-192.168.1.50
+  const fullMatch = range.match(/^(\d{1,3}(?:\.\d{1,3}){3})-(\d{1,3}(?:\.\d{1,3}){3})$/);
+  if (fullMatch) {
+    const startNum = ipToUint32(fullMatch[1]);
+    const endNum = ipToUint32(fullMatch[2]);
+    if (endNum < startNum) throw new Error(`Invalid range: end < start in ${range}`);
+    const count = endNum - startNum + 1;
+    if (count > 65534) throw new Error(`Range too large: ${count} hosts (max 65534)`);
+    const hosts = [];
+    for (let i = startNum; i <= endNum; i++) hosts.push(uint32ToIp(i >>> 0));
+    return hosts;
+  }
+
+  // Short range: 192.168.1.1-50 (last octet range)
+  const shortMatch = range.match(/^(\d{1,3}\.\d{1,3}\.\d{1,3})\.(\d{1,3})-(\d{1,3})$/);
+  if (shortMatch) {
+    const prefix = shortMatch[1];
+    const start = Number(shortMatch[2]);
+    const end = Number(shortMatch[3]);
+    if (start > 255 || end > 255) throw new Error(`Invalid octet in range: ${range}`);
+    if (end < start) throw new Error(`Invalid range: end < start in ${range}`);
+    const hosts = [];
+    for (let i = start; i <= end; i++) hosts.push(`${prefix}.${i}`);
+    return hosts;
+  }
+
+  throw new Error(`Invalid range notation: ${range}`);
+}
+
+/**
+ * Detect input type and return array of hosts.
+ * - If contains '/' → CIDR
+ * - If contains '-' with IP pattern → dash range
+ * - If file exists → host file
+ * - Otherwise → single IP/hostname
+ */
+export async function parseHostArg(arg) {
+  // Match CIDR notation: digits.digits.digits.digits/digits
+  if (/^\d{1,3}(\.\d{1,3}){3}\/\d{1,2}$/.test(arg)) {
+    return expandCidr(arg);
+  }
+
+  // Match dash-range notation: 192.168.1.1-50 or 192.168.1.1-192.168.1.50
+  if (/^\d{1,3}(\.\d{1,3}){3}-\d/.test(arg)) {
+    return expandRange(arg);
+  }
+
+  // Path traversal guard: reject absolute paths and paths resolving outside cwd
+  if (path.isAbsolute(arg)) return [arg]; // treat as hostname, not file
+  const resolved = path.resolve(arg);
+  if (!resolved.startsWith(process.cwd() + path.sep)) return [arg]; // outside CWD = hostname
+
+  try {
+    await fsp.access(arg);
+    return parseHostFile(arg);
+  } catch {
+    // Not a file — treat as single host
+    return [arg];
+  }
+}

package/utils/license.mjs

@@ -0,0 +1,29 @@
+// utils/license.mjs
+// CE stub implementation. Full ES256 JWT validation added in Phase 2 (roadmap).
+
+/**
+ * Parse tier from NSAUDITOR_LICENSE_KEY environment variable.
+ * Stub uses key prefix: pro_* → 'pro', enterprise_* → 'enterprise'.
+ * Phase 2 roadmap replaces this with offline jose ES256 JWT verification.
+ */
+export function getTierFromEnv() {
+  const key = process.env.NSAUDITOR_LICENSE_KEY;
+  if (!key) return 'ce';
+  if (key.startsWith('pro_')) return 'pro';
+  if (key.startsWith('enterprise_')) return 'enterprise';
+  return 'ce';
+}
+
+/**
+ * Validate a license key string.
+ * Phase 2 roadmap: replace with jose.jwtVerify() against embedded ECDSA P-256 public key.
+ * Gracefully degrades to CE on any failure — never throws.
+ *
+ * @param {string|undefined} keyStr
+ * @returns {Promise<{valid: boolean, tier: string, reason: string}>}
+ */
+export async function loadLicense(keyStr) {
+  if (!keyStr) return { valid: false, tier: 'ce', reason: 'no key provided' };
+  // TODO (Phase 2): implement jose.jwtVerify with embedded public key
+  return { valid: false, tier: 'ce', reason: 'JWT validation not yet implemented' };
+}

package/utils/net_validation.mjs

@@ -0,0 +1,66 @@
+// utils/net_validation.mjs
+// Shared IP/host validation utilities for SSRF prevention.
+
+import dns from 'node:dns/promises';
+
+/**
+ * Check whether an IP address belongs to a blocked (internal/private) range.
+ * Covers loopback, RFC 1918, RFC 6598, link-local, unspecified, and IPv6 equivalents.
+ * @param {string} ip
+ * @returns {boolean}
+ */
+export function isBlockedIp(ip) {
+  const addr = ip.replace(/^\[|\]$/g, '').trim();
+
+  // IPv6-mapped IPv4 — extract the IPv4 part and check it
+  const mappedMatch = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  if (mappedMatch) return isBlockedIp(mappedMatch[1]);
+
+  // IPv6 blocked addresses
+  if (addr === '::1' || addr === '::') return true;
+  if (/^fe80:/i.test(addr)) return true;                     // link-local (fe80::/10)
+  if (/^f[cd]/i.test(addr.slice(0, 2))) return true;        // fc00::/7 unique local (fc__ and fd__)
+  // IPv4-compatible loopback: ::127.0.0.1 maps to 127.0.0.1/8
+  const compatMatch = addr.match(/^::(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  if (compatMatch) return isBlockedIp(compatMatch[1]);
+
+  // IPv4 checks
+  const parts = addr.split('.');
+  if (parts.length === 4 && parts.every((p) => /^\d{1,3}$/.test(p))) {
+    const [a, b] = parts.map(Number);
+    if (a === 127) return true;                          // 127.0.0.0/8  (loopback)
+    if (a === 10) return true;                           // 10.0.0.0/8   (RFC 1918)
+    if (a === 172 && b >= 16 && b <= 31) return true;    // 172.16.0.0/12 (RFC 1918)
+    if (a === 192 && b === 168) return true;             // 192.168.0.0/16 (RFC 1918)
+    if (a === 100 && b >= 64 && b <= 127) return true;   // 100.64.0.0/10 (RFC 6598 CGNAT)
+    if (a === 169 && b === 254) return true;             // 169.254.0.0/16 (link-local)
+    if (a === 0) return true;                            // 0.0.0.0/8
+  }
+
+  return false;
+}
+
+/**
+ * True when `ip` is a private/local-network address.
+ * Plugins that operate only on local networks use this to filter targets.
+ * @param {string|null|undefined} ip
+ * @returns {boolean}
+ */
+export function isPrivateLike(ip) {
+  if (!ip) return false;
+  return isBlockedIp(ip);
+}
+
+/**
+ * Resolve a hostname and verify the resolved IP is not in a blocked range.
+ * @param {string} hostname
+ * @returns {Promise<string>} resolved IP address
+ * @throws {Error} if hostname resolves to a blocked IP or DNS fails
+ */
+export async function resolveAndValidate(hostname) {
+  const { address } = await dns.lookup(hostname);
+  if (isBlockedIp(address)) {
+    throw new Error(`Host resolves to blocked IP range`);
+  }
+  return address;
+}

package/utils/nvd_cache.mjs

@@ -0,0 +1,77 @@
+// utils/nvd_cache.mjs
+// File-based cache for NVD API responses to respect rate limits.
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+const DEFAULT_TTL_DAYS = 7;
+const MAX_ENTRIES = 10000;
+
+export class NvdCache {
+  constructor(cacheDir = '.nvd_cache') {
+    this.cacheFile = path.resolve(cacheDir, 'nvd_cache.json');
+    this.ttlMs = (Number(process.env.NVD_CACHE_TTL_DAYS) || DEFAULT_TTL_DAYS) * 86400000;
+    this._data = null;
+    this._writeQueue = Promise.resolve();
+  }
+
+  async _load() {
+    if (this._data) return;
+    try {
+      const raw = await fsp.readFile(this.cacheFile, 'utf8');
+      this._data = JSON.parse(raw);
+    } catch {
+      this._data = {};
+    }
+    this._sweepExpired();
+  }
+
+  _sweepExpired() {
+    const now = Date.now();
+    for (const key of Object.keys(this._data)) {
+      if (now - this._data[key].timestamp > this.ttlMs) {
+        delete this._data[key];
+      }
+    }
+  }
+
+  _evictOldest() {
+    const entries = Object.entries(this._data);
+    entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
+    const excess = entries.length - MAX_ENTRIES;
+    for (let i = 0; i < excess; i++) {
+      delete this._data[entries[i][0]];
+    }
+  }
+
+  async _save() {
+    await fsp.mkdir(path.dirname(this.cacheFile), { recursive: true });
+    await fsp.writeFile(this.cacheFile, JSON.stringify(this._data, null, 2), 'utf8');
+  }
+
+  async get(key) {
+    await this._load();
+    const entry = this._data[key];
+    if (!entry) return null;
+    if (Date.now() - entry.timestamp > this.ttlMs) {
+      delete this._data[key];
+      return null;
+    }
+    return entry.data;
+  }
+
+  async set(key, data) {
+    this._writeQueue = this._writeQueue.then(async () => {
+      await this._load();
+      this._data[key] = { data, timestamp: Date.now() };
+      if (Object.keys(this._data).length > MAX_ENTRIES) {
+        this._sweepExpired();
+        if (Object.keys(this._data).length > MAX_ENTRIES) {
+          this._evictOldest();
+        }
+      }
+      await this._save();
+    });
+    return this._writeQueue;
+  }
+}

package/utils/nvd_client.mjs

@@ -0,0 +1,130 @@
+// utils/nvd_client.mjs
+// NVD 2.0 API client with rate limiting and caching.
+
+import { NvdCache } from './nvd_cache.mjs';
+
+const NVD_BASE = 'https://services.nvd.nist.gov/rest/json/cves/2.0';
+
+// --- Rate limiter (sliding window) ---
+
+export class RateLimiter {
+  constructor(maxRequests, windowMs) {
+    this.max = maxRequests;
+    this.windowMs = windowMs;
+    this.timestamps = [];
+  }
+
+  async wait() {
+    const now = Date.now();
+    this.timestamps = this.timestamps.filter(t => now - t < this.windowMs);
+    if (this.timestamps.length >= this.max) {
+      const waitMs = this.windowMs - (now - this.timestamps[0]);
+      if (waitMs > 0) await new Promise(r => setTimeout(r, waitMs));
+    }
+    this.timestamps.push(Date.now());
+  }
+}
+
+// --- Helpers ---
+
+function extractCvss(metrics) {
+  const m31 = metrics?.cvssMetricV31?.[0]?.cvssData;
+  if (m31) return m31;
+  const m30 = metrics?.cvssMetricV30?.[0]?.cvssData;
+  return m30 || null;
+}
+
+function parseCve(vuln) {
+  const { cve } = vuln;
+  const cvss = extractCvss(cve.metrics);
+  const enDesc = cve.descriptions?.find(d => d.lang === 'en');
+  return {
+    cveId: cve.id,
+    description: enDesc?.value ?? '',
+    cvssScore: cvss?.baseScore ?? null,
+    severity: cvss?.baseSeverity ?? null,
+    vectorString: cvss?.vectorString ?? null,
+    published: cve.published,
+    lastModified: cve.lastModified,
+  };
+}
+
+// --- Client ---
+
+class NvdClient {
+  constructor({ apiKey, cacheDir } = {}) {
+    this.apiKey = apiKey || process.env.NVD_API_KEY || null;
+    this.cache = new NvdCache(cacheDir);
+    // With API key: 50 req / 30s. Without: 5 req / 30s.
+    const max = this.apiKey ? 50 : 5;
+    this.limiter = new RateLimiter(max, 30_000);
+  }
+
+  async _fetch(url) {
+    await this.limiter.wait();
+    const headers = {};
+    if (this.apiKey) headers.apiKey = this.apiKey;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 15_000);
+    try {
+      const res = await fetch(url, { headers, signal: controller.signal });
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`NVD API ${res.status}: ${text}`);
+      }
+      return res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async queryCvesByCpe(cpeString) {
+    const cacheKey = `cpe:${cpeString}`;
+    const cached = await this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    const url = `${NVD_BASE}?cpeName=${encodeURIComponent(cpeString)}`;
+    const body = await this._fetch(url);
+    const results = (body.vulnerabilities || []).map(parseCve);
+
+    await this.cache.set(cacheKey, results);
+    return results;
+  }
+
+  async validateCveId(cveId) {
+    const cacheKey = `cve:${cveId}`;
+    const cached = await this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    let result;
+    try {
+      const url = `${NVD_BASE}?cveId=${encodeURIComponent(cveId)}`;
+      const body = await this._fetch(url);
+      const vulns = body.vulnerabilities || [];
+      if (vulns.length === 0) {
+        result = { exists: false, cveId };
+      } else {
+        const parsed = parseCve(vulns[0]);
+        result = {
+          exists: true,
+          cveId: parsed.cveId,
+          cvssScore: parsed.cvssScore,
+          severity: parsed.severity,
+          description: parsed.description,
+        };
+      }
+    } catch {
+      // Transient failure — don't cache, return unknown
+      return { exists: false, cveId, transient: true };
+    }
+
+    await this.cache.set(cacheKey, result);
+    return result;
+  }
+}
+
+// --- Factory ---
+
+export function createNvdClient(options) {
+  return new NvdClient(options);
+}