Skip to content
/ user.js Public
forked from pyllyukko/user.js

user.js -- Firefox configuration hardening

License

MIT license
0 stars 233 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

ranisalt/user.js

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

822 Commits
screenshots
screenshots
 
 
.mailmap
.mailmap
 
 
.travis.yml
.travis.yml
 
 
CAs.md
CAs.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
cas.sh
cas.sh
 
 
gen-readme.sh
gen-readme.sh
 
 
ignore.list
ignore.list
 
 
user.js
user.js
 
 

Repository files navigation

user.js

Firefox configuration hardening

A user.js configuration file for Mozilla Firefox designed to harden browser settings and make it more secure.

This is a default template with every possible hardening measure enforced. See the relaxed branch for a variant providing more usability

Build Status

Main goals

  • Limit the possibilities to track the user through web analytics.
  • Harden the browser against known data disclosure or code execution vulnerabilities.
  • Limit the browser from storing anything even remotely sensitive persistently.
  • Make sure the browser doesn't reveal too much information to shoulder surfers.
  • Harden the browser's encryption (cipher suites, protocols, trusted CAs).
  • Limit possibilities to uniquely identify the browser/device using browser fingerprinting.
  • Hopefully limit the attack surface by disabling various features.
  • Still be usable in daily use.

How to achieve this?

There are several parts to all this and they are:

Download

Different download methods are available:

  • Clone using git: git clone https://github.com/pyllyukko/user.js
  • Download and extract the ZIP file containing the latest version.
  • Download the latest user.js directly

Installation

Backups

Do note that these settings alter your browser behaviour quite a bit, so it is recommended to either create a completely new profile for Firefox or backup your existing profile directory before putting the user.js file in place.

To enable the Profile Manager, run Firefox with command-line arguments: firefox --no-remote -P

Single profile installation

Copy user.js in your current user profile directory, or (recommended) to a fresh, newly created Firefox profile directory.

The file should be located at:

OS Path
Windows 7 %APPDATA%\Mozilla\Firefox\Profiles\XXXXXXXX.your_profile_name\user.js
Linux ~/.mozilla/firefox/XXXXXXXX.your_profile_name/user.js
OS X ~/Library/Application Support/Firefox/Profiles/XXXXXXXX.your_profile_name
Android /data/data/org.mozilla.firefox/files/mozilla/XXXXXXXX.your_profile_name and see issue #14
Sailfish OS + Alien Dalvik /opt/alien/data/data/org.mozilla.firefox/files/mozilla/XXXXXXXX.your_profile_name
Windows (portable) [firefox directory]\Data\profile\

With this installation method, if you change any of user.js settings through about:config or Firefox preferences dialogs, they will be reset to the user.js defined values after you restart Firefox. This makes sure they're always back to secure defaults when starting the browser. However this prevents persistently changing settings you don't consider appropriate. Either edit user.js directly, or use the system-wide installation method described below.

System-wide installation (all platforms)

