@fanboynz/network-scanner 3.0.0 → 3.0.1

package/.github/workflows/npm-publish.yml

@@ -48,9 +48,14 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Node.js
+        # Must be >=22.12.0 to satisfy package.json engines.node and to
+        # support require()-of-ESM for puppeteer 25 (the project's
+        # current floor). Bumping below this re-introduces the EBADENGINE
+        # warnings seen on 20.x runners and will fail npm publish for
+        # consumers on the same Node version.
         uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
       - run: npm ci

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to the Network Scanner (nwss.js) project.
 
+## [3.0.1] - 2026-05-24
+
+### Security
+- **Proxy credentials redacted in debug logs** — `lib/proxy.js` `getProxyInfo()` now replaces the `username:password@` segment with `[redacted]@` before logging; `lib/socks-relay.js` strips the username from both the relay-startup log (`auth: [redacted]` / `no auth`) and the close log (regex-trims the `:username` suffix from the relay key, IPv6-safe). Prior output exposed SOCKS5 credentials to anyone the user shared a debug dump, screenshot, or support ticket with.
+
+### Added
+- `scripts/test-stealth.js` — stealth smoke-test harness. Launches Puppeteer with `applyAllFingerprintSpoofing` applied and reports what bot.sannysoft.com / creepjs / browserleaks.com/javascript concluded. Flags: `--headful`, `--no-spoof` (baseline), `--ua=<family>` (validated against `USER_AGENT_COLLECTIONS`), `--format=json` (stable schema for diff/jq A/B), `--help`, positional target filtering. `PUPPETEER_NO_SANDBOX=1` env-var opt-in for CI/root containers (sandbox is on by default). Caught 3 real bugs that 5 rounds of static review missed.
+- `USER_AGENT_COLLECTIONS` exported from `lib/fingerprint.js` — single source of truth for valid UA families, consumed by the test harness so the list isn't duplicated.
+
+### Fixed
+- **Puppeteer 25 compatibility** — `browser.isConnected()` (removed in Puppeteer 25 per [puppeteer#14910](https://github.com/puppeteer/puppeteer/pull/14910)) replaced with the `browser.connected` property at 14 call sites across 6 files. Compatible with both Puppeteer 24 and 25.
+- **Fingerprint own-goal — PHANTOM_PROPERTIES + SELENIUM_DRIVER** — spoofing did `delete window[prop]` followed by `defineProperty(prop, { get: () => undefined })`. The undefined-returning getters left the properties detectable via the `in` operator, defeating the delete. Now only deletes. (caught by `scripts/test-stealth.js` sannysoft)
+- **`navigator.plugins instanceof PluginArray` failed** — the spoof returned a plain array. Now `Object.setPrototypeOf(pluginsArray, PluginArray.prototype)` with fallback to `Object.getPrototypeOf(navigator.plugins)` for environments where `PluginArray` isn't a global.
+- **`navigator.plugins[0].toString() === '[object Plugin]'` failed** — plain plugin objects returned `[object Object]`. Each plugin now wraps via `Object.create(Plugin.prototype)` with `Symbol.toStringTag` fallback.
+- **`window.chrome` descriptor was a fingerprinting tell** — had `writable: false, enumerable: false`; real Chrome has both `true`. Aligned.
+- **`_fingerprintCache` cross-UA poisoning** — was keyed by domain only, so the same domain visited under a different UA returned cached values from the wrong OS. Now keyed by `${domain}|${userAgent}`.
+- **7 broken regex patterns** in the fingerprint error-suppression list — double backslashes (`\\.X`) parsed as literal-backslash + wildcard and never matched real errors. All 7 repaired.
+- Constructor `.name` / `.length` preserved through 5 wrapper sites (Error, Image, RTCPeerConnection, PointerEvent, WheelEvent) — wrapped ctors had `.name = ''` and `.length = 0`, a fingerprinting tell.
+- `Error` static properties (`stackTraceLimit`, `captureStackTrace`, `prepareStackTrace`) forward to the OriginalError via live getter/setter instead of snapshot-copy (snapshot diverged once any caller mutated the wrapped Error).
+- `navigator.connection` fallback returns a closure-captured stable object — was re-allocating per call, so object identity changed every access.
+- `chrome.runtime.getManifest()` derives version from the spoofed UA instead of returning a hardcoded older version.
+
+### Improved
+- `isBrowserDead` helper extracted — deduped 3 spoof sites that hand-rolled the same `isConnected`/`closed` check.
+- `preserveCtorIdentity` helper added — applied at the 5 wrapper sites above.
+- GPU pool seeded by `domain + ':gpu'` (was just `domain`) — keeps per-domain GPU stable while decoupling it from any other per-domain seed we might add.
+- 10 dead module-level exports trimmed from `lib/fingerprint.js`.
+- `safeDefinePropertyLocal` forces `configurable: true` instead of merging it from the caller's descriptor (caller-side opt-in was unreliable).
+
 ## [3.0.0] - 2026-05-23
 
 ### Changed

package/CLAUDE.md

@@ -66,6 +66,28 @@ node nwss.js --dry-run                # Preview without network calls
 node nwss.js --headful                # Launch with browser GUI
 ```
 
+## Stealth Testing
+
+`scripts/test-stealth.js` is a smoke-test harness for the fingerprint spoofing
+stack. Launches Puppeteer with `applyAllFingerprintSpoofing` applied (same
+call shape nwss.js uses), navigates to public bot-detection pages, and
+reports what they concluded. Use it to A/B a stealth change — run before the
+edit, run after, diff. Found 3 real bugs that 5 rounds of static review
+missed (PHANTOM/SELENIUM own-goal, PluginArray instanceof, Plugin toString).
+
+```bash
+node scripts/test-stealth.js                  # all targets, human-readable
+node scripts/test-stealth.js sannysoft        # one target
+node scripts/test-stealth.js --no-spoof       # baseline (spoof disabled)
+node scripts/test-stealth.js --format=json    # machine-readable for diff/jq
+node scripts/test-stealth.js --help           # full flag list
+```
+
+Set `PUPPETEER_NO_SANDBOX=1` when running as root (CI containers). Off by
+default so local dev doesn't silently drop the sandbox. The harness depends
+on `USER_AGENT_COLLECTIONS` exported from `lib/fingerprint.js` — keep that
+export in sync if the UA list changes.
+
 ## Files to Ignore
 
 - `node_modules/**`

package/README.md

@@ -790,4 +790,21 @@ your_username ALL=(root) NOPASSWD: /usr/bin/wg-quick, /usr/bin/wg
 - Ghost-cursor (`cursor_mode: "ghost"`) is optional — install with `npm i ghost-cursor`. Falls back to built-in mouse if not installed
 - Ghost-cursor duration defaults to `interact_duration` (or 2000ms), capped by the 15s hard timeout
 
+## Stealth Testing
+
+`scripts/test-stealth.js` is a developer-facing smoke test for the fingerprint spoofing stack in `lib/fingerprint.js`. It launches Puppeteer with the same `applyAllFingerprintSpoofing` call that `nwss.js` uses, navigates to public bot-detection pages, and reports what they concluded — pass/warn/fail counts from sannysoft, trust score from creepjs, raw navigator values from browserleaks.
+
+Use it to A/B a stealth change: run before the edit, run after, diff the output. Not a unit test — it doesn't assert; it reports.
+
+```bash
+node scripts/test-stealth.js                  # all targets, human-readable
+node scripts/test-stealth.js sannysoft        # one target only
+node scripts/test-stealth.js --no-spoof       # baseline (spoof disabled)
+node scripts/test-stealth.js --ua=firefox     # spoof a different UA family
+node scripts/test-stealth.js --format=json    # machine-readable for diff/jq
+node scripts/test-stealth.js --help           # full flag list
+```
+
+Set `PUPPETEER_NO_SANDBOX=1` when running as root (CI containers, some Docker setups). Off by default so local dev doesn't silently drop the Chromium sandbox.
+
 ---

package/lib/browserexit.js

@@ -159,7 +159,7 @@ async function cleanupUserDataDir(userDataDir, forceDebug = false) {
  */
 async function gracefulBrowserCleanup(browser, forceDebug = false) {
   // FIX: Check browser connection before operations
-  if (!browser || !browser.isConnected()) {
+  if (!browser || !browser.connected) {
     if (forceDebug) console.log(formatLogMessage('debug', `${BROWSER_TAG} Browser not connected, skipping cleanup`));
     return;
   }
@@ -198,7 +198,7 @@ async function gracefulBrowserCleanup(browser, forceDebug = false) {
 
   // FIX: Check browser is still connected before closing
   try {
-    if (browser.isConnected()) {
+    if (browser.connected) {
       await browser.close();
       if (forceDebug) console.log(formatLogMessage('debug', `${BROWSER_TAG} Browser closed successfully`));
     } else {
@@ -336,7 +336,7 @@ async function forceBrowserKill(browser, forceDebug = false) {
   }
 
   try {
-    if (browser.isConnected()) {
+    if (browser.connected) {
       browser.disconnect();
       if (forceDebug) console.log(formatLogMessage('debug', `${BROWSER_TAG} Browser connection disconnected`));
     }
@@ -443,7 +443,7 @@ async function handleBrowserExit(browser, options = {}) {
       // isConnected() to false — in that case the nuclear path would just
       // murder other people's puppeteer-chrome instances for no gain.
       let stillConnected = false;
-      try { stillConnected = browser.isConnected(); } catch (_) {}
+      try { stillConnected = browser.connected; } catch (_) {}
       if (stillConnected) {
         if (forceDebug) console.log(formatLogMessage('debug', `${BROWSER_TAG} Targeted force kill didn't take — escalating to nuclear cleanup`));
         await killAllPuppeteerChrome(forceDebug);

package/lib/browserhealth.js

@@ -919,7 +919,7 @@ async function testBrowserConnectivity(browserInstance, timeout = 2500) {
 
   try {
     // Test 1: Basic browser connection
-    const isConnected = browserInstance.isConnected();
+    const isConnected = browserInstance.connected;
     connectivityResult.connected = isConnected;
     
     if (!isConnected) {

package/lib/fingerprint.js

@@ -26,13 +26,6 @@ function seededRandom(seed) {
 const _fingerprintCache = new Map();
 const FINGERPRINT_CACHE_MAX = 500;
 
-// Type-specific property spoofing functions for monomorphic optimization
-// Built-in properties that should not be modified
-const BUILT_IN_PROPERTIES = new Set([
-  'href', 'origin', 'protocol', 'host', 'hostname', 'port', 'pathname', 'search', 'hash',
-  'constructor', 'prototype', '__proto__', 'toString', 'valueOf', 'assign', 'reload', 'replace'
-]);
-
 // User agent collections with latest versions
 const USER_AGENT_COLLECTIONS = Object.freeze(new Map([
   ['chrome', "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"],
@@ -77,15 +70,53 @@ const GPU_POOL = {
 };
 
 /**
- * Select a GPU from the pool based on user agent string.
- * Called once per browser session so the GPU stays consistent across page loads.
+ * Select a GPU from the pool based on user agent string. When `domain` is
+ * provided, selection is deterministic per-domain (seeded) -- a tracker
+ * logging UNMASKED_RENDERER_WEBGL sees the SAME machine across reloads of
+ * the same site. Without `domain`, falls back to Math.random for ad-hoc
+ * callers. Matches the same per-domain consistency that
+ * generateRealisticFingerprint uses for the rest of the spoof set.
  */
-function selectGpuForUserAgent(userAgentString) {
+function selectGpuForUserAgent(userAgentString, domain = '') {
   let osKey = 'windows';
   if (userAgentString && (userAgentString.includes('Macintosh') || userAgentString.includes('Mac OS X'))) osKey = 'mac';
   else if (userAgentString && (userAgentString.includes('X11; Linux') || userAgentString.includes('Ubuntu'))) osKey = 'linux';
   const pool = GPU_POOL[osKey];
-  return pool[Math.floor(Math.random() * pool.length)];
+  // Distinct seed suffix so the GPU pick doesn't collide with the
+  // fingerprint generator's advance sequence for the same domain.
+  const rand = domain ? seededRandom(domain + ':gpu') : Math.random;
+  return pool[Math.floor(rand() * pool.length)];
+}
+
+/**
+ * One-shot "is this browser dead?" guard. Three of the four spoof entry
+ * points (applyUserAgentSpoofing, applyBraveSpoofing,
+ * applyFingerprintProtection) had this exact try/catch block inline:
+ *
+ *   try {
+ *     if (!page.browser().connected || page.isClosed()) return;
+ *     if (page.browser().process()?.killed) return;
+ *   } catch { return; }
+ *
+ * Three copies meant any Puppeteer API change (like the v25
+ * isConnected -> connected swap) needed three fixes. Now one.
+ *
+ * simulateHumanBehavior is NOT migrated here -- it has different debug
+ * log messages per failure mode ("page closed" vs "browser
+ * disconnected") that this helper doesn't preserve. Could plumb a
+ * callback for the log but the existing inline form is fine for one
+ * caller.
+ */
+function isBrowserDead(page) {
+  try {
+    if (!page || page.isClosed()) return true;
+    const browser = page.browser();
+    if (!browser.connected) return true;
+    if (browser.process()?.killed) return true;
+    return false;
+  } catch {
+    return true; // any failure reading browser state -> treat as dead
+  }
 }
 
 /**
@@ -103,67 +134,21 @@ function isSessionClosedError(err) {
 }
 
 /**
- * Safely defines a property with comprehensive error handling
- */
-function safeDefineProperty(target, property, descriptor, options = {}) {
-  if (BUILT_IN_PROPERTIES.has(property)) {
-    if (options.debug) console.log(`[fingerprint] Skipping built-in property: ${property}`);
-    return false;
-  }
-
-  try {
-    const existing = Object.getOwnPropertyDescriptor(target, property);
-    if (existing?.configurable === false) {
-      if (options.debug) console.log(`[fingerprint] Cannot modify non-configurable: ${property}`);
-      return false;
-    }
-
-    Object.defineProperty(target, property, descriptor);
-    return true;
-  } catch (err) {
-    if (options.debug) console.log(`[fingerprint] Failed to define ${property}: ${err.message}`);
-    return false;
-  }
-}
-
-/**
- * Safely executes spoofing operations with error handling
- */
-function safeSpoofingExecution(spoofFunction, description, options = {}) {
-  try {
-    spoofFunction();
-    return true;
-  } catch (err) {
-    if (options.debug) console.log(`[fingerprint] ${description} failed: ${err.message}`);
-    return false;
-  }
-}
-
-/**
- * Generates realistic screen resolutions based on common monitor sizes
- */
-function getRealisticScreenResolution() {
-  const commonResolutions = [
-    { width: 1920, height: 1080 },
-    { width: 1366, height: 768 },
-    { width: 1440, height: 900 },
-    { width: 1536, height: 864 },
-    { width: 1600, height: 900 },
-    { width: 2560, height: 1440 },
-    { width: 1280, height: 720 },
-    { width: 3440, height: 1440 }
-  ];
-  return commonResolutions[Math.floor(Math.random() * commonResolutions.length)];
-}
-
-/**
- * Generates randomized but realistic browser fingerprint values
- * When domain is provided, values are deterministic per-domain (consistent across reloads)
+ * Generates randomized but realistic browser fingerprint values.
+ * When domain is provided, values are deterministic per-(domain, userAgent)
+ * tuple -- consistent across reloads, but distinct across UA rotation so
+ * a re-scan with `userAgent: 'firefox'` doesn't reuse a previous
+ * `userAgent: 'chrome'` cache entry (which would ship Mac/Win-platform
+ * values under a Firefox UA, etc.).
  */
 function generateRealisticFingerprint(userAgent, domain = '') {
-  // Return cached fingerprint if same domain visited again
-  if (domain) {
-    const cached = _fingerprintCache.get(domain);
+  // Cache key includes UA so a domain scanned twice with different UAs
+  // doesn't get the first UA's OS-mismatched fingerprint reused for the
+  // second. The `|` separator can't appear in a hostname (RFC 952/RFC
+  // 1123 allow only LDH) so it's collision-safe.
+  const cacheKey = domain ? `${domain}|${userAgent}` : '';
+  if (cacheKey) {
+    const cached = _fingerprintCache.get(cacheKey);
     if (cached) return cached;
   }
 
@@ -239,12 +224,12 @@ function generateRealisticFingerprint(userAgent, domain = '') {
     doNotTrack: null // Most users don't enable DNT
   };
   
-  // Cache for this domain
-  if (domain) {
+  // Cache for this (domain, userAgent) tuple. Same key as the lookup above.
+  if (cacheKey) {
     if (_fingerprintCache.size >= FINGERPRINT_CACHE_MAX) {
       _fingerprintCache.delete(_fingerprintCache.keys().next().value);
     }
-    _fingerprintCache.set(domain, fingerprint);
+    _fingerprintCache.set(cacheKey, fingerprint);
   }
 
   return fingerprint;
@@ -257,7 +242,7 @@ async function validatePageForInjection(page, currentUrl, forceDebug) {
   try {
     if (!page || page.isClosed()) return false;
     
-    if (!page.browser().isConnected()) {
+    if (!page.browser().connected) {
       if (forceDebug) console.log(formatLogMessage('debug', `Page validation failed - browser disconnected: ${currentUrl}`));
       return false;
     }
@@ -277,14 +262,18 @@ async function validatePageForInjection(page, currentUrl, forceDebug) {
  */
 async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl) {
   if (!siteConfig.userAgent) return;
+  // Type guard: callers (including config-driven paths) might pass non-string
+  // values by accident (e.g. an array, an object). Without this guard, the
+  // .toLowerCase() call below would throw and crash the whole spoof
+  // pipeline for this URL with no actionable error.
+  if (typeof siteConfig.userAgent !== 'string') {
+    if (forceDebug) console.log(formatLogMessage('debug', `Invalid userAgent type for ${currentUrl}: expected string, got ${typeof siteConfig.userAgent}`));
+    return;
+  }
 
   if (forceDebug) console.log(formatLogMessage('debug', `User agent spoofing: ${siteConfig.userAgent}`));
 
-  // Browser connection check
-  try { 
-    if (!page.browser().isConnected() || page.isClosed()) return; 
-    if (page.browser().process()?.killed) return;
-  } catch { return; }
+  if (isBrowserDead(page)) return;
 
   // Validate page state before injection
   if (!(await validatePageForInjection(page, currentUrl, forceDebug))) return;
@@ -303,11 +292,27 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
     if (forceDebug) console.log(formatLogMessage('debug', `Applying stealth protection for ${currentUrl}`));
     
     try {
-      // Select GPU once per session — stays consistent across all page loads
-      const selectedGpu = selectGpuForUserAgent(ua);
+      // Derive site domain once -- used to seed the per-domain GPU pick
+      // (so a tracker logging UNMASKED_RENDERER_WEBGL sees one machine per
+      // site) AND to pre-compute hardware-concurrency from the SAME
+      // realistic-fingerprint generator that applyFingerprintProtection
+      // uses. That kills the order-dependent visible-value bug: previously
+      // hardwareConcurrency was random in the UA block (line 819) and
+      // domain-seeded in applyFingerprintProtection -- whichever evaluate
+      // ran second won. Now both paths produce the same value.
+      let siteDomain = '';
+      try { siteDomain = new URL(currentUrl).hostname; } catch (_) {}
+
+      const selectedGpu = selectGpuForUserAgent(ua, siteDomain);
       if (forceDebug) console.log(formatLogMessage('debug', `Selected GPU: ${selectedGpu.vendor} / ${selectedGpu.renderer}`));
 
-      await page.evaluateOnNewDocument((userAgent, debugEnabled, gpuConfig) => {
+      // Pre-compute hardware-concurrency from the (cached, domain-seeded)
+      // realistic fingerprint so the UA-spoof block uses the same value
+      // applyFingerprintProtection will later -- no order dependency,
+      // same value regardless of which evaluate runs first.
+      const realistic = generateRealisticFingerprint(ua, siteDomain);
+
+      await page.evaluateOnNewDocument((userAgent, debugEnabled, gpuConfig, seededCores) => {
       
         // Apply inline error suppression first
         (function() {
@@ -315,35 +320,53 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
           const originalWindowError = window.onerror;
           
           function shouldSuppressFingerprintError(message) {
+            // Suppression list, ordered specific -> general.
+            // .some() stops at first match, so a broken specific just means
+            // the general catchers below do the work instead.
+            //
+            // Fixed (was using `\\.` / `\\d` / `\\(` / `\\$` -- DOUBLE
+            // backslashes in source). Each `\\X` parses as
+            // literal-backslash + wildcard-X, requiring a literal `\` in
+            // the error text -- which never appears. So those entries
+            // silently never matched anything; only the general catchers
+            // below were actually suppressing those error families.
+            // Switched to single-backslash form (literal-X escapes) so
+            // each specific entry now matches its intended error class
+            // for accurate debug logging of WHICH pattern matched.
+            //
+            // Also dropped:
+            //   - /Failed to load resource.*40[34]/i -- fully subsumed by
+            //     the broader /[45]\d{2}/i below.
             const patterns = [
               /\.closest is not a function/i,
               /\.querySelector is not a function/i,
               /\.addEventListener is not a function/i,
-              /Cannot read propert(y|ies) of null \\(reading 'fp'\\)/i,
-              /Cannot read propert(y|ies) of undefined \\(reading 'fp'\\)/i,
+              /Cannot read propert(y|ies) of null \(reading 'fp'\)/i,
+              /Cannot read propert(y|ies) of undefined \(reading 'fp'\)/i,
               /Cannot redefine property: href/i,
               /Cannot redefine property: __webdriver_script_func/i,
               /Cannot redefine property: webdriver/i,
-              /Cannot read propert(y|ies) of undefined \\(reading 'toLowerCase'\\)/i,
-              /\\.toLowerCase is not a function/i,
+              /Cannot read propert(y|ies) of undefined \(reading 'toLowerCase'\)/i,
+              /\.toLowerCase is not a function/i,
               /fp is not defined/i,
               /fingerprint is not defined/i,
               /FingerprintJS is not defined/i,
-              /\\$ is not defined/i,
+              /\$ is not defined/i,
               /jQuery is not defined/i,
               /_ is not defined/i,
-              /Failed to load resource.*server responded with a status of [45]\\d{2}/i,
+              /Failed to load resource.*server responded with a status of [45]\d{2}/i,
               /Failed to fetch/i,
               /(webdriver|callPhantom|_phantom|__nightmare|_selenium) is not defined/i,
               /Failed to execute 'observe' on 'IntersectionObserver'.*parameter 1 is not of type 'Element'/i,
               /tz check/i,
-              /new window\\.Error.*<anonymous>/i,
-              /Failed to load resource.*server responded with a status of 40[34]/i,
+              /new window\.Error.*<anonymous>/i,
               /Blocked script execution in 'about:blank'.*sandboxed.*allow-scripts/i,
               /Page JavaScript error:/i,
               /^[a-zA-Z0-9_$]+\[.*\]\s+is not a function/i,
               /^[a-zA-Z0-9_$]+\(.*\)\s+is not a function/i,
               /^[a-zA-Z0-9_$]+\.[a-zA-Z0-9_$]+.*is not a function/i,
+              // General catchers — kept last so the specific entries
+              // above can match first for accurate debug attribution.
               /Failed to load resource/i,
               /is not defined/i,
               /is not a function/i
@@ -383,6 +406,30 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
           }
           return fn;
         }
+
+        // Wrapper-constructor identity preserver. Function.name and
+        // Function.length are own data properties of every function
+        // object, NOT inherited via prototype chain -- so even after
+        // Object.setPrototypeOf(wrapper, OriginalCtor), the wrapper
+        // still has its own name (empty for anonymous expressions) and
+        // length (count of leading formal params). A bot detector that
+        // checks `Error.name === 'Error'` would see '' on our spoof.
+        //
+        // Real Chrome's Function.name has descriptor
+        //   {value: ..., writable: false, enumerable: false, configurable: true}
+        // -- match that shape so getOwnPropertyDescriptor checks pass too.
+        function preserveCtorIdentity(wrapper, original) {
+          try {
+            Object.defineProperty(wrapper, 'name', {
+              value: original.name, writable: false, enumerable: false, configurable: true
+            });
+            Object.defineProperty(wrapper, 'length', {
+              value: original.length, writable: false, enumerable: false, configurable: true
+            });
+          } catch (e) {
+            if (debugEnabled) console.log(`[fingerprint] preserveCtorIdentity failed: ${e.message}`);
+          }
+        }
         
         Function.prototype.toString = function() {
           if (nativeFunctionStore.has(this)) {
@@ -393,10 +440,14 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
         // Protect the toString override itself
         nativeFunctionStore.set(Function.prototype.toString, 'toString');
         
-        // Create safe property definition helper
+        // Create safe property definition helper.
+        // configurable: true is a DEFAULT (not a force) -- if a caller
+        // wants to lock a property (configurable: false) the spread won't
+        // override their explicit value. Previously `{ ...descriptor,
+        // configurable: true }` silently overrode any caller intent.
         function safeDefinePropertyLocal(target, property, descriptor) {
           const builtInProps = new Set(['href', 'origin', 'protocol', 'host', 'hostname', 'port', 'pathname', 'search', 'hash', 'constructor', 'prototype', '__proto__', 'toString', 'valueOf', 'assign', 'reload', 'replace']);
-       
+
           if (builtInProps.has(property)) {
             if (debugEnabled) console.log(`[fingerprint] Skipping built-in property: ${property}`);
             return false;
@@ -410,8 +461,8 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
             }
 
             Object.defineProperty(target, property, {
-              ...descriptor,
-              configurable: true
+              configurable: true,
+              ...descriptor
             });
             return true;
           } catch (err) {
@@ -473,13 +524,21 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
             '$cdc_asdjflasutopfhvcZLmcfl_', '$chrome_asyncScriptInfo', '__$webdriverAsyncExecutor'
           ];
           
+          // Just delete -- DO NOT re-add as undefined-returning getters.
+          // The previous version did:
+          //   delete window[prop];
+          //   safeDefinePropertyLocal(window, prop, { get: () => undefined });
+          // which made `window.callPhantom` return undefined (good) but ALSO
+          // made `'callPhantom' in window` return TRUE (bad) -- the property
+          // exists on the object even if the getter returns undefined. Real
+          // Chrome doesn't have these props at all, so `in`-operator and
+          // Object.getOwnPropertyNames probes saw a present property and
+          // flagged us as a bot. This own-goal was caught by
+          // scripts/test-stealth.js sannysoft (PHANTOM_PROPERTIES and
+          // SELENIUM_DRIVER cells went red because of it).
           automationProps.forEach(prop => {
-            try {
-              delete window[prop];
-              delete navigator[prop];
-              safeDefinePropertyLocal(window, prop, { get: () => undefined });
-              safeDefinePropertyLocal(navigator, prop, { get: () => undefined });
-            } catch (e) {}
+            try { delete window[prop]; } catch (e) {}
+            try { delete navigator[prop]; } catch (e) {}
           });
         }, 'automation properties removal');
 
@@ -501,12 +560,21 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
                 postMessage: () => {}, 
                 disconnect: () => {} 
               }),
-              getManifest: () => ({ 
-                name: "Chrome", 
-                version: "146.0.0.0",
-                manifest_version: 3,
-                description: "Chrome Browser"
-              }),
+              getManifest: () => {
+                // Derive Chrome version from the spoofed UA so a tracker
+                // cross-checking navigator.userAgent's Chrome version
+                // against chrome.runtime.getManifest().version sees a
+                // consistent number. Was hardcoded "146.0.0.0" which lied
+                // any time the UA was rotated to a different Chrome major.
+                const m = userAgent.match(/Chrome\/(\d+)/);
+                const major = m ? m[1] : '146';
+                return {
+                  name: "Chrome",
+                  version: `${major}.0.0.0`,
+                  manifest_version: 3,
+                  description: "Chrome Browser"
+                };
+              },
               getURL: (path) => `chrome-extension://invalid/${path}`,
               id: undefined,
               getPlatformInfo: (callback) => callback({
@@ -571,11 +639,22 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
             });
           }
 
-          // Make chrome object non-enumerable to match real Chrome
+          // The old comment claimed "non-enumerable to match real Chrome" --
+          // but real Chrome's window.chrome property descriptor is
+          // {value: ..., writable: true, enumerable: true, configurable: true}.
+          // The previous writable:false + enumerable:false were themselves
+          // fingerprintable tells: a bot detector reading
+          //   Object.getOwnPropertyDescriptor(window, 'chrome')
+          // would see {writable:false, enumerable:false} and know this
+          // isn't real Chrome. `window.chrome = 'x'` would also silently
+          // fail (vs succeed on real Chrome). Match real Chrome's
+          // descriptor instead. The defineProperty is kept (rather than
+          // removed entirely) so re-injection on reload doesn't lose the
+          // descriptor shape if anything earlier tightened it.
           Object.defineProperty(window, 'chrome', {
             value: window.chrome,
-            writable: false,
-            enumerable: false,
+            writable: true,
+            enumerable: true,
             configurable: true
           });
 
@@ -649,6 +728,30 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
             // Safari typically has no plugins in modern versions
             plugins = [];
           }
+          // Each plugin object needs to identify as a Plugin instance so
+          // `navigator.plugins[i].toString() === '[object Plugin]'` passes.
+          // (Sannysoft's actual PluginArray check tests this -- found via
+          // scripts/test-stealth.js sannysoft.) Resolve Plugin.prototype the
+          // same way we resolve PluginArray.prototype below: prefer the
+          // global, fall back to navigator.plugins[0]'s prototype if a real
+          // plugin exists, fall back to just Symbol.toStringTag if neither.
+          let pluginProto = null;
+          try {
+            if (typeof Plugin !== 'undefined' && Plugin.prototype) {
+              pluginProto = Plugin.prototype;
+            } else if (navigator.plugins && navigator.plugins[0]) {
+              pluginProto = Object.getPrototypeOf(navigator.plugins[0]);
+            }
+          } catch (e) {}
+          plugins = plugins.map(p => {
+            const wrapped = Object.assign(Object.create(pluginProto || Object.prototype), p);
+            if (!pluginProto) {
+              // Last-ditch: at least toString() returns "[object Plugin]"
+              wrapped[Symbol.toStringTag] = 'Plugin';
+            }
+            return wrapped;
+          });
+
           // Create proper array-like object with enumerable indices and length
           // Create proper PluginArray-like object with required methods
           const pluginsArray = {};
@@ -671,6 +774,27 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
           pluginsArray[Symbol.iterator] = function*() { for (const p of plugins) yield p; };
           pluginsArray[Symbol.toStringTag] = 'PluginArray';
 
+          // Make `navigator.plugins instanceof PluginArray` evaluate true.
+          // Multiple ways to get PluginArray.prototype, in order of
+          // preference -- evaluateOnNewDocument can fire before all globals
+          // are bound, so we don't assume `PluginArray` is in scope. Falls
+          // back to inheriting from the existing navigator.plugins's own
+          // prototype, which is ALWAYS a real PluginArray.prototype on
+          // any DOM-bearing context.
+          try {
+            let pluginArrayProto = null;
+            if (typeof PluginArray !== 'undefined' && PluginArray.prototype) {
+              pluginArrayProto = PluginArray.prototype;
+            } else if (navigator.plugins) {
+              pluginArrayProto = Object.getPrototypeOf(navigator.plugins);
+            }
+            if (pluginArrayProto && pluginArrayProto !== Object.prototype) {
+              Object.setPrototypeOf(pluginsArray, pluginArrayProto);
+            }
+          } catch (e) {
+            if (debugEnabled) console.log(`[fingerprint] PluginArray prototype setup failed: ${e.message}`);
+          }
+
           safeDefinePropertyLocal(navigator, 'plugins', { get: () => pluginsArray });
         }, 'plugins spoofing');
 
@@ -813,12 +937,17 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
           }
         }, 'enhanced OS fingerprinting protection');
 
-        // Hardware concurrency spoofing (universal coverage)
-        //
+        // Hardware concurrency spoofing (universal coverage).
+        // Uses the domain-seeded value passed in from the Node-side
+        // generateRealisticFingerprint call -- previously did its own
+        // Math.random() pick from [4,6,8,12], which conflicted with the
+        // domain-seeded value set later by applyFingerprintProtection.
+        // Whichever evaluate ran second won, producing an order-dependent
+        // visible value. Now both paths use the same seeded value, so
+        // double-spoof becomes idempotent.
         safeExecute(() => {
-          const spoofedCores = [4, 6, 8, 12][Math.floor(Math.random() * 4)];
           const hardwareProps = {
-            hardwareConcurrency: { get: () => spoofedCores }
+            hardwareConcurrency: { get: () => seededCores }
           };
           spoofNavigatorProperties(navigator, hardwareProps);
         }, 'hardware concurrency spoofing');
@@ -889,12 +1018,24 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
           
           window.Error.prototype = OriginalError.prototype;
           Object.setPrototypeOf(window.Error, OriginalError);
+          preserveCtorIdentity(window.Error, OriginalError);
           
-          // Copy static properties
+          // Forward static properties via getter/setter pairs instead of
+          // value-copy, so live mutations to OriginalError (e.g. page
+          // code doing `Error.stackTraceLimit = 100`) propagate through
+          // the wrapper. Previously the value-copy froze a snapshot at
+          // injection time; a tracker that mutated stackTraceLimit and
+          // then read it back from the wrapped Error would see the old
+          // value -- a real fingerprint tell.
           ['captureStackTrace', 'stackTraceLimit', 'prepareStackTrace'].forEach(prop => {
-            if (OriginalError[prop]) {
-              try { window.Error[prop] = OriginalError[prop]; } catch (e) {}
-            }
+            try {
+              Object.defineProperty(window.Error, prop, {
+                get: () => OriginalError[prop],
+                set: (v) => { OriginalError[prop] = v; },
+                configurable: true,
+                enumerable: false
+              });
+            } catch (e) {}
           });
         }, 'Error stack protection');
 
@@ -1161,19 +1302,25 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
           }
         }, 'window dimension spoofing');
 
-        // navigator.connection — missing or incomplete in headless
+        // navigator.connection — missing or incomplete in headless.
+        // Object literal hoisted out of the getter so identity is stable
+        // across reads. Real Chrome's NetworkInformation instance has
+        // `navigator.connection === navigator.connection`; previously
+        // the getter returned a new object on every read, which a
+        // tracker could detect by comparing references.
         safeExecute(() => {
           if (!navigator.connection) {
+            const connectionInfoStable = {
+              effectiveType: '4g',
+              rtt: 50,
+              downlink: 10,
+              saveData: false,
+              type: 'wifi',
+              addEventListener: () => {},
+              removeEventListener: () => {}
+            };
             Object.defineProperty(navigator, 'connection', {
-              get: () => ({
-                effectiveType: '4g',
-                rtt: 50,
-                downlink: 10,
-                saveData: false,
-                type: 'wifi',
-                addEventListener: () => {},
-                removeEventListener: () => {}
-              })
+              get: () => connectionInfoStable
             });
           }
         }, 'connection API spoofing');
@@ -1254,7 +1401,10 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
             return img;
           };
           window.Image.prototype = OrigImage.prototype;
-          Object.defineProperty(window, 'Image', { writable: true, configurable: true });
+          preserveCtorIdentity(window.Image, OrigImage);
+          // (Note: the prior Object.defineProperty(window, 'Image', ...) here
+          // was a no-op -- changed descriptor flags without setting value.
+          // Removed; the wrapper is already assigned to window.Image above.)
         }, 'broken image dimension spoofing');
         
         // Fetch Request Headers Normalization
@@ -1345,6 +1495,7 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
             };
             Object.setPrototypeOf(window.RTCPeerConnection, OriginalRTC);
             window.RTCPeerConnection.prototype = OriginalRTC.prototype;
+            preserveCtorIdentity(window.RTCPeerConnection, OriginalRTC);
           }
         }, 'WebRTC spoofing');
 
@@ -1587,8 +1738,9 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
               return new OriginalPointerEvent(type, enhancedDict);
             };
             Object.setPrototypeOf(window.PointerEvent, OriginalPointerEvent);
+            preserveCtorIdentity(window.PointerEvent, OriginalPointerEvent);
           }
-          
+
           // Spoof touch capabilities for mobile detection evasion
           if (!window.TouchEvent && Math.random() > 0.8) {
             // 20% chance to add touch support to confuse fingerprinters
@@ -1612,6 +1764,8 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
               };
               return new originalWheelEvent(type, enhancedDict);
             };
+            Object.setPrototypeOf(window.WheelEvent, originalWheelEvent);
+            preserveCtorIdentity(window.WheelEvent, originalWheelEvent);
           }
           
         }, 'enhanced mouse/pointer spoofing');
@@ -1744,7 +1898,7 @@ async function applyUserAgentSpoofing(page, siteConfig, forceDebug, currentUrl)
           }
         }, 'interaction-gated script trigger');
 
-      }, ua, forceDebug, selectedGpu);
+      }, ua, forceDebug, selectedGpu, realistic.hardwareConcurrency);
     } catch (stealthErr) {
       if (isSessionClosedError(stealthErr)) {
         if (forceDebug) console.log(formatLogMessage('debug', `Page closed during stealth injection: ${currentUrl}`));
@@ -1762,12 +1916,8 @@ async function applyBraveSpoofing(page, siteConfig, forceDebug, currentUrl) {
   if (!siteConfig.isBrave) return;
 
   if (forceDebug) console.log(formatLogMessage('debug', `Brave spoofing enabled for ${currentUrl}`));
-  
-  // Browser connection check
-  try { 
-    if (!page.browser().isConnected() || page.isClosed()) return; 
-    if (page.browser().process()?.killed) return;
-  } catch { return; }
+
+  if (isBrowserDead(page)) return;
 
   // Validate page state before injection
   if (!(await validatePageForInjection(page, currentUrl, forceDebug))) return;
@@ -1814,12 +1964,8 @@ async function applyFingerprintProtection(page, siteConfig, forceDebug, currentU
   if (!fingerprintSetting) return;
 
   if (forceDebug) console.log(formatLogMessage('debug', `Fingerprint protection enabled for ${currentUrl}`));
-  
-  // Browser connection check
-  try { 
-    if (!page.browser().isConnected() || page.isClosed()) return; 
-    if (page.browser().process()?.killed) return;
-  } catch { return; }
+
+  if (isBrowserDead(page)) return;
   
   // Validate page state before injection
   if (!(await validatePageForInjection(page, currentUrl, forceDebug))) return;
@@ -1864,14 +2010,30 @@ async function applyFingerprintProtection(page, siteConfig, forceDebug, currentU
         }
       }
       
+      // Mirror of the helper defined inside applyUserAgentSpoofing's
+      // evaluate -- both behave identically: skip built-ins, refuse to
+      // touch non-configurable, default (not force) configurable:true so
+      // explicit caller intent is preserved. Previously this copy
+      // diverged: it had no built-in check AND it force-overrode
+      // configurable:true regardless of caller. Now consistent.
       function safeDefinePropertyLocal(target, property, descriptor) {
+        const builtInProps = new Set(['href', 'origin', 'protocol', 'host', 'hostname', 'port', 'pathname', 'search', 'hash', 'constructor', 'prototype', '__proto__', 'toString', 'valueOf', 'assign', 'reload', 'replace']);
+
+        if (builtInProps.has(property)) {
+          if (debugEnabled) console.log(`[fingerprint] Skipping built-in property: ${property}`);
+          return false;
+        }
+
         try {
           const existing = Object.getOwnPropertyDescriptor(target, property);
-          if (existing?.configurable === false) return false;
-          
+          if (existing?.configurable === false) {
+            if (debugEnabled) console.log(`[fingerprint] Cannot modify non-configurable: ${property}`);
+            return false;
+          }
+
           Object.defineProperty(target, property, {
-            ...descriptor,
-            configurable: true
+            configurable: true,
+            ...descriptor
           });
           return true;
         } catch (err) {
@@ -1982,7 +2144,7 @@ async function simulateHumanBehavior(page, forceDebug) {
     }
     
     // Check if browser is still connected
-    if (!page.browser().isConnected()) {
+    if (!page.browser().connected) {
       if (forceDebug) console.log(formatLogMessage('debug', `Human behavior simulation skipped - browser disconnected`));
       return;
     }
@@ -2128,16 +2290,17 @@ async function applyAllFingerprintSpoofing(page, siteConfig, forceDebug, current
   }
 }
 
+// Public surface kept narrow on purpose -- only what nwss.js actually
+// imports. Internal helpers (generateRealisticFingerprint,
+// applyUserAgentSpoofing, applyBraveSpoofing, applyFingerprintProtection,
+// simulateHumanBehavior, selectGpuForUserAgent, isBrowserDead,
+// isSessionClosedError, validatePageForInjection, seededRandom,
+// DEFAULT_PLATFORM, DEFAULT_TIMEZONE) stay as module-local; move back to
+// module.exports only if a new external consumer appears.
 module.exports = {
-  generateRealisticFingerprint,
-  getRealisticScreenResolution,
-  applyUserAgentSpoofing,
-  applyBraveSpoofing,
-  applyFingerprintProtection,
   applyAllFingerprintSpoofing,
-  simulateHumanBehavior,
-  safeDefineProperty,
-  safeSpoofingExecution,
-  DEFAULT_PLATFORM,
-  DEFAULT_TIMEZONE
+  // Exposed for scripts/test-stealth.js so the harness can validate --ua=
+  // against the canonical UA list (instead of duplicating the keys here).
+  // The Map itself is frozen; consumers cannot mutate the spoof source.
+  USER_AGENT_COLLECTIONS
 };

package/lib/proxy.js

@@ -335,7 +335,14 @@ async function testProxy(siteConfig, timeoutMs = 5000) {
 }
 
 /**
- * Returns human-readable proxy info string for logging.
+ * Returns human-readable proxy info string for logging. The auth portion
+ * is REDACTED -- previously the username was emitted verbatim, which
+ * meant any error log line carrying this value (see nwss.js's
+ * ERR_SOCKS_CONNECTION_FAILED handler) leaked the proxy username to
+ * stderr / support tickets / screenshots. Password was already absent
+ * here. We keep an explicit `[redacted]@` marker when auth was configured
+ * so the reader still knows "yes, credentials were attached" without
+ * disclosing what they were.
  *
  * @param {object} siteConfig
  * @returns {string}
@@ -347,7 +354,7 @@ function getProxyInfo(siteConfig) {
   const parsed = parseProxyUrl(proxyUrl);
   if (!parsed) return 'invalid';
 
-  const auth = parsed.username ? `${parsed.username}@` : '';
+  const auth = parsed.username ? '[redacted]@' : '';
   return `${parsed.protocol}://${auth}${parsed.host}:${parsed.port}`;
 }
 

package/lib/redirect.js

@@ -62,7 +62,7 @@ async function navigateWithRedirectHandling(page, currentUrl, siteConfig, gotoOp
       }
       
       // Check if browser is still connected
-      if (!page.browser().isConnected()) {
+      if (!page.browser().connected) {
         if (forceDebug) {
           console.log(formatLogMessage('debug', 'JS redirect detector skipped - browser disconnected'));
         }

package/lib/socks-relay.js

@@ -234,7 +234,12 @@ async function ensureRelay(upstream, forceDebug = false) {
   const port = server.address().port;
   _relays.set(key, { server, port, activeSockets });
   if (forceDebug) {
-    console.log(formatLogMessage('proxy', `${SOCKS_RELAY_TAG} 127.0.0.1:${port} -> ${upstream.host}:${upstream.port} (auth user "${upstream.username}")`));
+    // auth status is kept as a presence flag only -- previously printed
+    // the raw username, which leaked into shared debug output (support
+    // tickets, screenshots, gists). Same redaction policy as the
+    // proxy.js getProxyInfo() change.
+    const authTag = upstream.username ? ' (auth: [redacted])' : ' (no auth)';
+    console.log(formatLogMessage('proxy', `${SOCKS_RELAY_TAG} 127.0.0.1:${port} -> ${upstream.host}:${upstream.port}${authTag}`));
   }
   return port;
 }
@@ -259,7 +264,15 @@ async function closeAllRelays(forceDebug = false) {
     await new Promise((res) => {
       try { r.server.close(() => res()); } catch (_) { res(); }
     });
-    if (forceDebug) console.log(formatLogMessage('proxy', `${SOCKS_RELAY_TAG} closed relay for ${key}`));
+    if (forceDebug) {
+      // upstreamKey embeds the username (host:port:username), so the raw
+      // key would leak it in debug output. Strip just the trailing
+      // `:username` segment for display; using a regex (not split-on-':')
+      // so IPv6 hosts with embedded colons (e.g. 2001:db8::1:1080:user)
+      // aren't mangled. The relay identity stays unambiguous from host+port.
+      const displayKey = key.replace(/:[^:]*$/, '');
+      console.log(formatLogMessage('proxy', `${SOCKS_RELAY_TAG} closed relay for ${displayKey}`));
+    }
   }
   _relays.clear();
 }

package/nwss.js

@@ -2323,7 +2323,7 @@ function setupFrameHandling(page, forceDebug) {
           let browserResponsive = false;
           try {
               // Check if browser is still connected before attempting health check
-              if (!browserInstance.isConnected()) {
+              if (!browserInstance.connected) {
                   throw new Error('Browser not connected');
               }
 
@@ -5713,7 +5713,7 @@ function setupFrameHandling(page, forceDebug) {
     console.log(messageColors.info('Browser kept open.') + ' Close the browser window or press Ctrl+C to exit.');
     const cleanup = async () => {
       try {
-        if (browser.isConnected()) await browser.close();
+        if (browser.connected) await browser.close();
       } catch {}
       process.exit(0);
     };
@@ -5731,7 +5731,7 @@ function setupFrameHandling(page, forceDebug) {
 
   // Enhanced final validation for Puppeteer 23.x
   try {
-    const isStillConnected = browser.isConnected();
+    const isStillConnected = browser.connected;
     if (forceDebug) console.log(formatLogMessage('debug', `Browser connection status before cleanup: ${isStillConnected}`));
   } catch (connErr) {
     if (forceDebug) console.log(formatLogMessage('debug', `Browser connection check failed: ${connErr.message}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanboynz/network-scanner",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "A Puppeteer-based network scanner for analyzing web traffic, generating adblock filter rules, and identifying third-party requests. Features include fingerprint spoofing, Cloudflare bypass, content analysis with curl/grep, and multiple output formats.",
   "main": "nwss.js",
   "scripts": {

package/scripts/test-stealth.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * Stealth integration smoke test.
+ *
+ * Launches Puppeteer, applies the project's full fingerprint spoofing stack
+ * (lib/fingerprint.js's applyAllFingerprintSpoofing), navigates to public
+ * bot-detection test pages, and reports what the page concluded about us.
+ *
+ * Purpose: replace "I think the spoof works" theoretical reviews with real
+ * signal -- which checks pass, which fail, which moved after a fingerprint
+ * change. Run before and after a stealth-related commit to A/B the impact.
+ *
+ * Usage:
+ *   node scripts/test-stealth.js                  # all targets, human-readable
+ *   node scripts/test-stealth.js sannysoft        # one target
+ *   node scripts/test-stealth.js --headful        # show browser GUI
+ *   node scripts/test-stealth.js --no-spoof       # baseline (no fingerprint protection)
+ *   node scripts/test-stealth.js --ua=firefox     # change UA family
+ *   node scripts/test-stealth.js --format=json    # machine-readable output
+ *   node scripts/test-stealth.js --help           # show usage
+ *
+ * Environment:
+ *   PUPPETEER_NO_SANDBOX=1   pass --no-sandbox --disable-setuid-sandbox to
+ *                            Chromium. Required when running as root (CI
+ *                            containers, some Docker setups). Off by default
+ *                            so local dev doesn't silently drop the sandbox.
+ *
+ * Targets (extend by adding to TARGETS below):
+ *   sannysoft     https://bot.sannysoft.com/                  — classic fingerprint tests
+ *   creepjs       https://abrahamjuliot.github.io/creepjs/    — modern fingerprint suite
+ *   browserleaks  https://browserleaks.com/javascript         — JS env probe
+ *
+ * Output: one line per target with PASS / WARN / FAIL counts (where parseable),
+ * plus a short summary of any explicit detection markers ("Bot detected",
+ * "Headless", etc.) found in the page text. With --format=json, emits a single
+ * JSON object suitable for piping to diff/jq for before/after comparison.
+ *
+ * This is a SMOKE test, not a unit test. It doesn't make assertions; it
+ * reports what the page reports. Use the output to decide if a stealth
+ * change moved the needle.
+ */
+
+'use strict';
+
+const puppeteer = require('puppeteer');
+const path = require('path');
+const {
+  applyAllFingerprintSpoofing,
+  USER_AGENT_COLLECTIONS
+} = require(path.resolve(__dirname, '..', 'lib', 'fingerprint'));
+
+const args = process.argv.slice(2);
+const HELP = args.includes('--help') || args.includes('-h');
+const HEADFUL = args.includes('--headful');
+const NO_SPOOF = args.includes('--no-spoof');
+const UA_FLAG = (args.find(a => a.startsWith('--ua=')) || '').slice(5) || 'chrome';
+const FORMAT = (args.find(a => a.startsWith('--format=')) || '').slice(9) || 'text';
+const filterTargets = args.filter(a => !a.startsWith('-'));
+// Anything starting with '-' is a flag claim; we validate the known set
+// below so typos like "-headful" or "--no_spoof" don't silently no-op.
+const flagArgs = args.filter(a => a.startsWith('-'));
+const KNOWN_FLAGS = new Set(['--headful', '--no-spoof', '--help', '-h']);
+const KNOWN_FLAG_PREFIXES = ['--ua=', '--format='];
+
+const TARGETS = [
+  {
+    name: 'sannysoft',
+    url: 'https://bot.sannysoft.com/',
+    // Parse the result tables. Sannysoft uses td.passed / td.failed / td.warn.
+    extract: async (page) => {
+      return await page.evaluate(() => {
+        const cells = Array.from(document.querySelectorAll('td'));
+        const out = { passed: 0, failed: 0, warn: 0, total: 0, failures: [] };
+        for (const c of cells) {
+          const cls = c.className || '';
+          if (cls.includes('passed')) { out.passed++; out.total++; }
+          else if (cls.includes('failed')) {
+            out.failed++; out.total++;
+            // Try to capture the row label for context
+            const row = c.closest('tr');
+            const label = row?.querySelector('td')?.textContent?.trim() || '?';
+            out.failures.push(label);
+          }
+          else if (cls.includes('warn')) { out.warn++; out.total++; }
+        }
+        return out;
+      });
+    }
+  },
+  {
+    name: 'creepjs',
+    url: 'https://abrahamjuliot.github.io/creepjs/',
+    extract: async (page) => {
+      // CreepJS surfaces a trust score in the page. Wait briefly for the
+      // async fingerprinting tests to complete.
+      await page.waitForSelector('#fingerprint-data', { timeout: 30000 }).catch(() => {});
+      await new Promise(r => setTimeout(r, 8000)); // give async tests time
+      return await page.evaluate(() => {
+        const text = document.body.innerText || '';
+        // CreepJS reports a "Trust Score" percentage and individual signal entries.
+        const trustMatch = text.match(/Trust Score[:\s]+(\d+(?:\.\d+)?)\s*%/i);
+        const lieMatch = text.match(/lies[:\s]+(\d+)/i);
+        const botMatch = text.match(/bot[:\s]+(true|false)/i);
+        return {
+          trustScore: trustMatch ? parseFloat(trustMatch[1]) : null,
+          lies: lieMatch ? parseInt(lieMatch[1], 10) : null,
+          botDetected: botMatch ? botMatch[1] === 'true' : null,
+          excerpt: text.split('\n').slice(0, 15).join('\n').slice(0, 400)
+        };
+      });
+    }
+  },
+  {
+    name: 'browserleaks',
+    url: 'https://browserleaks.com/javascript',
+    extract: async (page) => {
+      return await page.evaluate(() => {
+        // browserleaks shows the values; we just capture the navigator-related ones
+        // and report which look anomalous.
+        return {
+          userAgent: navigator.userAgent,
+          platform: navigator.platform,
+          webdriver: navigator.webdriver,
+          languages: JSON.stringify(navigator.languages),
+          hardwareConcurrency: navigator.hardwareConcurrency,
+          deviceMemory: navigator.deviceMemory,
+          plugins: navigator.plugins?.length,
+          chromeRuntime: typeof window.chrome?.runtime,
+          chromeRuntimeVersion: (() => { try { return window.chrome?.runtime?.getManifest?.()?.version; } catch (e) { return 'error'; } })(),
+          windowChromeDescriptor: (() => {
+            const d = Object.getOwnPropertyDescriptor(window, 'chrome');
+            return d ? `writable=${d.writable},enumerable=${d.enumerable},configurable=${d.configurable}` : 'no-descriptor';
+          })(),
+          errorName: Error.name,
+          errorLength: Error.length,
+          rtcName: window.RTCPeerConnection?.name,
+          imageName: window.Image?.name
+        };
+      });
+    }
+  }
+];
+
+function printHelp() {
+  console.log(`Usage: node scripts/test-stealth.js [options] [target...]
+
+Options:
+  --headful           launch with browser GUI visible
+  --no-spoof          baseline run — skip applyAllFingerprintSpoofing
+  --ua=<family>       UA family to spoof (default: chrome)
+                      valid: ${Array.from(USER_AGENT_COLLECTIONS.keys()).join(', ')}
+  --format=<fmt>      output format: text (default) | json
+  --help, -h          show this message
+
+Environment:
+  PUPPETEER_NO_SANDBOX=1   pass --no-sandbox to Chromium (required in some CI)
+
+Targets: ${TARGETS.map(t => t.name).join(', ')} (default: all)`);
+}
+
+function formatResult(target, result) {
+  const lines = [`\n=== ${target.name} (${target.url}) ===`];
+  if (target.name === 'sannysoft') {
+    lines.push(`  passed: ${result.passed} | warn: ${result.warn} | failed: ${result.failed} | total: ${result.total}`);
+    if (result.failures.length) {
+      lines.push(`  failure rows: ${result.failures.slice(0, 10).join(', ')}${result.failures.length > 10 ? ` ... +${result.failures.length - 10} more` : ''}`);
+    }
+  } else if (target.name === 'creepjs') {
+    lines.push(`  trust score: ${result.trustScore ?? 'n/a'}%`);
+    lines.push(`  lies detected: ${result.lies ?? 'n/a'}`);
+    lines.push(`  bot flagged: ${result.botDetected ?? 'n/a'}`);
+    if (result.excerpt) lines.push(`  excerpt:\n    ${result.excerpt.split('\n').join('\n    ')}`);
+  } else if (target.name === 'browserleaks') {
+    for (const [k, v] of Object.entries(result)) {
+      lines.push(`  ${k.padEnd(24)} ${v}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+(async () => {
+  if (HELP) { printHelp(); process.exit(0); }
+
+  // Validate --ua= against the canonical UA list. Previously a typo like
+  // --ua=opera silently fell through to applyUserAgentSpoofing's "unknown UA,
+  // no-op" path, producing run results that looked spoofed but weren't.
+  if (!USER_AGENT_COLLECTIONS.has(UA_FLAG)) {
+    console.error(`Invalid --ua=${UA_FLAG}. Valid: ${Array.from(USER_AGENT_COLLECTIONS.keys()).join(', ')}`);
+    process.exit(2);
+  }
+
+  if (!['text', 'json'].includes(FORMAT)) {
+    console.error(`Invalid --format=${FORMAT}. Valid: text, json`);
+    process.exit(2);
+  }
+
+  // Reject unrecognised flags before we launch a browser. Typos like
+  // "-headful" or "--no_spoof" used to silently no-op and produce a
+  // misleading "spoof on" run that wasn't actually spoofed.
+  const badFlags = flagArgs.filter(f =>
+    !KNOWN_FLAGS.has(f) && !KNOWN_FLAG_PREFIXES.some(p => f.startsWith(p))
+  );
+  if (badFlags.length) {
+    console.error(`Unrecognised flag(s): ${badFlags.join(', ')}. See --help.`);
+    process.exit(2);
+  }
+
+  const targetsToRun = filterTargets.length
+    ? TARGETS.filter(t => filterTargets.includes(t.name))
+    : TARGETS;
+
+  if (targetsToRun.length === 0) {
+    console.error(`No targets matched. Available: ${TARGETS.map(t => t.name).join(', ')}`);
+    process.exit(2);
+  }
+
+  if (FORMAT === 'text') {
+    console.log(`Stealth test config: spoof=${!NO_SPOOF}, ua=${UA_FLAG}, headful=${HEADFUL}`);
+    console.log(`Targets: ${targetsToRun.map(t => t.name).join(', ')}`);
+  }
+
+  // Sandbox is on by default; opt out via env var rather than baking
+  // --no-sandbox into the launch line. CI-as-root needs it; local dev should
+  // not silently drop the sandbox just because the test happens to start it.
+  const launchArgs = ['--disable-blink-features=AutomationControlled'];
+  if (process.env.PUPPETEER_NO_SANDBOX === '1') {
+    launchArgs.push('--no-sandbox', '--disable-setuid-sandbox');
+  }
+
+  const browser = await puppeteer.launch({
+    headless: !HEADFUL,
+    args: launchArgs
+  });
+
+  // Collected for JSON output (and to support a future --fail-on-detection
+  // exit code without restructuring the loop).
+  const collected = [];
+
+  try {
+    for (const target of targetsToRun) {
+      const page = await browser.newPage();
+      const started = Date.now();
+      try {
+        if (!NO_SPOOF) {
+          // Apply the same spoofing stack nwss.js uses for real scans.
+          await applyAllFingerprintSpoofing(page,
+            { userAgent: UA_FLAG, fingerprint_protection: 'random' },
+            false,
+            target.url
+          );
+        }
+        await page.goto(target.url, { waitUntil: 'networkidle2', timeout: 60000 });
+        const result = await target.extract(page);
+        collected.push({ name: target.name, url: target.url, ok: true, durationMs: Date.now() - started, result });
+        if (FORMAT === 'text') console.log(formatResult(target, result));
+      } catch (err) {
+        collected.push({ name: target.name, url: target.url, ok: false, durationMs: Date.now() - started, error: err.message });
+        if (FORMAT === 'text') {
+          console.error(`\n=== ${target.name} (${target.url}) ===`);
+          console.error(`  ERROR: ${err.message}`);
+        }
+      } finally {
+        await page.close().catch(() => {});
+      }
+    }
+  } finally {
+    await browser.close().catch(() => {});
+  }
+
+  if (FORMAT === 'json') {
+    // Single object, not NDJSON — easier to diff with `jq` or `diff` between
+    // before/after runs. Schema is stable: top-level config + targets[].
+    process.stdout.write(JSON.stringify({
+      config: { spoof: !NO_SPOOF, ua: UA_FLAG, headful: HEADFUL, noSandbox: process.env.PUPPETEER_NO_SANDBOX === '1' },
+      targets: collected
+    }, null, 2) + '\n');
+  }
+})().catch(err => {
+  console.error('test-stealth fatal:', err);
+  process.exit(1);
+});