{{Header}} {{title|title= systemcheck - Security Check Application }} {{#seo: |description=System Integrity Test. Connectivity Test. Update Check. And More. |image=Systemchecknotification.png }} {{intro| System Integrity Test. Connectivity Test. Update Check. And More. }} [[File:Systemchecknotification.png|thumb|systemcheck completion]] [[File:Systemcheckgui.png|thumb|systemcheck progress meter]] [[File:Systemcheckcli.png|thumb|systemcheck in Terminal]] = Introduction = * Purpose of systemcheck: {{Code2|systemcheck}} checks numerous, important system variables to assess system status. * Usage methods: It can be run in a {{cli}} environment (such as in a terminal emulator like qterminal) or via the {{gui}} option, which features a progress meter and summary notification popup. * Non-intrusive design: systemcheck is designed to be read-only and does not intentionally change the system state. * Optional component: {{project_name_long}} remains functional without running systemcheck, as it is purely for status checking. * Silent operation by default: Many checks produce no output unless warnings or errors occur. For detailed success and skip messages, use the --verbose option. * Community benefit: systemcheck keeps the entire {{project_name_short}} community informed about critical updates or guidance, especially for users who do not frequently launch the browser or visit the {{project_name_short}} website. = Running systemcheck = systemcheck verifies that the {{project_name_short}} system is up-to-date and that everything is in proper working order. Follow the steps below to manually run systemcheck and check the system status. == How-to: Manually Run systemcheck == {{Box|text= If you are using [[Qubes|{{q_project_name_long}}]], complete the following steps. Qube Manager → right-click the VM you want to check → select "Run command in qube"

Type each command below, followed by the ENTER key. {{CodeSelect|code= qterminal }} {{CodeSelect|code= systemcheck }} Qubes App Launcher (blue/grey "Q") → click the VM you want to check → System Check If you are using a graphical environment, complete the following steps. Start Menu → System → systemcheck If you are using a terminal environment, complete the following step. Standard run. {{CodeSelect|code= systemcheck }} Verbose run (for [[Advanced Users]] only). {{CodeSelect|code= systemcheck --verbose }} }} Depending on system specifications, systemcheck can take up to a few minutes to complete. If everything is working as intended, the output should highlight each INFO heading in green (not red). A successful systemcheck process will have output similar to below. == Sample systemcheck Output == {{PreBox|[INFO] [systemcheck] {{project_name_workstation_short}} {{!}} {{project_name_workstation_short}} {{project_name_workstation_template}} TemplateBased AppVM {{!}} Sun 25 Apr 2021 07:56:41 AM UTC [INFO] [systemcheck] Connected to Tor. [INFO] [systemcheck] {{project_name_short}} APT Repository: Enabled. When the {{project_name_short}} team releases BUSTER-PROPOSED-UPDATES updates, they will be AUTOMATICALLY installed (when you run apt full-upgrade) along with updated packages from the Debian team. Please read https://www.{{project_clearnet}}/wiki/Trust to understand the risk. If you want to change this, use: sudo repository-dist [INFO] [systemcheck] Debian Package Update Check: Checking for software updates via apt... ( Documentation: https://www.{{project_clearnet}}/wiki/Update ) [INFO] [systemcheck] Debian Package Update Check Result: No updates found via apt. [INFO] [systemcheck] Please donate! See: https://www.{{project_clearnet}}/wiki/Donate}} == Tor Bootstrap == Tor bootstrap refers to the process of attempting to connect to the Tor network (successfully or unsuccessfully). Familiar output related to this process includes: "Tor connecting xx percent...", "Tor not connected", "Tor connected" and so on. Bootstrapping does not refer to related concepts, such as whether connections are "secure", "not secure", "anonymous" or "not anonymous". = System Checks = systemcheck runs a long list of checks, but it intentionally hides most "all good" messages to avoid overwhelming users. Errors and warnings are always displayed, while detailed success messages require --verbose. Any operating system updates, downloads or other network activity are Tor stream-isolated by default. {| class="wikitable" |+ ''System Checks run by systemcheck'' |- ! '''Check''' ! '''Description''' |- ! Canary | An automated {{project_name_short}} warrant canary check is available with the --verbose parameter, see: [[#Warrant Canary Check|Warrant Canary Check]]. |- ! Clock Source | Check if the clock source is KVMClock and warn if that is the case. This is only expected to affect those following the [[KVM]] instructions. |- ! Entropy Test | An entropy availability check confirms {{Code|/proc/sys/kernel/random/entropy_avail}} contains no less than 112 bits. |- ! Hostname | Check if: * {{Code|hostname --fqdn}} outputs {{Code|host.localdomain}}. * {{Code|hostname }} outputs {{Code|host}}. * {{Code|hostname --ip-address }} outputs {{Code|127.0.0.1}}. * {{Code|hostname --domain }} outputs {{Code|localdomain}}. (Whonix only.) |- ! Connectivity Tests | When using --ip-test (previously called, same as --leak-tests): # Download https://check.torproject.org with curl through an extra SocksPort. # Download https://check.torproject.org with curl through regular connection. Checks if check.torproject.org reports the IP to be a Tor IP address. |- ! Log Inspection | When using the --verbose option, check if {{Code|~/.msgcollector/msgdispatcher-error.log}} exists and report this if confirmed. |- ! Meta-package Check | Check if the relevant meta-packages These capture packages which depend on all other recommended / default-installed packages. are installed. Also see: [[Debian_Packages|{{project_name_short}} Debian Packages]]. |- ! Network Connection | Check that setup-dist has properly configured networking. |- ! Operating System Updates Check | "apt-get update" is run. A notification is provided whether the system is up-to-date or requires updating. |- ! Package Manager | Check if a package manager is currently running and wait until the process is finished. Otherwise, the system might become locked or the package manager might be left in a broken state. Advice is provided on what to do in such circumstances. This prevents connection failures during concurrent upgrades. |- ! Tor | Check: * If Tor has been enabled by checking whether {{Code|DisableNetwork 1}} has been commented out from {{Code|/usr/local/etc/torrc.d/50_user.conf}}. * The validity of Tor configuration files. * Notify about the Tor connection and IP address. Some users may wonder why it is necessary to check the IP address if the {{project_name_short}} design ensures that the real IP cannot be leaked. Sometimes check.torproject.org reports false positives and fails to detect Tor exit nodes, so it is better to provide information about that possibility. This also reduces support requests and bad press. Users are welcome to investigate a Tor exit node that could not be detected, but it can be stated with high confidence that the IP address will be associated with a known Tor exit node. Another reason to perform this check is because some users set up dangerous and/or unsupported configurations, such as: * Using virtualizers which are entirely unsupported and untested by {{project_name_short}} developers. * Installing arbitrary packages on {{project_name_workstation_long}} ({{project_name_workstation_template}}). This could theoretically create leak vectors, and systemcheck is the last layer of defense against such issues. (Whonix only.) |- ! Services (systemd) | Check for failed systemd units and report them. |- ! pkexec Self-Test | Run a PolicyKit self-test (pkexec /usr/libexec/systemcheck/pkexec-test) to verify authorization is implemented as designed. Produces output only on failure. |- ! Privilege Escalation Framework | Verify that privilege escalation is implemented as designed (privleap, sudo, pkexec, etc.) |- ! Repository Notification | Notifies whether [[Project-APT-Repository|Derivative APT Repository]] is enabled or not. |- ! Stream Isolation | When using --ip-test (previously called, same as --leak-tests): # Download https://check.torproject.org with curl through an extra SocksPort. # Download https://check.torproject.org with curl through regular connection. A stream isolation test checks that the IP addresses from (1) and (2) differ. (Whonix only) |- ! Tor Bootstrap | Shows Tor bootstrap status messages (for example: "Tor connecting xx percent...", "Tor not connected", "Tor connected"). Also see: [[#Tor Bootstrap|Tor Bootstrap]]. |- ! Miscellaneous | * control port filter proxy running (Whonix only) * remarkable kernel messages * timedatectl check |- ! Virtualization Platform | Check {{project_name_short}} is being run on one of the supported virtualizer platforms, including [[VirtualBox]], [[KVM]] or [[Qubes]]. (Whonix only.) |- ! su access check | Checks if su is locked down so only root can use su. {{CodeSelect|code= systemcheck --function check_su_access --verbose }} 
[INFO] [systemcheck] su access check: Locked down - only account root can use su.
See also: https://www.kicksecure.com/wiki/Dev/Strong_Linux_User_Account_Isolation#su_restrictions
|- ! Full Disk Encryption (crypt-check) | Check if the root partition is encrypted (LUKS header detection). Prints an info message on success or failure. Also see: [[Systemcheck#Physical_Security_Check|Physical Security Check]]. (When running on real hardware only.) |- ! GRUB Security | GRUB bootloader password set or not. |- ! Unwanted Packages Check | Check for packages listed as unwanted (see configuration directive systemcheck_unwanted_package) and warn if any are installed. Also see: [[Systemcheck#Unwanted_Packages_Check|Unwanted Packages Check]]. |- ! Physical Security Check | See [[Systemcheck#Physical_Security_Check|Physical Security Check]]. |- ! Environment Variables | Verifies expected flag environment variables are present to distinguish the environment. * On Whonix, checks WHONIX=1. * On Kicksecure, checks KICKSECURE=1. Warns if missing. |- ! Network Interface Checks | Verifies at least one external network interface is up, using different mechanisms depending on platform. * Kicksecure: uses a helper script (for example check-network-access) to detect global IP connectivity. * Whonix: uses leaprun link tests on eth0 (and also eth1 on gateway). In Qubes TemplateVMs, networking is assumed inactive and the result may be reported as unknown. |- ! Tor SocksPort Reachability | todo: document |- ! Spectre and Meltdown Vulnerability Check | Optionally runs spectre-meltdown-checker (when explicitly enabled). Uses a timeout and warns if the checker indicates potential vulnerability. |- ! Time and Timezone Checks | Confirms the system timezone and time handling are sane. (Whonix only) |- ! Journal Inspection and Diagnostics Logs | Inspect logs and report issues. |- ! Debian End-of-Life Status | Checks whether the underlying Debian release is end-of-life and warns if the platform is no longer supported. |- ! User and sysmaint Account Separation | Checks whether user maintenance separation (for example user-sysmaint-split) is in effect and whether account separation expectations are met, warning if misconfigured. |- ! Login Restrictions | Checks login security posture such as password presence and autologin status for local Linux accounts as part of physical security related checks, warning when insecure settings are detected. |- ! Secure Boot Status | Checks Secure Boot status and reports unexpected states depending on platform and expectations. |- ! "tirdad" Module Check | Checks for the presence of the tirdad module and warns on unexpected findings. |- ! APT Repository Consistency | todo: document |- ! IP Forwarding Disabled | Additional confirmation that IP forwarding is disabled on {{project_name_gateway_short}}, warning if routing behavior is detected when it should not occur by default. (Whonix-Gateway only.) |- ! Output Behavior and Verbose Mode | Many checks are intentionally quiet on success to reduce noise. Warnings and errors are always displayed. Success, skip and informational output becomes much more visible when using --verbose. |- |} = Update Notifications by updatecheck = '''Figure:''' ''updatecheck notification (passive popup)'' [[File:updatecheck.png|400px]] Platform specific. * Kicksecure: Applicable. See below. * Kicksecure for Qubes: Not applicable, because Qubes has its own updater, which is documented on the [[Operating_System_Software_and_Updates|Operating System Software and Updates]] wiki page. Runs approximately every 6 hours. Features: * Passive popup. * Wait for a good time to run the update check. ** Waits 2 minutes after boot before checking for updates, to give the user a chance to run APT before the package database gets locked. Updatecheck runs APT, which locks the package database as it updates it. ** Runs {{CodeSelect|inline=true|code=leaprun onion-time-pre-script}} up to 5 times until it succeeds. Waits 2 minutes between each call if it fails. This is to ensure Tor bootstrap has been completed. ** Waits up to 6 minutes for sdwdate to complete time synchronization. ** Waits up to 20 minutes for the package database to be unlocked, which means no other APT process (run by the user) is currently locking it. * Stale notifications are cleared. If there was an issue upgrading but not when updatecheck runs again, the stale, no longer applicable notification will be cleared to avoid confusion. Note: No administrative ("[[root|root]]") rights required. Do not use sudo! Check logs. {{CodeSelect|code= journalctl --boot --user -u updatecheck.service }} Check status. {{CodeSelect|code= systemctl --boot --user status updatecheck.service }} Disable. {{CodeSelect|code= systemctl --user mask updatecheck.service }} Re-enable. {{CodeSelect|code= systemctl --user unmask updatecheck.service }} Information for developers: See wiki page [[Dev/Automatic_Updates|Dev/Automatic Updates]] chapter [[Dev/Automatic_Updates#updatecheck|updatecheck]]. == updatecheck for accounts other than user == updatecheck starts automatically when a normal user logs in graphically into a normal desktop. This is triggered by the file /etc/xdg/autostart/updatecheck.desktop. This is only expected to happen if the system is booted in PERSISTENT mode - USER session or LIVE mode - USER session. This means all normal user accounts will automatically have updatecheck working for them. When user-sysmaint-split is installed, the sysmaint user account will only be able to log into a sysmaint graphical session, and only when the system is booted into a SYSMAINT session. The sysmaint graphical session is not a normal desktop, and it does not automatically run all of the services configured in /etc/xdg/autostart. This means updatecheck will not run in a sysmaint session. = Physical Security Check = '''Figure:''' ''systemcheck - Physical Security Check'' [[File:physical-security-check.png|600px]] Several checks related to [[Protection Against Physical Attacks]]. * [[Login]] security check: ** Checks if all Linux user accounts have a password set or if it is absent. ** Checks if all Linux user accounts have an autologin set or if it is absent. * Whether [[Full Disk Encryption|{{fde}}]] is enabled or disabled. * Whether the [[Grub|GRUB]] boot menu is protected by a [[Protection_Against_Physical_Attacks#Bootloader_Password|Bootloader Password]]. Checks not included: * [[Protection_Against_Physical_Attacks#BIOS_Password|BIOS Password]] check. Operating systems do not have permission to detect if a BIOS password is set or absent. = Unwanted Packages Check = Unwanted packages that systemcheck will warn against. systemcheck default configuration file {{Github_link |repo=systemcheck |path=/blob/master/etc/systemcheck.d/30_default.conf |text=/etc/systemcheck.d/30_default.conf }} contains several configuration directives systemcheck_unwanted_package. At the time of writing, these are packages associated with privacy issues or deprecated packages. = Version Numbers = {{Anchor|Whonix Build Version}} {{Anchor|Kicksecure Build Version}} == Build Version == {{#widget:Icon_Bullet_List |addClass=minimal |fontSize=17px |item=fa-solid fa-lock cs-blue,Build version never changes: The {{project_name_short}} build version - the version number of the {{project_name_short}} build - is immutable, similar to a date of birth. It does not change and is not supposed to. |item=fa-solid fa-clock cs-blue,Version embedded at build time: When the image is created, the current {{project_name_short}} version number is embedded in it. This allows systemcheck to determine which build script version was used. |item=fa-solid fa-screwdriver-wrench cs-blue,Static for diagnostics: The version number remains fixed and is not affected by updates. It is mainly relevant to older build script versions and is useful for diagnostics. Deprecated builds may be announced if upgrading becomes too difficult or costly. In such cases, we intend to use systemcheck or dismissable one time popups to inform users. |item=fa-solid fa-ban cs-blue,Non-upgradable build version numbers: Build version cannot be upgraded. This is by design. |item=fa-solid fa-user-check cs-blue,Generally not important for users: Unless instructed otherwise by documentation or developers, users typically do not need to worry about the build version. |item=fa-solid fa-arrow-up-right-dots cs-green,Updates remain possible: Standard ("everyday") updates can still be installed. |item=fa-solid fa-rocket cs-green,Release upgrades remain possible: Even Release Upgrades are typically possible when announced via {{project_name_short}} News. So Follow Announcements. |item=fa-solid fa-book cs-blue,See also: Update vs Image Re-Installation. }} == Check Version == To check the current {{project_name_short}} version, run the following command: {{CodeSelect|code= systemcheck --verbose --function show_versions }} The output should be similar to the following, depending on the platform. Non-Qubes: {{PreBox|[INFO] [systemcheck] Kicksecure build version: {{VersionNew}} [INFO] [systemcheck] kicksecure-dependencies-cli: 31.5-1 [INFO] [systemcheck] derivative_major_release_version /etc/kicksecure_version: {{VersionShort}}}} Qubes: {{PreBox|[INFO] [systemcheck] Kicksecure build version: 3:10.2-1 [INFO] [systemcheck] kicksecure-dependencies-cli: 31.5-1 [INFO] [systemcheck] derivative_major_release_version /etc/kicksecure_version: {{VersionShort}}}} == Technical Details == For advanced users only. The [https://github.com/{{project_name_short}}/dist-base-files dist-base-files] package contains the script {{Github_link|repo=dist-base-files|path=/blob/master/debian/dist-base-files.postinst|text=dist-base-files.postinst}}, which essentially runs: 
echo "$dist_build_version" > "$build_version_file"
Platform-specific details: * For non-Qubes, this corresponds to the derivative-maker Git tag version used to create the image. * For Qubes, the following command is executed during the initial installation of dist-base-files. {{CodeSelect|code=zless /usr/share/doc/dist-base-files/changelog.Debian.gz {{!}} dpkg-parsechangelog -l- -SVersion }} = Warrant Canary Check = == Introduction == {{mbox | type = notice | image = [[File:Ambox_notice.png|40px|alt=Info]] | text = Prerequisite knowledge: [[Trust#canary|{{project_name_short}} warrant canary]]. }} There are several reasons an Automated Warrant Canary Check is justified: * The {{project_name_short}} warrant canary has limited utility if it is forgotten over time and not regularly verified. * It is unlikely the {{project_name_short}} warrant canary is routinely verified by the community. * If a community member discovers the {{project_name_short}} warrant canary verification has failed, there is no effective way to notify all {{project_name_short}} users. == Features == {| class="wikitable" |+ ''Automated Warrant Canary Check Features'' |- ! '''Feature''' ! '''Description''' |- ! Function | Functions similarly to an update check but determines if the {{project_name_short}} warrant canary is still valid. |- ! Security | * Downloads over Tor from .onion link [http://download.{{project_onion}}/developer-meta-files/canary/canary.txt.embed.sig canary.txt.embed.sig]. For convenience, the clearnet link (unused by systemcheck) can be previewed here: https://download.{{project_clearnet}}/developer-meta-files/canary/canary.txt.embed.sig * The downloader {{Github_link|repo=systemcheck|path=/tree/master/usr/libexec/systemcheck/canary-download|text=canary-download.py}} is written in the memory-safe Python language (python3-requests) and runs under a dedicated and limited Linux user account canary. * canary.txt.embed.sig is verified using signify-openbsd. {{CodeSelect|code= sudo -u canary signify-openbsd -V -e -p /usr/share/repository-dist/derivative-distribution-signify-key.pub -x /var/lib/canary/canary.txt.embed.sig -m /var/lib/canary/canary-unembed.txt }} * Has an {{Github_link|repo=systemcheck|path=/tree/master/etc/apparmor.d/usr.libexec.systemcheck.canary|text=AppArmor profile}}. * Has {{Github_link|repo=systemcheck|path=/tree/master/usr/lib/systemd/system/canary.service|text=systemd hardening (seccomp)}}. * Similar to [[sdwdate]], it fetches time from onion time sources. |- ! Implementation details | * Minimal {{Github_link|repo=systemcheck|path=/tree/master/usr/libexec/systemcheck/canary-daemon|text=canary-daemon}} (with systemd-notify). * The {{Github_link|repo=systemcheck|path=/tree/master/usr/libexec/systemcheck/canary|text=canary}} wrapper includes logic on when to run canary-download.py. ** This only runs on {{project_name_gateway_short}} to reduce server load. * Comprises a systemcheck module {{Github_link|repo=systemcheck|path=/tree/master/usr/libexec/systemcheck/check_warrant_canary.bsh|text=check_warrant_canary.bsh}}. |- ! Verbose parameter | During the initial deployment phase of this new feature, systemcheck will only show canary status information when using the --verbose parameter. The reason is that there might be non-security-related potential bugs to address: * The server file location might change. * The server file might become unreadable due to Linux file access permissions. * Onion connectivity issues could emerge. * Server caching issues could serve a stale warrant copy. * General warrant canary improvements. |- ! Troubleshooting | In case of issues, manually verify the {{project_name_short}} warrant canary. Also see: [https://forums.whonix.org/t/whonix-warrant-canary/3208/24 Whonix Warrant Canary Forum Discussion] |- |} == Disable Warrant Canary Check == {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = This disables automated verification of the {{project_name_short}} warrant canary when running systemcheck. }} This will prevent the daily {{project_name_short}} census. {{Open with root rights|filename= /etc/systemcheck.d/50_user.conf }} Add the following content. {{CodeSelect|code= canary=false }} == autostart systemcheck == Perform these steps to automatically start systemcheck; this step is optional. '''1.''' Create folder ~/.config/autostart. {{CodeSelect|code= mkdir -p ~/.config/autostart }} '''2.''' Create a symlink from /usr/share/applications/systemcheck.desktop to ~/.config/autostart/systemcheck.desktop. {{CodeSelect|code= ln -s /usr/share/applications/systemcheck.desktop ~/.config/autostart/systemcheck.desktop }} '''3.''' Done. systemcheck will now automatically start after boot. = Arg Max Check = Only useful in case of systemcheck GUI issues. {{CodeSelect|code= systemcheck --function check_arg_max }} Expected result: 
[INFO] [systemcheck] ERROR: ARG_MAX exceeded!

debug information:
output_func was called with too many arguments.
${FUNCNAME[0]}: output_func
${FUNCNAME[1]}: output_func_cli
${FUNCNAME[2]}: check_arg_max
${FUNCNAME[3]}: systemcheck_run_function
${FUNCNAME[5]}: systemcheck_main
${FUNCNAME[6]}: main
$0: /usr/libexec/systemcheck/systemcheck
The output message will probably be improved in the future. "ERROR: ARG_MAX exceeded!" will be rewritten to "ARG_MAX detected.". = Related = * [[System Audit]] = See Also = * [[Dev/systemcheck]] = Footnotes = {{reflist|close=1}} {{Footer}} [[Category:Documentation]] [[Category:Design]]