A Brief User Guide on Fiddler Orchestra

This is a guide for getting to know and setting up Fiddler Orchestra, a new flavor of the Fiddler web debugger. Please note the guide is accurate as of Fiddler 5.0.

What is Fiddler Orchestra

Fiddler Orchestra is a new flavor of the world famous Fiddler web debugger that delivers the benefits of remote debugging and web UI. Find out more about Fiddler Orchestra.

Fiddler Orchestra Architecture Summary

Two roles are possible in Fiddler Orchestra – Controller and Client. The Controller harvests data from and controls any number of Clients. The Client reports data to and takes commands from any number of Controllers. It is only the Controller that keeps a port open and accepts incoming connections from the Clients. All Client-Controller communication is encrypted.

Fiddler Orchestra First Release

The first release of Fiddler Orchestra comes packaged in (WinForms) Fiddler 5.0 and consists of Fiddler Orchestra .NET Core Clients and Fiddler Orchestra Controller built in Fiddler 5.0. The .NET Core clients can run on MAC, Linux and Windows.

In this first release the Orchestra Controller is capable only of harvesting data in the first release. It lacks any client control capabilities. The .NET Core Clients can only connect to a single controller in this release.

Requirements (as of Fiddler 5.0)

Fiddler Orchestra runs on multiple platforms but most of its codebase is platform agnostic. That is, the same code with very minor changes runs on all platforms. That being the case, the core of Fiddler Orchestra is compiled as .NET Standard 2.0 assembly. Hence, Fiddler Orchestra clients and Controllers will run only on frameworks that support at least .NET Standard 2.0. At the time of writing this article these are:

• .NET Framework 4.6.1
• .NET Core 2.0
•  Xamarin.iOS 10.14
• Xamarin.Android 7.5

At the time of writing this article only WinForms Fiddler can be Orchestra controller. That functionality, however, will be available only on machines where .NET 4.6.1 or above is installed.

Setup

There are two steps to set up the connection between a Fiddler Orchestra .NET Core Client(s) and WinForms Fiddler Orchestra Controller (the only available Orchestra controller at the time of writing this article). In essence, one has to set up the controller to accept connections first and then one has to set up the client(s) to connect to the controller.

Setting up the WinForms Fiddler Orchestra Controller

In WinForms Fiddler 5.0 there is a new Fiddler Orchestra tab:

This is the starting point of Orchestra Controller configuration. It takes just a port and a private key to start a controller. The port must be open for external connections so that Orchestra Client(s) can connect. The private key is used to encrypt the communication with the clients. The clients must have the same private key set to be able to connect to this controller. The private key can be regenerated only when the controller is stopped.

Setting up the .NET Core Fiddler Orchestra Client (on MAC, Linux, Windows, etc.)

Background

The .NET Core Fiddler Orchestra Client has the full Fiddler capabilities built-in. Rather unfortunately, at the time of writing this article these are hidden behind a very limited Web UI that allows only setting up Fiddler to capture traffic and setting up a connection to a Fiddler Orchestra Controller.

The .NET Core Fiddler Orchestra Client captures traffic by acting as a proxy much like the good old WinForms Fiddler does. The WinForms Fiddler, however, is pretty good at hiding this proxy behavior by automagically setting itself as the system proxy at startup on Windows, i.e. the user not only does not have to do any manual proxy setup but also might not even be aware that Fiddler acts as a proxy.

At the time of writing this article Fiddler Orchestra Client does not have the automagical proxy set up capabilities. So, the user must take care of the proxy setup, i.e. the user must manually change the settings of browsers or any other applications to point to Fiddler Orchestra Client Proxy on startup and then revert the settings on exit. In future versions of Fiddler Orchestra the user will be able to provide a script to do that, which will get automatically executed on startup.

Setup

The .NET Core Fiddler Orchestra Client binaries come with WinForms Fiddler 5.0. A convenient shortcut is provided on the Fiddler Orchestra tab in Fiddler 5.0, as shown below.

At the time of writing this article .NET Core Fiddler Orchestra Client is a vanilla ASP .NET Core application. So, its startup is quite simple:

At this point the Web UI is up and running at http://localhost:8800 and any combination of HTTP/HTTPS proxy/reverse proxy can be started to capture traffic. A connection to a Fiddler Orchestra Controller can also be set up and any traffic going through any of the proxies will be reported to the connected Controller.

A more detailed view of the proxy and Orchestra connection configuration follows.

The Proxy Page

The home page is the HTTP/HTTPS proxy setup page.

The proxy settings are the same as in WinForms Fiddler.

Decrypt HTTPS enables MITM HTTPS traffic decryption by the proxy. Having mentioned MITM it is worth also mentioning that HTTPS traffic decryption will not work unless an HTTPS root certificate is either created or uploaded via the HTTPS Root Certificate tab.

Unless “Allow remote clients” to connect is checked, the proxy will accept connections only from the machine it is running on.

Specifying an upstream gateway allows all outgoing traffic to be funneled through another proxy.

The HTTP Reverse Proxy Page

A reverse proxy allows for intercepting incoming traffic to the machine where it is running. More often than not a reverse proxy will be used to intercept incoming traffic to a webserver, webservice, etc.

The reverse proxy would position itself between the webserver/webservice and its clients. So, all the requests would reach the reverse proxy first and then it will redirect them to the actual recipient.

The “Listen on port” setting specifies the port at which the reverse proxy will be expecting incoming traffic to arrive. The “Host listens on port” setting specifies the port that the original webserver/webservice listens to. The reverse proxy will redirect any traffic it receives on the “Listen on port” to “Host listens on port.”

Unless “Allow remote clients” to connect is checked the proxy will accept connections only from the machine it is running on. Since this is rarely useful in a reverse proxy setup that option is checked by default.

HTTPS Reverse Proxy

The HTTPS reverse proxy follows the same logic as the HTTP reverse proxy. The only setting added is the Hostname. A certificate under that hostname will be generated and signed with the root certificate provided/generated in the HTTPS Root Certificate tab. That certificate will be used by the HTTPS reverse proxy to encrypt the responses to the incoming requests.

Consequently, the clients that send the requests should trust the root certificate provided/generated in the HTTPS Root Certificate tab. It is technically feasible that the actual certificate used by the proxied webserver/webservice gets used by the reverse proxy, but at the time of writing this functionality is not yet implemented.

HTTPS Root Certificate

The HTTPS root certificate presence is a prerequisite for running HTTPS (reverse) proxy. An existing certificate can be uploaded or a new one can be generated.

The generated certificate file may be password protected. An alias name could also be added for the generated certificate.

Orchestra Connection

The Orchestra Connection tab allows for setting up a connection to a Fiddler Orchestra Controller. The Controller should be running prior to making connection attempts.

The connection setup is straightforward. The IP address and port of the Controller are needed. The Controller is set up to encrypt traffic using a specific private key. That private key should also be provided (it could be copied from the WinForms Fiddler Orchestra Controller setup tab).

Finally, filtering the Fiddler Orchestra configuration traffic will prevent the Fiddler Orchestra Web Client traffic from being sent to the Controller and displayed there.