Settings Module (SettingsPage)

1. Overview

The Settings module provides a centralized configuration interface for BastionGuard™, implemented in GTKmm (GTK4). It orchestrates both user-scoped and privileged system operations, including antivirus runtime controls, ransomware and phishing protection, DNS-level filtering, firewall integration, secure payment sandboxing, email protection, language switching, service management, and embedded web server configuration.

The page is organized around a multi-tab Gtk::Notebook and integrates both internal BastionGuard components and system services.

The module interacts with:

  • ClamdConfig – advanced scan options, on-access monitored paths, and persistence of clamd.conf
  • Backend – anti-ransomware, anti-phishing, firewall integration, YARA/Sanesecurity updates, Google Safe Browsing, quarantine path management, and auxiliary protection logic
  • SettingsStore – persistent storage for UI-level feature toggles such as Secure Payments
  • systemd – lifecycle management for both user units and privileged system units
  • pkexec – privileged writes, service control, and system configuration installation
  • dnsmasq – DNS-based phishing blacklist enforcement via generated configuration snippets
  • CEF Sandbox – isolated browsing environment for secure payment workflows
  • Thunderbird integration – SMTP profile discovery/import and extension installation support for the Email module
  • Mail proxy subsystem – JSON-driven outbound email protection and SMTP relay configuration

2. Page Layout and Navigation

The Settings UI is structured using a Gtk::Notebook and contains the following tabs:

  • Base – real-time antivirus and monitored folders
  • Avanzate – advanced ClamAV scan options and configuration persistence
  • Anti-Ransomware – user service control, YARA rules, SaneSecurity DB, and scanner configuration
  • Anti-Ransomware avanzate – SHA256 allowlist and false-positive filtering
  • Anti-Phishing – system service control, blacklist status, auto-update, Google Safe Browsing, and firewall integration
  • Anti-Phishing avanzate – whitelist and custom blacklist management with dnsmasq integration
  • Pagamenti Sicuri – CEF sandbox toggle and payments.json domain/URL allowlist
  • Servizi Utente – management of systemctl --user units
  • Email – outbound email protection, SMTP profile import, and Thunderbird integration
  • Servizi Sistema – privileged system service management through pkexec systemctl
  • DB ClamAV – installed signature inspection under /var/lib/clamav
  • Opzioni – language selection and web server configuration

3. Core Utilities and Runtime Helpers

3.1 Command Execution Helpers

The module defines several internal helpers for process execution, output capture, and privileged actions:

  • run_cmd(argv, out_stdout, silence_stderr) – executes a process through Gio::Subprocess
  • pkexec_systemctl(args) – wraps privileged systemctl actions via pkexec systemctl ...
  • run_cmd_capture(cmd, out, exit_code) – executes shell commands through popen() and captures output
  • write_temp_script_and_elevate(...) – creates a temporary script and runs it with pkexec or sudo fallback
  • run_privhelper_and_capture(...) – invokes the privileged email helper /usr/bin/bastionguard-emailproxy

These helpers are reused throughout the module for service control, file installation, DNS/web server updates, and email protection setup.

3.2 Distribution Detection

The module includes a distro detection routine, detect_distro(), used to select the correct configuration layout for the web stack and other system-specific paths.

Detection order:

  1. Preferred: lsb_release -si
  2. Fallback: parsing /etc/os-release for ID=
  3. Fallback: probing distro-specific marker files such as /etc/arch-release and /etc/debian_version

The resulting value is normalized and mapped to categories such as debian, fedora, arch, opensuse, gentoo, slackware, and bsd.

3.3 Web Server Detection and Port Persistence

Web server detection is handled through detect_webserver(), which checks active services, binary presence, and running processes for:

  • Apache (apache2 / httpd)
  • Nginx (nginx)
  • LiteSpeed (lshttpd / lsws)

Internal BastionGuard web ports are stored in:

/etc/BastionGuard/webports.conf

