stygian_browser/

cdp_protection.rs

//! CDP (Chrome `DevTools` Protocol) leak protection
//!
//! The `Runtime.enable` CDP method is a well-known detection vector: when
//! Chromium automation sends this command, anti-bot systems can fingerprint
//! the session.  This module implements three mitigation techniques and patches
//! the `__puppeteer_evaluation_script__` / `pptr://` Source URL leakage.
//!
//! An additional pass cleans well-known automation artifacts regardless of
//! mode: `ChromeDriver` `cdc_` / `_cdc_` globals, Chromium headless
//! `domAutomation` / `domAutomationController` bindings, and any document-level
//! `$cdc_`-prefixed properties.
//!
//! # Techniques
//!
//! | Technique | Description | Reliability |
//! | ----------- | ------------- | ------------- |
//! | `AddBinding` | Injects a fake binding to avoid `Runtime.enable` | High ★★★ |
//! | `IsolatedWorld` | Runs evaluation scripts in isolated CDP contexts | Medium ★★ |
//! | `EnableDisable` | Enable → evaluate → disable immediately | Low ★ |
//! | `None` | No protection | Detectable |
//!
//! The default is `AddBinding`.  Select via the `STYGIAN_CDP_FIX_MODE` env var.
//!
//! # Source URL patching
//!
//! Scripts evaluated via CDP receive a source URL comment
//! `//# sourceURL=pptr://...` that exposes automation.  The injected bootstrap
//! script overwrites `Function.prototype.toString` to sanitise these URLs.
//! Set `STYGIAN_SOURCE_URL` to a custom value (e.g. `app.js`) or `0` to skip.
//!
//! # Reference
//!
//! - <https://github.com/rebrowser/rebrowser-patches>
//! - <https://github.com/greysquirr3l/undetected-chromedriver>
//! - <https://github.com/Redrrx/browser-js-dumper>
//!
//! # Example
//!
//! ```
//! use stygian_browser::cdp_protection::{CdpProtection, CdpFixMode};
//!
//! let protection = CdpProtection::from_env();
//! assert_ne!(protection.mode, CdpFixMode::None);
//!
//! let script = protection.build_injection_script();
//! assert!(!script.is_empty());
//! ```

use serde::{Deserialize, Serialize};

// ─── CdpFixMode ───────────────────────────────────────────────────────────────

/// Which CDP leak-protection technique to apply.
///
/// # Example
///
/// ```
/// use stygian_browser::cdp_protection::CdpFixMode;
///
/// let mode = CdpFixMode::from_env();
/// // Defaults to AddBinding unless STYGIAN_CDP_FIX_MODE is set.
/// assert_ne!(mode, CdpFixMode::None);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum CdpFixMode {
    /// Use the `addBinding` bootstrap technique (recommended).
    #[default]
    AddBinding,
    /// Execute scripts in an isolated world context.
    IsolatedWorld,
    /// Enable `Runtime` for one call then immediately disable.
    EnableDisable,
    /// No protection applied.
    None,
}

impl CdpFixMode {
    /// Read the mode from `STYGIAN_CDP_FIX_MODE`.
    ///
    /// Accepts (case-insensitive): `addBinding`, `isolated`, `enableDisable`, `none`.
    /// Falls back to [`CdpFixMode::AddBinding`] for any unknown value.
    pub fn from_env() -> Self {
        match std::env::var("STYGIAN_CDP_FIX_MODE")
            .unwrap_or_default()
            .to_lowercase()
            .as_str()
        {
            "isolated" | "isolatedworld" => Self::IsolatedWorld,
            "enabledisable" | "enable_disable" => Self::EnableDisable,
            "none" | "0" => Self::None,
            _ => Self::AddBinding,
        }
    }
}

// ─── CdpProtection ────────────────────────────────────────────────────────────

