@fanboynz/network-scanner 2.0.49 → 2.0.51

package/README.md

@@ -17,6 +17,7 @@ A Puppeteer-based tool for scanning websites to find third-party (or optionally
 - Subdomain handling (collapse to root or full subdomain)
 - Optionally match only first-party, third-party, or both
 - Enhanced redirect handling with JavaScript and meta refresh detection
+- Per-site proxy routing (SOCKS5, SOCKS4, HTTP, HTTPS) with pre-flight health checks
 
 ---
 
@@ -315,6 +316,86 @@ Route traffic through a VPN for specific sites. Requires `sudo` privileges. The
 
 > **Authentication:** If the `.ovpn` file already contains credentials (via `auth-user-pass /path/to/file` or an inline `<auth-user-pass>` block), no additional config is needed — just provide the config path. The `username`/`password` fields are only needed when the `.ovpn` file has a bare `auth-user-pass` directive that expects interactive input.
 
+### Proxy Options
+
+Route traffic through a proxy for specific sites. Supports SOCKS5, SOCKS4, HTTP, and HTTPS proxies. Unlike VPN, proxy routing is per-site-group — only URLs in the same config block use the proxy; other sites connect directly.
+
+> **Note:** Chromium's `--proxy-server` flag is browser-wide. Sites requiring different proxies (or direct vs proxied) are automatically separated into different browser instances. Tasks are sorted so proxy groups are contiguous to minimise restarts.
+
+| Field                | Values | Default | Description |
+|:---------------------|:-------|:-------:|:------------|
+| `proxy`              | String | - | Proxy URL: `socks5://host:port`, `http://host:port`, `https://host:port`, or `http://user:pass@host:port` |
+| `proxy_bypass`       | Array  | `[]` | Domains that skip the proxy (e.g. `["localhost", "127.0.0.1", "*.local"]`) |
+| `proxy_remote_dns`   | Boolean | `true` | Resolve DNS through the proxy (SOCKS only — prevents DNS leaks) |
+| `proxy_debug`        | Boolean | `false` | Print proxy diagnostics: launch args, auth, health checks, error codes |
+
+Legacy aliases (`socks5_proxy`, `socks5_bypass`, `socks5_remote_dns`, `socks5_debug`) are supported for backwards compatibility.
+
+#### Proxy Examples
+
+**SOCKS5 — no auth:**
+```json
+{
+  "url": ["https://blocked-site.com/", "https://another-blocked.com/"],
+  "proxy": "socks5://127.0.0.1:1080",
+  "search_string": ["tracking.js"]
+}
+```
+
+**HTTP proxy with credentials:**
+```json
+{
+  "url": ["https://geo-restricted.com/"],
+  "proxy": "http://user:pass@proxy.corp.com:3128",
+  "search_string": ["analytics"]
+}
+```
+
+**SOCKS5 with bypass list and debug:**
+```json
+{
+  "url": ["https://target-site.com/"],
+  "proxy": "socks5://user:pass@proxy.example.com:9050",
+  "proxy_bypass": ["localhost", "127.0.0.1", "*.internal.corp"],
+  "proxy_remote_dns": true,
+  "proxy_debug": true,
+  "search_string": ["tracker"]
+}
+```
+
+**Mixed direct + proxied in one config:**
+```json
+[
+  {
+    "url": ["https://direct-site.com/"],
+    "search_string": ["ads"]
+  },
+  {
+    "url": ["https://blocked-site.com/"],
+    "proxy": "socks5://127.0.0.1:1080",
+    "search_string": ["ads"]
+  }
+]
+```
+
+#### Proxy Error Handling
+
+If a proxy is unreachable, the batch is skipped with a clear error before any navigation is attempted:
+
+```
+[error] [proxy] Unreachable: socks5://127.0.0.1:1080 — Connection refused
+[error] [proxy] Skipping 5 URL(s) in this batch
+```
+
+If a proxy fails mid-scan, Chromium's error code is detected and diagnosed:
+
+```
+[error] [proxy] ERR_SOCKS_CONNECTION_FAILED — proxy: socks5://127.0.0.1:1080 — URL: https://example.com/
+[error] [proxy] Check: is the proxy running? Are credentials correct? Is the target reachable from the proxy?
+```
+
+Detected error codes: `ERR_PROXY_CONNECTION_FAILED`, `ERR_SOCKS_CONNECTION_FAILED`, `ERR_TUNNEL_CONNECTION_FAILED`, `ERR_PROXY_AUTH_UNSUPPORTED`, `ERR_PROXY_AUTH_REQUESTED`, `ERR_SOCKS_CONNECTION_HOST_UNREACHABLE`, `ERR_PROXY_CERTIFICATE_INVALID`, `ERR_NO_SUPPORTED_PROXIES`.
+
 ### Global Configuration Options
 
 These options go at the root level of your config.json:

package/lib/cloudflare.js

@@ -58,11 +58,76 @@ const FAST_TIMEOUTS = {
   ELEMENT_INTERACTION_DELAY: 250, // Fast element interactions
   SELECTOR_WAIT: 3000,            // Fast selector waits
   TURNSTILE_OPERATION: 6000,      // Fast Turnstile operations
-  JS_CHALLENGE: 19000,            // Fast JS challenge completion
+  JS_CHALLENGE: 10000,            // Fast JS challenge completion
   CHALLENGE_SOLVING: 30000,       // Fast overall challenge solving
   CHALLENGE_COMPLETION: 8000      // Fast completion check
 };
 
+/**
+ * Finds and clicks an element inside shadow DOM trees via page.evaluate
+ * Returns {found, clicked, x, y} - coordinates allow fallback mouse.click
+ */
+async function clickInShadowDOM(context, selectors, forceDebug = false, waitMs = 1500) {
+  // Try Puppeteer's pierce/ selector first � handles CLOSED shadow roots via CDP
+  for (const selector of selectors) {
+    try {
+      // Wait for element to appear (handles delayed rendering)
+      const start = Date.now();
+      const element = await context.waitForSelector(`pierce/${selector}`, { timeout: waitMs });
+      if (element) {
+        const box = await element.boundingBox();
+        if (box && box.width > 0 && box.height > 0) {
+          if (forceDebug) console.log(formatLogMessage('cloudflare', `pierce/${selector} matched in ${Date.now() - start}ms � box: ${box.width}x${box.height} at (${box.x},${box.y})`));
+          await element.click();
+          await element.dispose();
+          return { found: true, clicked: true, selector, x: box.x + box.width / 2, y: box.y + box.height / 2 };
+        }
+        if (forceDebug) console.log(formatLogMessage('cloudflare', `pierce/${selector} found but not visible (0x0)`));
+        await element.dispose();
+        // Element found but not visible
+        return { found: true, clicked: false, selector, x: 0, y: 0 };
+      }
+    } catch (e) {
+      if (forceDebug) console.log(formatLogMessage('cloudflare', `pierce/${selector} timeout after ${waitMs}ms`));
+      continue;
+    }
+  }
+
+  // Fallback: manual traversal for open shadow roots
+  const result = await context.evaluate((sels) => {
+    function deepQuery(root, selector) {
+      // Try direct query first
+      const el = root.querySelector(selector);
+      if (el) return el;
+
+      // Traverse shadow roots
+      const allElements = root.querySelectorAll('*');
+      for (const node of allElements) {
+        if (node.shadowRoot) {
+          const found = deepQuery(node.shadowRoot, selector);
+          if (found) return found;
+        }
+      }
+      return null;
+    }
+
+    for (const selector of sels) {
+      const el = deepQuery(document, selector);
+      if (el) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+          el.click();
+          return { found: true, clicked: true, selector, x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+        }
+        return { found: true, clicked: false, selector, x: 0, y: 0 };
+      }
+    }
+    return { found: false, clicked: false, selector: null, x: 0, y: 0 };
+  }, selectors);
+
+  return result;
+}
+
 /**
  * Error categories for better handling
  */