and are read or updated through helper routines such as read_webports_conf(), read_current_ports(), and update_webserver_ports().

4. Base Tab

4.1 Real-Time Antivirus

The Base tab exposes real-time antivirus status through:

  • clamonaccSwitch – enable/disable UI switch
  • realtimeLabel – immediate runtime status label

The effective state is detected dynamically by probing:

  • clamonacc.service
  • clamav-clamonacc.service

The switch updates the UI immediately and delegates service-side behavior to the application/backend layer.

4.2 Quarantine Path

The quarantine path is displayed as a read-only label and configured using a folder chooser dialog:

  • quarantineLabel shows the current result of Backend::getQuarantinePath()
  • quarantineButton opens a Gtk::FileChooserDialog
  • Selected values are persisted through Backend::setQuarantinePath()

4.3 On-Access Monitored Folders

The Base tab also manages on-access monitored folders for ClamAV:

  • Folders are rendered in listbox_paths
  • btn_addPath adds a folder and propagates it to clamdConfig.addOnAccessPath()
  • btn_removePath removes the selected entry and propagates it to clamdConfig.removeOnAccessPath()

5. Advanced (ClamAV) Tab

5.1 Scan Options

Advanced ClamAV scan options are loaded from clamdConfig.getScanOptions() and rendered as a grid of checkboxes inside a Gtk::FlowBox with selection disabled.

Each checkbox is tracked inside the internal checkOptions map. A warning label is displayed above the grid to discourage unsafe bulk changes.

5.2 Toggle-All Controller with Loop Prevention

A global toggle (toggleAllSwitch) enables bulk activation of advanced scan options. To prevent recursive signal loops and preserve manual user choices, the implementation uses:

  • updatingToggle – reentrancy guard
  • toggleControlled[opt] – tracks options enabled specifically by the global toggle

When the global switch is disabled, only the options that were previously enabled by the bulk controller are reverted.

5.3 Atomic Save of clamd.conf

Saving advanced configuration is handled by onSave():

  1. Checkbox states are written back into the ClamdConfig model
  2. The target configuration path is resolved through choose_clamd_conf_target()
  3. A temporary file is written to /tmp
  4. The file is installed atomically using a privileged helper with automatic backup of the previous configuration
  5. If needed, Backend::installClamdIfMissing() attempts automatic installation of missing ClamAV runtime components

The privileged installation path uses the following pattern:

pkexec sh -c 'if [ -f target ]; then cp -a target target.bak.timestamp; fi; install -D -m 0644 tmp target'

6. Anti-Ransomware Tab

6.1 Service Toggle and State

The Anti-Ransomware protection is managed through the user unit:

BastionGuard-ransomware-scanner.service

The tab exposes:

  • antiransomSwitch – service enable/disable control
  • antiransomStatus – runtime status label

The state is checked through:

systemctl --user is-active BastionGuard-ransomware-scanner.service

Toggling starts or stops the service and invokes backend logic through:

  • Backend::instance().start_antiransom()
  • Backend::instance().stop_antiransom()

6.2 YARA Rules Inventory and Updates

YARA rules are loaded from:

/usr/share/BastionGuard/data/yara

The loader enumerates .yar and .yara files, parses rule names through regex, and populates a GTK list model.

Rule updates are performed asynchronously through:

  • Backend::instance().updateYaraRules()

UI status refreshes are marshaled back to the GTK main loop using Glib::signal_idle().

6.3 SaneSecurity DB Update

The tab provides a manual update action for SaneSecurity DB through:

  • Backend::instance().updateSanesecurityDB()

Execution runs in a detached background thread and UI feedback is synchronized through idle callbacks.

6.4 Scanner Configuration

The ransomware scanner configuration is loaded from a text file through loadScannerConfig() and includes the following keys:

  • enable_yara
  • enable_sanesecurity
  • scan_interval
  • scan_path

