Using Proxyman to Inspect Network Traffic

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 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?

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:

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:

When you open Proxyman for the first time, it’ll prompt 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:

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

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

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.

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!

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…

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

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:

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.