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. Firejail successfully stopped this attack.


This document describes some of the most common Firefox sandbox setups. We start with the default setup, recommended for entertainment and casual browsing.


Default Setup

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

$ firejail firefox --no-remote

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:

If the sandbox was already integrated with your desktop manager by running "sudo firecfg" as described on our Download page, just click the browser icon in your desktop manager menus.

You can also configure a starter for your desktop. This is a simple text file in your ~/Desktop directory with the following content:

$ cat ~/Desktop/firefox.desktop
[Desktop Entry]
Exec=/usr/bin/firejail /opt/firefox/firefox -no-remote

In the example above I show a desktop starter for a browser installed from Mozilla’s download page in /opt directory. When you click the icon, the browser opens automatically in a sandbox.


Sandbox description

The three main attacks we target are ransomware, privilege escalations, and local network attacks. This is a short description of the technologies we use to prevent them.

For privacy purposes we deploy a very restrictive Mandatory Access Control system. The sandbox allows Firefox to access only a small set of system files and directories. All private user information was removed from home directory. Please remember to save your downloaded files in Downloads, everything else will evaporate when you close the browser.

Whitelisting home files and directories for Firefox browser.
User home directory in Firefox browser.

Note: The same home directory layout is imposed by Firejail for all networked applications and games. For email we bring in email folders, for media players we add Videos, Music etc. Usually, Documents directory is highly restricted, only few applications have access to it.

Password files, encryption keys and development tools were also removed from the sandbox. If Firefox tries to access such a 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

Privilege escalations are handled mainly by seccomp-bpf and nonewprivs. These are two Linux kernel technologies specifically designed for this purpose. A number of other kernel technologies are layered on top of them, such as capability sets, a user namespace without the root user, and mounting partitions and directories using nosuid flag. If available, we also start AppArmor on top of everything. With all these kernel layers upon layers in place, it is hard to tell in a real scenario which layer triggered first and stopped the exploit.

The local network attacks are mostly happening in enterprise settings. After failing a regular ransomware since only Downloads directory is present, and after failing to rise privileges and become root, the attacker will most likely try to exploit servers running on the local network. The way to deal with this situations is described in Network/Incognito setup below.

The video from the beginning of the article describes a full hacking session from the perspective of an attacker, and how the Mandatory Access Control, seccomp-bpf, and a combination of network namespace and netfilter firewall can be used to prevent further escalation.


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:

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

Work setup

Use this setup for remote office work, or when you have a number of programs employed for a specific purpose. Start by creating a new directory, let’s say /home/username/work, and segregate your applications in this directory. Pass this directory to --private when you start your apps:

$ 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. The configuration is preserved when the sandbox is closed.


Network/Incognito setup

Assuming eth0 is the main Ethernet interface, we create a new TCP/IP stack, and we connect it to the wired Ethernet interface. Then, we automatically ARP-scan the network and pick up a random, unused IP address:

$ firejail --net=eth0 firefox
Network namespace configured in a Firejail sandbox
Network namespace configured in a Firejail sandbox

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, you can customize it, or you can bring in your own.

$ firejail --net=eth0 --netfilter=/etc/firejail/ firefox filter above allows only traffic from outside, all local traffic is dropped.

On top of that, you can 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 command 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.


Tor Browser

Tor Browser is the ultimate tool for protecting privacy while browsing online. All the traffic that passes through Tor network is encrypted, and it is virtually impossible to track the IP address back to its user.

These are our recommended steps to set up the browser in Firejail sandbox. The setup should work on all Linux distributions.


1. Download Tor Browser from

2. Assuming the archive was downloaded in ~/Downloads directory, extract the files:

$ cd ~
$ tar -xvf Downloads/tor-browser-linux64-X.Y.Z.tar.xz

3. Find the name of your Ethernet interface:

$ ip addr show

4. Create a desktop starter in ~/Desktop directory:

$ cat ~/Desktop/tor.desktop
[Desktop Entry]
Exec=firejail --name=tor --private=~/tor-browser_en-US --net=INTERFACE ./start-tor-browser.desktop


Replace USERNAME with your user name, and INTERFACE with the name of your Ethernet interface you found on step 3.

5. Start the browser by clicking the tor icon on your desktop. This is the default setup, also available for older Firejail versions.

6. Optionally, lock down your network by adding --netlock on your exec line in the starter.



This is the simplest VPN setup ever: Linux workstation running Firefox browser under Firejail, and a virtual machine in the cloud running an SSH server. The tunnel uses SOCKS5 feature of OpenSSH. This setup should work with any other application supporting SOCKS5 protocol.

OpenSSH protects the traffic with strong, industry standard encryption algorithms such as Advanced Encryption Standard (AES). Due to the large number of enterprise users using SSH in the cloud, you are very likely to go through a VPN blockade undetected. Fly under the radar and have fun!





136 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.


  11. Bob Goodwin

    I just installed Firejail from the Linux Mint (ubuntu) repo. Firefox will not read any of my local html files. I assume this is part of the isolation but I do need to be able to read those files from time to time. What do I do to access those files from Firefox?
    I have to say, I’m impressed. This certainly proves that the ‘jail’ is working.
    Best regards,
    Bob G.


  12. GooBubble

    Under Lubuntu18.04
    First install of tor-web-browser with synaptic and ubuntu repository
    1 tor work from desktop menu icone : tor-browser-launcher and tor-browser-setting (after some issue and configuration in apparmor)
    2 tor work from command line
    3 firejail tor-browser-setting work from command line
    4 firejail torbrowser-launcher dont work : all seem ok in the cli and tor windows is create with only the 3 first header “tor browser and – + x” and “private tab and +” and menuheader ” levelsecurity icone | newidentity button | menu burger “(button and menu work) but no webpage or Error display inside the window… just nothing
    –>after hours of try finally sudo apt-get –purge remove tor
    Second install of tor from
    1 tor work from cli (in the directory of uncompressed file) with ./Browser/start-tor-browser.desktop
    2 firejail ./Browser/start-tor-browser.desktop from the same directory dont work and give the same issue describe in point 4 : all seem ok but just nothing into the window
    3 firejail sh -c ‘”/home/acer/.local/share/tor-browser/Browser/start-tor-browser” –detach || ([ ! -x “/home/acer/.local/share/tor-browser/Browser/start-tor-browser” ] && “$(dirname “$*”)”/Browser/start-tor-browser –detach)’ dummy %k dont work and give the same issue describe in point 4 : all seem ok but just nothing into the window

    in dmesg no error but :
    audit: type=1326 audit(1610235269.317:33): auid=4294967295 uid=1000 gid=1000 ses=4294967295 pid=9196 comm=4368726F6F742048656C706572 exe=”/home/acer/.local/share/tor-browser/Browser/firefox.real” sig=31 arch=c000003e syscall=161 compat=0 ip=0x7f70161a8fb7 code=0x0

    I ve read man firejail
    i dont manage to understand which other firejail setting i ve to configure to make torbrowser running inside firejail himself inside apparmor (if ive understand fine)
    firejail firefox or firejail other application work …


  13. Randy

    I am trying to setup my Firefox using the below. But, for some reason the “–private-home=.mozilla” is giving me problems. Whenever I include this in the command, when Firefox opens my profile settings will pop in for about 1 second, then revert to a standard profile. I know this because my theme will be reset and my Addons will disappear. If I omit that argument it will run fine but just not achieve the purpose of that argument.

    I’m running the latest firejail, firefox 84.0.2, on Linux Mint 20.1.

    firejail –name=firefox –private-home=.mozilla –noexec=/tmp –nogroups –nonewprivs –apparmor firefox -no-remote -private-window -P profilename

    Thanks for your help!


    1. netblue30 Post author

      You are doing it wrong. Start like this

      $ firejail firefox -no-remote -private-window -P profilename

      The sandbox configures noexec, nogroups nonewprivs and apparmor by default. After your browser comes up, in the URL bar type “/home/username” and press enter (replace username with the name of your user account). You should only see ~/Downloads, ~/.mozilla and other dot files such as ~/.config

      Liked by 1 person

      1. Randy


        First, thanks for the reply. So I’m trying to setup a pretty restrictive session that basically gets setup in a temp directory and then blown away when I close the session. I want to be able to use sites such as Google sites in a session that they can’t track other activity and when i close the session the info basically goes into the intergalactic bitbucket with a clean session each time. Here’s the video where I got the idea.

        Now mind you, I’m new to firejail and apparmor, so I may be misunderstanding how they work together. I appreciate your assistance.



  14. Pingback: Possible to configure (Squid) proxy so a browser can bypass a VPN? - Boot Panic

  15. whfire

    There is one annoyance I have encountered on KDE systems. It seems Firejail don’t respect the native file-picker. It works with Firefox “widget.use-xdg-desktop-portal.file-picker” config value set to 2, but it wont open the dialog when the value is set to 1, which opens the native file dialog.
    Since it will work as expected when Firejail is not active, my conclusion is that it is not compatibile with “xdg-desktop-portal-kde” package.


  16. HDRuser

    Hi thanks for all you hard work over the years. I don’t know if this is the right place to request this but I wonder if anyone has had luck with viewing HDR video properly through firejailed apps. I use freetube as well as browsers firejailed and HDR content always seems to revert to SDR. Outside the sandbox HDR works fine. Is there some access setting in Firejail that enables this functionality?



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 )

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