The configuration is saved through saveScannerConfig(), which writes a clean scanner configuration and installs it through pkexec cp when a privileged destination is required.

7. Anti-Ransomware Advanced Tab

7.1 SHA256 Allowlist

The advanced ransomware tab provides an allowlist of trusted SHA256 values, optionally associated with a rule name.

The allowlist is persisted in:

~/.config/BastionGuard/allowlist.txt

Each line supports the format:

SHA256;optional_rule

The UI supports add and remove actions and loads/saves the list through dedicated helper routines.

7.2 False Positive Filters

The advanced tab also exposes several filtering controls for reducing false positives:

  • Suspicious-only mode – suspicious_only
  • Ignore paths – ignore_paths
  • Ignore extensions – ignore_ext
  • Suspicious extensions – suspicious_ext

These settings are persisted in:

~/.config/BastionGuard/scanner.conf

The save routine preserves comments and unknown keys where possible, updates only the relevant configuration entries, and restores effective ownership/permissions for the target user.

8. Anti-Phishing Tab

8.1 System Service

The Anti-Phishing protection uses the system unit:

BastionGuard-phishing-scanner.service

It is managed through privileged commands such as:

pkexec systemctl start BastionGuard-phishing-scanner.service
pkexec systemctl stop BastionGuard-phishing-scanner.service
pkexec systemctl restart BastionGuard-phishing-scanner.service

Operational feedback is displayed through antiphishStatus.

8.2 Automatic Blacklist Updates

A dedicated checkbox enables or disables periodic blacklist updates every two hours through backend methods:

  • Backend::instance().isPhishAutoUpdateEnabled()
  • Backend::instance().enablePhishAutoUpdate(enable)

The operation is performed asynchronously and the result is propagated to the UI through idle callbacks.

8.3 Google Safe Browsing Integration

The module exposes optional Google Safe Browsing integration through:

  • googleSafeSwitch – enable/disable additional verification
  • googleSafeKeyEntry – API key entry with visibility toggle
  • Save and verification actions implemented through backend helpers

The UI supports key visibility toggling, persistence, and live validation through Backend::instance().testGoogleSafeKey().

8.4 Blacklist State and Manual Update

The anti-phishing tab shows blacklist state by reading:

  • phishing/blacklist-reduce.txt – loaded line by line and counted
  • phishing/blacklist.txt – validated and displayed as the reference full list

Manual updates are triggered via:

  • Backend::instance().updatePhishLists()

If the anti-phishing service is active, it is restarted after list update so that the new blacklist becomes effective immediately.

8.5 Firewall Integration

A dedicated card-style section exposes automatic firewall IP blocking for malicious hosts detected by the Anti-Phishing subsystem.

Supported firewall backends:

  • UFW
  • firewalld

When enabled, the UI allows the user to select the firewall backend through FirewallChoiceDialog. The backend layer is then updated through:

  • Backend::instance().setFirewallType(type)
  • Backend::instance().setFirewallEnabled(true)
  • Backend::instance().applyFirewallFromPhishingBlacklist()

Status labels indicate whether the firewall feature is disabled or currently operating with UFW or firewalld.

9. Anti-Phishing Advanced Tab

9.1 Whitelist

The advanced Anti-Phishing tab manages a user-maintained whitelist of domains or IPv4 addresses that should be excluded from phishing enforcement.

The whitelist is stored in:

  • User path:
    ~/.local/share/BastionGuard/phishing/whitelist.txt

  • System install path:
    /usr/share/BastionGuard/data/phishing/whitelist.txt

The UI uses a searchable Gtk::SearchEntry, Gio::ListStore<Gtk::StringObject>, Gtk::SingleSelection, and Gtk::ListView for list rendering and filtering.

9.2 Custom Blacklist (dnsmasq)

The same tab also manages a custom phishing blacklist that can be enforced at DNS level through dnsmasq.

