Skip to content

Adopting Foxhound for your Requirements

Jump to bottom
David K. edited this page Jul 17, 2025 · 1 revision

Foxhound supports a wide range of taint sources and sinks. Enabling all of them (i.e., the current behavior) can quickly get overwhelming. Therefore, we support tailoring the set of active sources and sinks to your project. This can be done in several ways:

  1. Manually, via about:config
  2. By providing a preferences file
  3. If using playwright, by providing appropriate preferences

We now detail all three variants. The first variant is mainly intended for a) on-the-fly testing and b) discoverability. So even if you do not plan to change the settings manually, the following Section will explain how to get an idea of what you can configure and how the machinery works.

Lastly, we detail some pitfalls you might run into that might seem counterintuitive.

Manual Changes

This mode is mainly useful for a) exploring the set of options and b) testing an option's impact. To manually adjust what Foxhound shall taint, visit about:config and confirm that you know what you are doing.

You should now see a screen that looks roughly as follows:

image

All tainting-related options are named tainting.name, so to explore what you can configure, enter tainting. in the search field.

This should look roughly as follows:

image

Option Types

The options are divided into three groups:

  1. tainting.active: Setting this to false disables all taint tracking from now on. This is helpful if you detect a difference in behavior between Foxhound and Vanilla Firefox, for example.
  2. tainting.sink.name: Every sink has a flag that can be disabled individually. For example, if you do not care about tainted data being used as a header value for an XHR request, you can disable tainting.sink.XMLHttpRequest.setRequestHeader(value), which will stop reporting such events.
  3. tainting.source.name: Similar to sinks, you can disable each source as well. For example, if you are not interested in dynamic user input (i.e., typing into an input field) for your experiment, simply set tainting.source.input.value to false.

Now, setting these manually is cumbersome, error-prone, and difficult to share; consequently, there are ways to automate this. Especially as many Foxhound users probably do not regularly interact with the UI at all.

Providing a Preferences File

Firefox, and by extension, Foxhound, allows users to place JavaScript files into certain locations to initialize preferences upon startup.

If you use the binary we host, i.e., from foxhound.ias.tu-bs.de, after unzipping the version you want to use, you end up with a foxhound directory containing the binary, libraries, resources, and some additional files. In the defaults/pref folder, you can see that Foxhound already ships with files that initialize configuration options at startup. These are inherited from Firefox and unrelated to Foxhound, but serve as a nice example.

Inspecting defaults/pref/channel-prefs.js should contain something like the following:

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
//
// This pref is in its own file for complex reasons. See the comment in
// browser/app/Makefile.in, bug 756325, and bug 1431342 for details. Do not add
// other prefs to this file.

pref("app.update.channel", "default");

This gives a good indicator of how to automatically set preferences. To, for example, disabling tainting at startup you could simply create a file defaults/pref/user.js with the following content:

pref("tainting.active", false);

After starting Foxhound again, you will notice that no taint flows are reported anymore. By checking about:config, you can see that the option has been applied. You can still override these settings in about:config.

Playwright Based

When launching Foxhound or Firefox with Playwright, you can provide a wide range of options listed here. Relevant for our specific use case is the firefox-user-prefs aspect.

These can be set as follows:

const ff_config = {
  executablePath: ff_path,
  firefoxUserPrefs: {
    'tainting.active': true
  }
};
let browser = await firefox.launch(Object.assign(ff_config, {}));

This, too, would disable tainting for your crawl.

FAQ

Some source/sink seems to be missing from the configuration

Sadly, ensuring that every sink we introduce in the code has a corresponding configuration option is a manual process, so mistakes can happen. If you detect such a case, please open a pull request and add the missing one(s). The list is maintained here and follows the same format as user.js shown above.

Custom Sources and Sinks

It is possible to dynamically insert custom sources and sinks into your JavaScript code to make Foxhound track arbitrary strings. At the moment, these can not be disabled via the configuration. If you believe this is an important omission, please open an Issue, and we can look into adding it.

How does this work internally

Disabling a source ensures that the string resulting from the operation is not tainted. Disabling tainting completely effectively disables all sources. I.e., if you profile Foxhound, you will still see tainting-related functions in the resulting profile, taking up time. So, for example, if you want to benchmark the overhead of tainting, simply setting tainting.active to false will not yield accurate results. To do so, please compile the matching Firefox version with the same mozconfig flags you use for Foxhound and compare these.

Disabling a sink simply suppresses the generation of the taint report,

Clone this wiki locally