Over the last few weeks I’ve been working on my Web load testing utility West Wind WebSurge. One of the key components of a load testing tool is the ability to capture URLs effectively so that you can play them back later under load. One of the options in WebSurge for capturing URLs is to use its built-in capture tool which acts as an HTTP proxy to capture any HTTP and HTTPS traffic from most Windows HTTP clients, including Web Browsers as well as standalone Windows applications and services.

To make this happen, I used Eric Lawrence’s awesome FiddlerCore library, which provides most of the functionality of his desktop Fiddler application, all rolled into an easy to use library that you can plug into your own applications. FiddlerCore makes it almost too easy to capture HTTP content!

For WebSurge I needed to capture all HTTP traffic in order to capture the full HTTP request – URL, headers and any content posted by the client. The result of what I ended up creating is this semi-generic capture form:

In this post I’m going to demonstrate how easy it is to use FiddlerCore to build this HTTP Capture Form. 

If you want to jump right in here are the links to get Telerik’s Fiddler Core and the code for the demo provided here.

• FiddlerCore Download
• FiddlerCore on NuGet
• Show me the Code (WebSurge Integration code from GitHub)
• Download the WinForms Sample Form
• West Wind Web Surge (example implementation in live app)

Note that FiddlerCore is bound by a license for commercial usage – see license.txt in the FiddlerCore distribution for details.

Integrating FiddlerCore

FiddlerCore is a library that simply plugs into your application. You can download it from the Telerik site and manually add the assemblies to your project, or you can simply install the NuGet package via:

      PM> Install-Package FiddlerCore

The library consists of the FiddlerCore.dll as well as a couple of support libraries (CertMaker.dll and BCMakeCert.dll) that are used for installing SSL certificates. I’ll have more on SSL captures and certificate installation later in this post.

But first let’s see how easy it is to use FiddlerCore to capture HTTP content by looking at how to build the above capture form.

Capturing HTTP Content

Once the library is installed it’s super easy to hook up Fiddler functionality. Fiddler includes a number of static class methods on the FiddlerApplication object that can be called to hook up callback events as well as actual start monitoring HTTP URLs.

In the following code directly lifted from WebSurge, I configure a few filter options on Form level object, from the user inputs shown on the form by assigning it to a capture options object. In the live application these settings are persisted configuration values, but in the demo they are one time values initialized and set on the form. Once these options are set, I hook up the AfterSessionComplete event to capture every URL that passes through the proxy after the request is completed and start up the Proxy service:

void Start()
{
    if (tbIgnoreResources.Checked)
        CaptureConfiguration.IgnoreResources = true;
    else
        CaptureConfiguration.IgnoreResources = false;

    string strProcId = txtProcessId.Text;
    if (strProcId.Contains('-'))
        strProcId = strProcId.Substring(strProcId.IndexOf('-') + 1).Trim();

    strProcId = strProcId.Trim();

    int procId = 0;
    if (!string.IsNullOrEmpty(strProcId))
    {
        if (!int.TryParse(strProcId, out procId))
            procId = 0;
    }
    CaptureConfiguration.ProcessId = procId;
    CaptureConfiguration.CaptureDomain = txtCaptureDomain.Text;

    FiddlerApplication.AfterSessionComplete += FiddlerApplication_AfterSessionComplete;
    FiddlerApplication.Startup(8888, true, true, true);
}

The key lines for FiddlerCore are just the last two lines of code that include the event hookup code as well as the Startup() method call. Here I only hook up to the AfterSessionComplete event but there are a number of other events that hook various stages of the HTTP request cycle you can also hook into. Other events include BeforeRequest, BeforeResponse, RequestHeadersAvailable, ResponseHeadersAvailable and so on.

In my case I want to capture the request data and I actually have several options to capture this data. AfterSessionComplete is the last event that fires in the request sequence and it’s the most common choice to capture all request and response data. I could have used several other events, but AfterSessionComplete is one place where you can look both at the request and response data, so this will be the most common place to hook into if you’re capturing content.

The implementation of AfterSessionComplete is responsible for capturing all HTTP request headers and it looks something like this:

private void FiddlerApplication_AfterSessionComplete(Session sess)
{
    // Ignore HTTPS connect requests
    if (sess.RequestMethod == "CONNECT")
        return;

    if (CaptureConfiguration.ProcessId > 0)
    {
        if (sess.LocalProcessID != 0 && sess.LocalProcessID != CaptureConfiguration.ProcessId)
            return;
    }

    if (!string.IsNullOrEmpty(CaptureConfiguration.CaptureDomain))
    {
        if (sess.hostname.ToLower() != CaptureConfiguration.CaptureDomain.Trim().ToLower())
            return;
    }

    if (CaptureConfiguration.IgnoreResources)
    {
        string url = sess.fullUrl.ToLower();

        var extensions = CaptureConfiguration.ExtensionFilterExclusions;
        foreach (var ext in extensions)
        {
            if (url.Contains(ext))
                return;
        }

        var filters = CaptureConfiguration.UrlFilterExclusions;
        foreach (var urlFilter in filters)
        {
            if (url.Contains(urlFilter))
                return;
        }
    }

    if (sess == null || sess.oRequest == null || sess.oRequest.headers == null)
        return;

    string headers = sess.oRequest.headers.ToString();
    var reqBody = sess.GetRequestBodyAsString();

    // if you wanted to capture the response
    //string respHeaders = session.oResponse.headers.ToString();
    //var respBody = session.GetResponseBodyAsString();

    // replace the HTTP line to inject full URL
    string firstLine = sess.RequestMethod + " " + sess.fullUrl + " " + sess.oRequest.headers.HTTPVersion;
    int at = headers.IndexOf("\r\n");
    if (at < 0)
        return;
    headers = firstLine + "\r\n" + headers.Substring(at + 1);

    string output = headers + "\r\n" +
                    (!string.IsNullOrEmpty(reqBody) ? reqBody + "\r\n" : string.Empty) +
                    Separator + "\r\n\r\n";

    BeginInvoke(new Action<string>((text) =>
    {
        txtCapture.AppendText(text);
        UpdateButtonStatus();
    }), output);

}

The code starts by filtering out some requests based on the CaptureOptions I set before the capture is started. These options/filters are applied when requests actually come in. This is very useful to help narrow down the requests that are captured for playback based on options the user picked. I find it useful to limit requests to a certain domain for captures, as well as filtering out some request types like static resources – images, css, scripts etc. This is of course optional, but I think it’s a common scenario and WebSurge makes good use of this feature.

AfterSessionComplete like other FiddlerCore events, provides a Session object parameter which contains all the request and response details. There are oRequest and oResponse objects to hold their respective data. In my case I’m interested in the raw request headers and body only, as you can see in the commented code you can also retrieve the response headers and body. Here the code captures the request headers and body and simply appends the output to the textbox on the screen. Note that the Fiddler events are asynchronous, so in order to display the content in the UI they have to be marshaled back the UI thread with BeginInvoke, which here simply takes the generated headers and appends it to the existing textbox test on the form. As each request is processed, the headers are captured and appended to the bottom of the textbox resulting in a Session HTTP capture in the format that Web Surge internally supports, which is basically raw request headers with a customized 1st HTTP Header line that includes the full URL rather than a server relative URL.

When the capture is done the user can either copy the raw HTTP session to the clipboard, or directly save it to file. This raw capture format is the same format WebSurge and also Fiddler use to import/export request data.

While this code is application specific, it demonstrates the kind of logic that you can easily apply to the request capture process, which is one of the reasonsof why FiddlerCore is so powerful. You get to choose what content you want to look up as part of your own application logic and you can then decide how to capture or use that data as part of your application.

The actual captured data in this case is only a string. The user can edit the data by hand or in the the case of WebSurge, save it to disk and automatically open the captured session as a new load test.

Stopping the FiddlerCore Proxy

Finally to stop capturing requests you simply disconnect the event handler and call the FiddlerApplication.ShutDown() method:

void Stop()
{
    FiddlerApplication.AfterSessionComplete -= FiddlerApplication_AfterSessionComplete;

    if (FiddlerApplication.IsStarted())
        FiddlerApplication.Shutdown();
}