Backing files:

  • User path:
    ~/.local/share/BastionGuard/phishing/blacklist_custom.txt

  • System install path:
    /usr/share/BastionGuard/data/phishing/blacklist_custom.txt

  • Generated dnsmasq configuration:
    /etc/dnsmasq.d/bastionguard-blacklist.conf

For each blacklisted domain, the module generates entries such as:

address=/domain.com/127.0.0.2

After saving, the module installs the whitelist, blacklist, and generated dnsmasq configuration using a privileged shell command and reloads DNS filtering with:

pkexec systemctl reload dnsmasq

This provides DNS-level phishing mitigation independent of browser-level enforcement.

10. Secure Payments Tab

10.1 Feature Toggle and Persistence

The Secure Payments feature provides an isolated CEF-based browsing mode for payment and checkout flows.

The feature state is persisted through:

  • SettingsStore::get_secure_payments_enabled()
  • SettingsStore::set_secure_payments_enabled(enabled)

The same state is synchronized into the JSON allowlist configuration through update_payments_enabled_only().

10.2 payments.json Domain/URL Allowlist

The Secure Payments allowlist is stored in:

~/.config/BastionGuard/payments.json

If the file is missing, it is created with default metadata and an initial payment-provider allowlist.

The structure includes:

{
  "version": 1,
  "updated_at": "YYYY-MM-DD",
  "enabled": true,
  "list": [ "paypal.com", "stripe.com", ... ]
}

Normalization is handled by normalize_domain_or_url(), which:

  • Trims whitespace
  • Extracts the host from URLs
  • Removes credentials and port
  • Strips the www. prefix
  • Forces lowercase
  • Validates the resulting hostname through regex and requires a TLD

Saving uses a temporary file followed by atomic rename to reduce corruption risk.

11. User Services Tab

The Servizi Utente tab manages BastionGuard user-scoped services through systemctl --user. The UI is built dynamically through build_services_section().

Typical actions include:

systemctl --user enable --now <unit>
systemctl --user start <unit>
systemctl --user stop <unit>
systemctl --user disable --now <unit>

The current implementation includes user services such as:

  • BastionGuard-privacyd.service
  • BastionGuard-ransomware-alert.service
  • BastionGuard-ransomware-realtime-alert.service
  • BastionGuard-ransomware-scanner.service
  • BastionGuard-useragent.service
  • BastionGuard-pacd.service
  • BastionGuard-cef.service
  • BastionGuard-mailproxy.service

A refresh action re-queries service state and synchronizes all switches.

12. Email Tab

12.1 Overview

The Email tab provides configuration for outbound email protection through a local BastionGuard mail proxy. It is backed by a structured JSON configuration and supports SMTP relay profiles, signature injection, listener configuration, Thunderbird profile import, and Thunderbird extension installation.

12.2 Configuration File

The user configuration is stored in:

~/.config/BastionGuard/mail.json

If missing, it is created automatically through ensure_mail_json_exists().

The JSON model contains fields such as:

  • enabled
  • scan_outgoing
  • inject_signature
  • local_smtp_host
  • local_smtp_port
  • local_smtp_tls_port
  • local_submission_port
  • advertise_starttls
  • enable_implicit_tls_listener
  • default_profile_id
  • profiles

12.3 SMTP Profiles

SMTP relay profiles are modeled through MailRelayProfile and include:

  • Profile identifier and label
  • match_from and match_from_domain matching rules
  • SMTP host, port, STARTTLS, and implicit TLS flags
  • Username and password
  • Embedded mail signature settings

Profiles are persisted through load_mail_security_config() and save_mail_security_config(), using atomic rename semantics.

12.4 Automatic Signature Injection

The Email module supports optional automatic signature injection. Signature data includes:

  • display_name
  • job_title
  • company
  • phone
  • website
  • logo_path

A fixed logo path is used in the current implementation:

/usr/share/BastionGuard/data/logo.png

An HTML preview can be generated through build_email_signature_preview_html().

12.5 Thunderbird Import

