Third-party Injection Policy

The Firefox browser supports expanding its functionality with browser extensions and provides an extensive and well documented set of APIs for developers known as the WebExtensions API. To date, developers have contributed tens of thousands of extensions available on addons.mozilla.org. Nevertheless, some third-party developers seek to modify the browser in ways beyond what is possible with a browser extension and resort to “hooking” the browser, effectively injecting third-party executable code modules into Firefox processes. Security software such as anti-virus products on Windows are the most prevalent examples.

Maintaining the User Experience - Reliable and Secure Browsing

Even when the desired behavior might be beneficial to users, modifying Firefox in this way is inherently risky. Such modifications may cause browser crashes, broken features, or other unexpected problems that degrade the user experience. When third-party software is found to destabilize the browser, Firefox may intervene.

Interventions* may include, but are not limited to:

1. Detecting instability locally, notifying the user, and offering them the opportunity to block specific modules from being injected.
2. Detecting instability locally, automatically blocking the unstable module, and providing the user an option to unblock it.
3. Detecting aggregate instability across many users, and proactively blocking the module globally across all Firefox instances.

*Current versions of Firefox do not automatically block problematic modules or prompt the user to do so, but we are exploring this functionality. Firefox does maintain a block list which is already used when problems are discovered from crash reporting and bug reports. See below for more information.

If a third-party feature achieved with Firefox injection works well, that’s great. However, if we become aware of a problem, we will contact the vendor if they have shared a responsive support contact with Mozilla. We are happy to alert external vendors about such issues and welcome proactive communication with vendors before issues arise. Please contact us at thirdpartysoftware@mozilla.com.

While we prefer to work cooperatively with other developers, our resources are finite and oftentimes we have to act quickly. We reserve the right to block third-party injections whenever we believe this is in the best interest of Firefox users.

We intend to review this position over time and may be more restrictive with third-party module injection in the future.

In-Browser Diagnostics

When we encounter an interoperability issue caused by a third-party module, we look for a workaround or implement a mitigation patch in Firefox while contacting the vendor to request a fix. If those attempts are not successful, we globally block the module using our blocklist. In most cases, blocking can be limited to the problematic versions of the module and modules can be unblocked after a fix is implemented. Not all third-party interoperability issues are addressed. For example, some may only affect a small number of users.

In Firefox, we provide an in-browser diagnostics page. The about:third-party page (only available on Firefox for Windows) in Firefox lists the injected modules together with details about the injection technique, loading time, and - if possible - vendor and product names.

If we detect at runtime that previous Firefox crashes were caused by a third-party module, we may prompt the user to block or we may automatically block the module giving the user the option to unblock the module in the future, depending on the severity of the impact.

Technical Recommendations

The rest of this document contains guidelines and best practices to minimize the risk of instability. We strongly recommend following these guidelines, both to reduce stability risk and to avoid potentially being misclassified as a source of instability.

Some of the details in this document concern implementation details that are subject to change as we improve the performance, security and functionality of the browser. Note that Mozilla publishes Beta and Nightly versions of Firefox that can give you an early warning about upcoming changes that may affect your software. We recommend testing on Nightly and Beta as well as Release versions of Firefox.

Firefox Process Structure

• Launcher Process (Windows-specific)

  • Browser Process (main process, sometimes referred to as ‘parent process’ or ‘chrome process’ inside Firefox sources and legacy documentation)

    • Content Processes (render web pages)
    • Privileged Content Process (for Mozilla accounts and addons.mozilla.org)
    • Privileged about: Content-like Process
    • GPU Process
    • RDD Process (media decoding)
    • GMP Process (DRM decoding)
    • Socket Process (network handling - WebRTC)
    • WebExtensions Process
    • WebVR Process

Guidelines for Module Injection

Processes other than the Browser Process and the Socket Process should preferably not be injected into. Specifically, processes sitting below the browser process will tend to be heavily sandboxed and may have very limited ability to interact with the operating system, including standard Win32 APIs (i.e. win32k.sys may not even be accessible), or may be blocked from loading code with third party signatures (Arbitrary Code Guard/Code Injection Guard). Injecting into these may stop security functionality from working, or render the browser non functional.

As more functionality related to networking moves to the Socket Process, injecting there may be unavoidable for software that wants to monitor low-level network access.

The Launcher Process is a process to launch the browser process and apply several security mitigations. Because the launcher process terminates quickly after launching the browser process and is isolated from browsing-related work, there is no benefit to injecting a third-party module into the launcher process.

These guidelines mean that if a third party vendor wants a module to be loaded into our process, it is necessary that their module or injector program recognizes the target process type and does not modify our sandboxed processes. With the current design, the easiest way to detect the process type is to check the last token in the command line string. If this is “-contentproc”, then you are dealing with a child process (of any type, not necessarily content!) and typically do not want to inject. If the type of child process is needed, this corresponds to the last token (With “socket” being the Socket Process). Such implementation details are subject to change.

On Windows, there are many known techniques to inject a module into a remote process. In general, a technique implemented as a part of Windows OS is safer, such as Window message hook or AppInit_DLLs. On the other hand, a technique that modifies a code segment of a mapped image, such as Microsoft Detours, is strongly NOT recommended because if more than one application applies a hook on the same function, behavior is undefined and the result is almost certainly breakage.

Please contact us at thirdpartysoftware@mozilla.com with questions.