As you can see, adding HTTP capture functionality to an application is very straight forward. FiddlerCore offers tons of features I’m not even touching on here – I suspect basic captures are the most common scenario, but a lot of different things can be done with FiddlerCore’s simple API interface. Sky’s the limit!

The source code for this sample capture form (WinForms) is provided as part of this article.

Adding Fiddler Certificates with FiddlerCore

One of the sticking points in West Wind WebSurge has been that if you wanted to capture HTTPS/SSL traffic, you needed to have the full version of Fiddler and have HTTPS decryption enabled. Essentially you had to use Fiddler to configure HTTPS decryption and the associated installation of the Fiddler local client certificate that is used for local decryption of incoming SSL traffic.

While this works just fine, requiring to have Fiddler installed and then using a separate application to configure the SSL functionality isn’t ideal. Fortunately FiddlerCore actually includes the tools to register the Fiddler Certificate directly using FiddlerCore.

Why does Fiddler need a Certificate in the first Place?

Fiddler and FiddlerCore are essentially HTTP proxies which means they inject themselves into the HTTP conversation by re-routing HTTP traffic to a special HTTP port (8888 by default for Fiddler) and then forward the HTTP data to the original client. Fiddler injects itself as the system proxy in using the WinInet Windows settings  which are the same settings that Internet Explorer uses and that are configured in the Windows and Internet Explorer Internet Settings dialog. Most HTTP clients running on Windows pick up and apply these system level Proxy settings before establishing new HTTP connections and that’s why most clients automatically work once Fiddler – or FiddlerCore/WebSurge are running.

For plain HTTP requests this just works – Fiddler intercepts the HTTP requests on the proxy port and then forwards them to the original port (80 for HTTP and 443 for SSL typically but it could be any port). For SSL however, this is not quite as simple – Fiddler can easily act as an HTTPS/SSL client to capture inbound requests from the server, but when it forwards the request to the client it has to also act as an SSL server and provide a certificate that the client trusts. This won’t be the original certificate from the remote site, but rather a custom local certificate that effectively simulates an SSL connection between the proxy and the client. If there is no custom certificate configured for Fiddler the SSL request fails with a certificate validation error. The key for this to work is that a custom certificate has to be installed that the HTTPS client trusts on the local machine.

For a much more detailed description of the process you can check out Eric Lawrence’s blog post on Certificates.

If you’re using the desktop version of Fiddler you can install a local certificate into the Windows certificate store. Fiddler proper does this from the Options menu:

This operation does several things:

• It installs the Fiddler Root Certificate
• It sets trust to this Root Certificate
• A new client certificate is generated for each HTTPS site monitored

Certificate Installation with FiddlerCore

You can also provide this same functionality using FiddlerCore which includes a CertMaker class. Using CertMaker is straight forward to use and it provides an easy way to create some simple helpers that can install and uninstall a Fiddler Root certificate:

public static bool InstallCertificate()
{
    if (!CertMaker.rootCertExists())
    {
        if (!CertMaker.createRootCert())
            return false;

        if (!CertMaker.trustRootCert())
            return false;
    }

    return true;
}

public static bool UninstallCertificate()
{
    if (CertMaker.rootCertExists())
    {
        if (!CertMaker.removeFiddlerGeneratedCerts(true))
            return false;
    }
    return true;
}

InstallCertificate() works by first checking whether the root certificate is already installed and if it isn’t goes ahead and creates a new one. The process of creating the certificate is a two step process – first the actual certificate is created and then it’s moved into the certificate store to become trusted. I’m not sure why you’d ever split these operations up since a cert created without trust isn’t going to be of much value, but there are two distinct steps.

When you trigger the trustRootCert() method, a message box will pop up on the desktop that lets you know that you’re about to trust a local private certificate. This is a security feature to ensure that you really want to trust the Fiddler root since you are essentially installing a man in the middle certificate. It’s quite safe to use this generated root certificate, because it’s been specifically generated for your machine and thus is not usable from external sources, the only way to use this certificate in a trusted way is from the local machine. IOW, unless somebody has physical access to your machine, there’s no useful way to hijack this certificate and use it for nefarious purposes (see Eric’s post for more details).

