wizard_window.hpp

1. Overview

The wizard_window.hpp header defines the BastionGuard::wizard::WizardWindow class, a GTKmm (GTK4) top-level window that implements BastionGuard’s interactive setup wizard. This UI orchestrates a multi-step configuration flow, allowing users to enable and apply system and browser security settings (resolver overrides, firewall configuration, nftables rules, certificate generation, native messaging host installation, user-agent controls, and optional bank list download).

Functionally, WizardWindow provides:

  • A multi-page setup wizard implemented with a GTK stack and sidebar navigation
  • User selection of optional setup actions through checkboxes and inputs
  • Background execution of privileged and non-privileged setup tasks
  • Logging and progress reporting in a scrollable log view
  • Dedicated configuration UI for local web warning server ports
  • Optional bank list (MISP) download workflow with status reporting
  • Completion signaling for integration with the application shell

2. Licensing and Linking Exception

This file header indicates the project is distributed under the GNU General Public License (GPL), with an additional exception permitting linking with the OpenSSL library under the terms described in the file. Implementations and redistributions must comply with the GPL for non-OpenSSL code and respect the stated exception conditions.

3. Dependencies and Includes

#include <gtkmm.h>
#include <filesystem>
#include <string>
#include <thread>
#include <mutex>
#include <vector>
  • gtkmm.h – GTK4 C++ bindings, widgets, stacks, signals, and dispatchers
  • <filesystem> – configuration path handling and file operations
  • <string> – textual configuration, identifiers, and diagnostics
  • <thread> – background worker thread for long-running setup tasks
  • <mutex> – synchronization for log queues and shared state
  • <vector> – storage for wizard steps and queued log lines

4. Namespace Declaration and Scope

namespace BastionGuard::wizard { ... }

The class is part of the BastionGuard::wizard namespace, indicating its role as the UI front-end for the privileged setup logic exposed by the wizard subsystem.

5. Class Declaration and Lifecycle

class WizardWindow : public Gtk::Window

WizardWindow derives from Gtk::Window and implements a multi-page wizard interface. It owns UI widgets, worker thread lifecycle, and the logging dispatch pipeline.

5.1 Constructor and Destructor

WizardWindow();
~WizardWindow() override;

Initializes wizard pages, navigation controls, and runtime state. The destructor is expected to ensure worker thread termination and clean teardown of UI resources and dispatchers.

6. Completion Signaling

sigc::signal<void()> signal_finished();

Exposes a signal emitted when the wizard finishes its execution flow (success or failure), enabling the hosting application to proceed (e.g., close the wizard and refresh settings).

7. UI Construction and Navigation Flow

7.1 UI Builders

void build_headerbar();
void build_sidebar(Gtk::Box& mainBox);
void build_pages();
void set_page(int idx);
void update_nav();
  • build_headerbar() – constructs the window header and title controls
  • build_sidebar() – creates step navigation buttons (wizard steps)
  • build_pages() – builds each wizard page and adds it to the stack
  • set_page() – switches the active wizard page by index
  • update_nav() – updates button enablement and navigation state

7.2 Navigation Handlers

void on_next();
void on_back();
void on_cancel();
void on_finish();

Implements user navigation across the wizard flow, including cancellation and finalization. The finish action typically triggers background execution of selected steps.

8. Logging and UI Updates

void append_log(const Glib::ustring& line);

Enqueues log lines produced by background operations and ensures they are rendered on the GTK main thread. This design avoids UI-thread blocking and maintains responsiveness during privileged operations.

9. Execution Pipeline

void start_execution();
void worker_run();
void finish_execution(bool ok);
  • start_execution() – transitions the wizard into “running” state and starts the worker thread
  • worker_run() – executes selected setup tasks in the background
  • finish_execution() – applies final UI updates and emits completion signals

10. Setup Actions and Helpers

The wizard coordinates multiple setup actions, including browser integration and network hardening:

bool install_native_host(const std::string& src_host,
                         const std::string& extension_id);
bool apply_web_config();

bool write_config_file();
bool install_native_host_user();
bool run_enable_user_agents();
bool run_net_setup();
bool configure_browser_doh();
bool download_bank_list_user();
bool install_browser_policies();
bool is_firewall_active();
bool run_locale_setup_pre();
  • write_config_file() – persists wizard selections and configuration to disk
  • run_net_setup() – runs network/resolver setup steps (typically elevated)
  • is_firewall_active() – detects whether firewall enforcement is currently enabled
  • install_browser_policies() – applies browser policy configuration (enterprise policies)
  • configure_browser_doh() – configures DNS-over-HTTPS settings where applicable
  • install_native_host()/install_native_host_user() – installs native messaging host manifests
  • run_enable_user_agents() – applies user-agent related changes or tooling
  • download_bank_list_user() – downloads and installs the bank list at user scope
  • apply_web_config() – applies local warning server configuration (ports/web server)
  • run_locale_setup_pre() – optional pre-step to configure localization prerequisites

