Install Additional Software Safely
A primary Whonix ™ goal is to greatly reduce the risk posed by (additional) software installations that are not exclusively designed to work with Tor.
Users can install any software inside Whonix-Workstation ™ using apt-get, since it is based on Debian. However, this is not a recommendation for installing additional software. Also, Whonix ™ is currently the most secure platform for running Tor-unsafe applications like the former Adobe Flash plugin (now deprecated); see the operating system comparison.
The Whonix ™ software page lists:
- pre-installed Whonix ™ applications which are available for different tasks
- recommended software for different user activities
- safety advice
- installation instructions
Install from Debian stable
To install a package from Debian stable, follow the steps below. Replace
package-name with the name of the software to be installed.
There are numerous examples of this procedure in the Software chapter and throughout the wiki.
Table: Best Software Installation Practices
|Always Verify Signatures||
|Avoid Manual Software Installation||
|Avoid Third Party Package Managers||
|Prefer Packages from Debian Stable Repository||
Debian's installation default is
--install-recommends. Debian packages have various metadata fields such as:
Depends:dependencies or dependency packages
When installing a package using
apt-get, dependencies (
Depends:) are always installed. The Debian default is for recommended packages (
Recommends:) to also be installed alongside the primary package (unless installed previously). To avoid that outcome, it is possible to use the
apt-get command line parameter
--no-install-recommends; this is in most cases optional.
Debian's default for suggested packages (
--no-install-suggests i.e. not to install suggested packages. Users can optionally use
--install-suggests, but there are no known cases where this would be useful at the time of writing. A host of other command line options [archive] are also available.
If a package is installed using
apt-get --no-install-recommends install package-name, then re-running
apt-get without any parameters or even with
--install-recommends will not result in installation of the recommended packages. To accomplish a "late" installation of recommended packages, the simplest method is first uninstalling the package. Alternatively, the list of
Recommends: can be viewed using
apt-cache package-name or by checking the package on https://packages.debian.org [archive].
A brief Q&A regarding the potential impacts of the "recommended" field is outlined below.
||Yes. For example, mmdebstrap [archive] uses |
||In corner cases, yes. For example consider a host operating system without a Host Firewall.  By omitting |
||The answer depends on the specific package. Advanced users who know exactly which packages are needed can use |
|Should Whonix ™ set the default to
||This is a good question. It is a big change and could lead to a lot of broken functionality for user-installed packages. At the moment, Whonix ™ user support is manageable because redirection to the Free Support Principle is possible. If |
For these reasons, such suggestions should first be raised at Debian's issue tracker after first searching for existing discussions on Debian mailing lists. Search Debian APT issue tracker [archive] for
Whonix ™ documentation uses
--no-install-recommends whenever appropriate. In general, whether users should use
--no-install-recommends for package installation is unspecific to Whonix ™ and should be resolved as per Free Support Principle.
Whonix ™ users are free to install their favorite software packages, but should be aware that additional software increases the attack surface [archive] of the platform. Almost any application can be installed, with a few exceptions for programs that are impossible to torify [archive]. In addition, Whonix ™ provides:
- protection from IP and DNS leaks (see above for details)
- partial protection against protocol leaks and fingerprinting, but this is far from perfect
When updating with
apt-get, information will leak about which software packages and versions have been installed, unless Tor onion repositories have been configured.  This meta-data cannot be directly linked to any other activity like web browsing, because the Whonix ™ apt-get uwt wrapper forces it to pass through its own circuit. Despite this isolation, it is still possible for updates to be correlated with the same pseudonym.  
For greater security when updating:
- Follow the guidelines below.
- Be especially careful when adding custom repositories, particularly Personal Package Archives (PPAs). Compared to main distribution repositories, solo developers are more susceptible to influence and theoretically might have malicious intent.
- Read the protocol leak and fingerprinting protection entry first. It highlights useful information, like the fact that DNS and IP-related leaks do not apply to Whonix ™.
- Refer to the Tor Project's Torify: How-to [archive] which discusses various protocol leaks [archive] and how to mitigate them.
- Review the Tor Project's Transparent Proxy Leaks [archive] documentation, which is particularly relevant for Microsoft Windows.
How-to: Install or Update with Utmost Caution
- Stop all activities and shutdown any open applications like Tor Browser.
- Change the Tor circuit -- this step may not apply if the user is running an onion service. 
- Update using
apt-getafter a random delay. By default, a new Tor circuit is generated after 10 seconds.
- Change the Tor circuit again.
- Continue user activities after another random period has elapsed.
Whonix-Workstation ™ is Firewalled
The Whonix-Gateway ™ firewall  has several effects upon Whonix-Workstation ™.
Table: Whonix-Gateway ™ Firewall Effects
|Additional Firewall Restrictions||The firewall on Whonix-Gateway ™ is very restrictive. It can be made even more restrictive by activating options within the firewall script.  It is possible to limit which outgoing ports are redirected to Tor's |
|DNS Requests||Standard DNS requests on UDP port |
|IPv6||Tor only partially supports IPv6 [archive], although full implementation is likely in the near term.  This is not a Whonix ™-specific issue. |
|Server Services||Onion Services and/or Location Hidden Services can be hosted.|
|Tor Routing||All traffic originating from Whonix-Workstation ™ and Whonix-Gateway ™ is routed over Tor.        Refer to the footnotes for further information.|
|UDP||Tor does not support UDP. This is not a Whonix ™-specific issue.|
Install Newer Software Versions
It is sometimes possible to install newer versions of software applications, either via available backports or by manual installation. When intending to use newer versions of certain applications like Electrum or Monero it is best to approach the process as an application installation, rather than an application update.
In oversimplified terms, a Debian package is just a vehicle to place files into a location. For example, the
binaries-freedom Debian package [archive] in Whonix ™ ships Electrum. It comes with the appimage file (
/usr/share/binaries-freedom/electrum-appimage/electrum-4.0.7-x86_64.AppImage) and a start menu entry (
/usr/share/applications/electrum-appimage.desktop). The presence of these files does not impose limitations; it is still possible to customize the system and install newer software versions.
These files can also be ignored; for example it is not necessary to use the electrum-appimage start menu entry. The
binaries-freedom package is intended to improve usability and it was never designed to limit customization, nor does it have that side effect. As per Whonix ™ policy there are No Intentional User Freedom Restrictions. 
As an illustration, a newer version of Electrum would require:
- installing Electrum appimage
To install other custom software, it is suggested to follow recommendations throughout this chapter for better security. Specific instructions for custom software installations will vary for each application. This process is mostly unspecific to Whonix ™ and therefore the Free Support Principle applies to installation steps. The same is true for Qubes-Whonix ™ users -- first consider how this process would be achieved in a Debian-based Qubes template.
Backports are packages taken from the next Debian release (called "testing"), adjusted and recompiled for usage on Debian stable.
This is a far safer alternative than the Debian testing or unstable repositories. However, Debian backports should be used conservatively.
Backports cannot be tested as extensively as Debian stable, and backports are provided on an as-is basis, with risk of incompatibilities with other components in Debian stable. Use with care!
Install from Debian Testing
Before completing steps in this section, first read Prefer Packages from Debian Stable Repository. Carefully check how packages will change before proceeding -- a host of upgrades is usually safe, but no Whonix ™ packages should be removed as part of the process; see Whonix Debian Packages. Be aware that problems are still possible; see here [archive] for an example.
It is recommended to complete this process in a separate Whonix-Workstation ™ (
whonix-ws-15-debian-testing-mix) due to the risks. Ask for advice in the forums on a case-by-case basis.
Install from Debian Unstable
Before completing steps in this section, first read Prefer Packages from Debian Stable Repository.
Mixing packages from Debian
stable with those from a later release like
unstable can destabilize the system due to associated software dependencies required for full functionality. First carefully check how packages will change before proceeding. 
A host of upgrades is usually safe, but no Whonix ™ packages should be removed as part of the process; see Whonix Debian Packages. It is recommended to complete this process in a separate Whonix-Workstation ™ (
whonix-ws-15-debian-unstable-mix) due to the risk. Ask for advice in the forums on a case-by-case basis.
As per the free support principle, package reinstallation utilizes normal Debian processes.
The example below shows how the thunderbird package would be reinstalled. It is possible to substitute thunderbird with many other packages, so long as they do not have too many dependencies. These instructions are not suitable for any packages needed for connectivity such as tor, because the reinstallation would be very difficult and is currently unsupported.
Even in the thunderbird package example, dependency complications emerge. The anon-workstation-packages-recommended package also depends on thunderbird. Further, the whonix-workstation package depends on anon-workstation-packages-recommended.
Install Software in a TemplateBasedVM
There is no reason to avoid installing software in TemplateBasedVMs [archive], although installed software will not persist across reboots. A custom script can be used to automate this process, which minimizes the time spent re-installing packages.
- Centralized Updates: AppVMs [archive] are based on a TemplateVM [archive]. This means the AppVM's root filesystem is based on the corresponding template's root filesystem. Any updates to the TemplateVM will be reflected in the TemplateBasedVM's root filesystem upon restart.
- Minimal Disk Usage: TemplateBasedVMs require much less disk space than StandaloneVMs, since the AppVM's root filesystem is based on the corresponding template. The AppVM only needs enough disk space to hold user files in the
- Semi-persistent Storage: User data stored in
/usr/localsurvives reboot. Many applications like Signal [archive] and Wire [archive] store user data in the
/homefolder. Since the custom script installs the software seamlessly with little or no user interaction, the AppVM has "quasi-full persistence", not unlike a StandaloneVM's full persistence.
Once user preparation is complete and the AppVM has started, it will automatically start the script to begin installing software. When the process finishes, the AppVM can be used like any other TemplateBasedVM. However when the AppVM is shutdown, all data outside of the persistent
/home folder will be lost, including the newly installed software packages. Following reboot, the VM will again install the software packages automatically.
Using bind-dirs Selective Persistence
Add Application Launcher to Start Menu
General forum discussion about snap: Snap Store / snaps / snapd / snapcraft.io - a new software source? [archive]
Qubes-Whonix ™ issues:
- Efforts to persistently install snap apps in Qubes-Whonix ™ via bind-dirs [archive] or with snap proxy settings have been unsuccessful. This means it must be installed in a TemplateBasedVM on every occasion it is required. Efforts to improve this situation are most welcome, see: Wickr Me vs Qubes-Whonix Persistence [archive] and snap totally unusable on Qubes whonix-ws [archive].
- Qubes TemplateVMs are non-networked by Qubes default,  which means snap does not run inside
whonix-ws-15TemplateVM. It is likely snap is similarly affected in other Qubes' TemplateVMs like the Debian TemplateVM. As per Free Support Principle it is recommended to test snap functionality in a non-Whonix based TemplateVM before attempting the same inside Whonix ™.
flatpak Package Manager Security
This entry compares flatpak security features (such as signed metadata) against Debian's APT package manager.  With one caveat, flatpak package manager security is comparable to Debian's APT package manager: Flatpak currently does not defend against
indefinite freeze attacks [archive].
An attacker continues to present files to a software update system files that the client has already seen. As a result, the client is kept unaware of new files.
For many adversaries this attack is difficult because it requires breaking TLS. While flatpak package version information is not protected by a
valid-until field [archive], it is fetched over TLS. Adversaries capable of breaking TLS face an obstacle when dealing with torified connections (like those in Whonix ™) -- an indefinite freeze attack cannot target a specific user, but will affect all Tor users. This increases the chances of being caught unless they also have the ability to break Tor. Even then the attack chain would be very complex:
Break Tor →
Target specific user(s) →
Break TLS →
Mount an indefinite freeze attack →
Exploit a vulnerability caused by an outdated software version.
To safeguard against this possibility, it is recommended to perform manual checks of version numbers for flatpak-installed applications -- they should match those available from the flathub repository. Every flathub application has a corresponding website page with an
Additional information section that lists
Version information. For example, at the time of writing for Chromium:
- This is the associated org.chromium.Chromium flathub website page [archive].
- The additional information section lists:
April 16, 2021
Researching version information on the flathub website with a browser is equally vulnerable to indefinite freeze attacks because it also relies upon TLS. It is therefore recommended to use Whonix ™ or Tor Browser for this purpose. 
Sometimes APT software versions are quite old, which can lead to less functionality or even exposure to known vulnerabilities that are being exploited in the wild (see footnote).  Conversely, flatpak usually offers more recent software versions and/or deploys security fixes in a more timely manner.
In summary, flatpak advantages are considered to outweigh the potential risks of an indefinite freeze attack because the attack chain is complex. Also, flatpak is sometimes the only trustworthy, easy-to-use software source that provides newer versions than available in Debian stable (with Frozen Packages) (or newer).
Qubes OS Specific
At the time of writing, applications installed using flatpak do not present in the Qubes start menu. 
navigate to Qube settings →
applications tab →
press "Refresh Applications".
For most use cases the extensive software range available from the official Debian repositories should be sufficient. A selection of nearly 60,000 programs  can be installed within a couple of steps. These packages are constantly maintained for bug/security fixes and are tightly integrated to provide a stable distribution.
To guarantee stability, no new versions are uploaded to Debian stable archives to avoid breaking the system. This makes Debian stable a dependable distribution and an excellent base for downstream distributions. However, the Linux software scene is very dynamic and sometimes users will want software that is not yet packaged in Debian. In this case it may be necessary to install software from separate sources; either from third party repositories, as a stand-alone precompiled .deb binary, or directly compiled source packages. 
Foreign sources should be used infrequently because it can cause problems. Note this is simply a warning about the worst case scenario and not a predetermined outcome of installing third party software.
Foreign sources pose important security implications for the affected system. Installing software is tantamount to granting root privileges to the developers. Software originating from dubious sources could replace important system components with malicious versions that allow backdoors or Trojan horses [archive] to be installed on the system.
In general, the installation of software is a matter of trust. The fact is every installed software source must be trusted. This trust is two-fold: firstly that the developers have integrity, and secondly that the community will notice any suspicious code, which might indicate compromise of the developers' machines. 
Manually installed packages can contain library versions that are unavailable in the standard repositories. This causes problems with dependency resolution when installing additional software from the official repository. Individual applications are less critical in this context, but when important system libraries in the third-party software are considered, complications are inevitable.
Depending on the severity of the complications, upgrades to the next version of the operating system might fail, or the system may become unbootable or generally unstable.
GUI Applications with Root Rights
- Such as desirable software versions that are not yet bundled in the official repositories.
- https://web.archive.org/web/20170919173146/https://arstechnica.com/information-technology/2017/09/devs-unknowingly-use-malicious-modules-put-into-official-python-repository/ [archive]
- The pip developers refused to implement any kind of proper GPG signature verification, opting to support server HTTPS instead [archive] which is a lot weaker. While the TUF secure updater project has implemented a safe version of pip [archive], it is not clear how widely it has been adopted and whether it will become popular.
- https://github.com/theupdateframework/tuf/blob/develop/SECURITY.md [archive] http://www.webcitation.org/6F7Io2ncN [archive]
- https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html [archive]
If security or stability are at all important for you: install stable. period. This is the most preferred way.
... Since there is typically over 1 year between releases you might find that stable contains old versions of packages. However, they have been tested in and out. One can confidently say that the packages do not have any known severe bugs, security holes etc., in them. The packages in stable integrate seamlessly with other stable packages. These characteristics are very important for production servers which have to work 24 hours a day, 7 days a week. ... Stable is rock solid. It does not break and has full security support. But it might not have support for the latest hardware.
On the other hand, packages in testing or unstable can have hidden bugs, security holes etc. Moreover, some packages in testing and unstable might not be working as intended.
- There are no known examples at the time of writing.
- Most people nowadays are behind a NAT router which blocks unsolicited incoming connections by default. While that protects from outside Internet-based attacks, it does not protect against attacks launched from inside the local area network (LAN) (devices that use the same router). This is specifically dangerous when using shared WiFi hotspots.
- Perhaps including some recommended packages.
- See: set apt-get --no-install-recommends by default [archive]
- This wiki chapter has been authored so it may be a useful resource in the future.
- See software updaters [archive] for more information on this topic.
- Consider the following example. A user announces online that software X is being utilized, and another specific application set x, y, and z is installed. If this information becomes available to an adversary and the circuit-isolated apt-get passes through any Tor exit relays, mirrors or ISPs under their control, then they may guess it is associated with the same pseudonym. In that case, the adversary has a list of the user's installed packages, and can attempt a stale mirror attack (if the user has a custom Ubuntu build), or try other attacks against apt-get.
- As per the previous footnote, this threat equally applies to users who run an onion service with a specific set of server software, for example apache, mediawiki, phpbb, and others.
- Using PPA in Ubuntu Linux (Complete Guide) [archive]:
PPA stands for Personal Package Archive. The PPA allows application developers and Linux users to create their own repositories to distribute software. With PPA, you can easily get newer software version or software that are not available via the official Ubuntu repositories.
- One option is using Arm:
Navigate to Whonix-Gateway ™ (Qubes-Whonix ™: sys-whonix)→
Select Arm - Tor Controller→
Press "n" for a New Identity.
Press "m" for the menu→
Scroll down to "New Identity"→
- The firewall is found on Whonix-Gateway ™: /usr/bin/whonix_firewall
## Optionally restrict TransPort. ## Replace above rule with a more restrictive one, e.g.: #$iptables_cmd -t nat -A PREROUTING -i "$int_if_item" -p tcp --match multiport --dports 80,443 --syn -j REDIRECT --to-ports "$TRANS_PORT_WORKSTATION"
- If the DNS server is changed in Whonix-Workstation ™ /etc/resolv.conf, this will likely have no effect. The reason is the firewall on Whonix-Gateway ™ will redirect all those requests to Tor's
DnsPort. The working exception to this rule is when users tunnel / encrypt DNS requests (DNSCrypt, httpsdnsd), as per the secondary DNS resolver instructions.
- The only missing elements at the time of writing were automatic client connections and inter-relay connections via IPv6. Bridges are fully supported. See also: IPv6 roadmap [archive].
- https://phabricator.whonix.org/T509 [archive]
Since Whonix ™ version
0.2.1Whonix-Gateway ™ traffic is also routed over Tor. In this way, use of Whonix is hidden from persons or systems observing the network.
- To preserve the anonymity of a user's Whonix-Workstation ™ activities, it is not necessary to torify Whonix-Gateway ™ own traffic.
For reader interest: If DNS settings on Whonix-Gateway ™ are changed in
/etc/resolv.conf, this only affects Whonix-Gateway ™ own DNS requests issued by applications using the system's default DNS resolver. By default, no applications issuing network traffic on Whonix-Gateway ™ use the system's default DNS resolver. All applications installed by default on Whonix-Gateway ™ that issue network traffic (apt-get, whonixcheck, sdwdate) are explicitly configured, or forced by uwt wrappers, to use their own Tor
SocksPort(see Stream Isolation).
Whonix-Workstation ™ default applications are configured to use separate Tor
SocksPorts(see Stream Isolation), thereby not using the system's default DNS resolver. Any applications in Whonix-Workstation ™ that are not configured for stream isolation - for example
nslookup- will use the default DNS server configured in Whonix-Workstation ™ (via
/etc/network/interfaces), which is the Whonix-Gateway ™. Those DNS requests are redirected to Tor's DnsPort by Whonix-Gateway ™ firewall. Whonix-Gateway ™
/etc/resolv.confdoes not affect Whonix-Workstation ™ DNS requests.
Traffic generated by the Tor process itself which runs by Debian default under user
debian-tororiginating from Whonix-Gateway ™ can use the internet normally. This is because user
debian-toris exempted in Whonix-Gateway ™ Firewall, allowed to use the "normal" internet.
The Tor software (as of
0.4.5.6) (and no changed were announced at time of writing) almost exclusively uses TCP traffic. See also Tor wiki page, chapter UDP. For DNS, see next footnote.
Tor does not require, use functional (system) DNS for most functionality. IP addresses of Tor directory authorities are hardcoded in the Tor software as per Tor upstream default. Exceptions include:
- proxy settings using proxies with host names rather than IP addresses
- the Tor pluggable transport meek lite to resolve domains used in setting
front=to IP addresses.
- In simple terms, Whonix modifications can be ignored.
- Users should Prefer Packages from Debian Stable Repository, but using backports is better than manual software installation or using third party package managers since this prefers APT. To contain the risk, Non-Qubes-Whonix ™ users might want to consider using Multiple Whonix-Workstation ™ and Qubes-Whonix ™ users might want to consider using Multiple Qubes-Whonix ™ TemplateVMs or Software Installation in a TemplateBasedVM.
- Most often this step applies before attempting major Whonix ™ upgrades; upgrade instructions are also made available at that time (see Stay Tuned).
- Most often this step applies before attempting major Whonix ™ upgrades; upgrade instructions are also made available at that time (see Stay Tuned).
- https://www.debian.org/releases/sid/ [archive]
- https://www.debian.org/security/faq#unstable [archive]
- See: https://wiki.debian.org/DebianUnstable#What_are_some_best_practices_for_testing.2Fsid_users.3F [archive]
- It is recommended to create aMultiple Whonix-Workstation ™ to install the package due to these risks.
- Most often this step applies before attempting major Whonix upgrades; upgrade instructions are also made available at that time (see stay tuned).
- Qubes install software [archive]
- https://www.qubes-os.org/doc/software-update-vm/#note-on-treating-appvms-root-filesystem-non-persistence-as-a-security-feature [archive]
- Obvious hook targets include .bashrc, the Firefox profile directory (which contains extensions), or PDF or DOC documents that are likely to be opened by the user.
- APT works because of Qubes' qrexec-based updates proxy.
- Note that source code is not considered in this comparison.
- In theory some adversaries are capable of mounting an indefinite freeze attack against all visitors arriving from the Tor network. This is considered unlikely because the threat of eventual detection is too high. Such an attack would be widely publicized and might lead to major improvements in how Internet encrypted/authenticated connections are established.
- Chromium exploitation example.
- flatpak installed applications do not show up in Qubes start menu [archive]
- https://www.debian.org/intro/why_debian [archive]
- https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html [archive]
- With reproducible package builds on the horizon, the security risk from the second factor will be minimal in the future.