Once the Root certificate has been installed, FiddlerCore/Fiddler create new certificates for each site that is connected to with HTTPS. You can end up with quite a few temporary certificates in your certificate store. To uninstall you can either use Fiddler and simply uncheck the Decrypt HTTPS traffic option followed by the remove Fiddler certificates button, or you can use FiddlerCore’s CertMaker.removeFiddlerGeneratedCerts() which removes the root cert and any of the intermediary certificates Fiddler created.

Keep in mind that when you uninstall you uninstall the certificate for both FiddlerCore and Fiddler, so use UninstallCertificate() with care and realize that you might affect the Fiddler application’s operation by doing so as well.

When to check for an installed Certificate

Note that the check to see if the root certificate exists is pretty fast, while the actual process of installing the certificate is a relatively slow operation that even on a fast machine takes a few seconds. Further the trust operation pops up a message box so you probably don’t want to install the certificate repeatedly.

Since the check for the root certificate is fast, you can easily put a call to InstallCertificate() in any capture startup code – in which case the certificate installation only triggers when a certificate is in fact not installed.

Personally I like to make certificate installation explicit – just like Fiddler does, so in WebSurge I use a small drop down option on the menu to install or uninstall the SSL certificate:

This code calls the InstallCertificate and UnInstallCertificate functions respectively – the experience with this is similar to what you get in Fiddler with the extra dialog box popping up to prompt confirmation for installation of the root certificate. Once the cert is installed you can then capture SSL requests.

There’s a gotcha however…

Gotcha: FiddlerCore Certificates don’t stick by Default

When I originally tried to use the Fiddler certificate installation I ran into an odd problem. I was able to install the certificate and immediately after installation was able to capture HTTPS requests. Then I would exit the application and come back in and try the same HTTPS capture again and it would fail due to a missing certificate. CertMaker.rootCertExists() would return false after every restart and if re-installed the certificate a new certificate would get added to the certificate store resulting in a bunch of duplicated root certificates with different keys.

What the heck?

CertMaker and BcMakeCert create non-sticky Certificates
I turns out that FiddlerCore by default uses different components from what the full version of Fiddler uses. Fiddler uses a Windows utility called MakeCert.exe to create the Fiddler Root certificate. FiddlerCore however installs the CertMaker.dll and BCMakeCert.dll assemblies, which use a different crypto library (Bouncy Castle) for certificate creation than MakeCert.exe which uses the Windows Crypto API. The assemblies provide support for non-windows operation for Fiddler under Mono, as well as support for some non-Windows certificate platforms like iOS and Android for decryption.

The bottom line is that the FiddlerCore provided bouncy castle assemblies are not sticky by default as the certificates created with them are not cached as they are in Fiddler proper. To get certificates to ‘stick’ you have to explicitly cache the certificates in Fiddler’s internal preferences.

A cache aware version of InstallCertificate looks something like this:

public static bool InstallCertificate()
{
    if (!CertMaker.rootCertExists())           
    {
        if (!CertMaker.createRootCert())
            return false;

        if (!CertMaker.trustRootCert())
            return false;

        App.Configuration.UrlCapture.Cert = 
            FiddlerApplication.Prefs.GetStringPref("fiddler.certmaker.bc.cert", null);
        App.Configuration.UrlCapture.Key = 
            FiddlerApplication.Prefs.GetStringPref("fiddler.certmaker.bc.key", null);
    }
    
    return true;
}

public static bool UninstallCertificate()
{
    if (CertMaker.rootCertExists())
    {
        if (!CertMaker.removeFiddlerGeneratedCerts(true))
            return false;
    }
    App.Configuration.UrlCapture.Cert = null;
    App.Configuration.UrlCapture.Key = null;
    return true;
}

In this code I store the Fiddler cert and private key in an application configuration settings that’s stored with the application settings (App.Configuration.UrlCapture object). These settings automatically persist when WebSurge is shut down. The values are read out of Fiddler’s internal preferences store which is set after a new certificate has been created. Likewise I clear out the configuration settings when the certificate is uninstalled.