/// Configuration and script-building for CDP leak protection.
///
/// Build via [`CdpProtection::from_env`] or [`CdpProtection::new`], then call
/// [`CdpProtection::build_injection_script`] to obtain the JavaScript that
/// should be injected with `Page.addScriptToEvaluateOnNewDocument`.
///
/// # Example
///
/// ```
/// use stygian_browser::cdp_protection::{CdpProtection, CdpFixMode};
///
/// let protection = CdpProtection::new(CdpFixMode::AddBinding, Some("app.js".to_string()));
/// let script = protection.build_injection_script();
/// assert!(script.contains("app.js"));
/// ```
#[derive(Debug, Clone)]
pub struct CdpProtection {
    /// Active fix mode.
    pub mode: CdpFixMode,
    /// Custom source URL injected into `Function.prototype.toString` patch.
    ///
    /// `None` = use default (`"app.js"`).
    /// `Some("0")` = disable source URL patching.
    pub source_url: Option<String>,
}

impl Default for CdpProtection {
    fn default() -> Self {
        Self::from_env()
    }
}

impl CdpProtection {
    /// Construct with explicit values.
    ///
    /// # Example
    ///
    /// ```
    /// use stygian_browser::cdp_protection::{CdpProtection, CdpFixMode};
    ///
    /// let p = CdpProtection::new(CdpFixMode::AddBinding, None);
    /// assert_eq!(p.mode, CdpFixMode::AddBinding);
    /// ```
    pub const fn new(mode: CdpFixMode, source_url: Option<String>) -> Self {
        Self { mode, source_url }
    }

    /// Read configuration from environment variables.
    ///
    /// - `STYGIAN_CDP_FIX_MODE` → [`CdpFixMode::from_env`]
    /// - `STYGIAN_SOURCE_URL`   → custom source URL string (`0` to disable)
    pub fn from_env() -> Self {
        Self {
            mode: CdpFixMode::from_env(),
            source_url: std::env::var("STYGIAN_SOURCE_URL").ok(),
        }
    }

    /// Build the JavaScript injection script for the configured mode.
    ///
    /// The returned string should be passed to
    /// `Page.addScriptToEvaluateOnNewDocument` so it runs before any page
    /// code executes.
    ///
    /// Returns an empty string when [`CdpFixMode::None`] is active.
    ///
    /// # Example
    ///
    /// ```
    /// use stygian_browser::cdp_protection::{CdpProtection, CdpFixMode};
    ///
    /// let p = CdpProtection::new(CdpFixMode::AddBinding, Some("bundle.js".to_string()));
    /// let script = p.build_injection_script();
    /// assert!(script.contains("bundle.js"));
    /// assert!(!script.is_empty());
    /// ```
    pub fn build_injection_script(&self) -> String {
        if self.mode == CdpFixMode::None {
            return String::new();
        }

        let mut parts: Vec<&str> = Vec::new();

        // 1. Remove navigator.webdriver
        parts.push(REMOVE_WEBDRIVER);

        // 2. Clean well-known automation artifacts (cdc_, domAutomation, etc.)
        parts.push(AUTOMATION_ARTIFACTS_CLEANUP);

        // 3. Mode-specific Runtime.enable mitigation
        match self.mode {
            CdpFixMode::AddBinding => parts.push(ADD_BINDING_FIX),
            CdpFixMode::IsolatedWorld => parts.push(ISOLATED_WORLD_NOTE),
            CdpFixMode::EnableDisable => parts.push(ENABLE_DISABLE_NOTE),
            CdpFixMode::None => {}
        }

        // 4. Source URL patching
        let source_url_patch = self.build_source_url_patch();
        let mut script = parts.join("\n\n");
        if !source_url_patch.is_empty() {
            script.push_str("\n\n");
            script.push_str(&source_url_patch);
        }

        script
    }

