@fanboynz/network-scanner 3.2.0 → 3.4.0

package/lib/wireguard_vpn.js

@@ -388,6 +388,14 @@ function validateVpnConfig(vpnConfig) {
  * @returns {Promise<Object>} { success, interface, error }
  */
 async function connectForSite(siteConfig, forceDebug = false) {
+  // Platform guard: WireGuard routing here relies on the iproute2 `ip` command
+  // and wg-quick conventions, which are Linux-only. Fail with a clear message
+  // instead of a cryptic `ip: command not found` on macOS/Windows. WSL2 reports
+  // 'linux' and passes.
+  if (process.platform !== 'linux') {
+    return { success: false, error: `WireGuard routing is currently Linux-only (needs the iproute2 'ip' command + wg-quick; not available on ${process.platform}). Run on Linux/WSL2, or remove the 'vpn' option from the site config.` };
+  }
+
   const vpnConfig = normalizeVpnConfig(siteConfig.vpn);
   if (!vpnConfig) {
     return { success: false, error: 'Invalid VPN configuration' };

package/nwss.1

@@ -138,12 +138,32 @@ 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.
+Nameserver(s) for the DNS pre-check, nettools' dig, and \(em when they map to a
+known public DoH provider \(em Chrome's page navigation via DNS-over-HTTPS on
+direct connections (does not affect 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.
+.IP
+Chrome ignores \fB\--dns\fR for navigation and reads /etc/resolv.conf directly,
+so a broken system resolver could fail a domain the pre-check already resolved.
+When the \fB\--dns\fR servers match a known DoH provider (Google, Cloudflare,
+Quad9, OpenDNS, AdGuard, CleanBrowsing, DNS.SB, Mullvad \(em including
+malware/family/unfiltered variants), Chrome is launched with secure-DNS
+\fIautomatic\fR mode pointed at that provider, so navigation resolves through
+the same resolver. \fIautomatic\fR (not \fIsecure\fR) keeps a system-DNS
+fallback if DoH is unreachable. Skipped under a proxy or VPN (the exit/tunnel
+resolves); unmapped resolvers (custom/ISP, per-account providers, IPv6) fall
+back to system DNS with a warning.
+
+.TP
+.B \--doh-disable
+Opt out of the Chrome-navigation DoH pinning (default: off). Chrome then
+resolves page navigation via the system /etc/resolv.conf even when \fB\--dns\fR
+maps to a known provider; the pre-check and dig still honor \fB\--dns\fR. Use
+when DoH adds latency, is blocked on the network, or system-path resolution is
+specifically wanted.
 
 .TP
 .BR \--cleanup-interval " \fINUMBER\fR"
@@ -153,6 +173,14 @@ Browser restart interval in URLs processed (1-1000, overrides config/default).
 .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
+.BI \--block-ads= FILE\fR[,\fIFILE\fR...]
+Block ads/trackers during the scan using EasyList-format filter list(s) \(em network rules like \fB||domain^\fR, \fB/ads/*\fR, \fB||domain^$script\fR. Comma-separated for multiple lists. Cosmetic (\fB##\fR) rules are ignored; the scanned page's own top-level document is never blocked (only sub-resources).
+
+.TP
+.BI \--adblock-engine= js|rust
+Matcher backend for \fB\-\-block-ads\fR (default: \fBjs\fR). \fBjs\fR is the built-in pure-JS matcher (no extra dependencies). \fBrust\fR uses Brave's \fBadblock-rs\fR \(em much faster on large lists, same rules and results, but requires \fBnpm install adblock-rs\fR (needs a Rust toolchain).
+
 .TP
 .BR \-h ", " \--help
 Show help message and exit.
@@ -318,6 +346,14 @@ Integer. Number of random content-zone clicks per load, capped at 20 (default: 3
 .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 click_elements
+Array of CSS selectors. After the page loads, click each selector's first match \fBin order\fR (searched across the main frame and any iframe) \(em reaching content via organic navigation/gesture instead of a direct deep-load (which some sites JS-redirect away). Example: \fB["a[href*='/movie/']", ".play"]\fR clicks a movie link then a play button. The request interceptor stays attached, so the post-click page's requests are matched against \fBfilterRegex\fR/\fBdig\fR as usual; a click that navigates is followed and later selectors query the resulting page. Honors \fBrealistic_click\fR and \fBcursor_mode: "ghost"\fR (Bezier travel to the element); missing elements are skipped and never fail the scan.
+
+.TP
+.B click_wait
+Per click: maximum time in milliseconds to wait for the element to appear and be visible (\fBwaitForSelector\fR) AND the navigation/settle wait after the click (default: 5000; capped at half the per-URL timeout).
+
 .TP
 .B delay
 Milliseconds to wait after page load (default: 4000).
@@ -342,6 +378,10 @@ Boolean. Allow first-party request matching (default: false).
 .B thirdParty
 Boolean. Allow third-party request matching (default: true).
 
+.TP
+.B redirect_first_party
+Boolean (default: true). Whether redirect-destination domains (and chain hops) are treated as first-party. Set to \fBfalse\fR to keep redirect targets \fBthird-party\fR so \fBfilterRegex\fR/\fBdig\fR can match them under \fBthirdParty: true\fR \(em e.g. capturing the end domain of an ad/cloak redirect. The originally-scanned domain stays first-party either way; note this also un-excludes the redirect target's own same-domain resources.
+
 .TP
 .B fingerprint_protection
 Boolean or \fB"random"\fR. Enable browser fingerprint spoofing.