In order for these setting to be used you have to also load the configuration settings into the Fiddler preferences *before* a call to rootCertExists() is made. I do this in the capture form’s constructor:

public FiddlerCapture(StressTestForm form)
{
    InitializeComponent();
    CaptureConfiguration = App.Configuration.UrlCapture;
    MainForm = form;

    if (!string.IsNullOrEmpty(App.Configuration.UrlCapture.Cert))
    {
        FiddlerApplication.Prefs.SetStringPref("fiddler.certmaker.bc.key", App.Configuration.UrlCapture.Key);
        FiddlerApplication.Prefs.SetStringPref("fiddler.certmaker.bc.cert", App.Configuration.UrlCapture.Cert);
    }
}

This is kind of a drag to do and not documented anywhere that I could find, so hopefully this will save you some grief if you want to work with the stock certificate logic that installs with FiddlerCore.

MakeCert provides sticky Certificates and the same functionality as Fiddler

But there’s actually an easier way. If you want to skip the above Fiddler preference configuration code in your application you can choose to distribute MakeCert.exe instead of certmaker.dll and bcmakecert.dll. When you use MakeCert.exe, the certificates settings are stored in Windows so they are available without any custom configuration inside of your application. It’s easier to integrate and as long as you run on Windows and you don’t need to support iOS or Android devices is simply easier to deal with.

To integrate into your project, you can remove the reference to CertMaker.dll (and the BcMakeCert.dll assembly) from your project. Instead copy MakeCert.exe into your output folder. To make sure MakeCert.exe gets pushed out, include MakeCert.exe in your project and set the Build Action to None, and Copy to Output Directory to Copy if newer.

Note that the CertMaker.dll reference in the project has been removed and on disk the files for Certmaker.dll, as well as the BCMakeCert.dll files on disk. Keep in mind that these DLLs are resources of the FiddlerCore NuGet package, so updating the package may end up pushing those files back into your project. Once MakeCert.exe is distributed FiddlerCore checks for it first before using the assemblies so as long as MakeCert.exe exists it’ll be used for certificate creation (at least on Windows).

Summary

FiddlerCore is a pretty sweet tool, and it’s absolutely awesome that we get to plug in most of the functionality of Fiddler right into our own applications. A few years back I tried to build this sort of functionality myself for an app and ended up giving up because it’s a big job to get HTTP right – especially if you need to support SSL. FiddlerCore now provides that functionality as a turnkey solution that can be plugged into your own apps easily.

The only downside is FiddlerCore’s documentation for more advanced features like certificate installation which is pretty sketchy. While for the most part FiddlerCore’s feature set is easy to work with without any documentation, advanced features are often not intuitive to gleam by just using Intellisense or the FiddlerCore help file reference (which is not terribly useful). While Eric Lawrence is very responsive on his forum and on Twitter, there simply isn’t much useful documentation on Fiddler/FiddlerCore available online. If you run into trouble the forum is probably the first place to look and then ask a question if you can’t find the answer.

The best documentation you can find is Eric’s Fiddler Book which covers a ton of functionality of Fiddler and FiddlerCore. The book is a great reference to Fiddler’s feature set as well as providing great insights into the HTTP protocol. The second half of the book that gets into the innards of HTTP is an excellent read for anybody who wants to know more about some of the more arcane aspects and special behaviors of HTTP – it’s well worth the read. While the book has tons of information in a very readable format, it’s unfortunately not a great reference as it’s hard to find things in the book and because it’s not available online you can’t electronically search for the great content in it.

But it’s hard to complain about any of this given the obvious effort and love that’s gone into this awesome product for all of these years. A mighty big thanks to Eric Lawrence  for having created this useful tool that so many of us use all the time, and also to Telerik for picking up Fiddler/FiddlerCore and providing Eric the resources to support and improve this wonderful tool full time and keeping it free for all. Kudos!

Resources

• FiddlerCore Download
• FiddlerCore NuGet
• Fiddler Capture Sample Form
• Fiddler Capture Form in West Wind WebSurge (GitHub)
• Eric Lawrence’s Fiddler Book