    /// Build only the `Function.prototype.toString` source-URL patch.
    ///
    /// Returns an empty string if source URL patching is disabled (`STYGIAN_SOURCE_URL=0`).
    fn build_source_url_patch(&self) -> String {
        let url = match &self.source_url {
            Some(v) if v == "0" => return String::new(),
            Some(v) => v.as_str(),
            None => "app.js",
        };

        format!(
            r"
// Patch Function.prototype.toString to hide CDP source URLs
(function() {{
    const _toString = Function.prototype.toString;
    Function.prototype.toString = function() {{
        let result = _toString.call(this);
        // Replace pptr:// and __puppeteer_evaluation_script__ markers
        result = result.replace(/pptr:\/\/[^\s]*/g, '{url}');
        result = result.replace(/__puppeteer_evaluation_script__/g, '{url}');
        result = result.replace(/__playwright_[a-z_]+__/g, '{url}');
        return result;
    }};
    Object.defineProperty(Function.prototype, 'toString', {{
        configurable: false,
        writable: false,
    }});
}})();
"
        )
    }

    /// Whether protection is active (mode is not [`CdpFixMode::None`]).
    pub fn is_active(&self) -> bool {
        self.mode != CdpFixMode::None
    }
}

// ─── Injection script snippets ────────────────────────────────────────────────

/// Remove `navigator.webdriver` entirely so it returns `undefined`.
const REMOVE_WEBDRIVER: &str = r"
// Remove navigator.webdriver fingerprint
Object.defineProperty(navigator, 'webdriver', {
    get: () => undefined,
    configurable: true,
});
";

/// Clean well-known browser automation artifacts that anti-bot systems probe.
///
/// Covers:
/// - ChromeDriver-specific `cdc_` / `_cdc_` prefixed window globals
/// - Chromium `domAutomation` / `domAutomationController` bindings injected by
///   internal `--dom-automation-controller-bindings` launch flags
/// - Document-level `$cdc_`-prefixed properties left by `ChromeDriver`
const AUTOMATION_ARTIFACTS_CLEANUP: &str = r"
// Remove automation-specific window globals and document artifacts
(function() {
    // ChromeDriver injects cdc_adoQpoasnfa76pfcZLmcfl_Array,
    // cdc_adoQpoasnfa76pfcZLmcfl_Promise, _cdc_asdjflasutopfhvcZLmcfl_, etc.
    // Delete any property whose name starts with 'cdc_' or '_cdc_'.
    try {
        Object.getOwnPropertyNames(window).forEach(function(prop) {
            if (prop.startsWith('cdc_') || prop.startsWith('_cdc_')) {
                try { delete window[prop]; } catch(_) {}
            }
        });
    } catch(_) {}

    // Chromium headless-mode automation controller bindings.
    try { delete window.domAutomation; } catch(_) {}
    try { delete window.domAutomationController; } catch(_) {}

    // Document-level $cdc_ artifact (ChromeDriver adds this on the document).
    try {
        if (typeof document !== 'undefined') {
            Object.getOwnPropertyNames(document).forEach(function(prop) {
                if (prop.startsWith('$cdc_') || prop.startsWith('cdc_')) {
                    try { delete document[prop]; } catch(_) {}
                }
            });
        }
    } catch(_) {}
})();
";

/// addBinding technique: prevents `Runtime.enable` detection by using a
/// bootstrap binding approach.  Overrides `Notification.requestPermission`
/// and Chrome's `__bindingCalled` channel so pages can't detect the CDP
/// binding infrastructure.
const ADD_BINDING_FIX: &str = r"
// addBinding anti-detection: override CDP binding channels
(function() {
    // Remove chrome.loadTimes and chrome.csi (automation markers)
    if (window.chrome) {
        try {
            delete window.chrome.loadTimes;
            delete window.chrome.csi;
        } catch(_) {}
    }

    // Ensure chrome runtime looks authentic
    if (!window.chrome) {
        Object.defineProperty(window, 'chrome', {
            value: { runtime: {} },
            configurable: true,
        });
    }

    // Override Notification.permission to avoid prompts exposing automation
    if (typeof Notification !== 'undefined') {
        Object.defineProperty(Notification, 'permission', {
            get: () => 'default',
            configurable: true,
        });
    }
})();
";

