{{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 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 [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 check.torproject.org
using curl.
https://phabricator.whonix.org/T80
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. The order differs for {{project_name_gateway_long}} ({{project_name_gateway_vm}}
) and {{project_name_workstation_long}} ({{project_name_workstation_vm}}
). 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]].
== 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.
entropy_file="/proc/sys/kernel/random/entropy_avail" entropy_size="$(cat "$entropy_file")" if [ "${entropy_size}" -lt "112" ]; thenNow it is possible to use, copy and paste, or create a common boilerplate for making discoveries visible.
local MSG="To limit the notifications to those running systemcheck with theEntropy Available Check Result: low.
" $output ${output_opts[@]} --messagex --typex "warning" --message "$MSG" $output ${output_opts[@]} --messagecli --typecli "warning" --message "$MSG"$entropy_file
:$entropy_size
Please report this issue!
--verbose
option, add.
if [ "$verbose" = "1" ]; thenOther useful variables include:
{{project_name_gateway_vm}}
) / 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.
| {{No}} For example, if five AppVMs were in operation that would cause five error popups.
|}
'''Table:''' ''systemcheck Notification Matrix''
{| class="wikitable"
|-
! scope="col"| '''Circumstance'''
! scope="col"| '''Notification'''
|-
! scope="row"| Tor bootstrapping completes promptly Tor is connected when whonxicheck runs function {{Code2|check_tor_bootstrap}}
| "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 For example, if unwanted packages are installed. Also see: [[#System_Checks|System Checks]]. found
| Active error popup with advice
|-
! scope="row"| No grave issue found
| No GUI output
|-
! scope="row"| Manual run of systemcheck
| Then silent
is set to 0
, resulting in a progress bar and run of all tests Verbose output still requires the --verbose
option. 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): 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. The same as {{project_name_short}} 11.
'''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 Relating to no connectivity, Tor not being detected and false positives.
|-
| 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. In other words, do not notify about a disabled {{project_name_short}} repository.
|}
= 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 --verbose
option).
# VPN / tunnel functionality test.
# To educate users that stream isolation is broken when adding a VPN.
== Planned Features ==
When an error occurs, provide: 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.
* 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]]