How Firefox Updates and Maintains the HSTS Preload List

This article provides a complete overview of how the Mozilla Firefox web browser maintains and updates its HTTP Strict Transport Security (HSTS) preload list. It explains how Mozilla sources the initial domain data from the Chromium project, the automated verification process used to validate the security of those domains, how the finalized list is compiled into the Firefox source code, and how updates are delivered to users through the standard browser release cycle.

Sourcing from the Chromium Project

Mozilla does not operate its own independent submission portal for the HSTS preload list. Instead, Firefox relies on the central HSTS preload list maintained by the Chromium project. Website administrators submit their domains to the Chromium list, which acts as the universal starting point for most major web browsers, including Firefox, Chrome, Edge, and Safari.

Automated Verification and Pruning

Firefox does not blindly import the Chromium preload list. Instead, Mozilla runs an automated periodic script within its own infrastructure to verify that the domains on the Chromium list actively meet Mozilla's strict security standards.

The automated script fetches the current Chromium JSON file and tests every newly submitted domain, as well as existing domains on the list. To pass Mozilla's verification, a domain must meet the following criteria:

  • It must serve a valid HTTPS certificate.
  • It must redirect all HTTP traffic to HTTPS.
  • It must serve the Strict-Transport-Security header on the base domain.
  • The HSTS header must include the preload directive.
  • The HSTS header must include the includeSubDomains directive.
  • The max-age directive in the header must be set to at least 18 weeks (10,886,400 seconds).

If a domain on the Chromium list fails to respond or no longer meets these criteria during Mozilla's automated scan, it is excluded or pruned from the Firefox version of the list. This ensures that dead domains or sites that have intentionally downgraded their security do not bloat the browser or become inaccessible to Firefox users.

Compiling the List into Firefox

Once the automated script finishes querying the domains, it generates a C++ header file named nsSTSPreloadList.inc. This file contains a static, binary-searchable list of all the validated HSTS domains.

Mozilla engineers review the automated output, and the updated nsSTSPreloadList.inc file is committed directly into the mozilla-central source code repository. Because the list is hardcoded into the browser's source code for performance and security reasons, it becomes a permanent part of that specific Firefox build.

Delivering Updates to Users

Updates to the HSTS preload list are delivered to end-users through Firefox's standard rapid release cycle, often referred to as "riding the trains."

  1. Firefox Nightly: The automated HSTS update script runs roughly once a week. When the updated list is committed to the source code, users on the Nightly channel receive the new preload list immediately in their next daily update.
  2. Firefox Beta: Every four weeks, the code from Nightly merges into the Beta channel. The HSTS preload list is frozen at this point for that specific version, barring any critical security issues or urgent removal requests.
  3. Firefox Stable: Four weeks after entering Beta, the build is pushed to the general public as the official Stable release.

Because of this train model, it typically takes between four to eight weeks from the time a domain is added to the Chromium preload list for it to be actively enforced as preloaded in the standard release of Firefox.

Local Maintenance and Overrides

Between browser updates, Firefox maintains HSTS states locally in the user's profile folder within a file named SiteSecurityServiceState.txt.

If a user visits a website that is not yet on the preload list, but the site sends a valid HSTS header, Firefox records the domain in this local text file. Conversely, if a site is on the hardcoded preload list and sends a header with max-age=0 (which is the standard way to revoke HSTS), Firefox will ignore the revocation request. Because preloaded statuses are compiled into the browser binary, a domain can only be removed from Firefox's preload enforcement by requesting removal through the Chromium project and waiting for the change to propagate through Mozilla's automated scripts and release cycle.