Dev/systemcheck
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:
- /usr/lib/msgcollector/error_handler
- /usr/lib/helper-scripts/tor_enabled_check
- /usr/lib/helper-scripts/pkg_manager_running_check
- 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:
- Function parse_cmd_options
while passing command line arguments.
- Function preparation
.
- 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 |
|
Silent >= 1 |
|
Silent <= 2 |
|
Silent >= 2 |
|
Silent >= 3 |
|
Silent >= 4 |
|
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]
- 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[edit]
- 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: [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]
- ↑
https://phabricator.whonix.org/T80
- ↑ 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. - ↑ It is necessary to provide feedback if Tor bootstrapping is slow or there are other grave problems.
- ↑ This is designed to reduce the number and duplication of popups, like when Tor bootstrapping has not yet finished.
- ↑ 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. - ↑ For example, if five AppVMs were in operation that would cause five error popups.
- ↑ Tor is connected when whonxicheck runs function check_tor_bootstrap
- ↑ For example, if unwanted packages are installed.
- ↑ Also see: System Checks.
- ↑ Verbose output still requires the
--verbose
option. - ↑ The same as Whonix ™ 11.
- ↑ Relating to no connectivity, Tor not being detected and false positives.
- ↑ In other words, do not notify about a disabled Whonix ™ repository.
- ↑ 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.