BastionGuard Technical Documentation

1. Software Purpose

BastionGuard™ is a desktop security application providing local endpoint protection through malware scanning, blacklist filtering, secure browser orchestration, and service lifecycle management built around ClamAV and custom security modules.

The application supports:

  • Full graphical execution (GTK4-based interface)
  • Headless execution (automation, cron jobs, systemd timers)

2. Architecture Overview

BastionGuard is implemented in modern C++ and built on the following stack:

  • GTKmm (GTK4) – Primary graphical user interface
  • D-Bus – System tray integration and inter-process communication
  • nlohmann::json – Configuration handling
  • GNU gettext – Internationalization and localization
  • systemd – Service lifecycle orchestration (external integration)

The application does not depend on Qt. The tray icon implementation is fully D-Bus based and follows StatusNotifierItem specifications where supported.

3. Application Startup and Bootstrap

The entry point is main.cpp. During initialization, BastionGuard prepares:

  • Localization configuration
  • Environment variables
  • Secure wrapper installation
  • Privilege handling for ClamAV
  • Desktop environment detection
  • Wizard bootstrap logic

3.1 Localization Management

At startup, the application ensures the existence of:

~/.config/BastionGuard/lang.conf

If missing, it is created using:

  • The system LANG environment variable
  • Fallback: en_US.UTF-8

The file contains:

LANG=<locale>
LC_ALL=<locale>

These values are applied via setenv() and GNU gettext is initialized:

bindtextdomain("BastionGuard", LOCALEDIR);
bind_textdomain_codeset("BastionGuard", "UTF-8");
textdomain("BastionGuard");

3.2 Command Line Arguments

Supported options:

  • --update-phish – Executes phishing blacklist update (headless mode)
  • --update-sanesecurity – Executes SaneSecurity update (headless mode)
  • --minimized – Starts the UI minimized (if tray is supported)

Unknown arguments are forwarded to GTK.

3.3 Secure xdg-open Wrapper Installation

At startup, BastionGuard ensures the presence of:

~/.local/bin/xdg-open

which is a symbolic link to:

/usr/bin/BastionGuard-bankopener

If required:

  • The symlink is created or corrected
  • User shell configuration files are updated to prepend ~/.local/bin to PATH
  • The runtime PATH is updated for the current session

Supported shell configurations:

  • .bashrc
  • .zshrc
  • .config/fish/config.fish
  • .cshrc
  • .tcshrc

3.4 Headless Execution Modes

BastionGuard supports non-graphical execution:

Phishing Update

Backend::instance().updatePhishLists()

SaneSecurity Update

SaneSecurityUpdater::runHeadless()

Structured exit codes are returned to indicate operational status. These modes are intended for automation (cron, systemd timers, CI environments).

3.5 Privilege Handling (ClamAV Integration)

If the system user clamav exists:

  • Original effective UID/GID are stored in environment variables:
    • BastionGuard_ORIG_EUID
    • BastionGuard_ORIG_EGID
  • initgroups() is invoked
  • Temporary privilege switching occurs
  • Original privileges are immediately restored

This mechanism ensures subprocesses can execute with restricted privileges while maintaining secure separation of execution context.

3.6 Wizard Bootstrap Detection

The configuration file:

~/.config/BastionGuard/config.json

is inspected for:

"wizard_completed": true

If absent or false, the Setup Wizard is launched before the main interface.

3.7 Desktop Environment Detection

The following environment variables are inspected:

  • XDG_CURRENT_DESKTOP
  • XDG_SESSION_DESKTOP
  • DESKTOP_SESSION

Tray icon policy (D-Bus implementation):

  • Disabled: GNOME, XFCE (unless extensions provide support)
  • Enabled: KDE Plasma, Cinnamon, MATE, LXQt, LXDE

Close behavior depends on desktop environment and tray availability.

4. Graphical Interface Lifecycle

BastionGuard uses a custom subclass of Gtk::Application.

On activation:

  • If wizard is required → launch wizard window
  • Otherwise → launch main window
  • Optional first-run services dialog may be displayed

When tray support is active, closing the window hides it instead of terminating the application.

5. Main Window (MainWindow)

5.1 ClamAV Configuration Discovery

The application attempts to load clamd.conf from:

/etc/clamd/clamd.conf
/etc/clamav/clamd.conf
/etc/clamd.d/clamd.conf
/etc/clamd.conf

5.2 Interface Structure

The UI consists of:

  • Custom HeaderBar
  • Navigation sidebar
  • Gtk::Stack for page switching

Primary pages:

  • Dashboard
  • Scan
  • Anti-Ransomware
  • Secure Bank Browser
  • Quarantine
  • Update
  • Logs
  • Privacy
  • About

6. System Requirements

  • Optional system user: clamav
  • ClamAV database directory: /var/lib/clamav
  • User config directory: ~/.config/BastionGuard
  • Secure browser executable: /usr/bin/BastionGuard-bankopener
  • D-Bus session support for tray functionality

BastionGuard™ is licensed under the GNU General Public License v3. The BastionGuard™ name and branding are trademarks and are not licensed under the GPL.

Published on:
Last updated on: