proxy_set_fingerprint_spoof

Instructions

Implementation Reference

• src/tools/tls.ts:143-192 (handler)

  MCP tool handler for 'proxy_set_fingerprint_spoof'. Defines the tool schema (preset, user_agent, host_patterns, disable_redirect, insecure_skip_verify), resolves browser preset via resolveBrowserPreset(), builds FingerprintSpoofConfig, and calls proxyManager.setFingerprintSpoof(config) to apply it.

  // ── Set full fingerprint spoof ──
  server.tool(
    "proxy_set_fingerprint_spoof",
    "Enable outgoing TLS + HTTP/2 fingerprint spoofing via impit (native TLS impersonation, no Docker required). Supports browser presets that select an impit target (rustls, matching real Chrome/Firefox).",
    {
      preset: z.string().optional().describe("Browser preset name (e.g. 'chrome_131', 'chrome_136'). Use proxy_list_fingerprint_presets to see available options."),
      user_agent: z.string().optional().describe("User-Agent header to use with spoofed requests (overrides preset UA)"),
      host_patterns: z.array(z.string()).optional().describe("Only spoof requests to hostnames containing these substrings. Empty = spoof all HTTPS."),
      disable_redirect: z.boolean().optional().describe("Disable automatic redirect following"),
      insecure_skip_verify: z.boolean().optional().describe("Skip TLS certificate verification"),
    },
    async ({ preset, user_agent, host_patterns, disable_redirect, insecure_skip_verify }) => {
      try {
        let config: FingerprintSpoofConfig;
  
        if (preset) {
          const base = resolveBrowserPreset(preset);
          config = {
            userAgent: user_agent ?? base.userAgent,
            hostPatterns: host_patterns,
            disableRedirect: disable_redirect,
            insecureSkipVerify: insecure_skip_verify,
            preset,
          };
        } else {
          config = {
            userAgent: user_agent,
            hostPatterns: host_patterns,
            disableRedirect: disable_redirect,
            insecureSkipVerify: insecure_skip_verify,
          };
        }
  
        await proxyManager.setFingerprintSpoof(config);
  
        return {
          content: [{
            type: "text" as const,
            text: JSON.stringify({
              status: "success",
              message: "Fingerprint spoofing enabled",
              config,
            }),
          }],
        };
      } catch (e) {
        return { content: [{ type: "text" as const, text: JSON.stringify({ status: "error", error: String(e) }) }] };
      }
    },
  );

• src/state.ts:1063-1066 (helper)

  ProxyManager.setFingerprintSpoof() - stores the config and triggers mockttp rule rebuild to apply the spoofing to outgoing requests.

  async setFingerprintSpoof(config: FingerprintSpoofConfig): Promise<void> {
    this._ja3SpoofConfig = config;
    if (this._running) await this.rebuildMockttpRules();
  }

• src/state.ts:243-249 (schema)

  FingerprintSpoofConfig interface - defines the config shape used by the tool (userAgent, hostPatterns, disableRedirect, insecureSkipVerify, preset).

  export interface FingerprintSpoofConfig {
    userAgent?: string;
    hostPatterns?: string[];
    disableRedirect?: boolean;
    insecureSkipVerify?: boolean;
    preset?: string;
  }

• src/browser-presets.ts:9-14 (schema)

  BrowserPreset interface - defines the preset shape (name, description, userAgent, impitBrowser) used by the tool to map preset names to impit impersonation targets.

  export interface BrowserPreset {
    name: string;
    description: string;
    userAgent: string;
    impitBrowser: string;     // impit Browser enum value, e.g. "chrome131"
  }

• src/browser-presets.ts:70-77 (helper)

  resolveBrowserPreset() - resolves a preset name string to a BrowserPreset object, used by the tool handler to get the userAgent and impitBrowser for the chosen preset.

  export function resolveBrowserPreset(name: string): BrowserPreset {
    const preset = PRESETS[name];
    if (!preset) {
      const available = Object.keys(PRESETS).join(", ");
      throw new Error(`Unknown browser preset '${name}'. Available: ${available}`);
    }
    return preset;
  }