{{Header}}
{{#seo:
|description={{project_name_long}} Security Check Application Development Notes
}}
{{intro|
{{project_name_long}} Security Check Application Development Notes
}}
{{archived}}
This page would require some updates.
= Security =
When using <code>systemcheck</code> with parameter <code>--leak-tests</code> curl will verify the SSL certificate for downloads from <code>check.torproject.org</code> -- <code>SocksPort</code> Test, <code>TransPort</code> Test, -- and abort if the certificate is not valid. The [https://packages.debian.org/source/stable/ca-certificates ca-certificates Debian package] is installed on {{project_name_short}}.

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. {{project_name_short}} developers have assessed that the benefits of this check outweigh the potential risks.

== SSL Certificate Pinning ==

=== Introduction ===
By default, {{project_name_short}} has not yet implemented direct SSL certificate pinning for <code>check.torproject.org</code> using curl. <ref>
https://phabricator.whonix.org/T80
</ref> 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 ===
Interested readers can learn more about why this feature is not enabled by default [[Dev/SSL Certificate Pinning#Defaults Discussion|here]].

= Source Code Introduction =

== systemcheck Information Sources ==

[https://github.com/{{project_name_short}}/systemcheck/tree/master/usr/bin/systemcheck /usr/bin/systemcheck] {{Code2|source}}s:
# [https://github.com/{{project_name_short}}/msgcollector/tree/master/usr/libexec/msgcollector/error_handler /usr/lib/msgcollector/error_handler]
# [https://github.com/{{project_name_short}}/helper-scripts/tree/master/usr/libexec/helper-scripts/tor_enabled_check /usr/lib/helper-scripts/tor_enabled_check]
# [https://github.com/{{project_name_short}}/helper-scripts/tree/master/usr/libexec/helper-scripts/pkg_manager_running_check /usr/lib/helper-scripts/pkg_manager_running_check]
# Followed by all files in [https://github.com/{{project_name_short}}/systemcheck/tree/master/usr/libexec/systemcheck /usr/libexec/systemcheck/] in lexical order.

== systemcheck Operation ==

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

Function {{Code2|systemcheck_main}} then calls:

# Function [https://github.com/{{project_name_short}}/systemcheck/tree/master/usr/libexec/systemcheck/parse_cmd.bsh {{Code2|parse_cmd_options}}] while passing command line arguments.
# Function [https://github.com/{{project_name_short}}/systemcheck/tree/master/usr/libexec/systemcheck/preparation.bsh#L82 {{Code2|preparation}}].
# Then uses function [https://github.com/{{project_name_short}}/systemcheck/tree/master/usr/libexec/systemcheck/preparation.bsh#L17 {{Code2|systemcheck_run_function}}] to run all other functions. <ref>The order differs for {{project_name_gateway_long}} (<code>{{project_name_gateway_vm}}</code>) and {{project_name_workstation_long}} (<code>{{project_name_workstation_vm}}</code>). For detailed information concerning differences, see {{Code2|/usr/bin/systemcheck}}. The purpose of function {{Code2|systemcheck_run_function}} is to allow users to add function names to configuration variable {{Code2|systemcheck_skip_functions}}, which permits the skipping of certain functions. Also see: [[Systemcheck_Hardening|systemcheck Hardening]].</ref>

== Additional Functions ==

The {{Code2|/usr/libexec/systemcheck/}} folder is not a real .d style plugin drop-in folder. The shell function for separate [{{project_name_short}}, unit] checks can be placed in separate files for better readability. The provided functions are then supposed to be run from {{Code2|/usr/bin/systemcheck}} function {{Code2|systemcheck_main}}.

As a simple example, inspect the file [https://github.com/{{project_name_short}}/systemcheck/tree/master/usr/libexec/systemcheck/check_entropy.bsh {{Code2|/usr/libexec/systemcheck/check_entropy}}] which contains function {{Code2|check_entropy}}. Users can gather as much information as they like for analysis via this function.

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

Now it is possible to use, copy and paste, or create a common boilerplate for making discoveries visible.
<pre>
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"
</pre>

To limit the notifications to those running systemcheck with the <code>--verbose</code> option, add.

<pre>
 if [ "$verbose" = "1" ]; then
</pre>

Other useful variables include:

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* $TEMP_DIR
* $VM "{{project_name_gateway_short}}" or "{{project_name_workstation_short}}"
* $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
</div>
For further examples, please inspect the behavior of other functions in folder {{Code2|/usr/libexec/systemcheck/}}

= Silent Mode =
'''Table:''' ''systemcheck Default Operation'' (outdated!)

{| class="wikitable"
|-
! scope="col"| '''Category'''
! scope="col"| '''{{project_name_gateway_short}}'''
! scope="col"| '''{{project_name_workstation_short}}'''
|-
! scope="row"| Runs after boot (autostart mode)
| {{Yes}} <ref>It is necessary to provide feedback if Tor bootstrapping is slow or there are other grave problems.</ref>
| {{No}}  <ref>This is designed to reduce the number and duplication of popups, like when Tor bootstrapping has not  yet finished.</ref>
|-
! scope="row"| Runs regularly during {{project_name_short}} operation (daemon mode)
| {{No}} <ref>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 {{project_name_gateway_short}} (<code>{{project_name_gateway_vm}}</code>) / 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.</ref>
| {{No}} <ref>For example, if five AppVMs were in operation that would cause five error popups.</ref>
|}

'''Table:''' ''systemcheck Notification Matrix''

{| class="wikitable"
|-
! scope="col"| '''Circumstance'''
! scope="col"| '''Notification'''
|-
! scope="row"| Tor bootstrapping completes promptly <ref>Tor is connected when whonxicheck runs function {{Code2|check_tor_bootstrap}}</ref>
| "Connected to Tor" passive popup only
|-
! scope="row"| 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
|-
! scope="row"| Grave issue <ref>For example, if unwanted packages are installed.</ref> <ref>Also see: [[#System_Checks|System Checks]].</ref> found
| Active error popup with advice
|-
! scope="row"| No grave issue found
| No GUI output
|-
! scope="row"| Manual run of systemcheck
| Then <code>silent</code> is set to <code>0</code>, resulting in a progress bar and run of all tests <ref>Verbose output still requires the <code>--verbose</code> option.</ref> and active popup with results when complete
|}

== Other Silent Mode Settings ==

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

* When autostarted (after boot): <code>silent=3</code>
* Daemon mode (planed iteration during run): <code>silent=3</code>
* Silent only applies to autostart and daemon mode. When it is manually run, all messages are shown. <ref>The same as {{project_name_short}} 11.</ref>

'''Table:''' ''Silent Level Overview''

{|   class="wikitable"
!| '''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 <ref>Relating to no connectivity, Tor not being detected and false positives.</ref>
|-
| 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 {{project_name_short}} 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 {{project_name_short}} News check at all
* No apt update check at all
* Skip notification if {{project_name_short}} 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 {{project_name_short}} repository is enabled/disabled. <ref>In other words, do not notify about a disabled {{project_name_short}} repository.</ref>
|}

= Development =
== Use Cases ==

systemcheck 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 {{project_name_short}} Debian package and build version (build version requires the <code>--verbose</code> option).
# VPN / tunnel functionality test.
# To educate users that stream isolation is broken when adding a VPN.

== Planned Features ==

When an error occurs, provide: <ref>Issues resolved in {{project_name_short}} 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.</ref>
* 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 =
* [[System Audit]]

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Design]] [[Category:Development]]