@fanboynz/network-scanner 3.0.2 → 3.1.0

package/lib/validate_rules.js

@@ -583,7 +583,11 @@ function validateRulesetFile(filePath, options = {}) {
       errors.push(`Line ${lineNumber}: ${validation.error} - ${line}`);
       
       if (errors.length >= maxErrors) {
-        errors.push(`... (stopping after ${maxErrors} errors, ${stats.total - i - 1} lines remaining)`);
+        // Lines remaining in the file = total lines − current index − 1.
+        // (Previously `stats.total - i - 1`, which mixed "non-empty lines
+        // processed" with "file line index" and went negative when empties
+        // were interleaved.)
+        errors.push(`... (stopping after ${maxErrors} errors, ${lines.length - i - 1} lines remaining)`);
         break;
       }
     }
@@ -1075,9 +1079,286 @@ function testDomainValidation() {
   return allPassed;
 }
 
+// ─── Per-site config normalization (runs on every scan, not just --validate-config) ───
+//
+// Catches the silent-failure class that bit a user across multiple scan iterations:
+//   1. Typo'd siteConfig keys (whois_terms vs whois) silently ignored.
+//   2. Boolean fields given truthy/falsy non-boolean values (interact: 1 vs interact: true)
+//      silently disabled by strict `=== true` checks downstream.
+//   3. Misleading downstream warnings that blame the wrong field.
+//
+// normalizeSiteConfig() mutates siteConfig in place (coercing 1→true, etc) and returns
+// warnings the caller surfaces. Designed to run at scan startup, ALWAYS, not gated on
+// --validate-config (which most users never run).
+
+// Whitelist of every siteConfig.X key read across nwss.js + lib/*.js.
+// Regenerate via BOTH:
+//   grep -hoE "siteConfig\.[a-zA-Z_][a-zA-Z0-9_]*" nwss.js lib/*.js | sort -u
+//   grep -hoE "siteConfig\[['\"][^'\"]+['\"]\]" nwss.js lib/*.js | sort -u
+// The second pattern catches bracket-notation access required for keys with
+// hyphens (e.g. 'dig-or', 'whois-or'). Dot-notation grep alone missed these
+// and produced false 'unknown siteConfig key' warnings for valid config.
+// Also grep for destructured siteConfig keys (master destructure block in
+// processUrl) — those don't show up in either pattern.
+const KNOWN_SITE_CONFIG_KEYS = new Set([
+  'adblock_rules', 'blocked', 'bypass_cache', 'capture_popups',
+  'capture_popups_max_depth', 'capture_popups_window_ms', 'cdp', 'cdp_specific',
+  'clear_sitedata', 'clear_sitedata_full_on_reload',
+  'cloudflare_bypass', 'cloudflare_max_retries', 'comments',
+  'cloudflare_parallel_detection', 'cloudflare_phish', 'cloudflare_retry_on_error',
+  'css_blocked', 'curl', 'cursor_mode', 'custom_headers', 'delay',
+  'delay_uncapped', 'detect_js_patterns', 'dig', 'dig-or', 'digRecordType', 'dig_subdomain',
+  'disable_adblock', 'dnsmasq', 'dnsmasq_old', 'evaluateOnNewDocument',
+  'even_blocked',
+  'filterRegex', 'fingerprint_protection', 'firstParty', 'flowproxy_additional_delay',
+  'flowproxy_delay', 'flowproxy_detection', 'flowproxy_js_timeout', 'flowproxy_nav_timeout',
+  'flowproxy_page_timeout', 'forcereload', 'ghost_cursor_duration',
+  'ghost_cursor_hesitate', 'ghost_cursor_overshoot', 'ghost_cursor_speed',
+  'goto_options', 'grep', 'headful', 'ignore_similar', 'ignore_similar_ignored_domains',
+  'ignore_similar_threshold', 'interact', 'interact_click_count', 'interact_clicks',
+  'interact_duration', 'interact_intensity', 'interact_scrolling', 'isBrave',
+  'js_redirect_timeout', 'localhost', 'max_redirects', 'openvpn', 'pihole',
+  'plain', 'privoxy', 'proxy', 'proxy_bypass', 'proxy_debug', 'proxy_remote_dns',
+  'realistic_click', 'referrer_disable', 'referrer_headers', 'regex_and',
+  'reload', 'resourceTypes', 'screenshot', 'searchstring', 'searchstring_and',
+  'socks5_bypass', 'socks5_debug', 'socks5_proxy', 'socks5_remote_dns',
+  'subDomains',
+  'thirdParty', 'timeout', 'unbound', 'url', 'userAgent', 'verbose', 'vpn',
+  'whois', 'whois-or', 'whois_delay', 'whois_max_retries', 'whois_retry_on_error',
+  'whois_retry_on_timeout', 'whois_server', 'whois_server_mode',
+  'whois_timeout_multiplier', 'whois_use_fallback', 'window_cleanup',
+  'window_cleanup_threshold',
+  // Internal sentinel added by nwss.js when fanning array URLs into tasks.
+  '_originalUrl',
+]);
+
+// Boolean siteConfig fields where strict `=== true` is used downstream.
+// Listed only for fields with UNAMBIGUOUS boolean semantics — fields with
+// multi-type overloads stay out:
+//   forcereload         : true | string[]
+//   cloudflare_bypass   : true | 'debug'
+//   cloudflare_phish    : true | 'debug'
+//   window_cleanup      : true | 'all' | 'realtime'
+//   cursor_mode         : string ('ghost')
+// Update both this set AND the strict-equality call sites if a new boolean
+// siteConfig field is added.
+const BOOLEAN_SITE_CONFIG_FIELDS = new Set([
+  'adblock_rules', 'bypass_cache', 'capture_popups', 'cdp', 'clear_sitedata',
+  'clear_sitedata_full_on_reload', 'curl', 'delay_uncapped',
+  'detect_js_patterns', 'dig_subdomain',
+  'disable_adblock', 'dnsmasq', 'dnsmasq_old', 'evaluateOnNewDocument',
+  'even_blocked', 'firstParty', 'flowproxy_detection',
+  'grep', 'headful', 'ignore_similar', 'ignore_similar_ignored_domains',
+  'interact', 'interact_clicks', 'interact_scrolling', 'isBrave', 'localhost',
+  'pihole', 'plain', 'privoxy', 'proxy_debug', 'proxy_remote_dns',
+  'realistic_click', 'referrer_disable', 'regex_and', 'screenshot',
+  'searchstring_and', 'socks5_debug', 'socks5_remote_dns', 'thirdParty',
+  'unbound', 'whois_retry_on_error', 'whois_retry_on_timeout', 'whois_use_fallback',
+]);
+
+// Fields that accept BOTH `"x"` (single term) and `["x", "y"]` (multi-term).
+// Downstream consumers (nwss.js line ~2824, lib/nettools.js line ~1149-1152)
+// do `Array.isArray(val) && val.length > 0` checks, so a string value
+// previously caused silent feature-disable. normalizeSiteConfig() now wraps
+// any string value in a single-element array so both forms are first-class.
+// Non-string non-array values still warn (and stay as-is, since we don't
+// know how to coerce them).
+const STRING_TO_ARRAY_FIELDS = new Set([
+  'dig', 'dig-or', 'whois', 'whois-or',
+]);
+
+// Truthy-but-not-true → true. Falsy-but-not-false → false. Otherwise leave alone.
+// Strings are lower-cased before matching so "True"/"TRUE"/"Yes"/etc all match.
+function _coerceBooleanLike(val) {
+  if (val === true || val === false) return { coerced: false, value: val };
+  const s = typeof val === 'string' ? val.toLowerCase() : val;
+  if (s === 1 || s === '1' || s === 'true' || s === 'yes' || s === 'on') {
+    return { coerced: true, value: true };
+  }
+  if (s === 0 || s === '0' || s === 'false' || s === 'no' || s === 'off') {
+    return { coerced: true, value: false };
+  }
+  return { coerced: false, value: val };
+}
+
+// Tiny Levenshtein for "did you mean?" suggestions. Inlined rather than
+// imported from lib/ignore_similar (which has its own dependency tree we
+// don't want to drag into validation) -- 18 lines of well-known algorithm.
+function _editDistance(a, b) {
+  if (a === b) return 0;
+  if (!a) return b.length;
+  if (!b) return a.length;
+  const m = a.length, n = b.length;
+  let prev = new Array(n + 1);
+  let curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      curr[j] = a[i - 1] === b[j - 1]
+        ? prev[j - 1]
+        : 1 + Math.min(prev[j - 1], prev[j], curr[j - 1]);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+// Suggest a known key for an unknown one. Two parallel candidate searches,
+// then pick the better signal:
+//
+//   1. EDIT-DISTANCE candidate — classic typo case ('intract' → 'interact').
+//      Threshold scales with the unknown key's length (40%, min 2) so short
+//      typos stay matchable.
+//
+//   2. PREFIX candidate — "user added a suffix to a known root" case.
+//      'whois_terms' starts with 'whois' (known key) → suggest 'whois'.
+//      Requires the prefix to be at least 3 chars to avoid spurious matches
+//      on accidental 1-2 letter prefixes. Among multiple prefix candidates,
+//      we take the LONGEST (most specific category boundary).
+//
+// Ranking: if there's a very close edit-distance match (≤2 edits), prefer
+// it — almost certainly a misspelling of that specific key (e.g.
+// 'whois_max_retri' → 'whois_max_retries' at distance 2 beats the prefix
+// match 'whois'). Otherwise prefer the prefix match when present, since
+// "extra suffix on a known root" is a stronger signal than a 4+-edit
+// distance to an unrelated key.
+function _suggestKey(unknownKey, knownKeys) {
+  const threshold = Math.max(2, Math.floor(unknownKey.length * 0.4));
+  let distBest = null, distBestVal = Infinity;
+  let prefixBest = null, prefixBestLen = 0;
+
+  for (const k of knownKeys) {
+    const d = _editDistance(unknownKey, k);
+    if (d < distBestVal && d <= threshold) {
+      distBestVal = d;
+      distBest = k;
+    }
+    if (k.length >= 3 && unknownKey !== k &&
+        unknownKey.startsWith(k) && k.length > prefixBestLen) {
+      prefixBest = k;
+      prefixBestLen = k.length;
+    }
+  }
+
+  if (distBest && distBestVal <= 2) return distBest;
+  return prefixBest || distBest;
+}
+
+/**
+ * Per-site validation + boolean coercion run at scan startup (always, not
+ * gated on --validate-config).
+ *
+ * Mutates siteConfig in place to coerce boolean-like values (1, 0, "true",
+ * "false", "yes", "no", "on", "off") to true/false for fields in
+ * BOOLEAN_SITE_CONFIG_FIELDS. Returns warnings the caller surfaces via the
+ * usual logging path.
+ *
+ * Catches the failure classes:
+ *   1. Unknown siteConfig keys → typo warning + "did you mean?" suggestion.
+ *      Example: 'whois_terms' → "did you mean 'whois'?"
+ *   2. Boolean field with truthy non-boolean value → coerce + warn.
+ *      Example: 'interact: 1' → coerced to 'interact: true', warning emitted.
+ *   3. Boolean field with non-boolean non-truthy value → warn only, no coerce.
+ *      Example: 'interact: "maybe"' → warned, left alone.
+ *
+ * @param {object} siteConfig - mutated in place
+ * @param {number} siteIndex - for warning messages
+ * @returns {{warnings: string[], errors: string[]}}
+ */
+function normalizeSiteConfig(siteConfig, siteIndex = 0) {
+  const warnings = [];
+  const errors = [];
+  if (!siteConfig || typeof siteConfig !== 'object') {
+    errors.push(`Site ${siteIndex}: not an object`);
+    return { warnings, errors };
+  }
+  const tag = siteConfig.url ? `Site ${siteIndex} (${siteConfig.url})` : `Site ${siteIndex}`;
+
+  // 1. Unknown-key detection. Scan every top-level key; report with
+  // Levenshtein-based suggestion when close to a known key.
+  for (const key of Object.keys(siteConfig)) {
+    if (KNOWN_SITE_CONFIG_KEYS.has(key)) continue;
+    const suggestion = _suggestKey(key, KNOWN_SITE_CONFIG_KEYS);
+    warnings.push(
+      `${tag}: unknown siteConfig key '${key}'` +
+      (suggestion ? ` — did you mean '${suggestion}'?` : '') +
+      ' — value will be ignored at runtime'
+    );
+  }
+
+  // 2. Boolean coercion for known boolean fields. Mutates siteConfig.
+  for (const field of BOOLEAN_SITE_CONFIG_FIELDS) {
+    if (!(field in siteConfig)) continue;
+    const original = siteConfig[field];
+    if (original === undefined || original === null) continue;
+    const { coerced, value } = _coerceBooleanLike(original);
+    if (coerced) {
+      siteConfig[field] = value;
+      warnings.push(
+        `${tag}: '${field}' value ${JSON.stringify(original)} should be ${value} ` +
+        `(boolean) — coerced for compatibility; please update config to use ${value}`
+      );
+    } else if (typeof original !== 'boolean') {
+      warnings.push(
+        `${tag}: '${field}' should be boolean (true/false), got ${JSON.stringify(original)} ` +
+        `— may not work as expected (downstream strict-equality check will treat as disabled)`
+      );
+    }
+  }
+
+  // 3. String → single-element array coercion for fields that accept both
+  // forms (dig, dig-or, whois, whois-or). Downstream consumers all gate on
+  // Array.isArray(), so a bare string value previously silently disabled
+  // the feature. Wrapping in [val] is the canonical "user gave one term"
+  // outcome and matches user intent. Both forms are first-class — no
+  // warning is emitted on the string path, just the in-place mutation.
+  //
+  // Empty string is left alone: the downstream `siteConfig.dig && ...`
+  // check sees the empty string as falsy and disables the feature. If we
+  // coerced "" to [""], nettools' array.length>0 check would PASS and then
+  // every dig/whois output would match (`"".includes(anything)` is true),
+  // turning a clearly-empty config into a match-everything one.
+  //
+  // Non-string non-array values DO warn since we can't sensibly coerce.
+  for (const field of STRING_TO_ARRAY_FIELDS) {
+    if (!(field in siteConfig)) continue;
+    const val = siteConfig[field];
+    if (val === undefined || val === null) continue;
+    if (typeof val === 'string') {
+      if (val.length > 0) siteConfig[field] = [val];
+      // empty string: leave as-is (preserves disable-on-falsy semantics)
+    } else if (!Array.isArray(val)) {
+      warnings.push(
+        `${tag}: '${field}' should be a string or array of strings, got ${typeof val} ` +
+        `(${JSON.stringify(val).slice(0, 60)}) — feature will be disabled at runtime`
+      );
+    }
+  }
+
+  // 4. Dependent-flag implication: clear_sitedata_full_on_reload only takes
+  // effect inside the `if (clear_sitedata === true)` guard at nwss.js:4627
+  // — setting it WITHOUT clear_sitedata: true silently does nothing. That's
+  // the same silent-failure pattern this validator was created to prevent,
+  // so auto-enable clear_sitedata and warn the user. They almost certainly
+  // intended both to be true; opt-in to heavy-storage clearing without
+  // opt-in to clearing-at-all doesn't make sense as a configuration.
+  if (siteConfig.clear_sitedata_full_on_reload === true &&
+      siteConfig.clear_sitedata !== true) {
+    siteConfig.clear_sitedata = true;
+    warnings.push(
+      `${tag}: 'clear_sitedata_full_on_reload: true' requires 'clear_sitedata: true' ` +
+      `— auto-enabled clear_sitedata for compatibility; please add 'clear_sitedata: true' ` +
+      `to your config explicitly`
+    );
+  }
+
+  return { warnings, errors };
+}
+
 // Public surface used by nwss.js (validateRulesetFile, validateFullConfig,
-// testDomainValidation, cleanRulesetFile). The rest (isValidDomain,
-// isValidDomainLabel, isValidTLD, isIPAddress, isIPv4, isIPv6,
+// testDomainValidation, cleanRulesetFile, normalizeSiteConfig). The rest
+// (isValidDomain, isValidDomainLabel, isValidTLD, isIPAddress, isIPv4, isIPv6,
 // validateRegexPattern, validateAdblockModifiers, validateAdblockRule,
 // validateSiteConfig) stay internal-helper-but-exported for now since
 // downstream callers MAY import them via the dotted path even if grep
@@ -1100,5 +1381,6 @@ module.exports = {
   cleanRulesetFile,
   validateSiteConfig,
   validateFullConfig,
+  normalizeSiteConfig,
   testDomainValidation
 };

package/lib/wireguard_vpn.js

@@ -33,8 +33,15 @@ function getExternalIP(interfaceName) {
 // Track active interfaces for cleanup
 const activeInterfaces = new Map();
 
-// Temp config directory for inline configs
-const TEMP_CONFIG_DIR = '/tmp/nwss-wireguard';
+// Temp config directory for inline configs — namespaced per process.
+// disconnectAll() rmSync's this whole directory on exit; a fixed shared path
+// meant two concurrent nwss processes using inline configs would clobber each
+// other: the first to exit deleted the survivor's live .conf, so its
+// `wg-quick down <path>` then failed (file gone) and the kernel interface
+// leaked. Scoping to the PID keeps each process's teardown to its own files.
+// (Stale dirs from a crashed process are left for manual cleanup — sweeping
+// them would reintroduce the same cross-process destruction this avoids.)
+const TEMP_CONFIG_DIR = path.join('/tmp/nwss-wireguard', String(process.pid));
 
 /**
  * Check if running with sufficient privileges
@@ -85,9 +92,11 @@ function resolveInterfaceName(vpnConfig) {
  * @returns {string} Path to temp config file
  */
 function writeInlineConfig(interfaceName, configContent) {
-  if (!fs.existsSync(TEMP_CONFIG_DIR)) {
-    fs.mkdirSync(TEMP_CONFIG_DIR, { recursive: true, mode: 0o700 });
-  }
+  // mkdirSync with recursive:true is a no-op when the directory exists,
+  // so the prior existsSync gate was redundant. Saves one stat() syscall
+  // per VPN bringup and follows the standard "act, don't check-then-act"
+  // idiom (also avoids a microscopic TOCTOU window).
+  fs.mkdirSync(TEMP_CONFIG_DIR, { recursive: true, mode: 0o700 });
 
   const configPath = path.join(TEMP_CONFIG_DIR, `${interfaceName}.conf`);
   fs.writeFileSync(configPath, configContent, { mode: 0o600 });
@@ -114,6 +123,14 @@ function interfaceUp(configPath, interfaceName, forceDebug = false) {
     // spawnSync with arg array (no shell) — configPath comes from user
     // JSON, so naive `sudo wg-quick up "${configPath}"` was vulnerable
     // to a `";rm -rf ~;"` payload escaping the quotes.
+    //
+    // NOTE: an "already exists" failure here usually means a previous
+    // run's teardown failed and left the kernel interface alive. Recover
+    // manually with `sudo wg-quick down <name>` or `sudo ip link delete
+    // <name>`. A self-heal mechanism was tried (commit e032bde) and
+    // reverted because it raced with concurrent nwss processes sharing
+    // the same VPN config — process B's self-heal would destroy process
+    // A's live interface. Keep the manual-recovery default for safety.
     const upRes = spawnSync('sudo', ['wg-quick', 'up', configPath], {
       encoding: 'utf8',
       timeout: 15000
@@ -193,10 +210,12 @@ function interfaceDown(interfaceName, forceDebug = false) {
     // down failure where the kernel interface might persist briefly.
     // Was previously only inside the try block, so failure paths
     // leaked the temp file.
+    //
+    // No existsSync gate — unlinkSync throws ENOENT for missing files
+    // and the try/catch already swallows it. Saves one stat() and
+    // closes a microscopic TOCTOU window.
     const tempPath = path.join(TEMP_CONFIG_DIR, `${interfaceName}.conf`);
-    if (fs.existsSync(tempPath)) {
-      try { fs.unlinkSync(tempPath); } catch {}
-    }
+    try { fs.unlinkSync(tempPath); } catch {}
   }
 }
 
@@ -310,6 +329,22 @@ function validateVpnConfig(vpnConfig) {
     result.warnings.push('Both "config" and "config_inline" provided; "config" takes precedence');
   }
 
+  // F1: Validate user-provided interface name to prevent path traversal via
+  // resolveInterfaceName → writeInlineConfig's path.join. Also enforces
+  // Linux IFNAMSIZ (15 chars max). User would need to attack their own
+  // config (same trust boundary as rest of nwss + must run as root for WG),
+  // so this is defensive rather than security-critical — but the validation
+  // catches typos that would otherwise produce confusing wg-quick errors.
+  if (vpnConfig.interface !== undefined && vpnConfig.interface !== null) {
+    if (typeof vpnConfig.interface !== 'string' || !/^[a-zA-Z0-9_-]{1,15}$/.test(vpnConfig.interface)) {
+      result.isValid = false;
+      result.errors.push(
+        `Invalid 'interface' name ${JSON.stringify(vpnConfig.interface)}: ` +
+        `must match /^[a-zA-Z0-9_-]{1,15}$/ (Linux IFNAMSIZ limit + path-safe chars)`
+      );
+    }
+  }
+
   // Validate config file exists
   if (vpnConfig.config) {
     const configPath = vpnConfig.config;
@@ -365,8 +400,11 @@ async function connectForSite(siteConfig, forceDebug = false) {
 
   const interfaceName = resolveInterfaceName(vpnConfig);
 
-  // Resolve config path
-  let configPath;
+  // Resolve config path. A file-based config path is fixed up-front; an
+  // inline config is a temp file we (re)write inside the retry loop below
+  // (it can't be hoisted — see the writeInlineConfig call for why).
+  const useInlineConfig = !vpnConfig.config;
+  let configPath = null;
   if (vpnConfig.config) {
     configPath = vpnConfig.config;
     // Resolve wg-quick style: if no path separators, look in /etc/wireguard/
@@ -376,8 +414,6 @@ async function connectForSite(siteConfig, forceDebug = false) {
         configPath = etcPath;
       }
     }
-  } else {
-    configPath = writeInlineConfig(interfaceName, vpnConfig.config_inline);
   }
 
   const maxAttempts = vpnConfig.retry ? vpnConfig.max_retries + 1 : 1;
@@ -395,9 +431,25 @@ async function connectForSite(siteConfig, forceDebug = false) {
       await new Promise(resolve => setTimeout(resolve, 2000));
     }
 
+    // (Re)write the inline temp config before each attempt. interfaceDown's
+    // finally unlinks the temp .conf (both the retry reset just above and any
+    // teardown from a prior run), so hoisting this above the loop meant a
+    // retry's `wg-quick up` ran against a deleted file and always failed.
+    // Idempotent on the first attempt.
+    if (useInlineConfig) {
+      configPath = writeInlineConfig(interfaceName, vpnConfig.config_inline);
+    }
+
     const upResult = interfaceUp(configPath, interfaceName, forceDebug);
     if (!upResult.success) {
       if (attempt === maxAttempts) {
+        // interfaceUp never registered the interface (no activeInterfaces
+        // entry), so interfaceDown's finally won't run to clean the temp.
+        // Unlink the inline config here so a fully-failed connect doesn't
+        // leave a PrivateKey-bearing .conf in /tmp until process exit.
+        if (useInlineConfig && configPath) {
+          try { fs.unlinkSync(configPath); } catch {}
+        }
         return upResult;
       }
       continue;