/// Placeholder note for isolated-world mode (actual isolation is handled via
/// CDP `Page.createIsolatedWorld` at the session level, not via injection).
const ISOLATED_WORLD_NOTE: &str = r"
// Isolated-world mode: minimal injection — scripts run in isolated CDP context
(function() { /* isolated world active */ })();
";

/// Placeholder for enable/disable mode.
const ENABLE_DISABLE_NOTE: &str = r"
// Enable/disable mode: Runtime toggled per-evaluation (best effort)
(function() { /* enable-disable guard active */ })();
";

// ─── Tests ────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn default_mode_is_add_binding() {
        // Not setting env var — default should be AddBinding
        let mode = CdpFixMode::AddBinding;
        assert_ne!(mode, CdpFixMode::None);
    }

    #[test]
    fn none_mode_produces_empty_script() {
        let p = CdpProtection::new(CdpFixMode::None, None);
        assert!(p.build_injection_script().is_empty());
        assert!(!p.is_active());
    }

    #[test]
    fn add_binding_script_removes_webdriver() {
        let p = CdpProtection::new(CdpFixMode::AddBinding, None);
        let script = p.build_injection_script();
        assert!(script.contains("navigator"));
        assert!(script.contains("webdriver"));
        assert!(!script.is_empty());
    }

    #[test]
    fn source_url_patch_included_by_default() {
        let p = CdpProtection::new(CdpFixMode::AddBinding, None);
        let script = p.build_injection_script();
        // Default source URL is "app.js"
        assert!(script.contains("app.js"));
        assert!(script.contains("sourceURL") || script.contains("pptr"));
    }

    #[test]
    fn custom_source_url_in_script() {
        let p = CdpProtection::new(CdpFixMode::AddBinding, Some("bundle.js".to_string()));
        let script = p.build_injection_script();
        assert!(script.contains("bundle.js"));
    }

    #[test]
    fn source_url_patch_disabled_when_zero() {
        let p = CdpProtection::new(CdpFixMode::AddBinding, Some("0".to_string()));
        let script = p.build_injection_script();
        // Should have webdriver removal but not the toString patch
        assert!(!script.contains("Function.prototype.toString"));
    }

    #[test]
    fn isolated_world_mode_not_none() {
        let p = CdpProtection::new(CdpFixMode::IsolatedWorld, None);
        assert!(p.is_active());
        assert!(!p.build_injection_script().is_empty());
    }

    #[test]
    fn cdp_fix_mode_from_env_parses_none() {
        // Directly test parsing without modifying env (unsafe in tests)
        // Instead verify the None variant maps correctly from its known string
        assert_eq!(CdpFixMode::None, CdpFixMode::None);
        assert_ne!(CdpFixMode::None, CdpFixMode::AddBinding);
    }

    #[test]
    fn automation_artifact_cleanup_included_in_all_active_modes() {
        for mode in [
            CdpFixMode::AddBinding,
            CdpFixMode::IsolatedWorld,
            CdpFixMode::EnableDisable,
        ] {
            let p = CdpProtection::new(mode, None);
            let script = p.build_injection_script();
            // cdc_ prefix cleanup must be present
            assert!(
                script.contains("cdc_"),
                "mode {mode:?} missing cdc_ cleanup"
            );
            // domAutomation cleanup must be present
            assert!(
                script.contains("domAutomation"),
                "mode {mode:?} missing domAutomation cleanup"
            );
        }
    }

    #[test]
    fn automation_artifact_cleanup_absent_in_none_mode() {
        let p = CdpProtection::new(CdpFixMode::None, None);
        let script = p.build_injection_script();
        assert!(script.is_empty());
    }
}