thermoptic

You can inject custom Node.js logic into the thermoptic lifecycle using file paths provided via environment variables. This allows you to automate browser interactions or manipulate requests.

• ON_START_HOOK_FILE_PATH: Runs once when the proxy starts. The proxy will block listening until this script finishes. Use this for tasks like clicking through Cloudflare JavaScript challenges.
• BEFORE_REQUEST_HOOK_FILE_PATH: Runs before a request is proxied. Use this to ensure the browser passes specific checks before an HTTP request is made.
• AFTER_REQUEST_HOOK_FILE_PATH: Runs after a request is proxied. Use this for post-request cleanup, such as removing specific cookies set by the client via the Cookie header.

thermoptic loads the browser with the cookies specified in your client's Cookie header. This ensures that the server cannot fingerprint the user based on cookie ordering or other metadata.

Warning: These cookies persist in the browser context after the request is executed. If you require cookie cleanup, you must implement a custom thermoptic hook.

To mitigate JavaScript-based fingerprinting (common in WAFs like Cloudflare), thermoptic provides a hook framework. This allows you to automate the browser to solve challenges or capture artifacts before/after requests.

Supported hook types include:

• before-request
• after-request
• on-start

An example of a Cloudflare Turnstile solving hook can be found in the repository's ./hooks/onstart.js file.

When writing automation for anti-bot services, avoid using the Chrome Debugging Protocol (CDP) Runtime API (e.g., Runtime.enable).

Why? Using the Runtime API to inject or execute JavaScript can trigger an object-serialization nuance that makes your scraping immediately detectable to advanced anti-bot services like Cloudflare. Instead, use the DOM and Input APIs to interact with the page as a user would.

Thermoptic achieves browser-parity by using the Chrome Debugging Protocol (CDP) to puppet a real browser instance. The process follows these steps:

1. An HTTP request is sent to the thermoptic proxy from a client (e.g., curl).
2. thermoptic analyzes the request to determine the intended browser behavior (e.g., manual URL visit, form submission, or fetch()).
3. thermoptic uses CDP to command the browser to mock the request exactly as it would occur in a real session.
4. The request is executed by the browser's full network stack (TCP, TLS, HTTP).
5. thermoptic captures the browser's HTTP response and returns it to the original client.

Because the request is made by the actual browser, the resulting JA4+ fingerprints are indistinguishable from a real user.

To enable a custom hook (like the Turnstile bypass) in a thermoptic Docker deployment, set the ON_START_HOOK_FILE_PATH environment variable to the path of your hook file within the container. Ensure the hook file is mounted via a volume.

thermoptic:
  build: .
  volumes:
    - ./ssl:/work/cassl
    - ./hooks:/work/hooks
  depends_on:
    - chrome
  ports:
    - 1234:1234
  environment:
    HTTP_PROXY_PORT: 1234
    CHROME_DEBUGGING_PORT: 3003
    CHROME_DEBUGGING_HOST: chrome
    PROXY_USERNAME: changeme
    PROXY_PASSWORD: changeme
    # Path to your custom hook file
    ON_START_HOOK_FILE_PATH: /work/hooks/onstart.js

To handle advanced JavaScript fingerprinting or manual verification steps (like CAPTCHAs), you can use thermoptic hooks. These allow you to execute custom JavaScript using the Chrome Debugging Protocol (CDP) at specific lifecycle stages.

Available hook stages via environment variables:

• ON_START_HOOK_FILE_PATH: Executed when the browser first starts.
• BEFORE_REQUEST_HOOK_FILE_PATH: Executed before a request is proxied.
• AFTER_REQUEST_HOOK_FILE_PATH: Executed after a request has finished being proxied.

Each hook receives a cdp object, which is an instance of a connected browser via the chrome-remote-interface interface.

// `cdp` is an instance of a connected browser, use it to run your browser actions
export async function hook(cdp) {
    console.log(`[STATUS] Browser start hook called successfully!`);
}

Usage Warning

thermoptic is designed to be used only with HTTP clients that you explicitly trust. Do not expose the proxy to untrusted users.

Vulnerability Reporting

If you discover a security vulnerability, please report it to mandatory@ Gmail.

You can manually interact with the Dockerized Chrome browser using the Xpra web interface available at http://127.0.0.1:14111. This is useful for:

• Authentication: Logging into websites (e.g., Reddit) manually so that subsequent requests made via thermoptic (using curl or other clients) are automatically authenticated.
• Debugging: Testing your custom thermoptic hooks and observing how websites behave.