Kicksecure Security Check Application Development Notes

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

When manually running this test, attack surface for this script includes at least curl, apt, gpg, grep, sed, bash, uwt, torsocks, 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/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 [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_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 "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]

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 Kicksecure 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]

System Audit

Footnotes[edit]

↑ https://phabricator.whonix.org/T80
↑ 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.
↑ 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 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.
↑ 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 Kicksecure 11.
↑ Relating to no connectivity, Tor not being detected and false positives.
↑ In other words, do not notify about a disabled Kicksecure repository.
↑
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.

Unfinished: This wiki is a work in progress. Please do not report broken links until this notice is removed, use Search Engines First and contribute improving this wiki.

Kicksecure

A secure by default operating system with the latest security research in place.

Dark mode

FREE · PLUS · PREMIUM Support

At Kicksecure we value freedom and trust, supporting Open Source and Freedom Software

By using this website, you acknowledge you have read, understood, and agree to be bound by these these agreements: Terms of Service, Privacy Policy, Cookie Policy, E-Sign Consent, DMCA, Imprint

2012-2024 ENCRYPTED SUPPORT LP

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!

[1] ttps://phabricator.whonix.org/T80

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

[15] Non-zero exit codes when at least one warning or error was detected [for automated test suite]; and

[16] Check for failed systemd units (except perhaps apparmor) for automated test suite.

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]

Dev/systemcheck

Contents