@@ -306,12 +371,12 @@ function categorizeError(error) {
 /**
  * Implements exponential backoff delay
  */
-async function getRetryDelay(attempt) {
+function getRetryDelay(attempt) {
   const delay = Math.min(
     RETRY_CONFIG.baseDelay * Math.pow(RETRY_CONFIG.backoffMultiplier, attempt - 1),
     RETRY_CONFIG.maxDelay
   );
-  return new Promise(resolve => setTimeout(resolve, delay));
+  return delay;
 }
 
 /**
@@ -341,49 +406,8 @@ async function safePageEvaluate(page, func, timeout = TIMEOUTS.PAGE_EVALUATION_S
         throw new Error('Page URL access failed - likely detached');
       }
 
-      // Quick execution context validation with timeout
-      const contextValid = await Promise.race([
-        page.evaluate(() => {
-          try {
-            // Quick context validation
-            if (typeof window === 'undefined' || !document) {
-              return false;
-            }
-            // Check if document is ready for interaction
-            if (document.readyState === 'uninitialized') {
-              return false;
-            }
-            return true;
-          } catch (e) {
-            return false;
-          }
-        }),
-        new Promise((_, reject) => {
-          setTimeout(() => reject(new Error('Context validation timeout')), 3500);
-        })
-      ]).catch(() => false);
-
-      if (!contextValid) {
-        throw new Error('Page execution context is invalid');
-      }
-
       const result = await Promise.race([
-        page.evaluate(() => {
-          // Additional runtime validation inside evaluation
-          try {
-            if (typeof window === 'undefined' || !document) {
-              throw new Error('Execution context invalid during evaluation');
-            }
-            return func();
-          } catch (evalError) {
-            // Return error info instead of throwing to avoid unhandled promise rejections
-            return {
-              __evaluation_error: true,
-              message: evalError.message,
-              type: 'evaluation_error'
-            };
-          }
-        }),
+        page.evaluate(func),
         new Promise((_, reject) => {
           timeoutId = setTimeout(() => reject(new Error('Page evaluation timeout')), timeout);
         })
@@ -394,11 +418,6 @@ async function safePageEvaluate(page, func, timeout = TIMEOUTS.PAGE_EVALUATION_S
         clearTimeout(timeoutId);
       }
 
-      // Check if evaluation returned an error
-      if (result && result.__evaluation_error) {
-        throw new Error(`Evaluation failed: ${result.message}`);
-      }
-
       if (forceDebug && attempt > 1) {
         console.log(formatLogMessage('cloudflare', `Page evaluation succeeded on attempt ${attempt}`));
       }
@@ -438,7 +457,7 @@ async function safePageEvaluate(page, func, timeout = TIMEOUTS.PAGE_EVALUATION_S
       }
       
       // Wait before retrying with exponential backoff
-      await getRetryDelay(attempt);
+      await new Promise(resolve => setTimeout(resolve, getRetryDelay(attempt)));
     }
   }
   
@@ -460,15 +479,18 @@ async function safePageEvaluate(page, func, timeout = TIMEOUTS.PAGE_EVALUATION_S
  * Safe element clicking with timeout protection
  */
 async function safeClick(page, selector, timeout = TIMEOUTS.CLICK_TIMEOUT) {
+  let timeoutId;
   try {
     return await Promise.race([
       page.click(selector, { timeout: timeout }),
       new Promise((_, reject) => {
-        setTimeout(() => reject(new Error('Click timeout')), timeout + TIMEOUTS.CLICK_TIMEOUT_BUFFER);
+        timeoutId = setTimeout(() => reject(new Error('Click timeout')), timeout + TIMEOUTS.CLICK_TIMEOUT_BUFFER);
       })
     ]);
   } catch (error) {
     throw new Error(`Click failed: ${error.message}`);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
   }
 }
 
@@ -476,16 +498,18 @@ async function safeClick(page, selector, timeout = TIMEOUTS.CLICK_TIMEOUT) {
  * Safe navigation waiting with timeout protection
  */
 async function safeWaitForNavigation(page, timeout = TIMEOUTS.NAVIGATION_TIMEOUT) {
+  let timeoutId;
   try {
     return await Promise.race([
       page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: timeout }),
       new Promise((_, reject) => {
-        setTimeout(() => reject(new Error('Navigation timeout')), timeout + TIMEOUTS.NAVIGATION_TIMEOUT_BUFFER);
+        timeoutId = setTimeout(() => reject(new Error('Navigation timeout')), timeout + TIMEOUTS.NAVIGATION_TIMEOUT_BUFFER);
       })
     ]);
   } catch (error) {
     console.warn(formatLogMessage('cloudflare', `Navigation wait failed: ${error.message}`));
-    // Don't throw - just continue
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
   }
 }
 
@@ -583,7 +607,14 @@ async function quickCloudflareDetection(page, forceDebug = false) {
  */
 async function analyzeCloudflareChallenge(page) {
   try {
-    return await safePageEvaluate(page, () => {
+    // CDP-level frame check � bypasses closed shadow roots
+    const frames = page.frames();
+    const hasChallengeFrame = frames.some(f => {
+      const url = f.url();
+      return url.includes('challenges.cloudflare.com') || url.includes('/cdn-cgi/challenge-platform/');
+    });
+
+    const result = await safePageEvaluate(page, () => {
       const title = document.title || '';
       const bodyText = document.body ? document.body.textContent : '';
       
@@ -655,6 +686,15 @@ async function analyzeCloudflareChallenge(page) {
         bodySnippet: bodyText.substring(0, 200)
       };
     }, TIMEOUTS.PAGE_EVALUATION);
+
+    // Merge CDP frame detection � catches iframes behind closed shadow roots
+    if (hasChallengeFrame && !result.hasTurnstileIframe) {
+      result.hasTurnstileIframe = true;
+      result.isTurnstile = true;
+      result.isChallengePresent = true;
+    }
+
+    return result;
   } catch (error) {
     return {
       isChallengePresent: false,
@@ -862,7 +902,7 @@ async function handleVerificationChallengeWithRetries(page, currentUrl, siteConf
       
       // If this wasn't the last attempt, wait before retrying
       if (attempt < retryConfig.maxAttempts) {
-        const delay = await getRetryDelay(attempt);
+        const delay = getRetryDelay(attempt);
         if (forceDebug) {
           console.log(formatLogMessage('cloudflare', `Challenge attempt ${attempt} failed, retrying in ${delay}ms: ${result.error}`));
         }
@@ -904,7 +944,7 @@ async function handleVerificationChallengeWithRetries(page, currentUrl, siteConf
       
       // Wait before retrying with exponential backoff
       if (attempt < retryConfig.maxAttempts) {
-        await getRetryDelay(attempt);
+        await new Promise(resolve => setTimeout(resolve, getRetryDelay(attempt)));
       }
     }
   }
@@ -945,7 +985,7 @@ async function handlePhishingWarningWithRetries(page, currentUrl, siteConfig, fo
       
       // If this wasn't the last attempt, wait before retrying
       if (attempt < retryConfig.maxAttempts) {
-        const delay = await getRetryDelay(attempt);
+        const delay = getRetryDelay(attempt);
         if (forceDebug) {
           console.log(formatLogMessage('cloudflare', `Phishing warning attempt ${attempt} failed, retrying in ${delay}ms: ${result.error}`));
         }
@@ -975,7 +1015,7 @@ async function handlePhishingWarningWithRetries(page, currentUrl, siteConfig, fo
       
       // Wait before retrying with exponential backoff
       if (attempt < retryConfig.maxAttempts) {
-        await getRetryDelay(attempt);
+        await new Promise(resolve => setTimeout(resolve, getRetryDelay(attempt)));
       }
     }
   }
@@ -1046,6 +1086,23 @@ async function attemptChallengeSolve(page, currentUrl, challengeInfo, forceDebug
       
       const jsResult = await waitForJSChallengeCompletion(page, forceDebug);
       if (jsResult.success) {
+        // Wait for redirect after challenge completion
+        try {
+          const startUrl = await page.url();
+          await page.waitForFunction(
+            (origUrl) => {
+              const bodyText = document.body?.textContent || '';
+              return document.title !== 'Just a moment...' ||
+                     window.location.href !== origUrl ||
+                     bodyText.includes('Verification successful');
+            },
+            { timeout: 10000 },
+            startUrl
+          );
+          if (forceDebug) console.log(formatLogMessage('cloudflare', `Challenge page cleared for ${currentUrl}`));
+        } catch (_) {
+          if (forceDebug) console.log(formatLogMessage('cloudflare', `Challenge page not cleared after 10s � continuing`));
+        }
         result.success = true;
         result.method = 'js_challenge_wait';
         if (forceDebug) console.log(formatLogMessage('cloudflare', `JS challenge completed successfully for ${currentUrl}`));
@@ -1054,6 +1111,8 @@ async function attemptChallengeSolve(page, currentUrl, challengeInfo, forceDebug
     } catch (jsError) {
       if (forceDebug) console.log(formatLogMessage('cloudflare', `JS challenge wait failed for ${currentUrl}: ${jsError.message}`));
     }
+  } else if (forceDebug) {
+    console.log(formatLogMessage('cloudflare', `Skipping JS challenge method (not detected)`));
   }
 
   // Method 2: Handle Turnstile challenges (interactive)
@@ -1071,6 +1130,8 @@ async function attemptChallengeSolve(page, currentUrl, challengeInfo, forceDebug
     } catch (turnstileError) {
       if (forceDebug) console.log(formatLogMessage('cloudflare', `Turnstile method failed for ${currentUrl}: ${turnstileError.message}`));
     }
+  } else if (forceDebug) {
+    console.log(formatLogMessage('cloudflare', `Skipping Turnstile method (not detected)`));
   }
 
   // Method 3: Legacy checkbox interaction (fallback)
@@ -1088,10 +1149,23 @@ async function attemptChallengeSolve(page, currentUrl, challengeInfo, forceDebug
     } catch (legacyError) {
       if (forceDebug) console.log(formatLogMessage('cloudflare', `Legacy checkbox method failed for ${currentUrl}: ${legacyError.message}`));
     }
+  } else if (forceDebug) {
+    console.log(formatLogMessage('cloudflare', `Skipping legacy checkbox method (not detected)`));
   }
 
   if (!result.success) {
     result.error = result.error || 'All challenge bypass methods failed';
+    if (forceDebug) {
+      try {
+        const postState = await page.evaluate(() => ({
+          title: document.title,
+          url: window.location.href,
+          body: (document.body?.textContent || '').substring(0, 300)
+        }));
+        console.log(formatLogMessage('cloudflare', `Post-attempt page state: title="${postState.title}" url=${postState.url}`));
+        console.log(formatLogMessage('cloudflare', `Post-attempt body: ${postState.body}`));
+      } catch (_) {}
+    }
   }
 
   return result;
@@ -1109,88 +1183,57 @@ async function handleEmbeddedIframeChallenge(page, forceDebug = false) {
   try {
     if (forceDebug) console.log(formatLogMessage('cloudflare', `Checking for embedded iframe challenges`));
 
-    // Enhanced iframe selectors including challenges.cloudflare.com
-    const iframeSelectors = [
-      'iframe[src*="challenges.cloudflare.com"]',
-      'iframe[title*="Verify you are human"]',
-      'iframe[title*="Cloudflare security challenge"]',
-      'iframe[title*="Widget containing a Cloudflare"]'
-    ];
-
-    // Wait for iframe to appear
-    let iframeFound = false;
-    for (const selector of iframeSelectors) {
-      try {
-        await Promise.race([
-          page.waitForSelector(selector, { timeout: FAST_TIMEOUTS.SELECTOR_WAIT }),
-          new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), FAST_TIMEOUTS.SELECTOR_WAIT + 1000))
-        ]);
-        iframeFound = true;
-        if (forceDebug) console.log(formatLogMessage('cloudflare', `Found iframe: ${selector}`));
-        break;
-      } catch (e) {
-        continue;
+    // Use CDP-level frame detection � bypasses closed shadow roots
+    const frames = page.frames();
+    if (forceDebug) {
+      console.log(formatLogMessage('cloudflare', `Available frames (${frames.length}):`));
+      for (const f of frames) {
+        console.log(formatLogMessage('cloudflare', `  ${f.url()}`));
       }
     }
-
-    if (!iframeFound) {
-      result.error = 'No embedded iframe found';
-      return result;
-    }
-
-    // Find challenge frame using existing frame detection logic
-    const frames = await page.frames();
     const challengeFrame = frames.find(frame => {
       const frameUrl = frame.url();
       return frameUrl.includes('challenges.cloudflare.com') ||
+             frameUrl.includes('/cdn-cgi/challenge-platform/') ||
              frameUrl.includes('/turnstile/if/') ||
-             frameUrl.includes('captcha-delivery.com') ||
-             frameUrl.includes('/challenge-platform/') ||
              frameUrl.includes('turnstile');
     });
 
     if (!challengeFrame) {
-      result.error = 'Challenge iframe not accessible';
+      result.error = 'No challenge frame found via CDP';
       return result;
     }
 
     if (forceDebug) console.log(formatLogMessage('cloudflare', `Interacting with iframe: ${challengeFrame.url()}`));
 
-    // Reuse existing checkbox interaction logic
-    const checkboxSelectors = [
+    await waitForTimeout(page, 500);
+
+    let checkboxInteractionSuccess = false;
+    try {
+      const shadowResult = await clickInShadowDOM(challengeFrame, [
       'input[type="checkbox"]',
       '.ctp-checkbox',
-      'input.ctp-checkbox',
-      '.cf-turnstile input',
-      '.ctp-checkbox-label'
-    ];
-    
-    let checkboxInteractionSuccess = false;
-    for (const selector of checkboxSelectors) {
-      try {
-        await Promise.race([
-          challengeFrame.waitForSelector(selector, { timeout: FAST_TIMEOUTS.SELECTOR_WAIT }),
-          new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), FAST_TIMEOUTS.SELECTOR_WAIT + 1000))
-        ]);
-        
-        await waitForTimeout(page, FAST_TIMEOUTS.ELEMENT_INTERACTION_DELAY);
-        await challengeFrame.click(selector);
-        
-        if (forceDebug) console.log(formatLogMessage('cloudflare', `Clicked iframe element: ${selector}`));
+        '.ctp-checkbox-label',
+        '[role="checkbox"]',
+        'label.cb-lb',
+        'label'
+      ], forceDebug);
+
+      if (shadowResult.clicked) {
         checkboxInteractionSuccess = true;
-        break;
-      } catch (e) {
-        continue;
+        if (forceDebug) console.log(formatLogMessage('cloudflare', `Shadow DOM click succeeded: ${shadowResult.selector}`));
+      } else if (shadowResult.found && shadowResult.x > 0) {
+        await page.mouse.click(shadowResult.x, shadowResult.y);
+        checkboxInteractionSuccess = true;
+        if (forceDebug) console.log(formatLogMessage('cloudflare', `Shadow DOM mouse fallback at (${shadowResult.x}, ${shadowResult.y})`));
       }
+    } catch (shadowErr) {
+      if (forceDebug) console.log(formatLogMessage('cloudflare', `Shadow DOM click failed: ${shadowErr.message}`));
     }
 
-    // Try alternative interaction only if standard selectors failed
     if (!checkboxInteractionSuccess) {
-      if (forceDebug) console.log(formatLogMessage('cloudflare', `Checkbox interactions failed, trying container fallback`));
-      await waitForTimeout(page, 1000);
 
       try {
-        // Try clicking on the iframe container itself as fallback
         const iframeElement = await page.$('iframe[src*="challenges.cloudflare.com"]');
         if (iframeElement) {
           await iframeElement.click();
@@ -1199,8 +1242,6 @@ async function handleEmbeddedIframeChallenge(page, forceDebug = false) {
       } catch (containerClickError) {
         if (forceDebug) console.log(formatLogMessage('cloudflare', `Container click failed: ${containerClickError.message}`));
       }
-    } else {
-      if (forceDebug) console.log(formatLogMessage('cloudflare', `Checkbox interaction successful, skipping container fallback`));
     }
 
     // Reuse existing completion check pattern with error handling
@@ -1257,8 +1298,10 @@ async function waitForJSChallengeCompletion(page, forceDebug = false) {
     await Promise.race([
       page.waitForFunction(
         () => {
-          return !document.body.textContent.includes('Checking your browser') &&
-                 !document.body.textContent.includes('Please wait while we verify') &&
+          const bodyText = document.body.textContent;
+          if (bodyText.includes('Verification successful')) return true;
+          return !bodyText.includes('Checking your browser') &&
+                 !bodyText.includes('Please wait while we verify') &&
                  !document.querySelector('.cf-challenge-running') &&
                  !document.querySelector('[data-cf-challenge]');
         },
@@ -1342,28 +1385,26 @@ async function handleTurnstileChallenge(page, forceDebug = false) {
         console.log(formatLogMessage('cloudflare', `Found Turnstile iframe with URL: ${turnstileFrame.url()}`));
       }
       
-      const checkboxSelectors = [
-        'input[type="checkbox"].ctp-checkbox',
-        '.ctp-checkbox-label',
-        '.ctp-checkbox'
-      ];
-      
-      for (const selector of checkboxSelectors) {
-        try {
-          await Promise.race([
-            turnstileFrame.waitForSelector(selector, { timeout: FAST_TIMEOUTS.SELECTOR_WAIT }),
-            new Promise((_, reject) => setTimeout(() => reject(new Error('Checkbox timeout')), FAST_TIMEOUTS.SELECTOR_WAIT + 500))
-          ]);
-          
-          await waitForTimeout(page, FAST_TIMEOUTS.ELEMENT_INTERACTION_DELAY);
-          await turnstileFrame.click(selector);
-          
-          if (forceDebug) console.log(formatLogMessage('cloudflare', `Clicked Turnstile checkbox: ${selector}`));
-          break;
-        } catch (e) {
-          if (forceDebug) console.log(formatLogMessage('cloudflare', `Checkbox selector ${selector} not found or failed to click`));
-          continue;
+      await waitForTimeout(page, FAST_TIMEOUTS.ELEMENT_INTERACTION_DELAY);
+
+      try {
+        const shadowResult = await clickInShadowDOM(turnstileFrame, [
+          'input[type="checkbox"]',
+          '.ctp-checkbox',
+          '.ctp-checkbox-label',
+          '[role="checkbox"]',
+          'label.cb-lb',
+          'label'
+        ], forceDebug);
+
+        if (shadowResult.clicked) {
+          if (forceDebug) console.log(formatLogMessage('cloudflare', `Turnstile shadow DOM click succeeded: ${shadowResult.selector}`));
+        } else if (shadowResult.found && shadowResult.x > 0) {
+          await page.mouse.click(shadowResult.x, shadowResult.y);
+          if (forceDebug) console.log(formatLogMessage('cloudflare', `Turnstile shadow DOM mouse fallback at (${shadowResult.x}, ${shadowResult.y})`));
         }
+      } catch (shadowErr) {
+        if (forceDebug) console.log(formatLogMessage('cloudflare', `Shadow DOM fallback failed: ${shadowErr.message}`));
       }
       
       // Wait for Turnstile completion with reduced timeout
@@ -1551,7 +1592,11 @@ async function checkChallengeCompletion(page) {
  * }
  */
 async function handleCloudflareProtection(page, currentUrl, siteConfig, forceDebug = false) {
-  if (forceDebug) {
+  const cfDebug = forceDebug || siteConfig.cloudflare_bypass === 'debug' || siteConfig.cloudflare_phish === 'debug';
+  const cfBypassEnabled = siteConfig.cloudflare_bypass === true || siteConfig.cloudflare_bypass === 'debug';
+  const cfPhishEnabled = siteConfig.cloudflare_phish === true || siteConfig.cloudflare_phish === 'debug';
+
+  if (cfDebug) {
     console.log(formatLogMessage('cloudflare', `Using Cloudflare module v${CLOUDFLARE_MODULE_VERSION} for ${currentUrl}`));
   }
   
@@ -1581,7 +1626,7 @@ async function handleCloudflareProtection(page, currentUrl, siteConfig, forceDeb
   // Sets attempted: false, success: true for both protection types
  
   // Only proceed if we have indicators OR explicit config enables Cloudflare handling
-  if (!quickDetection.hasIndicators && !siteConfig.cloudflare_phish && !siteConfig.cloudflare_bypass) {
+  if (!quickDetection.hasIndicators && !cfPhishEnabled && !cfBypassEnabled) {
     if (forceDebug) console.log(formatLogMessage('cloudflare', `No Cloudflare indicators found and no explicit config, skipping protection handling for ${currentUrl}`));
     if (forceDebug) console.log(formatLogMessage('cloudflare', `Quick detection details: title="${quickDetection.title}", bodySnippet="${quickDetection.bodySnippet}"`));
     return {
@@ -1606,7 +1651,7 @@ async function handleCloudflareProtection(page, currentUrl, siteConfig, forceDeb
   try {
     // Adaptive timeout based on detection results and explicit config
     let adaptiveTimeout;
-    if (siteConfig.cloudflare_phish || siteConfig.cloudflare_bypass) {
+    if (cfPhishEnabled || cfBypassEnabled) {
       // Explicit config - give more time
       adaptiveTimeout = quickDetection.hasIndicators ? TIMEOUTS.ADAPTIVE_TIMEOUT_WITH_INDICATORS : TIMEOUTS.ADAPTIVE_TIMEOUT_WITHOUT_INDICATORS;
     } else {
@@ -1619,7 +1664,7 @@ async function handleCloudflareProtection(page, currentUrl, siteConfig, forceDeb
     }
     
     return await Promise.race([
-      performCloudflareHandling(page, currentUrl, siteConfig, forceDebug),
+      performCloudflareHandling(page, currentUrl, siteConfig, cfDebug),
       new Promise((resolve) => {
         setTimeout(() => {
         console.warn(formatLogMessage('cloudflare', `Adaptive timeout (${adaptiveTimeout}ms) for ${currentUrl} - continuing with scan`));
@@ -1651,6 +1696,9 @@ async function handleCloudflareProtection(page, currentUrl, siteConfig, forceDeb
  * @returns {Promise<Object>} Same structure as handleCloudflareProtection()
  */
 async function performCloudflareHandling(page, currentUrl, siteConfig, forceDebug = false) {
+  const cfBypassEnabled = siteConfig.cloudflare_bypass === true || siteConfig.cloudflare_bypass === 'debug';
+  const cfPhishEnabled = siteConfig.cloudflare_phish === true || siteConfig.cloudflare_phish === 'debug';
+
   const result = {
     phishingWarning: { attempted: false, success: false },
     verificationChallenge: { attempted: false, success: false },
@@ -1663,7 +1711,7 @@ async function performCloudflareHandling(page, currentUrl, siteConfig, forceDebu
   // Handle phishing warnings first - updates result.phishingWarning
   // Only runs if siteConfig.cloudflare_phish === true
   // Handle phishing warnings if enabled
-  if (siteConfig.cloudflare_phish === true) {
+  if (cfPhishEnabled) {
     if (forceDebug) console.log(formatLogMessage('cloudflare', `Phishing warning bypass enabled for ${currentUrl}`));
     
     const phishingResult = await handlePhishingWarningWithRetries(page, currentUrl, siteConfig, forceDebug);
@@ -1698,7 +1746,7 @@ async function performCloudflareHandling(page, currentUrl, siteConfig, forceDebu
   // Only runs if siteConfig.cloudflare_bypass === true
   // Sets requiresHuman: true if CAPTCHA detected (no bypass attempted)
   // Handle verification challenges if enabled
-  if (siteConfig.cloudflare_bypass === true) {
+  if (cfBypassEnabled) {
     if (forceDebug) console.log(formatLogMessage('cloudflare', `Challenge bypass enabled for ${currentUrl}`));
     
     const challengeResult = await handleVerificationChallengeWithRetries(page, currentUrl, siteConfig, forceDebug);
@@ -1751,55 +1799,28 @@ async function performCloudflareHandling(page, currentUrl, siteConfig, forceDebu
  * Performs parallel detection of multiple challenge types for better performance
  */
 async function parallelChallengeDetection(page, forceDebug = false) {
-  const detectionPromises = [];
-  
-  // Check for JS challenge
-  detectionPromises.push(
-    page.evaluate(() => {
-      return {
-        type: 'js',
-        detected: document.querySelector('script[src*="/cdn-cgi/challenge-platform/"]') !== null ||
-                  document.body?.textContent?.includes('Checking your browser') ||
-                  document.body?.textContent?.includes('Please wait while we verify')
-      };
-    }).catch(err => ({ type: 'js', detected: false, error: err.message }))
-  );
-  
-  // Check for Turnstile
-  detectionPromises.push(
-    page.evaluate(() => {
-      return {
-        type: 'turnstile',
-        detected: document.querySelector('.cf-turnstile') !== null ||
-                  document.querySelector('iframe[src*="challenges.cloudflare.com"]') !== null ||
-                  document.querySelector('.ctp-checkbox-container') !== null
-      };
-    }).catch(err => ({ type: 'turnstile', detected: false, error: err.message }))
-  );
-  
-  // Check for phishing warning
-  detectionPromises.push(
-    page.evaluate(() => {
-      return {
-        type: 'phishing',
-        detected: document.body?.textContent?.includes('This website has been reported for potential phishing') ||
-                  document.querySelector('a[href*="continue"]') !== null
-      };
-    }).catch(err => ({ type: 'phishing', detected: false, error: err.message }))
-  );
-  
-  // Check for managed challenge
-  detectionPromises.push(
-    page.evaluate(() => {
-      return {
-        type: 'managed',
-        detected: document.querySelector('.cf-managed-challenge') !== null ||
-                  document.querySelector('[data-cf-managed]') !== null
-      };
-    }).catch(err => ({ type: 'managed', detected: false, error: err.message }))
-  );
-  
-  const results = await Promise.all(detectionPromises);
+  let results;
+  try {
+    results = await page.evaluate(() => {
+      const bodyText = document.body?.textContent || '';
+      return [
+        { type: 'js', detected: document.querySelector('script[src*="/cdn-cgi/challenge-platform/"]') !== null ||
+            bodyText.includes('Checking your browser') || bodyText.includes('Please wait while we verify') },
+        { type: 'turnstile', detected: document.querySelector('.cf-turnstile') !== null ||
+            document.querySelector('iframe[src*="challenges.cloudflare.com"]') !== null ||
+            document.querySelector('.ctp-checkbox-container') !== null },
+        { type: 'phishing', detected: bodyText.includes('This website has been reported for potential phishing') ||
+            document.querySelector('a[href*="continue"]') !== null },
+        { type: 'managed', detected: document.querySelector('.cf-managed-challenge') !== null ||
+            document.querySelector('[data-cf-managed]') !== null }
+      ];
+    });
+  } catch (err) {
+    results = [
+      { type: 'js', detected: false }, { type: 'turnstile', detected: false },
+      { type: 'phishing', detected: false }, { type: 'managed', detected: false }
+    ];
+  }
   
   const detectedChallenges = results.filter(r => r.detected).map(r => r.type);
   

package/lib/proxy.js

@@ -0,0 +1,279 @@
+/**
+ * Proxy Module for NWSS Network Scanner
+ * ======================================
+ * Routes specific site URLs through SOCKS5, SOCKS4, HTTP, or HTTPS proxies.
+ *
+ * Chromium's --proxy-server flag is browser-wide, so sites requiring a proxy
+ * need a separate browser instance. This module handles:
+ *   - Parsing proxy URLs (all supported protocols)
+ *   - Generating Chromium launch args
+ *   - Per-page authentication via Puppeteer
+ *   - Proxy bypass lists
+ *   - Proxy health checks
+ *
+ * CONFIG EXAMPLES:
+ *
+ *   SOCKS5 (no auth):
+ *     "proxy": "socks5://127.0.0.1:1080"
+ *
+ *   SOCKS5 with auth:
+ *     "proxy": "socks5://user:pass@127.0.0.1:1080"
+ *
+ *   HTTP proxy (corporate):
+ *     "proxy": "http://proxy.corp.com:3128"
+ *
+ *   HTTP proxy with auth:
+ *     "proxy": "http://user:pass@proxy.corp.com:8080"
+ *
+ *   HTTPS proxy:
+ *     "proxy": "https://secure-proxy.example.com:8443"
+ *
+ *   With bypass list and remote DNS:
+ *     "proxy": "socks5://127.0.0.1:1080",
+ *     "proxy_bypass": ["localhost", "127.0.0.1", "*.local"],
+ *     "proxy_remote_dns": true
+ *
+ *   Debug mode:
+ *     "proxy": "socks5://127.0.0.1:1080",
+ *     "proxy_debug": true
+ *
+ *   Legacy key (backwards compatible):
+ *     "socks5_proxy": "socks5://127.0.0.1:1080"
+ *
+ * INTEGRATION (in nwss.js):
+ *   const { needsProxy, getProxyArgs, applyProxyAuth, getProxyInfo } = require('./lib/proxy');
+ *
+ *   // Before browser launch
+ *   if (needsProxy(siteConfig)) {
+ *     const proxyArgs = getProxyArgs(siteConfig, forceDebug);
+ *     browserArgs.push(...proxyArgs);
+ *   }
+ *
+ *   // After page creation, before page.goto()
+ *   await applyProxyAuth(page, siteConfig, forceDebug);
+ *
+ * @version 1.1.0
+ */
+
+const { formatLogMessage } = require('./colorize');
+
+const PROXY_MODULE_VERSION = '1.1.0';
+const SUPPORTED_PROTOCOLS = ['socks5', 'socks4', 'http', 'https'];
+
+const DEFAULT_PORTS = {
+  socks5: 1080,
+  socks4: 1080,
+  http: 8080,
+  https: 8443
+};
+
+/**
+ * Returns the configured proxy URL string from siteConfig.
+ * Supports both "proxy" (preferred) and "socks5_proxy" (legacy) keys.
+ *
+ * @param {object} siteConfig
+ * @returns {string|null}
+ */
+function getConfiguredProxy(siteConfig) {
+  return siteConfig.proxy || siteConfig.socks5_proxy || null;
+}
+
+/**
+ * Parses a proxy URL into components.
+ * Accepts: protocol://host:port, protocol://user:pass@host:port, bare host:port
+ *
+ * @param {string} proxyUrl - Proxy URL string
+ * @returns {object|null} Parsed proxy or null if invalid
+ */
+function parseProxyUrl(proxyUrl) {
+  if (!proxyUrl || typeof proxyUrl !== 'string') return null;
+
+  let cleaned = proxyUrl.trim();
+
+  // Normalise bare host:port to socks5:// URL
+  if (!cleaned.includes('://')) {
+    cleaned = `socks5://${cleaned}`;
+  }
+
+  try {
+    const url = new URL(cleaned);
+    const protocol = url.protocol.replace(':', '');
+
+    if (!SUPPORTED_PROTOCOLS.includes(protocol)) return null;
+
+    const host = url.hostname;
+    if (!host) return null;
+
+    const port = parseInt(url.port, 10) || DEFAULT_PORTS[protocol] || 1080;
+    const username = url.username ? decodeURIComponent(url.username) : null;
+    const password = url.password ? decodeURIComponent(url.password) : null;
+
+    return { protocol, host, port, username, password };
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Checks if a site config requires a proxy
+ *
+ * @param {object} siteConfig
+ * @returns {boolean}
+ */
+function needsProxy(siteConfig) {
+  return !!getConfiguredProxy(siteConfig);
+}
+
+/**
+ * Returns Chromium launch arguments for the configured proxy.
+ *
+ * @param {object} siteConfig
+ * @param {boolean} forceDebug
+ * @returns {string[]} Array of Chromium args (empty if no proxy configured)
+ */
+function getProxyArgs(siteConfig, forceDebug = false) {
+  const proxyUrl = getConfiguredProxy(siteConfig);
+  if (!proxyUrl) return [];
+
+  const parsed = parseProxyUrl(proxyUrl);
+  if (!parsed) {
+    console.warn(formatLogMessage('proxy', `Invalid proxy URL: ${proxyUrl}`));
+    return [];
+  }
+
+  const args = [
+    `--proxy-server=${parsed.protocol}://${parsed.host}:${parsed.port}`
+  ];
+
+  // Remote DNS: resolve hostnames through the proxy (prevents DNS leaks)
+  // Only meaningful for SOCKS proxies; HTTP proxies resolve remotely by default
+  const remoteDns = siteConfig.proxy_remote_dns ?? siteConfig.socks5_remote_dns;
+  if ((parsed.protocol === 'socks5' || parsed.protocol === 'socks4') && remoteDns !== false) {
+    args.push('--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE 127.0.0.1');
+  }
+
+  // Bypass list: domains that skip the proxy
+  const bypass = siteConfig.proxy_bypass || siteConfig.socks5_bypass || [];
+  if (bypass.length > 0) {
+    args.push(`--proxy-bypass-list=${bypass.join(';')}`);
+  }
+
+  const debug = forceDebug || siteConfig.proxy_debug || siteConfig.socks5_debug;
+  if (debug) {
+    console.log(formatLogMessage('proxy', `[${parsed.protocol}] Args: ${args.join(' ')}`));
+  }
+
+  return args;
+}
+
+/**
+ * Applies proxy authentication to a page via Puppeteer's authenticate API.
+ * Must be called BEFORE page.goto().
+ *
+ * @param {object} page - Puppeteer page instance
+ * @param {object} siteConfig
+ * @param {boolean} forceDebug
+ * @returns {Promise<boolean>} True if auth was applied
+ */
+async function applyProxyAuth(page, siteConfig, forceDebug = false) {
+  const proxyUrl = getConfiguredProxy(siteConfig);
+  if (!proxyUrl) return false;
+
+  const parsed = parseProxyUrl(proxyUrl);
+  if (!parsed || !parsed.username) return false;
+
+  try {
+    await page.authenticate({
+      username: parsed.username,
+      password: parsed.password || ''
+    });
+
+    const debug = forceDebug || siteConfig.proxy_debug || siteConfig.socks5_debug;
+    if (debug) {
+      console.log(formatLogMessage('proxy', `Auth set for ${parsed.username}@${parsed.host}:${parsed.port}`));
+    }
+
+    return true;
+  } catch (err) {
+    console.warn(formatLogMessage('proxy', `Failed to set proxy auth: ${err.message}`));
+    return false;
+  }
+}
+
+/**
+ * Tests proxy connectivity by attempting a TCP connection.
+ *
+ * @param {object} siteConfig
+ * @param {number} timeoutMs - Connection timeout (default 5000ms)
+ * @returns {Promise<object>} { reachable, latencyMs, error }
+ */
+async function testProxy(siteConfig, timeoutMs = 5000) {
+  const proxyUrl = getConfiguredProxy(siteConfig);
+  if (!proxyUrl) {
+    return { reachable: false, latencyMs: 0, error: 'No proxy configured' };
+  }
+
+  const parsed = parseProxyUrl(proxyUrl);
+  if (!parsed) {
+    return { reachable: false, latencyMs: 0, error: 'Invalid proxy URL' };
+  }
+
+  const net = require('net');
+  const start = Date.now();
+
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+
+    const onError = (err) => {
+      socket.destroy();
+      resolve({ reachable: false, latencyMs: Date.now() - start, error: err.message });
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.on('error', onError);
+    socket.on('timeout', () => onError(new Error('Connection timeout')));
+
+    socket.connect(parsed.port, parsed.host, () => {
+      const latency = Date.now() - start;
+      socket.destroy();
+      resolve({ reachable: true, latencyMs: latency, error: null });
+    });
+  });
+}
+
+/**
+ * Returns human-readable proxy info string for logging.
+ *
+ * @param {object} siteConfig
+ * @returns {string}
+ */
+function getProxyInfo(siteConfig) {
+  const proxyUrl = getConfiguredProxy(siteConfig);
+  if (!proxyUrl) return 'none';
+
+  const parsed = parseProxyUrl(proxyUrl);
+  if (!parsed) return 'invalid';
+
+  const auth = parsed.username ? `${parsed.username}@` : '';
+  return `${parsed.protocol}://${auth}${parsed.host}:${parsed.port}`;
+}
+
+/**
+ * Returns module version information
+ */
+function getModuleInfo() {
+  return { version: PROXY_MODULE_VERSION, name: 'Proxy Handler' };
+}
+
+module.exports = {
+  parseProxyUrl,
+  needsProxy,
+  getProxyArgs,
+  applyProxyAuth,
+  testProxy,
+  getProxyInfo,
+  getModuleInfo,
+  getConfiguredProxy,
+  PROXY_MODULE_VERSION,
+  SUPPORTED_PROTOCOLS
+};

package/nwss.js

@@ -1,4 +1,4 @@
-// === Network scanner script (nwss.js) v2.0.33 ===
+// === Network scanner script (nwss.js) v2.0.51 ===
 
 // puppeteer for browser automation, fs for file system operations, psl for domain parsing.
 // const pLimit = require('p-limit'); // Will be dynamically imported
@@ -44,6 +44,7 @@ const { performPageInteraction, createInteractionConfig } = require('./lib/inter
 const { createGlobalHelpers, getTotalDomainsSkipped, getDetectedDomainsCount } = require('./lib/domain-cache');
 const { createSmartCache } = require('./lib/smart-cache'); // Smart cache system
 const { clearPersistentCache } = require('./lib/smart-cache');
+const { needsProxy, getProxyArgs, applyProxyAuth, getProxyInfo, testProxy } = require('./lib/proxy');
 // Dry run functionality
 const { initializeDryRunCollections, addDryRunMatch, addDryRunNetTools, processDryRunResults, writeDryRunOutput } = require('./lib/dry-run');
 // Enhanced site data clearing functionality
@@ -1354,7 +1355,7 @@ function setupFrameHandling(page, forceDebug) {
    * Uses system Chrome and temporary directories to minimize disk usage
    * @returns {Promise<import('puppeteer').Browser>} Browser instance
    */
-  async function createBrowser() {
+  async function createBrowser(extraArgs = []) {
     // Create temporary user data directory that we can fully control and clean up
     const tempUserDataDir = `/tmp/puppeteer-${Date.now()}-${Math.random().toString(36).substring(7)}`;
     userDataDir = tempUserDataDir; // Store for cleanup tracking (use outer scope variable)
@@ -1458,6 +1459,7 @@ function setupFrameHandling(page, forceDebug) {
         '--disable-background-timer-throttling',
         '--disable-features=site-per-process', // Better for single-site scanning
         '--no-zygote', // Better process isolation
+        ...extraArgs,
         ],
         // Optimized timeouts for Puppeteer 23.x performance
         protocolTimeout: TIMEOUTS.PROTOCOL_TIMEOUT,
@@ -2130,6 +2132,11 @@ function setupFrameHandling(page, forceDebug) {
         }
       }
 
+      // --- Apply proxy authentication if configured ---
+      if (needsProxy(siteConfig)) {
+        await applyProxyAuth(page, siteConfig, forceDebug);
+      }
+
       // --- Apply all fingerprint spoofing (user agent, Brave, fingerprint protection) ---
       try {
         await applyAllFingerprintSpoofing(page, siteConfig, forceDebug, currentUrl);
@@ -3337,6 +3344,25 @@ function setupFrameHandling(page, forceDebug) {
           siteCounter++;
           // Continue processing with the redirected URL instead of throwing error
         } else {
+          // Detect proxy-specific failures and provide clear diagnostics
+          if (needsProxy(siteConfig) && err.message) {
+            const proxyErrors = [
+              'ERR_PROXY_CONNECTION_FAILED',
+              'ERR_SOCKS_CONNECTION_FAILED',
+              'ERR_TUNNEL_CONNECTION_FAILED',
+              'ERR_PROXY_AUTH_UNSUPPORTED',
+              'ERR_PROXY_AUTH_REQUESTED',
+              'ERR_SOCKS_CONNECTION_HOST_UNREACHABLE',
+              'ERR_PROXY_CERTIFICATE_INVALID',
+              'ERR_NO_SUPPORTED_PROXIES'
+            ];
+            const proxyErr = proxyErrors.find(e => err.message.includes(e));
+            if (proxyErr) {
+              const info = getProxyInfo(siteConfig);
+              console.error(formatLogMessage('error', `[proxy] ${proxyErr} — proxy: ${info} — URL: ${currentUrl}`));
+              console.error(formatLogMessage('error', `[proxy] Check: is the proxy running? Are credentials correct? Is the target reachable from the proxy?`));
+            }
+          }
           console.error(formatLogMessage('error', `Failed on ${currentUrl}: ${err.message}`));
           throw err;
         }
@@ -3662,6 +3688,26 @@ function setupFrameHandling(page, forceDebug) {
       }
       
     } catch (err) {
+      // Detect proxy-specific failures at top level
+      if (needsProxy(siteConfig) && err.message) {
+        const proxyErrors = [
+          'ERR_PROXY_CONNECTION_FAILED',
+          'ERR_SOCKS_CONNECTION_FAILED',
+          'ERR_TUNNEL_CONNECTION_FAILED',
+          'ERR_PROXY_AUTH_UNSUPPORTED',
+          'ERR_PROXY_AUTH_REQUESTED',
+          'ERR_SOCKS_CONNECTION_HOST_UNREACHABLE',
+          'ERR_PROXY_CERTIFICATE_INVALID',
+          'ERR_NO_SUPPORTED_PROXIES'
+        ];
+        const proxyErr = proxyErrors.find(e => err.message.includes(e));
+        if (proxyErr) {
+          const info = getProxyInfo(siteConfig);
+          console.error(formatLogMessage('error', `[proxy] ${proxyErr} — proxy: ${info} — URL: ${currentUrl}`));
+          console.error(formatLogMessage('error', `[proxy] Check: is the proxy running? Are credentials correct? Is the target reachable from the proxy?`));
+        }
+      }
+
       // Only restart for truly fatal browser errors
       const isFatalError = CRITICAL_BROWSER_ERRORS.some(errorType => 
         err.message.includes(errorType)
@@ -3789,6 +3835,14 @@ function setupFrameHandling(page, forceDebug) {
     }
   }
 
+  // Helper to get a stable proxy key for grouping browser instances
+  const proxyKeyFor = (siteConfig) => {
+    if (!needsProxy(siteConfig)) return '';
+    return getProxyInfo(siteConfig);
+  };
+
+  // Sort tasks so proxy groups are contiguous — direct connections first, then each proxy
+  allTasks.sort((a, b) => proxyKeyFor(a.config).localeCompare(proxyKeyFor(b.config)));
 
   let results = [];
   let processedUrlCount = 0;
@@ -3832,6 +3886,7 @@ function setupFrameHandling(page, forceDebug) {
 
  // Process URLs in batches with exception handling
  let siteGroupIndex = 0;
+ let currentProxyKey = '';  // Track active proxy config — '' means direct connection
  try {
    for (let batchStart = 0; batchStart < totalUrls; batchStart += RESOURCE_CLEANUP_INTERVAL) {
     const batchEnd = Math.min(batchStart + RESOURCE_CLEANUP_INTERVAL, totalUrls);
@@ -3952,14 +4007,67 @@ function setupFrameHandling(page, forceDebug) {
         if (forceDebug) console.log(formatLogMessage('debug', `Browser cleanup warning: ${browserCloseErr.message}`));
       }
       
-      // Create new browser for next batch
-      browser = await createBrowser();
+      // Create new browser for next batch (preserve current proxy config)
+      const restartProxyArgs = currentProxyKey ? getProxyArgs(currentBatch[0].config, forceDebug) : [];
+      browser = await createBrowser(restartProxyArgs);
       if (forceDebug) console.log(formatLogMessage('debug', `New browser instance created for batch ${Math.floor(batchStart / RESOURCE_CLEANUP_INTERVAL) + 1}`));
       
       // Reset cleanup counter and add delay
       urlsSinceLastCleanup = 0;
       await fastTimeout(TIMEOUTS.BROWSER_STABILIZE_DELAY);
     }
+
+    // --- Proxy-aware browser restart ---
+    // --proxy-server is browser-wide, so if the batch needs a different proxy we must restart
+    const batchProxyKey = proxyKeyFor(currentBatch[0].config);
+    if (batchProxyKey !== currentProxyKey) {
+      const debug = forceDebug || currentBatch[0].config.proxy_debug || currentBatch[0].config.socks5_debug;
+      if (debug) {
+        const from = currentProxyKey || 'direct';
+        const to = batchProxyKey || 'direct';
+        console.log(formatLogMessage('proxy', `Switching proxy: ${from} → ${to}`));
+      }
+
+      try {
+        await handleBrowserExit(browser, {
+          forceDebug, timeout: 10000, exitOnFailure: false,
+          cleanTempFiles: true, comprehensiveCleanup: removeTempFiles
+        });
+        if (userDataDir && fs.existsSync(userDataDir)) {
+          fs.rmSync(userDataDir, { recursive: true, force: true });
+        }
+      } catch (proxyRestartErr) {
+        if (forceDebug) console.log(formatLogMessage('debug', `Proxy switch browser cleanup: ${proxyRestartErr.message}`));
+      }
+
+      const proxyArgs = batchProxyKey ? getProxyArgs(currentBatch[0].config, forceDebug) : [];
+
+      // Pre-flight: verify proxy is reachable before launching browser
+      if (proxyArgs.length > 0) {
+        const health = await testProxy(currentBatch[0].config, 5000);
+        if (!health.reachable) {
+          const info = getProxyInfo(currentBatch[0].config);
+          console.error(formatLogMessage('error', `[proxy] Unreachable: ${info} — ${health.error}`));
+          console.error(formatLogMessage('error', `[proxy] Skipping ${currentBatch.length} URL(s) in this batch`));
+          const skipResults = currentBatch.map(task => ({
+            success: false, url: task.url, rules: [],
+            error: `Proxy unreachable: ${health.error}`
+          }));
+          results.push(...skipResults);
+          processedUrlCount += currentBatch.length;
+          urlsSinceLastCleanup += currentBatch.length;
+          continue;
+        }
+        if (forceDebug) {
+          console.log(formatLogMessage('proxy', `Proxy reachable (${health.latencyMs}ms)`));
+        }
+      }
+
+      browser = await createBrowser(proxyArgs);
+      currentProxyKey = batchProxyKey;
+      urlsSinceLastCleanup = 0;
+      await fastTimeout(TIMEOUTS.BROWSER_STABILIZE_DELAY);
+    }
     
     if (forceDebug) {
       console.log(formatLogMessage('debug', `Processing batch ${Math.floor(batchStart / RESOURCE_CLEANUP_INTERVAL) + 1}: ${batchSize} URL(s) (total processed: ${processedUrlCount})`));
@@ -3986,7 +4094,8 @@ function setupFrameHandling(page, forceDebug) {
      console.log(formatLogMessage('error', `[TIMEOUT] Batch hung. Restarting browser.`));
      try {
        await handleBrowserExit(browser, { forceDebug, timeout: 5000, exitOnFailure: false });
-       browser = await createBrowser();
+       const timeoutProxyArgs = currentProxyKey ? getProxyArgs(currentBatch[0].config, forceDebug) : [];
+       browser = await createBrowser(timeoutProxyArgs);
        urlsSinceLastCleanup = 0;
      } catch (restartErr) {
        throw restartErr;
@@ -4104,7 +4213,7 @@ function setupFrameHandling(page, forceDebug) {
             comprehensive: true 
           });
         }
-        browser = await createBrowser();
+        browser = await createBrowser(currentProxyKey ? getProxyArgs(currentBatch[0].config, forceDebug) : []);
         urlsSinceLastCleanup = 0; // Reset counter
         await fastTimeout(TIMEOUTS.EMERGENCY_RESTART_DELAY); // Give browser time to stabilize
       } catch (emergencyRestartErr) {
@@ -4116,7 +4225,7 @@ function setupFrameHandling(page, forceDebug) {
       console.log(`\n${messageColors.fileOp('🔄 Emergency hang detection restart:')} Browser appears hung, forcing restart`);
       try {
         await handleBrowserExit(browser, { forceDebug, timeout: 5000, exitOnFailure: false, cleanTempFiles: true });
-        browser = await createBrowser();
+        browser = await createBrowser(currentProxyKey ? getProxyArgs(currentBatch[0].config, forceDebug) : []);
         urlsSinceLastCleanup = 0;
         forceRestartFlag = false; // Reset flag
         await fastTimeout(TIMEOUTS.EMERGENCY_RESTART_DELAY);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanboynz/network-scanner",
-  "version": "2.0.49",
+  "version": "2.0.51",
   "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": {
@@ -48,7 +48,7 @@
   },
   "homepage": "https://github.com/ryanbr/network-scanner",
   "devDependencies": {
-    "eslint": "^9.32.0",
+    "eslint": "^10.0.2",
     "globals": "^16.3.0"
   }
 }