Actions

Whonixcheck

whonixcheck completion
whonixcheck progress meter
whonixcheck in Konsole

Introduction[edit]

whonixcheck is a bash script which checks numerous, important system variables. whonixcheck can be run in a CLI environment (Konsole / Terminal) or via the GUI option, which has an in-built progress meter and summary notification popup of the results. The script is stored in the /usr/bin/whonixcheck and /usr/lib/whonix/whonixcheck/ directories. Whonix is functional without the whonixcheck script since it only checks the system status; it is not responsible for core settings. Nothing is compiled, and the script can be easily inspected in the source code.

The whonixcheck script was inspired by https://check.torproject.org. In the past this was an important check when people were still recommended to use proxy settings to torify web browsers. Tor Browser is now securely pre-configured upon release, which means manual torification of web browsers is now recommended against. As an additional protection the default Tor Browser visits check.tpo to confirm everything is working as expected. [1] This site also checks whether Tor Browser is up-to-date by having Tor Button perform a local check after downloading version information.

check.tpo is useful for a browser check, but Whonix is a complete operating system. This means certain checks must be performed before the browser starts, otherwise a user's anonymity or security might be compromised. whonicheck's design allows the entire Whonix community to stay informed about important updates or advice, and this is particularly important for users who might not start the browser or visit the Whonix website regularly. For these reasons, whonixcheck is automatically started after boot/login if it has not been completed within the last 24 hours. This behavior holds true even if the system is not restarted, thereby keeping any long-running systems (like Onion Services) safely informed.

If it is necessary to hide Tor and Whonix use from an ISP, see here. While only a small minority of users configure their system to hide Tor, it is still desirable to hide any obvious Whonix signature. Whonix users are better off if adversaries cannot distinguish them from vanilla Tor Browser users, as the Whonix user pool is far smaller.

When whonixcheck auto-starts, it first waits for a randomized period of time ranging between 60 and 500 seconds. This obfuscation feature is intended to further stymie traffic analysis, while Tor is still responsible for basic defenses against traffic volume and pattern signatures. Without waiting for a randomized period traffic flows would be more distinguishable, since a spike in whonixcheck traffic would always occur immediately after bootstrapping.

Running whonixcheck[edit]

whonixcheck verifies that the Whonix system is up-to-date and that everything is in proper working order.

Users can manually run whonixcheck to check the system status by following the steps below.

How to Manually Run whonixcheck[edit]

If you are using Qubes-Whonix, complete the following steps. [2]

Qubes App Launcher (blue/grey "Q") -> click on the Whonix VM you want to check -> whonixcheck / System Check

If you are using a graphical Whonix, complete the following steps.

Start Menu -> System -> whonixcheck

If you are using a terminal-only Whonix, complete the following steps.

whonixcheck

Depending on the system specifications, whonixcheck may take up to a few minutes to run. Assuming everything is working as intended, the output should highlight each INFO heading in green (not red). A successful whonixcheck process results in output similar to the sample below.

Sample whonixcheck Output[edit]

[INFO] [whonixcheck] anon-whonix | Whonix-Workstation | {{whonix-ws}} TemplateBased AppVM | Thu Aug 9 18:09:23 UTC 2018
[INFO] [whonixcheck] Connected to Tor.
[INFO] [whonixcheck] Whonix APT Repository: Enabled.
When the Whonix team releases STRETCH-PROPOSED-UPDATES updates, they will be AUTOMATICALLY installed (when you run apt-get dist-upgrade) along with updated packages from the Debian team. Please read https://www.whonix.org/wiki/Trust to understand the risk.
If you want to change this, use:
    sudo whonix_repository
[INFO] [whonixcheck] Debian Package Update Check: Checking for software updates via apt-get... ( Documentation: https://www.whonix.org/wiki/Update )
[INFO] [whonixcheck] Debian Package Update Check Result: No updates found via apt-get.

System Checks[edit]

In all the checks below, whonixcheck warnings appear if a problem is detected. Conversely, whonixcheck output is otherwise quiet unless using the --verbose option. Any operating system updates, downloads or other network activity are stream-isolated by default.

Clock Source

  • Check if the clock source is KVMClock and warn if that is the case. [3]

Control Port Filter Proxy

Entropy Test

  • An entropy availability check confirms /proc/sys/kernel/random/entropy_avail contains no less than 112 bytes.

Hostname

  • Check if:
    • hostname --fqdn outputs host.localdomain.
    • hostname outputs host.
    • hostname --ip-address outputs 127.0.0.1.
    • hostname --domain outputs localdomain.
  • Inform if Whonix-APT-Repository is enabled, and if so, which repository has been selected.

IP Address Routing

  • Check if IP forwarding is disabled on Whonix-Gateway (sys-whonix).

Log Inspection

  • When using the --verbose option, check if ~/.whonix/msgdispatcher-error.log or ~/.whonix/whonix_torbrowser_updater_error.log exist and report this if confirmed.

Meta-package Check

  • Check if the relevant meta-packages [4] are installed on Whonix-Gateway (sys-whonix) or Whonix-Workstation (anon-whonix). Also see: Whonix Debian Packages.

Network Connection

  • Check whonixsetup has properly configured networking.

Operating System Updates

  • apt-get update is run through a separate apt-get SocksPort for stream isolation. A notification is provided whether the system is up-to-date or requires updating.

Package Manager

  • Check if a package manager is currently running and wait until the process is finished. [5] This prevents connection failures during concurrent upgrades of the Tor or Control Port Filter Proxy packages.

Tor

  • Check if Tor has been enabled by inspecting if DisableNetwork 1 has been commented out from /usr/local/etc/torrc.d/50_user.conf either manually or via whonixsetup.
  • Check if the Tor process (pid) is running on Whonix-Gateway (sys-whonix).
  • Check the validity of Tor configuration files in Whonix-Gateway (sys-whonix) by using sudo tor --verify-config.
  • Notify about the Tor connection / IP address. [6] [7]

Tor Bootstrap and Browser Version

Virtualization Platform

Whonix Version and News

  • Download the Whonix version and Whonix news. [8] [9]
    • Download Whonix News Files with curl through an extra Whonix news SocksPort.
  • This check is designed to be functional:
    • If the Whonix repository is down or has changed.
    • For users who have disabled Whonix-APT-Repository permanently or only enable it intermittently.
  • News features:
    • The Whonix News Format only reports the most important news for those not following Whonix developments. [10]
    • The Whonix version and news file is cryptographically signed by lead Whonix developer Patrick Schleizer.
    • Patrick's GPG key is copied to whonix_shared/usr/share/whonix/keys/whonix-keys.d/ at build time.
    • A warning appears if the file can not be GPG-verified with Patrick's OpenPGP key. In that instance the version information and news is ignored.
    • Messages signed more than one month in the past are rejected and the user is informed the message is no longer valid.

Version Numbers[edit]

Whonix Build Version[edit]

The version number of the Whonix build never changes. This is acceptable because at build time [11] the current Whonix version number is added to the image itself. [12] This information is made available so whonixcheck can determine which build script version was used to create that particular image.

This version number should remain static and be unaffected by updating or other issues, since it only applies to specific (usually older) versions of the build script. This is useful for diagnostic purposes and means specific build versions can be deprecated if they are too difficult or expensive to upgrade. In this case, whonixcheck's Whonix News function would inform users about the change.

Security[edit]

The ca-certificates Debian package is installed on Whonix. curl will verify the SSL certificate for downloads from check.tpo -- SocksPort Test, TransPort Test, Tor Browser version check -- and abort if the certificate is not valid.

The attack surface for this script includes at least curl, apt-get, gpg, grep, sed, bash, uwt, torsocks, zenity, and pgrep. Whonix developers have assessed that the benefits of this check outweigh the potential risks. Users are free to change this default behavior [13] and developers remain open to suggested improvements and reviews. Also see: SSL.

SSL Certificate Pinning[edit]

Introduction[edit]

By default, Whonix has not yet implemented direct SSL certificate pinning for check.torproject.org and torproject.org using curl. [14] The intent is to eventually provide users with an optional torproject.org certificate pinning option for the SocksPort Test, TransPort Test and Tor Browser Update Check. To manually configure this setting, see below.

How-to[edit]

These instructions have moved to: whonixcheck SSL Certificate Pinning.

Defaults Discussion[edit]

Interested readers can learn more about why this feature is not enabled by default here.

Source Code Introduction[edit]

whonixcheck Information Sources[edit]

/usr/bin/whonixcheck sources:

  1. /usr/lib/msgcollector/error_handler
  2. /usr/lib/anon-shared-helper-scripts/tor_enabled_check
  3. /usr/lib/anon-shared-helper-scripts/pkg_manager_running_check
  4. Followed by all files in /usr/lib/whonixcheck/ in lexical order.

whonixcheck Operation[edit]

After gathering the above information, whonixcheck runs functions in whonixcheck_main while passing command line arguments.

Function whonixcheck_main then calls:

  1. Function parse_cmd_options while passing command line arguments.
  2. Function preparation.
  3. Then uses function whonixcheck_run_function to run all other functions. [15]

Additional Functions[edit]

The /usr/lib/whonixcheck/ folder is not a real .d style plugin drop-in folder. The shell function for separate [Whonix, unit] checks can be placed in separate files for better readability. The provided functions are then supposed to be run from /usr/bin/whonixcheck function whonixcheck_main.

As a simple example, inspect the file /usr/lib/whonixcheck/check_entropy which contains function check_entropy. Users can gather as much information as they like for analysis via this function.

entropy_file="/proc/sys/kernel/random/entropy_avail"
entropy_size="$(cat "$entropy_file")"
if [ "${entropy_size}" -lt "112" ]; then

Now it is possible to use, copy and paste, or create a common boilerplate for making discoveries visible.

local MSG="<p>Entropy Available Check Result: low. <code>$entropy_file</code>: <code>$entropy_size</code> Please report this issue!</p>"
$output ${output_opts[@]} --messagex --typex "warning" --message "$MSG"
$output ${output_opts[@]} --messagecli --typecli "warning" --message "$MSG"

To limit the notifications to those running whonixcheck with the --verbose option, add.

 if [ "$verbose" = "1" ]; then

Other useful variables include:

  • $TEMP_DIR
  • $VM "Whonix-Gateway" or "Whonix-Workstation"
  • $vm_lower_case_short "gateway" or "workstation"
  • $GATEWAY_IP
  • $whonix_codename /etc/apt/sources.list.d/whonix.list codename
  • $whonix_codename_uppercase
  • $DAEMON = 1 run in daemon mode
  • $AUTOSTARTED = 1 run after boot
  • $manualrun = 1 manually run
  • $ARCH "$(uname --machine)"
  • $whonix_build_version
  • $whonix_deb_package_version

For further examples, please inspect the behavior of other functions in folder /usr/lib/whonixcheck/

Silent Mode[edit]

Table: whonixcheck Default Operation

Whonix-Gateway Whonix-Workstation
Runs after boot (autostart mode) Yes [16] No [17]
Runs regularly during Whonix operation (daemon mode) No [18] No [19]

Table: whonixcheck Notification Matrix

Circumstance Notification
Tor bootstrapping completes promptly [20] "Connected to Tor" passive popup only
Tor bootstrapping is incomplete "Connecting to Tor" passive popup and successful "Connected to Tor" passive popup when finished, or an active error popup with advice when it fails
Grave issue [21] [22] found Active error popup with advice
No grave issue found No GUI output
Manual run of whonixcheck Then silent is set to 0, resulting in a progress bar and run of all tests [23] and active popup with results when complete

Other Silent Mode Settings[edit]

whonixcheck was specifically made more silent to suit the Qubes AppVM design:

  • When autostarted (after boot): silent=3
  • Daemon mode (planed iteration during run): silent=3
  • Silent only applies to autostart and daemon mode. When it is manually run, all messages are shown. [24]


Table: Silent Level Overview

Silent Level Action
Silent <= 0
  • Show SocksPort and TransPort "Test Result: Connected to Tor. IP" messages
Silent >= 1
  • No "whonixcheck was recently run, no need to run it again, you could still manually start it" message
Silent <= 2
  • Complete a SocksPort and TransPort test, but only report errors [25]
Silent >= 2
  • No "Tor Bootstrap Result: Connected to Tor." message unless bootstrapping was slow and a progress bar was shown
  • Perform test stream isolation, but only report errors
  • No Whonix News result if there is no news and the Debian and build version are up-to-date
  • Absent "No updates found via apt-get" message
Silent >= 3
  • No Tor SocksPort / TransPort test is conducted
  • No stream isolation test at all
  • No Whonix News check at all
  • No apt-get update check at all
  • Skip notification if Whonix repository is enabled
  • No progress bar for the usual tests, except a progress bar if Tor has not bootstrapped yet
  • Skip the test for a concurrently running package manager
Silent >= 4
  • Skip the test for whether Whonix repository is enabled/disabled. [26]

Development[edit]

Use Cases[edit]

whonixcheck has specific use cases when it should be run either manually or automatically.

Automated Tests

  • Run after automatic boot by an automated test suite.

Auto-start Following Boot

  • To provide connectivity progress information (Tor bootstrap check), with the familiar "in progress...", "done" (or failed) messages.
  • As a general sanity check, for instance: the gateway is a ProxyVM and not an AppVM, IP forwarding is disabled, the clock is sane, and much more.

Manual User Start

  • Connection functionality test.
  • Connection leak test.
  • General sanity check.
  • General system security and anonymity check.
  • As an information gathering tool, for example reporting the Whonix Debian package and build version (build version requires the --verbose option).
  • VPN / tunnel functionality test.
  • To educate users that stream isolation is broken when adding a VPN.

Planned Features[edit]

When an error occurs, provide: [27]

  • A short error message.
  • A separate help button which opens advice relating to the problem.
  • A separate technical details drop-down button which contains debugging information.

Footnotes[edit]

  1. Tor Browser in Whonix is configured to load a local Whonix resource after launch -- the familiar landing page.
  2. Qubes VM Manager -> right-click on the Whonix VM you want to check -> select "Run command in VM"

    Type the following.
    konsole
    Then press.
    <ENTER>
    

    Type the following.

    whonixcheck

    Then press.

    <ENTER>
    
  3. This is only expected to affect those following the KVM instructions.
  4. These capture packages which depend on all other recommended / default-installed packages.
  5. Otherwise, eventually the system is locked or the package manager is left in a broken state. Advice is provided on what to do in such circumstances.
  6. Some users may wonder why it is necessary to check the IP address if the Whonix design ensures that the real IP cannot be leaked. Sometimes check.tpo reports false positives and fails to detect Tor exit nodes, so it is better to provide information about that possibility. This also reduces support requests and bad press. Users are welcome to investigate a Tor exit node that could not be detected, but it can be stated with high confidence that the IP address will be associated with a known Tor exit node.
  7. Another reason to perform this check is because some users set up dangerous and/or unsupported configurations, such as:
    • Changing the Whonix-Workstation (anon-whonix) network interface from internal network "Whonix" to bridged or NAT.
    • Using virtualizers which are entirely unsupported and untested by Whonix developers.
    • Installing arbitrary packages on Whonix-Workstation (whonix-ws-14). This could theoretically create leak vectors, and whonixcheck is the last layer of defense against such leaks.
  8. One future development goal is to provide protection against a Permanent Takedown Attack.
  9. Also see Trust.
  10. For example, if a theoretical IP address leak was discovered in Whonix, or exit nodes were discovered to be actively exploiting apt-get traffic, then this avenue would briefly inform users about the danger.
  11. The time at which the image was created.
  12. The anon-shared-build-log-build-version package, 70_log_build_version chroot script in essence runs:
    echo "$anon_dist_build_version" > "/var/lib/anon-dist/build_version"
    
  13. By running sudo chmod -x /usr/bin/whonixcheck
  14. https://phabricator.whonix.org/T80
  15. The order differs for Whonix-Gateway (sys-whonix) and Whonix-Workstation (anon-whonix). For detailed information concerning differences, see /usr/bin/whonixcheck. The purpose of function whonixcheck_run_function is to allow users to add function names to configuration variable whonixcheck_skip_functions, which permits the skipping of certain functions. Also see: whonixcheck Hardening.
  16. It is necessary to provide feedback if Tor bootstrapping is slow or there are other grave problems.
  17. This is designed to reduce the number and duplication of popups, like when Tor bootstrapping has not yet finished.
  18. Otherwise this could lead to a disruptive error popup while the user is doing something entirely different. One example is if the user has not used Whonix-Gateway (sys-whonix) / Tor for a while and Tor is no longer connected, this would be reported. If it is only a transient error, users are better off. If it is a permanent error that will be visible later, the user will hopefully run whonixcheck manually.
  19. For example, if five AppVMs were in operation that would cause five error popups.
  20. Tor is connected when whonxicheck runs function check_tor_bootstrap
  21. For example, if unwanted packages are installed.
  22. Also see: System Checks.
  23. Verbose output still requires the --verbose option.
  24. The same as Whonix 11.
  25. Relating to no connectivity, Tor not being detected and false positives.
  26. In other words, do not notify about a disabled Whonix repository.
  27. Issues resolved in Whonix 14 include:
    • Non-zero exit codes when at least one warning or error was detected [for automated test suite]; and
    • Check for failed systemd units (except perhaps apparmor) for automated test suite.

Random News:

We are looking for maintainers and developers.


https | (forcing) onion

Share: Twitter | Facebook

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation.

Whonix is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Libre Software license as Whonix itself. (Why?)