@fanboynz/network-scanner 3.1.2 → 3.2.0

package/lib/ghost-cursor.js

@@ -15,6 +15,11 @@
 //   npm install ghost-cursor            (optional dependency)
 
 const { formatLogMessage, messageColors } = require('./colorize');
+// humanClick gives the coordinate-click path the same press realism as the
+// built-in content clicks (hover dwell + mousedown/hold/mouseup, optional
+// hand-tremor + mouseup drift) instead of a 0ms page.mouse.click. One-way
+// require — interaction.js does not depend on ghost-cursor, so no cycle.
+const { humanClick } = require('./interaction');
 const GHOST_CURSOR_TAG = messageColors.processing('[ghost-cursor]');
 
 let ghostCursorModule = null;
@@ -56,7 +61,7 @@ function createGhostCursor(page, options = {}) {
     const cursor = ghostCursorModule.createCursor(page, { x: startX, y: startY });
 
     if (forceDebug) {
-      console.log(formatLogMessage('debug', '[ghost-cursor] Cursor instance created'));
+      console.log(formatLogMessage('debug', `${GHOST_CURSOR_TAG} Cursor instance created`));
     }
 
     return cursor;
@@ -98,7 +103,7 @@ async function ghostMove(cursor, toX, toY, options = {}) {
     const moveOpts = {};
     if (moveSpeed !== undefined) moveOpts.moveSpeed = moveSpeed;
     if (moveDelay > 0) moveOpts.moveDelay = moveDelay;
-    if (randomizeMoveDelay !== undefined) moveOpts.randomizeMoveDelay = randomizeMoveDelay;
+    moveOpts.randomizeMoveDelay = randomizeMoveDelay; // always defined (defaults to true)
     if (overshootThreshold !== undefined) moveOpts.overshootThreshold = overshootThreshold;
 
     await cursor.moveTo({ x: toX, y: toY }, moveOpts);
@@ -126,6 +131,8 @@ async function ghostMove(cursor, toX, toY, options = {}) {
  * @param {number} options.waitForClick - Delay (ms) between mousedown/mouseup (default: auto)
  * @param {number} options.moveDelay - Delay (ms) after moving to target
  * @param {number} options.paddingPercentage - Click point within element (0=edge, 100=center)
+ * @param {import('puppeteer').Page} options.page - Page for coordinate clicks (falls back to cursor.page)
+ * @param {boolean} options.realistic - Coordinate clicks: emit hand-tremor + mouseup drift (default: false)
  * @param {boolean} options.forceDebug - Enable debug logging
  * @returns {Promise<boolean>} true if click succeeded
  */
@@ -137,6 +144,8 @@ async function ghostClick(cursor, target, options = {}) {
     waitForClick,
     moveDelay,
     paddingPercentage,
+    page,
+    realistic = false,
     forceDebug
   } = options;
 
@@ -149,16 +158,25 @@ async function ghostClick(cursor, target, options = {}) {
     if (typeof target === 'string') {
       await cursor.click(target, clickOpts);
     } else {
-      // For coordinate clicks, move first then use page click
+      // Coordinate click: ghost-cursor's bezier moveTo brings the cursor to the
+      // point, then humanClick does the realistic press (hover dwell, mousedown
+      // → hold → mouseup, plus hand-tremor + down≠up drift when realistic). This
+      // replaces a 0ms page.mouse.click, so the ghost path gets the same click
+      // realism as built-in content clicks.
       await cursor.moveTo(target);
-      // Small hesitation before clicking
-      if (hesitate > 0) {
-        await new Promise(resolve => setTimeout(resolve, hesitate));
-      }
-      const page = cursor._page || cursor.page;
-      if (page && typeof page.mouse?.click === 'function') {
-        await page.mouse.click(target.x, target.y);
+      // Prefer the caller-supplied page; fall back to the cursor's own page
+      // (ghost-cursor exposes it as cursor.page) so we don't depend on internals.
+      // Return false (not silent success) if there's no usable page — otherwise
+      // the "Clicked" log + return true below would lie about a click that
+      // never fired.
+      const clickPage = page || cursor.page;
+      if (!clickPage || typeof clickPage.mouse?.down !== 'function') {
+        if (forceDebug) {
+          console.log(formatLogMessage('debug', `${GHOST_CURSOR_TAG} Coordinate click skipped: no usable page`));
+        }
+        return false;
       }
+      await humanClick(clickPage, target.x, target.y, { realistic, forceDebug });
     }
 
     if (forceDebug) {
@@ -189,7 +207,7 @@ async function ghostRandomMove(cursor, options = {}) {
   try {
     await cursor.randomMove();
     if (options.forceDebug) {
-      console.log(formatLogMessage('debug', '[ghost-cursor] Random movement performed'));
+      console.log(formatLogMessage('debug', `${GHOST_CURSOR_TAG} Random movement performed`));
     }
     return true;
   } catch (err) {

package/lib/interaction.js

@@ -1333,5 +1333,9 @@ module.exports = {
   simulateScrolling,
   interactWithElements,
   performContentClicks,
+  // Realistic timed click (hover dwell + mousedown/hold/mouseup, optional
+  // hand-tremor + mouseup drift). Reused by lib/ghost-cursor.js so the ghost
+  // coordinate click gets the same press realism as built-in content clicks.
+  humanClick,
   generateRandomCoordinates
 };

package/lib/nettools.js

@@ -124,7 +124,6 @@ function loadDiskCache(filePath, cache, ttl, maxSize) {
     // Surface the event so the user knows they lost their warm cache;
     // previously this was a silent reset, which made "why did my dns
     // cache stop helping?" hard to diagnose.
-    // eslint-disable-next-line no-console
     console.warn(`${messageColors.highlight('[dns-cache]')} ${path.basename(filePath)} was unreadable (${err.message}); starting fresh`);
     try { fs.unlinkSync(filePath); } catch {}
   }
@@ -256,6 +255,38 @@ function getDnsCacheStats() {
 // Disk cache is opt-in via --dns-cache flag
 let diskCacheEnabled = false;
 
+// Optional dig resolver(s), set from --dns. When non-empty, dig queries
+// `@<one of these>` (round-robin) instead of the system resolver — so dig uses
+// the same reliable servers as the pre-check rather than a flaky /etc/resolv.conf
+// (the cause of `dig: Command timeout` drops on Cloudflare-fronted ad domains).
+let digResolvers = [];
+let digResolverCursor = 0;
+// dig's `@server` wants a bare IP; strip any `ipv4:port` / `[ipv6]:port` form.
+function digServerFromSpec(spec) {
+  const s = String(spec);
+  const br = s.match(/^\[([0-9a-fA-F:]+)\]/);
+  if (br) return br[1];
+  const v4p = s.match(/^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/);
+  if (v4p) return v4p[1];
+  return s;
+}
+function setDigResolvers(servers) {
+  digResolvers = (Array.isArray(servers) ? servers : []).filter(Boolean).map(digServerFromSpec);
+}
+// Ordered `@server` attempt list for ONE dig lookup: starts at the round-robin
+// cursor (advanced once per lookup, preserving the old fairness) then falls
+// through the remaining resolvers as failover. Returns [null] when no --dns
+// resolvers are configured — a single attempt via the system resolver.
+function digServerAttemptList() {
+  if (digResolvers.length === 0) return [null];
+  const start = digResolverCursor++ % digResolvers.length;
+  const list = [];
+  for (let i = 0; i < digResolvers.length; i++) {
+    list.push('@' + digResolvers[(start + i) % digResolvers.length]);
+  }
+  return list;
+}
+
 /**
  * Enable persistent disk caching for dig/whois results.
  * Call this when --dns-cache flag is set. Idempotent — repeated calls
@@ -293,7 +324,6 @@ function enableDiskCache() {
   // Debug log only if anything was actually warmed; silent on fresh
   // installs / empty disk caches.
   if (digWarm > 0 || whoisWarm > 0) {
-    // eslint-disable-next-line no-console
     console.log(`${messageColors.highlight('[dns-cache]')} Warmed resolved-hostnames index from disk: ${digWarm} dig + ${whoisWarm} whois entries`);
   }
 
@@ -994,50 +1024,103 @@ async function whoisLookupWithRetry(domain = '', timeout = 10000, whoisServer =
  * @returns {Promise<Object>} Object with success status and output/error
  */
 async function digLookup(domain = '', recordType = 'A', timeout = 5000) {
-  try {
-    // Clean domain
-    const cleanDomain = domain.replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/:\d+$/, '');
+  // Clean domain (defensive — callers usually pass an already-clean digDomain).
+  const cleanDomain = domain.replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/:\d+$/, '');
+
+  // dig argv-injection guard. dig parses @/-/+ -leading tokens as options
+  // (`@host` redirects the query to an arbitrary server, `-f path` reads a
+  // file as a query batch) and has no `--` end-of-options marker like whois.
+  // Reject anything not hostname-shaped before shelling out — success:false so
+  // it's treated as no-match and not cached. (Charset blocks @ + / space etc;
+  // the leading-`-` check blocks `-f` and friends, since `-` is valid mid-host.)
+  if (!cleanDomain || /[^a-zA-Z0-9._-]/.test(cleanDomain) || cleanDomain.startsWith('-')) {
+    return { success: false, error: `invalid domain shape: ${cleanDomain}`, domain: cleanDomain, recordType };
+  }
+
+  // Resolver failover: try the round-robin resolver first, then fall through
+  // the remaining --dns resolvers on timeout / no-reply / REFUSED / SERVFAIL —
+  // the same resilience the whois path already has via whoisLookupWithRetry,
+  // and the DNS pre-check has via its rotation. Capped at 3 attempts (matches
+  // whois maxRetries default) so a host that's dead on every resolver can't
+  // burn the whole nettools budget.
+  const attempts = digServerAttemptList();
+  // Only do JS-level failover when --dns gave us pinned resolvers. Without it,
+  // attempts is [null]: a SINGLE system-resolver invocation that keeps dig's
+  // native resolv.conf rotation + retries (forcing +tries=1 there would strip
+  // that built-in resilience — the whole point is to be MORE resilient).
+  const usingResolvers = attempts[0] !== null;
+  const maxAttempts = usingResolvers ? Math.min(3, attempts.length) : 1;
+  // Pinned-resolver attempts use +time=2 +tries=1 (the JS loop owns failover)
+  // under a 4s SIGTERM ceiling. The system-resolver path keeps the full budget
+  // and dig's own retry behaviour, matching the pre-failover semantics exactly.
+  const perAttemptTimeout = usingResolvers ? Math.min(timeout, 4000) : timeout;
+
+  let lastError = 'no resolver attempts made';
+
+  for (let i = 0; i < maxAttempts; i++) {
+    const digServerArg = attempts[i];
+    // With a pinned resolver: one fast try (+time=2 +tries=1), then the JS loop
+    // moves to the next resolver. Without --dns: bare `dig name type` so dig
+    // applies its native resolv.conf rotation. execFile (no shell) => args
+    // can't be injected.
+    const digArgs = digServerArg
+      ? [digServerArg, '+time=2', '+tries=1', cleanDomain, recordType]
+      : [cleanDomain, recordType];
+    const resolverLabel = digServerArg ? digServerArg.slice(1) : 'system resolver';
+
+    try {
+      const { stdout: fullOutput } = await execFileWithTimeout('dig', digArgs, perAttemptTimeout);
+
+      // Judge success by RCODE, not by stderr. dig exits 0 for ANY server
+      // response, so non-zero exit (timeout / no-reply) already rejected above.
+      // REFUSED/SERVFAIL are resolver-SIDE failures another resolver may not
+      // share — fail over instead of accepting an answerless response (the
+      // EREFUSED-storm case). NOERROR/NXDOMAIN are definitive => accept.
+      const statusMatch = fullOutput.match(/status:\s*([A-Z]+)/i);
+      const rcode = statusMatch ? statusMatch[1].toUpperCase() : 'NOERROR';
+      if (rcode === 'REFUSED' || rcode === 'SERVFAIL') {
+        lastError = `dig ${rcode} from ${resolverLabel}`;
+        continue; // try next resolver in the failover list
+      }
+
+      // Non-empty stderr is intentionally NOT treated as failure here: dig
+      // prints `;; communications error ... timed out` warnings to stderr while
+      // still returning a valid ANSWER SECTION and exit 0. The old code failed
+      // the whole lookup on any stderr, discarding good answers — the exact
+      // missed-match pattern under flaky resolvers.
+      const answerMatch = fullOutput.match(/;; ANSWER SECTION:\n([\s\S]*?)(?:\n;;|\n*$)/);
+      let shortOutput = '';
+      if (answerMatch) {
+        shortOutput = answerMatch[1]
+          .split('\n')
+          .map(line => line.split(/\s+/).pop())
+          .filter(Boolean)
+          .join('\n');
+      }
 
-    // Single dig command — full output contains everything including short
-    // answers. execFile (no shell) so cleanDomain / recordType can contain
-    // any chars without injection risk.
-    const { stdout: fullOutput, stderr } = await execFileWithTimeout('dig', [cleanDomain, recordType], timeout);
-    
-    if (stderr && stderr.trim()) {
       return {
-        success: false,
-        error: stderr.trim(),
+        success: true,
+        output: fullOutput,
+        shortOutput,
         domain: cleanDomain,
-        recordType
+        recordType,
+        resolver: resolverLabel
       };
+    } catch (error) {
+      // Timeout or non-zero exit (e.g. dig exit 9 = no reply from this server).
+      // Record and fall through to the next resolver.
+      lastError = error.message;
     }
-    
-    // Extract short output from ANSWER SECTION of full dig output
-    const answerMatch = fullOutput.match(/;; ANSWER SECTION:\n([\s\S]*?)(?:\n;;|\n*$)/);
-    let shortOutput = '';
-    if (answerMatch) {
-      shortOutput = answerMatch[1]
-        .split('\n')
-        .map(line => line.split(/\s+/).pop())
-        .filter(Boolean)
-        .join('\n');
-    }
-    
-    return {
-      success: true,
-      output: fullOutput,
-      shortOutput,
-      domain: cleanDomain,
-      recordType
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: error.message,
-      domain: domain,
-      recordType
-    };
   }
+
+  // Every attempt timed out / was refused. success:false so the handler does
+  // NOT cache it (transient — caching would poison the domain for the TTL).
+  return {
+    success: false,
+    error: lastError,
+    domain: cleanDomain,
+    recordType
+  };
 }
 
 /**
@@ -1170,15 +1253,20 @@ function createNetToolsHandler(config) {
     // Determine which domain will be used for dig lookup
     const digDomain = digSubdomain && originalDomain ? originalDomain : domain;
 
-    // For whois: use root domain only (whois data is consistent for entire domain)
-    const whoisRootDomain = getRootDomain ? getRootDomain(`http://${domain}`) : domain;
-    
+    // For whois: use root domain only (whois data is consistent for entire
+    // domain). Only compute it when whois is actually configured — getRootDomain
+    // does a domain parse, so on a dig-only config (no whois/whois-or) this skips
+    // a parse + string build on every single request. whoisRootDomain is only
+    // ever read inside the whois branch, so the `domain` fallback is never used.
+    const wantWhois = hasWhois || hasWhoisOr;
+    const whoisRootDomain = wantWhois ? (getRootDomain ? getRootDomain(`http://${domain}`) : domain) : domain;
+
     // Check if we need to perform any lookups with appropriate deduplication
     // Whois: root domain + config (whois data same for sub.example.com and example.com)
-    const whoisDedupeKey = `${whoisRootDomain}:${whoisConfigKey}`;
+    const whoisDedupeKey = wantWhois ? `${whoisRootDomain}:${whoisConfigKey}` : '';
     // Dig: specific subdomain + config (DNS records can differ between subdomains)
     const digDedupeKey = `${digDomain}:${digConfigKey}`;
-    const needsWhoisLookup = (hasWhois || hasWhoisOr) && !processedWhoisDomains.has(whoisDedupeKey);
+    const needsWhoisLookup = wantWhois && !processedWhoisDomains.has(whoisDedupeKey);
     const needsDigLookup = (hasDig || hasDigOr) && !processedDigDomains.has(digDedupeKey);
 
     // Claim the dedupe keys NOW, synchronously, before executeNetToolsLookup
@@ -1606,11 +1694,20 @@ function createNetToolsHandler(config) {
               // backwards-compat additive: old code reading new cache
               // ignores it; new code reading old cache (no field) falls
               // back to lazy on-hit population in the cache-hit branch.
-              globalDigResultCache.set(digCacheKey, {
-                result: digResult,
-                timestamp: now,
-                hostname: digDomain
-              });
+              //
+              // Only cache a SUCCESSFUL dig. A timeout/error (success:false) is
+              // transient — caching it would poison the domain for the full
+              // cache TTL (20h when persisted via --dns-cache), so a host that
+              // resolves fine on the next attempt keeps getting dropped. (An
+              // NXDOMAIN is success:true with NXDOMAIN in the body — a real
+              // answer — so it's correctly still cached.)
+              if (digResult.success) {
+                globalDigResultCache.set(digCacheKey, {
+                  result: digResult,
+                  timestamp: now,
+                  hostname: digDomain
+                });
+              }
               dnsCacheStats.digMisses++;
               pushFreshSample(dnsCacheStats.freshDig, `${digDomain} (${digRecordType})`);
               // Index hostname IF dig actually proved resolution -- NXDOMAIN
@@ -1662,7 +1759,7 @@ function createNetToolsHandler(config) {
                 if (hasDig) logToConsoleAndFile(`${messageColors.highlight('[dig-and]')} Terms checked: ${digTerms.join(' AND ')}, matched: ${digMatched}`);
                 if (hasDigOr) logToConsoleAndFile(`${messageColors.highlight('[dig-or]')} Terms checked: ${digOrTerms.join(' OR ')}, matched: ${digOrMatched}`);
               }
-              logToConsoleAndFile(`${messageColors.highlight('[dig]')} Lookup completed for ${digDomain}, dig-and: ${digMatched}, dig-or: ${digOrMatched}`);
+              logToConsoleAndFile(`${messageColors.highlight('[dig]')} Lookup completed for ${digDomain}${digResult.resolver ? ` via ${digResult.resolver}` : ''}, dig-and: ${digMatched}, dig-or: ${digOrMatched}`);
               if (siteConfig.verbose === 1) {
                 if (hasDig) logToConsoleAndFile(`${messageColors.highlight('[dig]')} AND terms: ${digTerms.join(', ')}`);
                 if (hasDigOr) logToConsoleAndFile(`${messageColors.highlight('[dig]')} OR terms: ${digOrTerms.join(', ')}`);
@@ -1813,6 +1910,12 @@ module.exports = {
   validateDigAvailability,
   enableDiskCache,
   getDnsCacheStats,
+  // Route dig through the --dns resolver(s) instead of the system resolver.
+  setDigResolvers,
+  // Generic disk-cache primitives (atomic write, TTL/size-bounded) — reused by
+  // nwss.js to persist the DNS pre-check negative cache under --dns-cache.
+  loadDiskCache,
+  saveDiskCache,
   // Resolved-hostnames index for the DNS pre-check optimization.
   // nwss.js's per-task pre-check consults this BEFORE calling resolve4
   // so hosts already proven live by dig or whois (within their 20h

package/lib/output.js

@@ -133,32 +133,43 @@ function formatDomain(domain, options = {}) {
   if (!domain || domain.length <= 6 || !domain.includes('.')) {
     return null;
   }
-  
-  // If plain is true, always return just the domain regardless of other options
+
+  // Path-prefix rules (from output_regex) are stored as "host/path/" — they
+  // contain a '/'. Only adblock can express a path; every domain-only format
+  // (dnsmasq/unbound/pihole/hosts/privoxy/plain) falls back to the bare host
+  // (everything before the first '/') so output stays valid in all formats.
+  const slash = domain.indexOf('/');
+  const isPathRule = slash !== -1;
+  const host = isPathRule ? domain.slice(0, slash) : domain;
+
+  // If plain is true, always return just the host regardless of other options
   if (plain) {
-    return domain;
+    return host;
   }
-  
+
   // Apply specific format based on output mode
   if (pihole) {
     // Escape dots for regex and use Pi-hole format: (^|\.)domain\.com$
-    const escapedDomain = domain.replace(/\./g, '\\.');
+    const escapedDomain = host.replace(/\./g, '\\.');
     return `(^|\\.)${escapedDomain}$`;
   } else if (privoxy) {
-    return `{ +block } .${domain}`;
+    return `{ +block } .${host}`;
   } else if (dnsmasq) {
-    return `local=/${domain}/`;
+    return `local=/${host}/`;
   } else if (dnsmasqOld) {
-    return `server=/${domain}/`;
+    return `server=/${host}/`;
   } else if (unbound) {
-    return `local-zone: "${domain}." always_null`;
+    return `local-zone: "${host}." always_null`;
   } else if (localhostIP) {
-    return `${localhostIP} ${domain}`;
+    return `${localhostIP} ${host}`;
   } else if (adblockRules && resourceType) {
-    // Generate adblock filter rules with resource type modifiers
-    return `||${domain}^${resourceType}`;
+    // Adblock with resource-type modifier. A path rule self-anchors via its
+    // trailing '/', so it takes no '^' separator; a domain rule needs '^'.
+    return isPathRule ? `||${domain}${resourceType}` : `||${domain}^${resourceType}`;
   } else {
-    return `||${domain}^`;
+    // Default adblock: ||host^ for a domain, ||host/path/ for a path rule
+    // (the path already anchors, so no trailing '^').
+    return isPathRule ? `||${domain}` : `||${domain}^`;
   }
 }
 

package/lib/redirect.js

@@ -19,7 +19,10 @@ async function navigateWithRedirectHandling(page, currentUrl, siteConfig, gotoOp
   let httpStatus = null;
   let cfRay = null;
   const jsRedirectTimeout = siteConfig.js_redirect_timeout || 5000; // Wait 5s for JS redirects
-  const maxRedirects = siteConfig.max_redirects || 10;
+  // Use a number check, not || , so max_redirects: 0 (follow none) isn't
+  // swallowed as falsy and silently bumped to 10. Only absent/negative/non-number defaults.
+  const maxRedirects = (typeof siteConfig.max_redirects === 'number' && siteConfig.max_redirects >= 0)
+    ? siteConfig.max_redirects : 10;
   const detectJSPatterns = siteConfig.detect_js_patterns !== false; // Default to true
 
   // Monitor frame navigations to detect redirects

package/lib/validate_rules.js

@@ -806,7 +806,6 @@ function cleanRulesetFile(filePath, outputPath = null, options = {}) {
   } = options;
   
   const fs = require('fs');
-  const path = require('path');
 
   let content;
   try {
@@ -1118,6 +1117,7 @@ const KNOWN_SITE_CONFIG_KEYS = new Set([
   'ignore_similar_threshold', 'interact', 'interact_click_count', 'interact_clicks',
   'interact_duration', 'interact_intensity', 'interact_scrolling', 'isBrave',
   'js_redirect_timeout', 'localhost', 'max_redirects', 'openvpn', 'pihole',
+  'output_regex',
   'plain', 'privoxy', 'proxy', 'proxy_bypass', 'proxy_debug', 'proxy_remote_dns',
   'realistic_click', 'referrer_disable', 'referrer_headers', 'regex_and',
   'reload', 'resourceTypes', 'screenshot', 'searchstring', 'searchstring_and',
@@ -1307,6 +1307,21 @@ function normalizeSiteConfig(siteConfig, siteIndex = 0) {
     }
   }
 
+  // 2b. output_regex must be a compilable regex. An invalid one is silently
+  // disabled at runtime (the use-site try/catch falls back to ||host^), so
+  // surface it here at load time where the user can fix it.
+  if ('output_regex' in siteConfig && siteConfig.output_regex != null && siteConfig.output_regex !== '') {
+    if (typeof siteConfig.output_regex !== 'string') {
+      warnings.push(`${tag}: 'output_regex' should be a string regex, got ${JSON.stringify(siteConfig.output_regex)} — will be ignored`);
+    } else {
+      try {
+        new RegExp(siteConfig.output_regex);
+      } catch (e) {
+        warnings.push(`${tag}: 'output_regex' is not a valid regex (${e.message}) — will be ignored, output falls back to ||host^`);
+      }
+    }
+  }
+
   // 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

package/nwss.1

@@ -72,10 +72,6 @@ Output as \fB(^|\\.)domain\\.com$\fR format for Pi-hole regex filters.
 Generate adblock filter rules with resource type modifiers (requires \fB\-o\fR).
 
 .SS General Options
-.TP
-.B \--verbose
-Enable verbose output globally for all sites.
-
 .TP
 .B \--debug
 Enable debug mode with detailed logging of all network requests.
@@ -104,6 +100,10 @@ Output full subdomains instead of collapsing to root domains.
 .B \--no-interact
 Disable mouse simulation and page interaction globally.
 
+.TP
+.B \--ghost-cursor
+Use ghost-cursor Bezier mouse movements globally (requires \fBnpm i ghost-cursor\fR). See \fBGhost Cursor Options\fR. Equivalent to per-site \fBcursor_mode: "ghost"\fR.
+
 .TP
 .BR \--custom-json " \fIFILE\fR"
 Use \fIFILE\fR instead of \fBconfig.json\fR for configuration.
@@ -136,10 +136,23 @@ Remove Chrome/Puppeteer temporary files before exit.
 .BR \--max-concurrent " \fINUMBER\fR"
 Maximum concurrent site processing (1-50, overrides config/default).
 
+.TP
+.BR \--dns " \fIIP\fR[,\fIIP\fR...]"
+Nameserver(s) for the DNS pre-check AND nettools' dig \(em does not affect Chrome
+navigation or whois. A single address pins all queries to it; several are
+rotated per query (each leading once, the rest as failover) to spread the
+load. Routing dig through these avoids dig timeouts on a flaky system resolver
+silently dropping dig-gated domains. Overrides /etc/resolv.conf. Invalid
+entries are warned and dropped.
+
 .TP
 .BR \--cleanup-interval " \fINUMBER\fR"
 Browser restart interval in URLs processed (1-1000, overrides config/default).
 
+.TP
+.B \--show-dead-domains
+At end of scan, list hostnames that did not resolve or were unreachable (\fBNXDOMAIN\fR/\fBENODATA\fR plus \fBERR_NAME_NOT_RESOLVED\fR/\fBERR_ADDRESS_UNREACHABLE\fR). Excludes blocks and timeouts, since those mean the domain is alive. Useful for pruning dead URLs.
+
 .TP
 .BR \-h ", " \--help
 Show help message and exit.
@@ -249,6 +262,10 @@ Regex pattern(s) to match suspicious requests.
 .B regex_and
 Boolean. Use AND logic for multiple filterRegex patterns - ALL patterns must match the same URL (default: false).
 
+.TP
+.B output_regex
+String. Regex applied to each matched URL to build the rule body: capture group 1 (or the whole match) becomes \fB||<capture>\fR instead of \fB||host^\fR. For example \fB^https?://([^/]+/[^/]+/)\fR turns \fBhttps://host.com/script/abc.js\fR into \fB||host.com/script/\fR, collapsing randomized filenames under a path into one rule. The capture must include the host. If the regex does not match a URL, output falls back to \fB||host^\fR. Adblock-only; domain-based formats (dnsmasq, pihole, hosts, plain) emit the bare host.
+
 .TP
 .B comments
 Documentation strings or notes - completely ignored by the scanner. Can be a single string or array of strings. Used for adding context, URLs, timestamps, or any documentation notes to configuration files.
@@ -293,6 +310,14 @@ Boolean. Simulate mouse movements and clicks.
 .B interact_intensity
 String. Interaction simulation intensity: \fB"low"\fR, \fB"medium"\fR, \fB"high"\fR (default: "medium").
 
+.TP
+.B interact_click_count
+Integer. Number of random content-zone clicks per load, capped at 20 (default: 3). The default of 3 is a primary click plus two backups, since some ad SDKs suppress the first or second click as warmup.
+
+.TP
+.B realistic_click
+Boolean. Higher click fidelity: denser mouse approach (15 steps), sub-pixel hand-tremor micro-moves during the press, and a small mouseup drift so the mousedown and mouseup coordinates differ. For sites that score click realism. Costs roughly 80-120ms per click (default: false).
+
 .TP
 .B delay
 Milliseconds to wait after page load (default: 4000).
@@ -419,7 +444,7 @@ Object. Custom page.goto() options for Puppeteer navigation. Available options:
 .IP \(bu 4
 \fB"networkidle0"\fR - Wait until 0 network requests for 500ms
 .IP \(bu 4
-\fB"networkidle2"\fR - Wait until ≤2 network requests for 500ms
+\fB"networkidle2"\fR - Wait until \(<=2 network requests for 500ms
 .RE
 .IP \(bu 4
 \fBtimeout\fR: Maximum navigation time in milliseconds (overrides site timeout)
@@ -479,15 +504,28 @@ Both modes wait 16 seconds before cleanup to allow final operations to complete,
 
 .TP
 
-.SS Redirect Handling Options
+.SS Popup Capture Options
+.TP
+.B capture_popups
+Boolean. Capture popup windows opened during the scan and evaluate their landing URL and in-popup requests against \fBfilterRegex\fR/\fBdig\fR/\fBwhois\fR. Requires \fBinteract\fR plus interaction clicks to fire the user-gesture click that opens popups; \fBcapture_popups\fR alone registers the listener but no popups will fire (default: false).
+
+.TP
+.B interact_popups
+Boolean. Mouse-click inside captured popups (content-zone clicks) so the chain cascades to its next redirect or ad. Requires \fBcapture_popups\fR. Clicks popups up to \fBcapture_popups_max_depth\fR minus 1 \(em the deepest captured popup is observed, not clicked (default: false).
 
 .TP
-.B follow_redirects
-Boolean. Follow redirects to new domains (default: true).
+.B capture_popups_max_depth
+Integer. Maximum popup-chain depth to capture, e.g. \fBsite -> p1 -> p2 -> p3 -> destination\fR. Each extra level multiplies popups and time (default: 4).
+
+.TP
+.B capture_popups_window_ms
+Integer. Per-popup capture window in milliseconds before the popup is auto-closed (default: 5000).
+
+.SS Redirect Handling Options
 
 .TP
 .B max_redirects
-Number. Maximum number of redirects to follow (default: 10).
+Number. Maximum number of redirects to follow (default: 10; 0 = follow none).
 
 .TP
 .B js_redirect_timeout
@@ -501,6 +539,29 @@ Boolean. Analyze page source for redirect patterns (default: true).
 .B redirect_timeout_multiplier
 Number. Increase timeout for redirected URLs (default: 1.5).
 
+.SS Ghost Cursor Options
+Optional Bezier-curve mouse engine (the \fBghost-cursor\fR npm package, install
+with \fBnpm i ghost-cursor\fR). Falls back to the built-in mouse if not
+installed. Enable per-site with \fBcursor_mode\fR or globally with the
+\fB\-\-ghost-cursor\fR flag.
+.TP
+.B cursor_mode
+String. Set to \fB"ghost"\fR to use ghost-cursor Bezier mouse movements for this site.
+.TP
+.B ghost_cursor_speed
+Number. Movement speed multiplier (default: auto).
+.TP
+.B ghost_cursor_hesitate
+Number. Delay in milliseconds before a click (default: 50).
+.TP
+.B ghost_cursor_overshoot
+Number. Maximum overshoot distance in pixels before correcting back to the target (default: auto).
+.TP
+.B ghost_cursor_duration
+Number. How long the Bezier movement loop runs, in milliseconds (default: \fBinteract_duration\fR or 2000). Part of this budget (up to half) is reserved for clicks.
+.PP
+Ghost-cursor only \fIclicks\fR when both \fBinteract\fR and \fBinteract_clicks\fR are true. With \fBrealistic_click\fR set, each press adds hand-tremor during the hold plus a mouseup drift so mousedown and mouseup coordinates differ. Ghost mode honors \fBinteract_click_count\fR (default 3, cap 20); since realistic clicks take roughly 600-700ms each, raise \fBghost_cursor_duration\fR (about \fBinteract_click_count\fR x 700 plus movement, e.g. 5000-8000) to fit all of them \(em the default 2000 fits about one click.
+
 .SS Cloudflare Protection Options
 
 .TP
@@ -678,15 +739,15 @@ Global and per-site boolean to enable similarity filtering against ignoreDomains
 With default settings (\fBignore_similar_threshold: 80\fR):
 .RS
 .IP \(bu 4
-\fBanimerco.com\fR vs \fBanimerco.org\fR → 100% similar → Ignored
+\fBanimerco.com\fR vs \fBanimerco.org\fR \(-> 100% similar \(-> Ignored
 .IP \(bu 4
-\fBgoogle.com\fR vs \fBgoogle.co.uk\fR → 100% similar → Ignored
+\fBgoogle.com\fR vs \fBgoogle.co.uk\fR \(-> 100% similar \(-> Ignored
 .IP \(bu 4
-\fBamazon.com\fR vs \fBamazon2.org\fR → 89% similar → Ignored
+\fBamazon.com\fR vs \fBamazon2.org\fR \(-> 89% similar \(-> Ignored
 .IP \(bu 4
-\fBfacebook.com\fR vs \fBfaceboook.com\fR → 91% similar → Ignored
+\fBfacebook.com\fR vs \fBfaceboook.com\fR \(-> 91% similar \(-> Ignored
 .IP \(bu 4
-\fBapple.com\fR vs \fBmicrosoft.com\fR → 0% similar → Kept
+\fBapple.com\fR vs \fBmicrosoft.com\fR \(-> 0% similar \(-> Kept
 .RE
 
 .SH EXAMPLES
@@ -844,7 +905,7 @@ With default settings (\fBignore_similar_threshold: 80\fR):
 
 .SS Run with debug mode and similarity filtering:
 .EX
-node nwss.js --debug --dry-run --verbose
+node nwss.js --debug --dry-run
 .EE
 
 .SS Run with adblock output format: