Dev/systemcheck

From Kicksecure
< Dev
Jump to navigation Jump to search

Kicksecure Security Check Application Development Notes

Info This page is archived.

This page would require some updates.

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 packagearchive.org is installed on Kicksecure.

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

SSL Certificate Pinning[edit]

Introduction[edit]

By default, Kicksecure 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.

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/systemcheckarchive.org sources:

  1. /usr/lib/msgcollector/error_handlerarchive.org
  2. /usr/lib/helper-scripts/tor_enabled_checkarchive.org
  3. /usr/lib/helper-scripts/pkg_manager_running_checkarchive.org
  4. Followed by all files in /usr/libexec/systemcheck/archive.org 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_optionsarchive.org while passing command line arguments.
  2. Function preparationarchive.org.
  3. Then uses function systemcheck_run_functionarchive.org 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 [Kicksecure, 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_entropyarchive.org 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 "Kicksecure" or "Kicksecure"
  • $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 Kicksecure Kicksecure
Runs after boot (autostart mode) Yes [3] No [4]
Runs regularly during Kicksecure 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 Kicksecure 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 Kicksecure News check at all
  • No apt update check at all
  • Skip notification if Kicksecure 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 Kicksecure 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 Kicksecure 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/T80archive.org
  2. ↑ The order differs for Kicksecure (kicksecure) and Kicksecure (kicksecure). 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 Kicksecure (kicksecure) / 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 Kicksecure 11.
  12. ↑ Relating to no connectivity, Tor not being detected and false positives.
  13. ↑ In other words, do not notify about a disabled Kicksecure repository.
  14. ↑ Issues resolved in Kicksecure 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.
Your support makes
all the difference!

We believe security software like Kicksecure needs to remain Open Source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!

Retrieved from "https://www.kicksecure.com/w/index.php?title=Dev/systemcheck&oldid=87886"