Understanding FiddlerScript

Understanding FiddlerScript

FiddlerScript is one of the most powerful features in Fiddler; it allows you to enhance Fiddler's UI, add new features, and modify requests and responses “on the fly” to introduce any behavior you'd like.

FiddlerScript is based on JScript.NET, a .NET version of JavaScript, so it's easy for web developers to use, and the syntax is close enough to C# that most .NET developers can write simple rules with little effort.

Editing FiddlerScript

To get started, simply click Rules > Customize Rules to open your FiddlerScript file.

If the file opens in Notepad that means you haven't yet installed the FiddlerScript Editor, which offers syntax-highlighting, Intellisense-style code completion, and a Class Explorer:

If you're doing any non-trivial updates to your FiddlerScript, you should definitely install the FiddlerScript editor, which is bundled with the SyntaxView Inspectors that offer syntax-highlighting and formatting of common web types (HTML, CSS, JavaScript, etc).

No matter what editor you use, when you update the script and save it, Fiddler will automatically notice the new file version and attempt to load it. If the script loads successfully, a sound will play and the Fiddler status bar will say “CustomRules.js was loaded at <datetime>” (this text is actually set by the Main function inside the FiddlerScript file itself. You can change it to anything you'd like.) If compilation of the script fails, an error message will be shown and you can use it to help fix whatever problem you've found in your script.

If you ever corrupt your FiddlerScript so badly that you can't fix it, simply delete the CustomRules.js file from \Documents\Fiddler2\Scripts and restart Fiddler. Fiddler will automatically regenerate the file using the latest SampleRules.js file included in the Fiddler installation package.

FiddlerScript Methods

Your FiddlerScript file includes a single static class (named Handlers) which Fiddler uses to locate the methods that are called as it runs.

Generally speaking, all of your code should be placed inside static methods on this class.

Fiddler automatically executes a number of “Application event methods” as it runs:

As Fiddler processes Web Sessions, each Session is passed (as a parameter) to an method based on the current state of the Session.

The “Session event methods” are invoked in the following order:

Targeting Sessions

When using the Session event methods, your code typically consists of two major parts:

1. Recognizing of Web Sessions of interest (Targeting)
2. Making changes to those Sessions (Updating)

In most cases, you only want to update certain Web Sessions, so your code should examine the properties of the Web Session to decide if the current Session is one needing modification.

There are several useful helper methods for this task:

if (oSession.uriContains("caseInsensitiveStringFromURI")) {
  /* do something */
}

if (oSession.HostnameIs("SiteICareAbout.com")) {
  /* do something */
}

if (oSession.HTTPMethodIs("POST") &&
    oSession.oRequest.headers.ExistsAndContains("SoapAction", "SendBody") {
  /* do something for SOAP POSTS */
}

In many cases, you don't want to target requests which represent CONNECT tunnels through which secure traffic flows, because you instead only want to modify the HTTPS requests inside the tunnel rather than the tunnel itself.

To do that, simply check to see whether the request's HTTP Method is “Connect” and if so, skip the Session:

if (!oSession.HTTPMethodIs("CONNECT")) {
  /* ignore CONNECT tunnels */
}

Often, complaints that “My rules didn't update the Session properly” turn out to be related to the fact that the Sessions were not targeted properly.

To help identify such problems, each rule should always update the Session's UI so that it's plain to see whether the rule is being applied:

// case-sensitively replace oldString with newString
if (oSession.fullUrl.indexOf("oldString") > -) {
  oSession["ui-backcolor"] = "lime";
  oSession["ui-bold"] = "changing URL for this session";
  oSession.fullUrl = oSession.fullUrl.Replace("oldString", "newString");
}

This rule block changes the Web Session's background color to lime green and bolds its text before replacing all instances of “oldString” in the URL with “newString”.

That way, if the rule is running on Sessions you don't expect (or if it isn't running on Sessions you do) you can more easily identify the problem with your targeting