{{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, torsocks, 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: [[{{project_name_short}}check_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]]