11. Web Server and Port Configuration UI

The wizard includes a dedicated section (within the firewall page) for configuring the ports used by the local web warning server:

Gtk::ComboBoxText m_combo_os;
Gtk::Entry        m_entry_http_port;
Gtk::Entry        m_entry_https_port;
Gtk::Button       m_btn_apply_web;
Gtk::Box          m_pg_web;
Gtk::Label        m_desc_web;
Gtk::CheckButton  m_chk_webconf;

The implementation also includes recursion guards to prevent infinite signal loops when updating the UI:

bool m_ports_guard_refresh = false;
bool updating_https = false;
bool updating_http = false;

11.1 OS/Web Server Detection and Port Synchronization

std::string detect_distro() const;
std::string detect_webserver() const;
std::pair<int,int> read_current_ports(const std::string& websrv) const;
bool update_webserver_ports(const std::string& websrv, int http_port, int https_port);
void refresh_web_ports_ui();
  • detect_distro() – identifies the current distribution for conditional behavior
  • detect_webserver() – identifies the active local web server integration (implementation-defined)
  • read_current_ports() – reads the current configured ports from the detected backend
  • update_webserver_ports() – writes updated port configuration to the backend
  • refresh_web_ports_ui() – reloads actual values and updates the UI

12. Bank List (MISP) Page

Gtk::Box         m_pg_banks;
Gtk::Label       m_desc_banks;
Gtk::CheckButton m_chk_download_banks;
Gtk::Button      m_btn_download_banks;
Gtk::Label       m_lbl_status_banks;

Provides an optional workflow for downloading a bank list at user scope, including explicit user control and status reporting.

13. Wizard Pages and Options

13.1 Pages

Gtk::Box m_pg_welcome;
Gtk::Box m_pg_resolv;
Gtk::Box m_pg_firewall;
Gtk::Box m_pg_nftables;
Gtk::Box m_pg_certs;
Gtk::Box m_pg_native;
Gtk::Box m_pg_useragent;
Gtk::Box m_pg_summary;

13.2 Option Controls

Gtk::CheckButton m_chk_resolv;
Gtk::CheckButton m_chk_firewall;
Gtk::CheckButton m_chk_enable_nftables;
Gtk::CheckButton m_chk_certs;
Gtk::CheckButton m_chk_native_host;
Gtk::CheckButton m_chk_useragent;

Gtk::Entry  m_entry_extension_id;
Gtk::Button m_btn_run_useragent;
Gtk::Button m_btn_run_nftables;

These widgets capture user intent for which actions to run. The extension ID entry is used to scope native messaging host manifests where applicable.

14. Summary, Progress, and Logs

Gtk::Label m_label_summary;
Gtk::ScrolledWindow m_log_scroll;
Gtk::TextView m_log_view;
Glib::RefPtr<Gtk::TextBuffer> m_log_buf;

Gtk::ScrolledWindow m_log_scroll_nft;
Gtk::TextView m_log_view_nft;
Glib::RefPtr<Gtk::TextBuffer> m_log_buf_nft;

The wizard maintains one or more log buffers for displaying execution output and specific subsystem logs (e.g., nftables), improving transparency and troubleshooting.

15. Sidebar Navigation

std::vector<Gtk::ToggleButton*> m_step_buttons;

Stores sidebar toggle buttons associated with each wizard step, enabling direct step navigation and state visualization.

16. Dispatchers, Worker Thread, and State

int m_page_idx = 0;
bool m_running = false;
std::thread m_worker;
Glib::Dispatcher m_dispatcher;
Glib::Dispatcher m_done_dispatcher;

std::mutex m_log_mutex;
std::vector<Glib::ustring> m_log_queue;

bool m_result_ok = false;
  • m_worker – background worker executing long-running and privileged operations
  • m_dispatcher – dispatches pending log updates to the GTK main loop
  • m_done_dispatcher – dispatches completion events to the UI thread
  • m_log_queue – thread-safe buffer for log lines produced by the worker
  • m_result_ok – final success/failure state of the wizard execution

17. Configuration Paths

std::string config_dir;
std::string config_file;

Stores the resolved configuration directory and file path used to persist wizard settings.

18. Security and Reliability Considerations

  • Privilege minimization: only the steps that require elevation should be executed as root; all other actions should remain in user context
  • Safe defaults: when uncertain (e.g., web server detection fails), the wizard should default to conservative behavior and present actionable guidance
  • Threading correctness: all GTK widget updates must occur on the main thread; dispatchers are used to safely bridge worker output to the UI
  • Input validation: user-entered ports and extension IDs must be validated to prevent injection into configuration or shell commands
  • Atomic configuration writes: wizard configuration files should be written atomically to avoid corruption on interruption
  • Transparency: logging should provide clear, user-actionable diagnostics for permission, service, and configuration errors
  • CA trust impact: installing a local CA affects system-wide TLS trust; provide clear disclosure and a supported uninstall/removal path
Published on:
Last updated on: