Linux Sandboxed Tor Browser Documentation
'''WARNING: This project is no longer maintained. DO NOT EXPECT ANY FURTHER FIXES, INCLUDING SECURITY AND STOP USING THIS AS SOON AS POSSIBLE.'''
'''WARNING: There are several unresolved issues that affect security and fingerprinting. Do not assume that this is perfect, merely "an improvement over nothing".'''
'''WARNING: Active development is on indefinite hiatus. DO NOT EXPECT ANY SIGNIFICANT NEW FEATURES OR IMPROVEMENTS'''.
The current efforts towards sandboxing Tor Browser on Linux are centered
sandboxed-tor-browser and bubblewrap.
Note: This documentation refers to the
master git branch, which may be ahead of tagged revisions.
- A C compiler with development libraries for Gtk+3, libnotify, and X11.
- gb (https://getgb.io/)
- Go (Tested with 1.7.x)
- A modern Linux system on the x86_64 architecture.
- bubblewrap >= 0.1.3 (https://github.com/projectatomic/bubblewrap).
- Gtk+ >= 3.14.0
- (Optional) PulseAudio
- (Optional) The Adwaita Gtk+-2.0 theme (Install
- (Optional) libnotify
It is the aim to provide as much of the standard Tor Browser functionality as possible, while improving security. However, some things are broken by the sandbox, either intentionally, inadvertently, or optionally.
Inadvertent broken things that will be fixed:
- Foreign language input that requires system services like I-Bus (#20774)
- The meek pluggable transport (#20781)
Check for Tor Browser Update...(#21091 #21090)
Broken things that are unlikely to ever be supported:
- The FTE pluggable transport
- Hardware accelerated 3D rendering (Requires a dangerous amount of hardware access, software rendering is allowed)
- Printing, except to a file (No network interface in the container)
- Using Tor Browser to connect to something that isn't the Tor Network.
Using the (now deprecated) "hardened" series with a grsec kernel (ASAN/PaX conflict, not limited to the sandbox).
- Installing/Updating addons (The extensions bundled with Tor Browser are explicitly and individually exposed to the container as read-only files).
Functionality that must be explicitly allowed via configuration:
- Audio support
- The circuit display
New features will be judged on a case by case basis.
Where do I get bubblewrap for my distribution?
How do I check the hash/signature of the bundle archive?
sandboxed-tor-browser does that for you, with a hardcoded copy of
the Tor Browser Developer's PGP key as part of the install process.
Where are all my files?
The Tor Browser process does not see all of your files, to prevent an attacker that has compromised your browser from reading them all.
Improving the UI/UX surrounding this is a task for future versions.
Where do my downloads go?
This can be overridden (along with the
Desktop directory) via the sandbox
config when advanced options are enabled.
How do I reinstall the browser?
This will permanently delete your previous browser installation.
How do I reconfigure the tor or the sandbox?
Certain "advanced" options require:
sandboxed-tor-browser --advanced config
How do I get sound to work?
WARNING: This is likely unsafe against sophisticated adversaries.
As it stands right now, if PulseAudio is enabled in the sandbox, Firefox will get direct access to the host system's socket. There are likely non-trivial ways to use this to read files from the host filesystem.
(Thanks to "Jann Horn of Google Project Zero" for pointing out that this is a possibility.)
If you don't care about this possibility, assuming your system is
running PulseAudio (
pulseaudio --check -v), enable it via the sandbox
config. PulseAudio is required due to the sandbox container not having
direct access to hardware, and there being basically nothing better
despite the potential escape vectors.
For what it's worth, un-sandboxed Tor Browser also requires PulseAudio as of version 7.0, due to it being made a requirement for Firefox (See: https://bugzilla.mozilla.org/show_bug.cgi?id=1247056)
The Circuit Display is missing!
Unless it is explicitly enabled via the sandbox config, the Circuit Display is disabled, as that requires exposing more information to the firefox process than would otherwise be needed.
It should be disabled unless you are comfortable with the idea that firefox knows the IP address of your Guard or Bridges.
"Check for Tor Browser Update..." is missing!
Making it work again is a task for a future version. As of version 0.0.3-dev, updates are checked every 2 hours in the background and a notification is sent if your system supports it prompting you to restart the update.
Are the fonts supposed to look different from normal?
To reduce fingerprinting, only the fonts that are bundled with Tor Browser are used to display content and the UI.
Installing addons doesn't work, help!
This is a bad idea for security and privacy reasons and is not supported at all.
As of version 0.0.11-dev, the sandbox takes extra steps to ensure that only addons that are bundled with Tor Browser by default are exposed to the container as a security measure.
How do I edit the torrc?
That ability is not provided at this time. The tor daemon launched
sandboxed-tor-browser uses it's own torrc and does not honor the
one contained in the bundle directory.
Wait, Firefox uses X11, isn't security basically hopeless?
Yes. The current implementation of the sandbox does little to nothing to defend against Firefox doing evil things to or via the X socket.
If you want to attempt to mitigate this, the best options are:
- Run 0.0.8-dev or newer, where "something, but not likely enough" is done to defend against some of the easier evil.
- Use a nested X11 implementation like Xephyr or Xpra.
- Sit there and pray that Wayland will fix everything.
The ideal solution at current time is probably to probably do all three.
An advanced configuration option for setting the
DISPLAY that Firefox
will use is provided to enable easier nested X11 usage.
(Thanks to "Jann Horn of Google Project Zero" for pointing out that the documentation doesn't make it obvious that such things are beyond the threat model.)
How do I make this use a system tor instance?
sandboxed-tor-browser in this way is not recommended.
How do I disable the update check/auto update?
You don't. This software is for users that want extra security, and running out of date versions runs counter to that goal.
How do I install Flash/Siverlight/etc?
Your tears are delicious, and your plugins will burn.
More concretely, the sandbox only exposes system calls and shared libraries that are required for Tor Browser's functionality, and getting binary plugins to work would likely require loosening those restrictions.
What happened to x86 (32 bit Intel) support?
While early revisions of the software including the 0.0.2 release supported x86, the decision was made to remove support due to several factors including reduced effectiveness due to platform/OS limitations, declining userbase, and development resource limitations.
See #20940 for more details.
Modern Linux kernels without
USER_NSsupport MUST be capable of supporting the sandboxed Tor Browser.
Proxy bypass MUST be impossible without a sandbox escape, even if the adversary gets RCE capability.
The firefox process's write access to the filesystem MUST be limited to the user preferences, download directory and the bookmarks. The firefox process's read access to the filesystem SHOULD be limited to the Tor Browser installation directory.
There is a UX tradeoff here in that, without access to at least the user's home directory, uploading things is difficult, but there's a lot of data a potentially malicious firefox executable can get at if it can read from the entire home directory.
The firefox process MUST NOT be responsible for launching the tor instance. The tor process MUST live in a separate sandbox, with no access to user data (ie: tor MUST only be able to see it's
The firefox process MUST NOT be responsible for updating Tor Browser. The downloads MUST be fetched over tor, and a more permissive sandbox spawned to handle updating.
A user interface based on Gtk+ is provided to control installing/updating Tor Browser and to assist in configuring the tor daemon and sandbox.
Gtk+3.0 was used despite Tor Browser linking against 2.0 to avoid the need for a future migration.
Files are placed in accordance with the XDG Base Directory specification, honoring the appropriate overrides.
- Runtime files (eg: sockets):
sandboxed-tor-browser includes the capability to download and install the
latest version of Tor Browser.
Supports all of the channels and locales for a given architecture.
Supports doing the download over tor, assuming a system tor instance is present, and the
TOR_CONTROL_PORTenv var is set.
Also downloads the PGP signature of the bundle, and verifies it prior to installation with a hardcoded copy of the PGP key.
Modifies the bundle configuration post-install via writing out a set of configuration files using the Firefox Enterprise Deployment infrastructure.
This is needed so that the built in auto updater, and addon updating can be disabled, as the former is handled by
sandboxed-tor-browserand the latter will not work by default due to filesystem permissions in the sandbox container.
sandboxed-tor-browser handles keeping the installed bundle up to date,
as the bundle directory is mounted read-only inside the firefox container
while the browser is actually running, precluding the ability to use the
built in updater.
Checks and downloads updates over tor, launching tor in a container if required. Never uses the clear net for either. As of 0.0.3, Onion Services administered by the Tor Project are used for metadata.
Checks approximately every two hours in the background, and may check at launch.
Uses libnotify if present to notify the user that an update is available.
Independently validates the MAR signature prior to updating, with hardcoded copies of the signing keys.
Supports both full and incremental updates, favoring incremental.
Updates are done in a container with no network access, X11, or other things that are part of the firefox and tor containers.
Re-installs the config overrides after each update.
tor daemon interface
sandboxed-tor-browser can either use an existing tor daemon, or launch one
in a sandbox container, and is responsible for routing traffic between the tor
and firefox sandbox containers (or the system tor and the firefox container).
Interface to the system tor instance if one is configured.
Launches the tor daemon in a container with a auto-generated
torrcbased on the user configuration.
A SOCKS5 server that firefox talks to, that rewrites the SOCKS authentication (needed to isolate circuit/stream status information visible to the firefox process via the Tor Control Port).
A filtering Tor Control Port that firefox talks to. This provides the minimum subset of events/commands required for "New Identity" and (optionally, only if enabled) the circuit display to function.
Due to the re-writing of SOCKS5 authentication info, even if a system Tor is used, the firefox process never sees circuits or streams it is not responsible for.
sandboxed-tor-browserlaunches the tor, a SOCKS5 pass-through proxy is provided at the traditional address (
127.0.0.1:9150) so that the user can use other applications with the sandboxed tor daemon (nb: Some weirdness with torsocks and the pass-through proxy, needs investigation.).
Sandbox container launcher
sandboxed-tor-browser launches the various sandbox containers by
exec()ing bubblewrap and passing it various arguments and static assets
Each container is different, and will be describe in a separate section. The interface code also includes:
A seeccomp rule loader, that loads pre-compiled seccomp-bpf rules.
A dynamic linker cache parser (
/etc/ld.so.conf) along with routines used to enumerate the libraries required from the host system inside the container for the binaries that are to be executed.
~/.Xauthorityparser and generator, so that only the current target
$DISPLAYis exposed in the container.
Other misc routines for handling gtk+, PulseAudio, and other things.