Generate a file suitable for system-wide installation, by running make with one of the following targets:

  • systemwide_user.js: (the value will be used as default value for all Firefox Profiles where it is not explicitly set, it can be changed in about:config and is kept across browser sessions)
  • locked_user.js: (the value will be used as default value on Firefox profile creation, will be locked and can't be changed) in user.js or in Firefox's about:config or settings.
  • debian_locked.js: Debian specific. Users are not able to override preferences. See #415.

Copy the produced file to the Firefox installation directory. The file should be located at:

OS Path
Windows C:\Program Files (x86)\Mozilla Firefox\mozilla.cfg
Linux /etc/firefox/syspref.js, for older versions: /etc/firefox/firefox.js
Linux (Debian) /etc/firefox-esr/firefox-esr.js
Linux (Gentoo, Archlinux) /usr/lib/firefox/mozilla.cfg, might also be /usr/lib32/ or /usr/lib64/
OS X /Applications/Firefox.app/Contents/Resources/mozilla.cfg

Additional installation steps for Windows / OS X / Gentoo / Archlinux

Create local-settings.js in Firefox installation directory, with the following contents:

pref("general.config.obscure_value", 0);
pref("general.config.filename", "mozilla.cfg");

This file should be located at:

OS Path
Windows C:\Program Files (x86)\Mozilla Firefox\defaults\pref\
OS X /Applications/Firefox.app/Contents/Resources/defaults/pref
Linux (Gentoo, Archlinux) /usr/lib/firefox/defaults/pref/, might also be /usr/lib32/ or /usr/lib64/

If mozilla.cfg still fails to load, you must add a blank comment to the top of mozilla.cfg like so:

//

Updating using git

For any of the above methods, you can keep your browser's user.js with the latest version available here: Clone the repository, and create a symbolic link from the appropriate location to the user.js file in the repository. Just run git pull in the repository when you want to update, then restart Firefox:

cd ~/.mozilla/firefox
git clone 'https://github.com/pyllyukko/user.js.git'
cd XXXXXXXX.your_profile_name
ln -s ../user.js/user.js user.js

Verifying

Verify that the settings are effective from about:support (check the "Important Modified Preferences" and "user.js Preferences" sections).

What does it do?

There's a whole lot of settings that this modifies and they are divided in the following sections.

Some of the settings in this user.js file might seem redundant, as some of them are already set to the same values by default. We chose to explicitely set their values, which ensures these settings are enforced if a future Firefox update changes the default value.

HTML5 / APIs / DOM

HTML5 / APIs / DOM related settings. Mozilla is keen to implement every new HTML5 feature, which have had unforeseen security or privacy implications. This section disables many of those new and yet to be proven technologies.

  • Disable Service Workers [ 1 2 3 ]
  • Disable web notifications [ 1 ]
  • Disable DOM timing API [ 1 2 ]
  • Make sure the User Timing API does not provide a new high resolution timestamp [ 1 2 ]
  • Disable Web Audio API [ 1 ]
  • Disable Location-Aware Browsing (geolocation) [ 1 ]
  • When geolocation is enabled, use Mozilla geolocation service instead of Google [ 1 ]
  • When geolocation is enabled, don't log geolocation requests to the console
  • Disable raw TCP socket support (mozTCPSocket) [ 1 2 3 ]
  • Disable leaking network/browser connection information via Javascript
  • Disable network API (Firefox < 32) [ 1 2 ]
  • Disable WebRTC entirely to prevent leaking internal IP addresses (Firefox < 42)
  • Don't reveal your internal IP when WebRTC is enabled (Firefox >= 42) [ 1 2 ]
  • Disable WebRTC getUserMedia, screen sharing, audio capture, video capture [ 1 2 3 ]
  • Disable battery API (Firefox < 52) [ 1 2 ]
  • Disable telephony API [ 1 ]
  • Disable "beacon" asynchronous HTTP transfers (used for analytics) [ 1 ]
  • Disable speech recognition [ 1 2 3 ]
  • Disable speech synthesis [ 1 ]
  • Disable sensor API [ 1 ]
  • Disable pinging URIs specified in HTML ping= attributes [ 1 ]
  • When browser pings are enabled, only allow pinging the same host as the origin page [ 1 ]
  • Disable gamepad API to prevent USB device enumeration [ 1 2 ]
  • Disable virtual reality devices APIs [ 1 2 ]
  • Disable vibrator API
  • Disable resource timing API [ 1 ]
  • Disable Archive API (Firefox < 54) [ 1 2 ]
  • When webGL is enabled, use the minimum capability mode
  • When webGL is enabled, disable webGL extensions [ 1 ]
  • When webGL is enabled, force enabling it even when layer acceleration is not supported [ 1 ]
  • When webGL is enabled, do not expose information about the graphics driver [ 1 2 ]
  • Spoof dual-core CPU [ 1 2 ]
  • Disable WebAssembly [ 1 2 3 ]

Misc

Settings that do not belong to other sections or are user specific preferences.

  • Disable face detection
  • Disable GeoIP lookup on your address to set default search engine region [ 1 2 ]
  • Set Accept-Language HTTP header to en-US regardless of Firefox localization [ 1 ]
  • Don't use OS values to determine locale, force using Firefox locale setting [ 1 ]
  • Don't use Mozilla-provided location-specific search engines
  • Prevent leaking application locale/date format using JavaScript [ 1 2 ]
  • Don't trim HTTP off of URLs in the address bar. [ 1 ]
  • Don't try to guess domain names when entering an invalid domain name in URL bar [ 1 ]
  • When browser.fixup.alternate.enabled is enabled, strip password from 'user:password@...' URLs [ 1 ]
  • Send DNS request through SOCKS when SOCKS proxying is in use [ 1 ]
  • Don't monitor OS online/offline connection state [ 1 ]
  • Enforce Mixed Active Content Blocking [ 1 2 3 ]
  • Disable JAR from opening Unsafe File Types [ 1 ]
  • Set File URI Origin Policy [ 1 ]
  • Disable Displaying Javascript in History URLs [ 1 ]
  • Disable asm.js [ 1 2 3 4 ]
  • Disable SVG in OpenType fonts [ 1 2 ]
  • Disable video stats to reduce fingerprinting threat [ 1 2 3 ]
  • Don't reveal build ID
  • Enable only whitelisted URL protocol handlers [ 1 2 3 4 5 6 ]

Extensions / plugins

Harden preferences related to external plugins

  • Ensure you have a security delay when installing add-ons (milliseconds) [ 1 2 ]
  • Require signatures [ 1 ]
  • Opt-out of add-on metadata updates [ 1 ]
  • Opt-out of themes (Persona) updates [ 1 ]
  • Disable Flash Player NPAPI plugin [ 1 ]
  • Disable Java NPAPI plugin
  • Disable sending Flash Player crash reports
  • When Flash crash reports are enabled, don't send the visited URL in the crash report
  • When Flash is enabled, download and use Mozilla SWF URIs blocklist [ 1 2 ]
  • Disable Shumway (Mozilla Flash renderer) [ 1 ]
  • Disable Gnome Shell Integration NPAPI plugin
  • Enable plugins click-to-play [ 1 2 ]
  • Updates addons automatically [ 1 ]
  • Enable add-on and certificate blocklists (OneCRL) from Mozilla [ 1 2 3 4 5 ]
  • Decrease system information leakage to Mozilla blocklist update servers [ 1 ]
  • Disable system add-on updates (hidden & always-enabled add-ons from Mozilla) [ 1 2 3 4 ]

Firefox (anti-)features / components

Disable Firefox integrated metrics/reporting/experiments, disable potentially insecure/invasive/undesirable features

  • Disable WebIDE [ 1 2 ]
  • Disable remote debugging [ 1 2 ]
  • Disable Mozilla telemetry/experiments [ 1 2 3 4 5 6 7 8 9 ]
  • Disallow Necko to do A/B testing [ 1 ]
  • Disable sending Firefox crash reports to Mozilla servers [ 1 2 3 4 ]
  • Disable sending reports of tab crashes to Mozilla (about:tabcrashed), don't nag user about unsent crash reports [ 1 ]
  • Disable the UITour backend [ 1 ]
  • Enable Firefox Tracking Protection [ 1 2 3 4 5 ]
  • Enable contextual identity Containers feature (Firefox >= 52)
  • Enable hardening against various fingerprinting vectors (Tor Uplift project) [ 1 2 ]
  • Disable collection/sending of the health report (healthreport.sqlite*) [ 1 2 ]
  • Disable Heartbeat (Mozilla user rating telemetry) [ 1 2 ]
  • Disable Firefox Hello (Firefox < 49) [ 1 2 ]
  • Disable Firefox Hello metrics collection [ 1 ]
  • Enforce checking for Firefox updates [ 1 ]
  • Enable blocking reported web forgeries [ 1 2 3 4 ]
  • Enable blocking reported attack sites [ 1 ]
  • Disable querying Google Application Reputation database for downloaded binary files [ 1 2 ]
  • Disable Pocket [ 1 2 ]
  • Disable SHIELD [ 1 2 ]
  • Disable "Recommended by Pocket" in Firefox Quantum

Automatic connections

Prevents the browser from auto-connecting to some Mozilla services, and from predictively opening connections to websites during browsing.

  • Disable prefetching of URLs [ 1 2 ]
  • Disable DNS prefetching [ 1 2 ]
  • Disable the predictive service (Necko) [ 1 ]
  • Reject .onion hostnames before passing the to DNS [ 1 ]
  • Disable search suggestions in the search bar [ 1 ]
  • Disable SSDP [ 1 ]
  • Disable automatic downloading of OpenH264 codec [ 1 2 ]
  • Disable speculative pre-connections [ 1 2 ]
  • Disable downloading homepage snippets/messages from Mozilla [ 1 2 ]
  • Never check updates for search engines [ 1 ]
  • Disable automatic captive portal detection (Firefox >= 52.0) [ 1 ]

HTTP

HTTP protocol related entries. This affects cookies, the user agent, referer and others.

  • Disallow NTLMv1 [ 1 ]
  • Enable CSP 1.1 script-nonce directive support [ 1 ]
  • Enable Content Security Policy (CSP) [ 1 2 ]
  • Enable Subresource Integrity [ 1 2 ]
  • DNT HTTP header [ 1 2 3 4 ]
  • Send a referer header with the target URI as the source [ 1 2 ]
  • Don't send referer headers when following links across different domains [ 1 ]
  • Accept Only 1st Party Cookies [ 1 ]
  • Enable first-party isolation [ 1 2 3 ]
  • Make sure that third-party cookies (if enabled) never persist beyond the session. [ 1 2 3 ]
  • Spoof User-agent

Caching

Enable and configure private browsing mode, don't store information locally during the browsing session

  • Do not download URLs for the offline cache [ 1 ]
  • Set time range to "Everything" as default in "Clear Recent History"
  • Clear everything but "Site Preferences" in "Clear Recent History"
  • Disable disk cache [ 1 ]
  • Disable Caching of SSL Pages
  • Disable download history
  • Disable form autofill, don't save information entered in web page forms and the Search Bar
  • The cookie's lifetime is supplied by the server
  • Require manual intervention to autofill known username/passwords sign-in forms [ 1 2 ]
  • Disable formless login capture [ 1 ]
  • When username/password autofill is enabled, still disable it on non-HTTPS sites [ 1 ]
  • Show in-content login form warning UI for insecure login fields [ 1 ]
  • Delete Search and Form History
  • Clear SSL Form Session Data [ 1 ]
  • Delete temporary files on exit [ 1 ]
  • Do not create screenshots of visited pages (relates to the "new tab page" feature) [ 1 2 ]
  • Don't fetch and permanently store favicons for Windows .URL shortcuts created by drag and drop
  • Disable bookmarks backups (default: 15) [ 1 ]

UI related

Improve visibility of security-related elements, mitigate shoulder-surfing

  • Enable insecure password warnings (login forms in non-HTTPS pages) [ 1 2 3 ]
  • Disable "Are you sure you want to leave this page?" popups on page close [ 1 ]
  • Disable Downloading on Desktop
  • Always ask the user where to download [ 1 ]
  • Disable the "new tab page" feature and show a blank tab instead [ 1 2 ]
  • Disable Activity Stream [ 1 ]
  • Disable new tab tile ads & preload [ 1 2 3 4 5 ]
  • Enable Auto Notification of Outdated Plugins (Firefox < 50) [ 1 ]
  • Force Punycode for Internationalized Domain Names [ 1 2 3 4 5 ]
  • Disable inline autocomplete in URL bar [ 1 ]
  • Disable CSS :visited selectors [ 1 2 ]
  • Do not check if Firefox is the default browser
  • When password manager is enabled, lock the password storage periodically
  • Lock the password storage every 1 minutes (default: 30)
  • Display a notification bar when websites offer data for offline use [ 1 ]

Cryptography

TLS protocol related settings

  • Enable HSTS preload list (pre-set HSTS sites list provided by Mozilla) [ 1 2 3 ]
  • Enable Online Certificate Status Protocol [ 1 2 3 4 5 6 7 8 ]
  • Enable OCSP Stapling support [ 1 2 3 ]
  • Enable OCSP Must-Staple support (Firefox >= 45) [ 1 2 3 ]
  • Require a valid OCSP response for OCSP enabled certificates [ 1 ]
  • Disable TLS Session Tickets [ 1 2 3 4 5 ]
  • Only allow TLS 1.[0-3] [ 1 ]
  • Disable insecure TLS version fallback [ 1 2 ]
  • Enfore Public Key Pinning [ 1 2 ]
  • Disallow SHA-1 [ 1 2 ]
  • Warn the user when server doesn't support RFC 5746 ("safe" renegotiation) [ 1 2 ]
  • Disable automatic reporting of TLS connection errors [ 1 ]
  • Pre-populate the current URL but do not pre-fetch the certificate in the "Add Security Exception" dialog [ 1 2 ]

Cipher suites

This section tweaks the cipher suites used by Firefox. The idea is to support only the strongest ones with emphasis on forward secrecy, but without compromising compatibility with all those sites on the internet. As new crypto related flaws are discovered quite often, the cipher suites can be tweaked to mitigate these newly discovered threats.

  • Disable null ciphers
  • Disable SEED cipher [ 1 ]
  • Disable 40/56/128-bit ciphers
  • Disable RC4 [ 1 2 3 4 ]
  • Disable 3DES (effective key size is < 128) [ 1 2 3 ]
  • Disable ciphers with ECDH (non-ephemeral)
  • Disable 256 bits ciphers without PFS
  • Enable ciphers with ECDHE and key size > 128bits
  • Enable GCM ciphers (TLSv1.2 only) [ 1 ]
  • Enable ChaCha20 and Poly1305 (Firefox >= 47) [ 1 2 3 4 5 ]
  • Disable ciphers susceptible to the logjam attack [ 1 ]
  • Disable ciphers with DSA (max 1024 bits)
  • Fallbacks due compatibility reasons

Further hardening

This is not enough! Here's some other tips how you can further harden Firefox:

  • By default your browser trusts 100's of Certificate Authorities (CAs) from various organizations to guarantee privacy of your encrypted communications with websites. Some CAs have been known for misusing or deliberately abusing this power in the past, and a single malicious CA can compromise all your encrypted communications! Follow this document to only trust a selected, trimmed-down list of CAs.
  • Keep your browser updated! If you check Firefox's security advisories, you'll see that pretty much every new version of Firefox contains some security updates. If you don't keep your browser updated, you've already lost the game.
  • Disable/uninstall all unnecessary extensions and plugins!
  • Use long and unique passwords/passphrases for each website/service.
  • Prefer open-source, reviewed and audited software and operating systems whenever possible.
  • Do not transmit information meant to be private over unencrypted communication channels.
  • Use a search engine that doesn't track its users, and set it as default search engine.
  • If a plugin is absolutely required, check for plugin updates
  • Create different profiles for different purposes
  • Change the Firefox's built-in tracking protection to use the strict list
  • Change the timezone for Firefox by using the TZ environment variable (see here) to reduce it's value in browser fingerprinting
  • If you are concerned about more advanced threats, use specialized hardened operating systems and browsers such as Tails or Tor Brower Bundle

Add-ons

Here is a list of the most essential security and privacy enhancing add-ons that you should consider using:

Additional add-ons that you might consider using or reading about:

Known problems and limitations

Hardening your often implies a trade-off with ease-of-use and comes with reduced functionality. Here is a list of known problems/limitations:

  • Disabling ServiceWorkers breaks functionality on some sites (Google Street View...)
  • Disabling WebRTC breaks peer-to-peer file sharing tools (reep.io ...)
  • Disabling clipboard events breaks Ctrl+C/X/V copy/cut/paste functionaility in JS-based web applications (Google Docs...)
  • Disabling clipboard operations will break legitimate JS-based "copy to clipboard" functionality
  • Enabling Mixed Display Content blocking can prevent images/styles... from loading properly when connection to the website is only partially secured
  • Disabling nonessential protocols breaks all interaction with custom protocols such as mailto:, irc:, magnet: ... and breaks opening third-party mail/messaging/torrent/... clients when clicking on links with these protocols
  • Disabling system add-on updates prevents Mozilla from "hotfixing" your browser to patch critical problems (one possible use case from the documentation)
  • Containers are not available in Private Browsing mode
  • Firefox Hello requires setting media.peerconnection.enabled and media.getusermedia.screensharing.enabled to true, security.OCSP.require to false to work.
  • Fully automatic updates are disabled and left to package management systems on Linux. Windows users may want to change this setting.
  • Update check page might incorrectly report Firefox ESR as out-of-date
  • Do No Track must be enabled manually
  • Spoofing referers breaks functionality on websites relying on authentic referer headers
  • Spoofing referers breaks visualisation of 3rd-party sites on the Lightbeam addon
  • Spoofing referers disables CSRF protection on some login pages not implementing origin-header/cookie+token based CSRF protection
  • Blocking 3rd-party cookies breaks a number of payment gateways
  • First-party isolation breaks Microsoft Teams
  • First-party isolation causes HTTP basic auth to ask for credentials for every new tab (see #425)
  • You can not view or inspect cookies when in private browsing: https://bugzilla.mozilla.org/show_bug.cgi?id=823941
  • When Javascript is enabled, Websites can detect use of Private Browsing mode
  • Private browsing breaks Kerberos authentication
  • Disables "Containers" functionality (see below)
  • "Always use private browsing mode" (browser.privatebrowsing.autostart) disables the possibility to use password manager: https://support.mozilla.org/en-US/kb/usernames-and-passwords-are-not-saved#w_private-browsing
  • Installing user.js will remove your browsing history, caches and local storage.
  • Installing user.js will remove your saved passwords (pyllyukko#27)
  • Clearing open windows on Firefox exit causes 2 windows to open when Firefox starts https://bugzilla.mozilla.org/show_bug.cgi?id=1334945
  • Make sure to set a Master password to protect Firefox's password storage against basic malware that could extract your password information
  • .URL shortcut files will be created with a generic icon
  • OCSP leaks your IP and domains you visit to the CA when OCSP Stapling is not available on visited host
  • OCSP is vulnerable to replay attacks when nonce is not configured on the OCSP responder
  • OCSP adds latency (performance)
  • Short-lived certificates are not checked for revocation (security.pki.cert_short_lifetime_in_days, default:10)
  • Firefox falls back on plain OCSP when must-staple is not configured on the host certificate
  • security.OCSP.require will make the connection fail when the OCSP responder is unavailable
  • security.OCSP.require is known to break browsing on some captive portals

In addition see the current issues. You can use the web console to investigate what causes websites to break.

FAQ

Does this user.js file fix all security problems?

No. Please read Known problems and limitations, the project's issue tracker, and report new issues there. Please open separate issues for each individual problem/question you may have.

Why are obsolete/deprecated entries included in the user.js file?

This project is aimed at Firefox versions between the current ESR and the latest Firefox release. We will wait for widespread deployment of the current ESR (eg. adoption in major Linux distributions) before removing deprecated/obsolete preferences. Presence of deprecated entries causes no known problems.

Installing the user.js file breaks xyz plugin/addon/extension, how can I fix it?

See pyllyukko#100

Will there be an official addon/an android version/feature xyz?

Search the project issues.

How can I lock my preferences to prevent Firefox overwriting them?

See lockPref in System-wide installation.

Contributing

Yes please! All issues and pull requests are more than welcome. Please try to break down your pull requests or commits into small / manageable entities, so they are easier to process. All the settings in the user.js file should have some official references to them, so the effect of those settings can be easily verified from Mozilla's documentation.

Feel free to follow the latest commits RSS feed and other interesting feeds from the References section.

You may also reach other contributors through IRC (#user.js on Freenode) or Gitter.

For more information, see CONTRIBUTING

Online tests

Version checks

Fingerprinting tests

SSL tests

Other tests

References

Mozilla documentation

Other documentation

TLS/SSL documentation

About

user.js -- Firefox configuration hardening

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

3 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 68.7%
  • Shell 24.3%
  • Makefile 7.0%