Firefox Sandboxing Guide





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 .ssh, .gnupg and .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.


Starting Firefox

The easiest way to start a sandbox is to prefix the command with “firejail”:

$ firejail firefox

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:

$ firejail firefox -no-remote


Sandbox description

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.

Whitelisting home files and directories for Firefox browser.

Whitelisting home files and directories for Firefox browser.

Note: Only ~/Downloads and ~/.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:

Dec 3 11:43:25 debian firejail[70]: blacklist violation - sandbox 26370, exe firefox, syscall open64, path /etc/shadow
Dec 3 11:46:17 debian firejail[70]: blacklist violation - sandbox 26370, exe firefox, syscall opendir, path /boot

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:

Dec 8 09:48:21 debian kernel: [ 4315.656379] audit: type=1326 audit(1449586101.336:8): auid=1000 uid=1000 gid=1000 ses=1 pid=22006 comm="chmod" exe="/bin/chmod" sig=31 arch=c000003e syscall=268 compat=0 ip=0x7f027999f6b9 code=0x0
Dec 8 12:53:57 debian kernel: [17261.662738] audit: type=1326 audit(1450461237.367:2): auid=1000 uid=1000 gid=1000 ses=1 pid=4750 comm="strace" exe="/usr/bin/strace" sig=31 arch=c000003e syscall=101 compat=0 ip=0x7ff42f8cdc6c code=0x0

For most users, the default “firejail firefox” setup is enough. The following are some special cases:

High security 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:

$ firejail --private --dns= --dns= firefox -no-remote


Work setup

In this setup we use /home/username/work directory for work, email and related Internet browsing. This is how we start all up:

$ firejail --private=/home/username/work thunderbird &
$ firejail --private=/home/username/work firefox -no-remote &

Both Mozilla Thunderbird and Firefox think ~/work is the user home directory. The configuration is preserved when the sandbox is closed.


Network setup

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:

$ firejail --net=eth0 firefox

Network namespace configured in a Firejail sandbox

Network namespace configured in a Firejail sandbox

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:

$ firejail --net=eth0 --ip= firefox

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:

$ firejail --net=eth0 --dns= firefox

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:

$ firejail --net=eth0 --netfilter=/etc/firejail/ firefox

On top of that, you can even add a hosts file implementing an adblocker:

$ firejail --net=eth0 --netfilter=/etc/firejail/ \
--hosts-file=~/adblock firefox


X11 sandbox

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 commands is as follows:

$ firejail --x11 --net=eth0 firefox

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.

126 thoughts on “Firefox Sandboxing Guide

  1. hopelesshoper

    I am using ArchLinux.

    The problem is that I’ve learned how to make firejail to work as default for all applications for which it has profiles. “sudo firecfg”

    How to make it run only for firefox and chrome by default? I mostly open programs by rofi, so can’t really edit desktop files to help with this.


  2. me-anon

    I use this currently:
    firejail –name=firefox –private-home=.mozilla –noexec=/tmp –nogroups –nonewprivs –dns= –dns= firefox -no-remote -private-window -P profile-2
    I can’t access /home/user/Downloads/new_folder with my current usage.
    I would like to download files to work on, then place back in folder for browser to access. I need one folder real system can see. I also need the ability to choose a specific firefox profile, sometimes evil people insert bad .js files there, changing profiles can clear up some of these issues. Second my addons can persist when running with a specific profile.

    I like the fact that everything gets destroyed with –private but is there another way to preserve the .mozilla profiles so I can firefox -P profile-3 and have a work directory available?


  3. me-anon

    I am using this command for firejail:
    firejail –name=firefox –private-home=.mozilla –noexec=/tmp –nogroups –nonewprivs –dns= –dns= firefox -no-remote -private-window -P profile-3

    I like this because I can change my profile, addons work, nothing survives reboot of firejail.
    I would like to have one working directory: /home/user/Downloads/new_folder
    Can’t use two instance of –private, is there another solution to allow .mozilla for firefox profiles to function as above and have a working directory?



    I use firefox on debian,not the version in the repository, wich is old, but the latest download available in mozilla. It’s a tar.bz2, extracted and placed in the folder Download. Is there a way to run it with firejail.


  5. user


    i am runing firejail version
    and firefox 70.0.1 (64-bit) on ubuntu 19.04 gnome

    i have issue with –net –ip –dns when i running
    firejail –net=ens160 –ip=x.x.x.x –dns=x.x.x.x –private=/path/to/some/userowned/dir firefox everything is up and running, i can see –ip=x.x.xx in router with some random mac but there is NO internet access…
    if i am running firejail –net=ens160 –ip=x.x.x.x –dns=x.x.x.x firefox
    it works and i have internet access

    so –private make me problems here

    any help ?

    thanks !


  6. Sergey Shelukhin

    Is there documentation for setting up iptables rules for the network namespace firejail creates?


    1. netblue30 Post author

      The files have the regular syntax used by iptables. Actually I use /sbin/iptables-restore from firejail to push them into the kernel. I have some examples in /etc/firejail/*.net


  7. John

    If i run 2 sessions of firefox both using the same firefox profile… “firejail firefox” and “firefox normal” would this offer adequtae protection between each firefox session, say keep malicious scripts isolated or will this be irrelevant since they both use the same firefox profile? Pardon me i’m a noob.


  8. Haflü

    Just trying to understand the default “Firefox.profile”:
    Quote: “Note: Only ~/Downloads and ~/.mozilla directories are real, all other directories are created by Firefox.”

    -> So, do you mean, that the other directories are created temporary by firefox? If yes, where can I find the temporary file system? I have started firefox with “Firefox.profile”. And in address line of firefox I typed in “file:///home/VM-Konto/”. The result is the following list:

    I had a look into /home/user/.config/ but there is not a folder like “firejail”. And there also not are files there, like

    I also had a look into /tmp/ but there also I found not files like:

    Also when you write: “Note: Only ~/Downloads and ~/.mozilla directories are real, all other directories are created by Firefox.”
    My expectation would be, that the date of all the following files:

    … are from today, because I started today the first time firefox with firejail. But I found, that
    … are not from today. They are older.

    I just can understand this. Can you help me. Thank you.


  9. Tobias

    This is a question to the default profile “firefox.profile”.

    I do not understand the commands
    include firefox.local
    include globals.local

    As the command is similar to the command “include firefox-common.profile” in “firefox.profile”, I thought, maybe this is just another sub-profile like “firefox-common.profile”. But I did not find “firefox.local” in the folder “/etc/firejail/”.

    I have searched after a file or folder with the names firefox.local and globals.local on my whole system. But there is no such folder. What is the function of “include firefox.local”. In which case this is needed? What does it?

    Thabnk you.


  10. Tobias

    From “man firejail”:
    Quote: “Without any options, the sandbox consists of a filesystem build in a new mount namespace, … . The default Firejail filesystem is based on the host filesystem with the main system directories mounted read-only. These directories are /etc, /var, /usr, /bin, /sbin, /lib, /lib32, /libx32 and /lib64.”

    1. I do not understand the word “mount” and also I do not understand the phrase “a new mount namespace”. Does this simply mean, that it makes new folders and new files anywhere on my HD? Or only in RAM?

    2. Question: I understand, that it is building a new filesystem. How does it build this filesystem? Does it copy the directories ” /etc, /var, /usr, /bin, /sbin, /lib, /lib32, /libx32 and /lib64″ from my working system?
    Or: Does it make it’s own specific files that are different from the original files from the working system? Or is it a mixture? Some files are copied exactly from the working system, others are created new and are different from the working system.

    3. Question: I understand, that it is building a new filesystem. Where can I see this filesystem? In which folder is it? Or is it only in the RAM?

    4. Quote: “with the main system directories mounted read-only.”
    Why is this new filesystem only readable. Since it is only a copy anyway, it can easily be made writable. (?)

    Thank you.


    1. netblue30 Post author

      1. “mount namespace” is a Linux kernel feature we use to isolate the application. A description of all namespaces is here:

      2. Does it copy the directories? No, it does some magic in the mount table for the process. Each process in the box has a different view of the filesystem. Some view the filesystem as read-only, other processes see them as read-write.

      3. The easiest way to take a look is under firefox. Type /home in the URL bar and you can go from there.

      4. Is not a copy, these are the real files.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s