Proxyman
HomepageDownload
  • Overview
  • Changelog
  • License
  • License Manager
  • Raycast
  • Command-line
  • Security Compliance
  • Proxyman iOS
    • Proxyman for iOS
    • Map Local for iOS
    • Breakpoint for iOS
    • Tutorial for iOS
      • Map Local for iOS Tutorial
      • Breakpoint for iOS Tutorial
  • Debug on Devices
    • macOS
    • iOS Device
    • iOS Simulator
    • tvOS & watchOS
    • Android Device & Emulator
      • Automatic Script for Android Emulator
      • Sample Android Project
    • Firefox
    • Java VMs
    • Python
    • Ruby
    • NodeJS
    • Rust
    • Golang
    • React Native
    • Flutter
    • HTTP Clients
    • Docker
    • ElectronJS
    • NextJS (fetch)
  • Automatic Setup
    • Automatic Setup
    • Manual Setup
    • Troubleshooting
  • Atlantis
    • Atlantis for iOS
  • BASIC FEATURES
    • Proxyman Proxy Helper Tool
    • Request / Response Previewer
    • SSL Proxying
    • Bypass Proxy List
    • Import / Export
    • Content Filter
    • Multiple Tabs
    • Horizontal/Vertical/Window Layout
    • Copy as
    • Custom Previewer Tab
    • Custom Header Column
    • Regex (Regular Expression)
    • Filter JSON Response
    • Highlight by Color and Add Comment
    • Import / Export Settings
    • Multipart Form-Data Previewer
    • JSONPath
    • Customize Toolbar
    • Localization
    • Quick Preview
  • ADVANCED FEATURES
    • Repeat
    • Edit & Repeat
    • Compose new Request
    • No Caching
    • Breakpoint
    • Breakpoint Templates
    • Map Local (File)
    • Map Local (Directory)
    • Map Remote
    • External Proxy
    • Save Session
    • Protobuf
    • WebSocket
    • Clear Session
    • Block List
    • Allow List
    • Charles Proxy Converter
    • Custom Certificates
    • GraphQL
    • Network Conditions
    • Multiple Filters
    • Custom Filters
    • Publish to Gist
    • Reverse Proxy
    • Code Generator
    • Diff
    • Access Control
    • DNS Spoofing
    • SOCKS Proxy
    • Swagger OpenAPI
    • TLS Key Logging
  • Proxyman Windows
    • Install Certificate
    • WSL
  • Scripting
    • Scripting
    • async/await Request
    • Addons
    • Built-in JS Libraries
    • Write your own Addons
    • Snippet Code
    • Environment Variables
  • Troubleshooting
    • Proxyman does not work with VPN apps
    • My Remote Devices (iOS/Android) could not connect to Proxyman?
    • iOS 16 and iOS 17 issues
    • SSL Error from HTTPS Request/Response
    • I could not see any requests from my localhost server
    • I could not see any HTTP traffic from my NodeJS, Python, or Ruby scripts
    • *.local requests do not appear on Proxyman
    • I couldn't see any traffics on Proxyman
    • I couldn't see any requests from 3rd-party network libraries
    • [Breakpoint] Modify Request/Response by Raw Message
    • Could not change Proxyman App Icons
    • Lost data after updating Proxyman app?
    • Proxyman consumes too much RAM & unresponsive
Powered by GitBook
On this page
  • 1. What's it?
  • 2. Capture WS/WSS from iOS
  • ✅ Solution 1 (Recommended for iOS 17 or later)
  • ✅ Solution 2
  • 3. Capture WebSockets from your Web Browser (Chrome, Safari, etc)
  • 4. Capture Websocket from NodeJS, Golang, Python Server
  • 5. Map Websocket from Localhost <-> Production
  1. ADVANCED FEATURES

WebSocket

How to capture and decrypt Websocket (WS/WSS) from iOS devices / simulators with Proxyman. Works with Google Chrome Web Browser or websocket from NodeJS, Python, Golang Backend Server

PreviousProtobufNextClear Session

Last updated 1 month ago

1. What's it?

