Dev/systemcheck

From Whonix
< Dev
Jump to navigation Jump to search

Security[edit]

When using systemcheck with parameter --leak-tests curl will verify the SSL certificate for downloads from check.torproject.org -- SocksPort Test, TransPort Test, -- and abort if the certificate is not valid. The ca-certificates Debian package is installed on Whonix ™.

When manually running this test, attack surface for this script includes at least curl, apt, gpg, grep, sed, bash, uwt, torsocks, zenity, and pgrep. Whonix ™ developers have assessed that the benefits of this check outweigh the potential risks.

SSL Certificate Pinning[edit]

Introduction[edit]

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

How-to[edit]

These instructions have moved to: systemcheck 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]

systemcheck Information Sources[edit]

/usr/bin/systemcheck sources:

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

systemcheck Operation[edit]

After gathering the above information, systemcheck runs functions in systemcheck_main while passing command line arguments.

Function systemcheck_main then calls:

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

Additional Functions[edit]

The /usr/libexec/systemcheck/ 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/systemcheck function systemcheck_main.

As a simple example, inspect the file /usr/libexec/systemcheck/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 systemcheck 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
  • $derivative_codename /etc/apt/sources.list.d/derivative.list codename
  • $derivative_codename_uppercase
  • $DAEMON = 1 run in daemon mode
  • $AUTOSTARTED = 1 run after boot
  • $manualrun = 1 manually run
  • $ARCH "$(uname --machine)"
  • $derivative-maker_version
  • $derivative_deb_package_version

For further examples, please inspect the behavior of other functions in folder /usr/libexec/systemcheck/

Silent Mode[edit]

Table: systemcheck Default Operation (outdated!)

Category Whonix-Gateway Whonix-Workstation ™
Runs after boot (autostart mode) Yes [3] No [4]
Runs regularly during Whonix ™ operation (daemon mode) No [5] No [6]

Table: systemcheck Notification Matrix

Circumstance Notification
Tor bootstrapping completes promptly [7] "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 [8] [9] found Active error popup with advice
No grave issue found No GUI output
Manual run of systemcheck Then silent is set to 0, resulting in a progress bar and run of all tests [10] and active popup with results when complete

Other Silent Mode Settings[edit]

systemcheck 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. [11]

Table: Silent Level Overview

Silent Level Action
Silent <= 0
  • Show SocksPort and TransPort "Test Result: Connected to Tor. IP" messages
Silent >= 1
  • No "systemcheck 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 [12]
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" message
Silent >= 3
  • No Tor SocksPort / TransPort test is conducted
  • No stream isolation test at all
  • No Whonix ™ News check at all
  • No apt 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. [13]

Development[edit]

Use Cases[edit]

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

Automated Tests[edit]

Run after automatic boot by an automated test suite.

Auto-start Following Boot[edit]

  1. To provide connectivity progress information (Tor bootstrap check), with the familiar "in progress...", "done" (or failed) messages.
  2. 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[edit]

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

Planned Features[edit]

When an error occurs, provide: [14]

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

Related[edit]

Footnotes[edit]

  1. ↑ https://phabricator.whonix.org/T80
  2. ↑ The order differs for Whonix-Gateway ™ (sys-whonix) and Whonix-Workstation ™ (anon-whonix). For detailed information concerning differences, see /usr/bin/systemcheck. The purpose of function systemcheck_run_function is to allow users to add function names to configuration variable systemcheck_skip_functions, which permits the skipping of certain functions. Also see: systemcheck Hardening.
  3. ↑ It is necessary to provide feedback if Tor bootstrapping is slow or there are other grave problems.
  4. ↑ This is designed to reduce the number and duplication of popups, like when Tor bootstrapping has not yet finished.
  5. ↑ 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 systemcheck manually.
  6. ↑ For example, if five AppVMs were in operation that would cause five error popups.
  7. ↑ Tor is connected when whonxicheck runs function check_tor_bootstrap
  8. ↑ For example, if unwanted packages are installed.
  9. ↑ Also see: System Checks.
  10. ↑ Verbose output still requires the --verbose option.
  11. ↑ The same as Whonix ™ 11.
  12. ↑ Relating to no connectivity, Tor not being detected and false positives.
  13. ↑ In other words, do not notify about a disabled Whonix ™ repository.
  14. ↑ 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.


Retrieved from "https://www.whonix.org/w/index.php?title=Dev/systemcheck&oldid=83835"