TLDR – watch this short video:
In August 2015, Mozilla was notified by security researcher Cody Crews that a malicious advertisement on a Russian news site was exploiting a vulnerability in Firefox’s PDF Viewer. The exploit payload searched for sensitive files on users’ local filesystem, and reportedly uploaded them to the attacker’s server. The default Firejail configuration blocked access to
.filezilla in all directories present under
/home. More advanced sandbox configurations blocked everything else.
This document describes some of the most common Firefox sandbox setups. We start with the default setup, recommended for entertainment and casual browsing.
The easiest way to start a sandbox is to prefix the command with “firejail”:
If the sandbox was already integrated with your desktop manager by running
"sudo firecfg" as described on our Download page, just start your browser as you used to using your desktop manager menus.
Note: by default, a single Firefox process instance handles multiple browser windows. If you already have Firefox running, you would need to use
-no-remote command line option, otherwise you end up with a new tab or a new window attached to the existing Firefox process:
You can also configure a starter for your desktop. This is a simple text file in your
~/Desktop directory with the following content:
In the example above I show a desktop starter for a browser installed from Mozilla’s download page in
The filesystem container is created when the sandbox is started and destroyed when the sandbox is closed. It is based on the current filesystem installed on users computers. We strongly recommend updating the operating system on a regular basis. The sandbox allows Firefox to access only a small set of files and directories. All private user information has been removed from the home directory.
~/.mozilla directories are real, all other directories are created by Firefox. The same home directory layout is imposed by Firejail for all supported browsers and BitTorrent clients. Please make sure you save all your downloaded files in ~/Downloads directory.
This is how the rest of the filesystem looks like:
- /boot – blacklisted
- /bin – read-only
- /dev – read-only; a small subset of drivers is present, everything else has been removed
- /etc – read-only; /etc/passwd and /etc/group have been modified to reference only the current user; you can enable a subset of the files by editing /etc/firejail/firefox-common.profile (uncomment private-etc line in that file)
- /home – only the current user is visible
- /lib, /lib32, /lib64 – read-only
- /proc, /sys – re-mounted to reflect the new PID namespace; only processes started by the browser are visible
- /sbin – blacklisted
- /selinux – blacklisted
- /usr – read-only; /usr/sbin blacklisted
- /var – read-only; similar to the home directory, only a skeleton filesystem is available
- /tmp – only X11 directories are present
Password files, encryption keys and development tools are removed from the sandbox. If Firefox tries to access a blacklisted file, log messages are sent to syslog. Example:
The following security filters are enabled by default. The purpose of these filters is to reduce the attack surface of the kernel, and to protect the filesystem container:
- seccomp-bpf – we use a large blacklist seccomp filter. It is a dual 32-bit/64-bit filter.
- protocol – this seccomp-based filter checks the first argument of socket system call. It allows IPv4, IPv6, UNIX and netlink.
- noroot user namespace – it installs a namespace with only the current user.
- capabilities – the sandbox disables all Linux capabilities, restricting what a root user can do in the sandbox.
- AppArmor – starting with Firejail version 0.9.53, if AppArmor is active on the system and /etc/apparmor.d/firejail-default is enabled, the profile will be activated by default for about 140 applications, including browsers, BitTorrent clients and media players.
seccomp configuration enforces the rules by killing the browser process. Log messages are sent to syslog. Example:
For most users, the default “firejail firefox” setup is enough. The following are some special cases:
Private browser setup
Use this setup to access your bank account, or any other site dealing with highly sensitive private information. The idea is you trust the site, but you don’t trust the addons and plugins installed in your browser. Use
--private Firejail option to start with a factory default browser configuration, and an empty home directory.
Also, you would need to take care of your DNS setting – current home routers are ridiculously insecure, and the easiest attack is to reconfigure DNS, and redirect the traffic to a fake bank website. Use
--dns Firejail option to specify a DNS configuration for your sandbox:
In this setup we use /home/username/work directory for work, email and related Internet browsing. This is how we start all up:
Both Mozilla Thunderbird and Firefox think ~/work is the user home directory. The configuration is preserved when the sandbox is closed.
Assuming eth0 is the main Ethernet interface, we create a new TCP/IP stack, we connect it to the wired Ethernet network, and we start the browser:
To assign an IP address, Firejail ARP-scans the network and picks up a random address not already in use. Of course, we can be as explicit as we need to be:
Note: Ubuntu runs a local DNS server in the host network namespace. The server is not visible inside the sandbox. Use
--dns option to configure an external DNS server:
By default, if a network namespace is requested, Firejail installs a network filter customized for regular Internet browsing. It is a regular iptable filter. This is a setup example, where no access to the local network is allowed:
On top of that, you can even add a hosts file implementing an adblocker:
Firejail replaces the regular X11 server with Xpra or Xephyr servers (apt-get install xpra xserver-xephyr on Debian/Ubuntu), preventing X11 keyboard loggers and screenshot utilities from accessing the main X11 server.
The command is as follows:
A network namespace initialized with
--net is necessary in order to disable the abstract X11 socket. If for any reasons you cannot use a network namespace, the socket will still be visible inside the sandbox, and hackers can attach keylogger and screenshot programs to this socket.
- Firejail Tips and Tricks – all about Tor browser: setup, removing personally identifiable information, using Tor as a DNS proxy
- Firejail BitTorrent Sandboxing Guide – how to use a DNS over HTTPS proxy to stop DNS-based attacks for a browser/BitTorrent client setup
- A Survey of Public DNS over HTTPS Servers – how to choose a DoH service