Proxyman could capture WebSocket (WS) and Secure WebSocket (WSS) traffic and easily preview it.

  • Capture WS/WSS from iOS Physical devices and iOS Simulator (Required )

  • Capture WS/WSS from Web Browser and Mac applications.

  • Capture WS/WSS from Android Physical devices or Android Emulators.

  • Prettier WebSocket Message.

  • Filter All / Sent / Received messages.

  • See the content in JSON / Tree Preview / HEX format.

  • Customize Columns: Frame, Length, Data, Time, ...

  • Auto-decode Binary Message to JSON if possible

  • Open WebSocket messages by external Editors, such as Sublime, VSCode

2. Capture WS/WSS from iOS

If your iOS app is using URLSessionWebSocketTask or iOS WebSocket libraries, e.g. Starscream, SocketRocket, etc. Proxyman might not be able to capture WS/WSS traffic.

  • Reason: Apple's intention. URLSessionWebSocketTask doesn't respect the System HTTP Proxy. All WS/WSS traffic goes directly to the Internet. Thus, Proxyman or Charles Proxy can't capture it.

  • Example Ap:

✅ Solution 1 (Recommended for iOS 17 or later)

  1. Proxyman Setup: Tools > Proxy Settings > SOCKS Proxy settings -> Enable it (Take note of the port)

  2. On the main Proxyman app -> Take note of a current IP in the Proxyman Tools bar

  1. On your app: Configure a SOCK Proxy in your App, make sure this is only available for debug builds by implementing a switch or something, you might not want your release build with this configuration.

  • For NWConnection

let parameters = webSocketURL.scheme == "wss" ? NWParameters.tls : NWParameters.tcp

let options = NWProtocolWebSocket.Options()
options.autoReplyPing = true

parameters.defaultProtocolStack.applicationProtocols.insert(options, at: 0)

if #available(iOS 17.0, *) {
    let socksv5Proxy = NWEndpoint.hostPort(host: "x.x.x.x", port: 8889) //  Please x.x.x.x with a real Proxyman IP
    let config = ProxyConfiguration.init(socksv5Proxy: socksv5Proxy)
    let context = NWParameters.PrivacyContext(description: "my socksv5Proxy")
    context.proxyConfigurations = [config]

    parameters.setPrivacyContext(context)
}

let connection = NWConnection(to: .url(webSocketURL), using: parameters)
connection.start(queue: .main)
  • For URLSession and URLSessionWebSocketTask

private lazy var urlSession: URLSession = {
    let config = URLSessionConfiguration.default
    if #available(iOS 17.0, *) {
        let socksv5Proxy = NWEndpoint.hostPort(host: "x.x.x.x", port: 8889) //  Please x.x.x.x with a real Proxyman IP
        let proxyConfig = ProxyConfiguration.init(socksv5Proxy: socksv5Proxy)
        config.proxyConfigurations = [proxyConfig]
    }

    return URLSession(configuration: config, delegate: nil, delegateQueue: nil)
}()
  1. Done ✅

✅ Solution 2

3. Capture WebSockets from your Web Browser (Chrome, Safari, etc)

  • Proxyman can capture WS/WSS from a Web Browser out of the box. No need to configure anything.

  • How to use: Open Google Chrome -> Visit your website that makes a WS/WSS connection -> Open Proxyman -> Find your websocket domains -> On the Response Panel -> Click Enable SSL Proxying on these domains. Open your Browser, and reload your website -> Proxyman will capture and decrypt WS/WSS ✅

4. Capture Websocket from NodeJS, Golang, Python Server

  • Proxyman can capture WS/WSS from your NodeJS, Golang, Python, and Ruby server.

  • How to use: Read Automatic Setup to start your server on this Terminal -> Make a WS/WSS connection -> Proxyman automatically captures and decyrpts it ✅

5. Map Websocket from Localhost <-> Production

Follow the Setup guide for your or (Make sure we installed and trusted the certificate on your device)

Credit to ->

Tutorial:

Use (developed by Proxyman) to capture WS/WSS URLSessionWebSocketTask traffic from iOS.

Read more at

It's possible to map the WebSocket Traffic from localhost <-> Production. Please check out the

Atlantis framework
https://github.com/ProxymanApp/websocket-example-ios-app
iOS Devices
iOS Simulators
FranklinSamboni
https://github.com/ProxymanApp/Proxyman/issues/586#issuecomment-2125082129
https://proxyman.io/posts/2019-10-18-WebSocket-Debugging
Atlantis Framework
https://github.com/ProxymanApp/atlantis
Map Remote Tool.
Get Proxyman current IP
Capture Websocket from iOS with Proxyman