Using Proxyman to Inspect Network Traffic

Learn how to use Proxyman as a man-in-the-middle proxy to inspect network traffic on your iOS device or simulator. By Danijela Vrzan.

Leave a rating/review
Download materials
Save for later
Share

It’s almost impossible to write apps these days without using some kind of networking. It’s an essential concept every developer has to learn: Parse data from JSON and display it in your UI. Between fetching the data and displaying it, you often have a network call. Dealing with it can be frustrating at times. Have you ever coded everything right, with Xcode showing no errors, but still there’s no data displayed in your app? Fortunately, this is where Proxyman comes to the rescue. You can use its powerful toolkit to inspect and debug your network calls. It acts as a man-in-the-middle between your app and the web server.

In this tutorial you’ll learn how to:

  • Set up Proxyman on your Mac.
  • Enable SSL proxying of HTTPS requests.
  • Inspect your app’s network traffic.
  • Edit network responses to simulate different scenarios.
  • Use the Atlantis framework to inspect network calls on a physical device.

You’ll need a physical device if you’d like to try out proxying a device’s traffic. However, if you don’t have one, you can skip that part of the tutorial.

First, take a look at the app you’ll use for this tutorial.

Getting Started

Download the starter project by clicking Download Materials at the top or bottom of the tutorial.

Open Jokester.xcodeproj inside the starter folder. Build and run to see the app in action:

Jokester iOS app running on a Simulator. It has an image and a card. Tapping the card displays a random dad joke from network and a random image above it.

Jokester is a simple, one-screen app that fetches a random dad joke from this JokeAPI and a random image using the Lorem Picsum random image generator. Every time you tap the card, the app makes two network calls: One that gets a random joke in JSON format, parses it and then displays it in a card view and a second that generates a random image. These two calls are independent of each other.

Before you begin, you ask: What sorcery is proxying?

A witch boiling something in her cauldron with Swifties flying around her

Understanding Proxying

Networking — the Wingardium Leviosa of modern computing.

Sorcery or not, you’ll have a hard time finding an app that’s not using networking in some way.

Have you ever finished designing your UI, and the preview looks good, but once you build and run your app, it’s empty? You’re not getting any errors, and Xcode isn’t complaining when you need it to?

Xcode’s console output might give you some hints about what’s happening, but it’s not telling you much.

There’s a better way to debug your networking calls: using a proxy.

A proxy acts as a middleman between the client seeking the resources and a server that provides those resources:

A diagram of how proxying works. A conversation between Sam and Jack has a proxy in between.

When you have a proxy set up between the client and the server, the server doesn’t know to whom it’s sending the information. It’s only aware of the request and that it needs to send a response.

First, you need to download and set up Proxyman.

Setting up Proxyman

At the time of writing, version 2.31.0 is the latest version of Proxyman. While your version may be different, the concepts will still be the same.

Before you begin, you need to install Proxyman on your machine.

Installing Proxyman

Download the latest version from the Proxyman website. Click the button on the website entitled Download Proxyman for macOS and wait for the DMG file to download.

Open the file, then drag and drop Proxyman to Applications:

Installation process showing you to drag and drop Proxyman.dmg file to your Applications folder

When you open Proxyman for the first time, it’ll prompt you to Install Proxy Helper Tool:

When you open Proxyman for the first time you'll see this window that asks you to install Proxy Helper Tool

Proxyman uses a macOS command-line tool called networksetup to change the system proxy settings. It works, however it is less performant than installing Proxyman’s own helper tool for this. Installing it requires entering your password as it requires elevated privileges to function.

Click Install Helper Tool and enter your password when prompted. If you closed the pop-up or wish to install the helper tool later, go to Preference ▸ Advanced and install it from there.

Next, you’ll become familiar with the interface.

Getting Familiar With the Interface

The moment you opened Proxyman, it started inspecting all network calls on your machine. Depending on how many tabs you have open, it might be filling up the list very quickly. And you know you have more than one tab open, wink, wink.

Pause the proxying for now by clicking Pause Recording on the top-left:

Proxyman app showing where the Stop or Pause Recording button is at the top-left.

When you want to resume recording, click the same button to Start Recording again.

Proxyman has three main panels, highlighted in the screenshot below.

Proxyman app showing different parts of Proxyman's interface, the Source List, Flow List and a Flow Content panel.

Here’s what each of these panels provide:

Source List displays aggregated information about all domains and apps connected to the network on your machine. Once you start inspecting networks in the simulator or your iOS device, they’ll appear on the list.

Flow List displays detailed information about each network call on a specific domain.

But the area that interests you the most is Flow Content. It’s split into two main parts: Request and Response windows.

You look at requests and responses while you’re inspecting your network calls. You can see detailed information and even read the JSON you’re fetching in plain text. All this may look confusing at first, but it’ll get much clearer once you start using it in your app.

The top area has three buttons. The first one you already used to pause recording. The second one is for composing your own requests, and the third one clears all the network calls from the list.

Three buttons at the top of Proxyman interface.

Below them is a filtering bar where you can filter your calls by a specific format.

Setting up HTTPS Proxying

HTTPS mean using the HTTP protocol over SSL. SSL itself is a protocol designed to create authenticated and encrypted links between computers in a network. SSL was deprecated when the newer protocol, TLS, released in 1999. However, it’s still referred to as SSL or sometimes as SSL/TLS.

Click a row in the flow list where the URL starts with https://. Notice how the response tab has a lock that says This HTTPS response is encrypted and shows no information?

It’s like the Marauder’s Map — where the key to unlocking it is the magic words, “I solemnly swear that I am up to no good”.

You are actually performing a man-in-the-middle (MITM) attack on yourself when you proxy traffic. When you do it with HTTPS traffic you are technically tricking the server into believing that Proxyman is the app requesting data. However it’s not nefarious because you’re doing this to your own traffic on your machine!

Note: If you’re interested in learning more about man-in-the-middle attacks and how to prevent them, check out this Preventing Man-in-the-Middle Attacks in iOS with SSL Pinning tutorial. You’ll simulate the attack and learn how to defend against it.

To let Proxyman do its magic, you must first install a root certificate which Proxyman can use to encrypt/decrypt as it acts as the man-in-the-middle.

To show you the responses of your network calls in plain text, Proxyman requires you to install the Proxyman Root Certificate. The certificate is locally generated on your machine and stored and trusted in your Keychain.

Go to Certificate ▸ Install Certificate on this Mac…

Proxyman app showing how to navigate to Installing your Proxyman Root Certificate on your macOS

You’ll see a new Mac Setup Guide window with instructions to set up your macOS certificate:

Proxyman app showing the window of the Installing your Proxyman Root Certificate setup guide

If you have administrator privileges, it’s easiest to install the certificate automatically on the default selected Automatic. If you don’t, you can still do it manually by following the instructions in the Manual tab.

On the Automatic tab, click Install & Trust. When prompted, enter your password. You should now see Installed & Trusted!, which means you’ve completed the process:

Mac Setup Guide window in Proxyman showing Installed and Trusted for the Proxyman root certificate

Start recording network calls if you are still paused. You’ll notice that, while you’re able to see the responses, some of them are still locked.

You’ve done everything. But to decrypt encrypted responses you still need to enable SSL proxying for whatever domains you need to inspect connections to.

Note: It’s recommended you delete the Proxyman Root Certificate from your Keychain once you stop using Proxyman. Anyone who has the Proxyman Certificate can intercept your HTTP/HTTPS requests on your macOS machine.