The Email tab can discover Thunderbird SMTP profiles by inspecting the user’s Thunderbird installation, including:

  • ~/.thunderbird/installs.ini
  • ~/.thunderbird/profiles.ini
  • prefs.js within the selected default profile

Thunderbird profile discovery parses SMTP and identity entries and generates BastionGuard relay profiles. Passwords are not extracted from Thunderbird and must be entered manually.

12.6 Thunderbird Extension Installation

The tab also provides installation support for the BastionGuard Thunderbird extension and native host through the script:

/usr/share/BastionGuard/data/extension/bastionguard-tb-extension/install-tb-extension.sh

The installation output is captured and displayed inside a GTK text buffer for diagnostics.

13. System Services Tab

The Servizi Sistema tab manages privileged system services through pkexec systemctl. Supported actions include:

pkexec systemctl enable --now <unit>
pkexec systemctl start <unit>
pkexec systemctl stop <unit>
pkexec systemctl disable --now <unit>

Currently exposed system services include:

  • BastionGuard-phishing-scanner.service
  • BastionGuard-ransomware-realtime.service
  • BastionGuard-usbd.service

If a privileged service operation fails, the UI restores the previous switch state and presents a diagnostic dialog.

14. DB ClamAV Tab

The DB ClamAV tab enumerates installed signature files in:

/var/lib/clamav

Recognized signature extensions include:

.ndb .hdb .hsb .ldb .sdb .fp .mdb .pdb .wdb .cbc .cdb .cat

Files are filtered, sorted alphabetically, counted, and displayed inside a scrollable GTK container. The refresh action re-runs the signature scan and updates the file count label.

15. Options Tab

15.1 Language Selector

The Options tab allows the user to select the application locale. Supported values include language identifiers such as it_IT, en_US, de_DE, fr_FR, and others.

The selected language is saved in:

~/.config/BastionGuard/lang.conf

The file includes:

  • LANG
  • LC_ALL
  • LANGUAGE with a short fallback chain

After saving, a modal progress window is shown while relevant services are restarted. The application then re-executes itself via:

/proc/self/exe

15.2 Web Configuration

The Options tab also provides web server configuration support, including distro selection and internal HTTP/HTTPS port configuration.

Ports are stored in:

/etc/BastionGuard/webports.conf

When the user applies the web configuration, the module:

  • Reads and validates numeric port entries
  • Loads an NGINX template from DATA_DIR/vhosts
  • Replaces the placeholders:
    {{HTTP_PORT}}
    {{HTTPS_PORT}}

  • Creates a temporary configuration file
  • Builds a temporary elevated script that installs the correct distro-specific configuration
  • Writes the selected ports to /etc/BastionGuard/webports.conf
  • Validates and restarts NGINX with:
    nginx -t && systemctl restart nginx

The implementation supports distro-specific targets, including dedicated handling for Arch-like systems versus other Linux layouts.

Errors are surfaced through GTK message dialogs and include captured logs from the elevated execution path.

16. Security and Runtime Considerations

  • Privilege separation: user-scoped operations use systemctl --user, while system-wide changes and file installation use pkexec
  • DNS-level mitigation: Anti-Phishing advanced configuration can enforce domain blocking through generated dnsmasq rules
  • Atomic writes: JSON and configuration persistence use temporary files and rename-based replacement where possible
  • Thread safety: long-running updates and validation routines execute in background threads and marshal UI changes back through Glib::signal_idle()
  • Input validation: domains, URLs, IPv4 entries, and SHA256-related values are normalized and validated before persistence
  • Rollback behavior: service toggle failures restore the previous UI state and display actionable diagnostics
  • Operational transparency: status labels provide immediate feedback for antivirus, ransomware, phishing, firewall, secure payments, email protection, and service operations
  • Safe email relay configuration: imported SMTP profiles using loopback-only destinations are detected and sanitized to prevent invalid relay configuration
Published on:
Last updated on: