wizard_setup.hpp

1. Overview

The wizard_setup.hpp header defines the BastionGuard::wizard namespace, which exposes a set of helper functions used to orchestrate BastionGuard’s privileged setup wizard. This module generates and executes elevated commands required to prepare the host system for secure browsing and local enforcement, including DNS resolver overrides, firewall port configuration, certificate generation and installation, web warning server setup, phishing blacklist deployment, and native messaging host installation for browser integration.

Functionally, BastionGuard::wizard provides:

  • Generation of privileged command batches for multiple setup domains
  • Batch execution of elevated steps with optional logging
  • A high-level orchestrator to run selected setup actions
  • Idempotent/best-effort helpers for resolver, firewall, and certificate setup
  • Installation helpers for phishing blacklist files and native messaging host manifests
  • Optional installation of a local CA into the system trust store

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 <string>
#include <vector>
  • <string> – paths, option identifiers, and diagnostic output
  • <vector> – command batches and wizard option lists

4. Namespace Declaration and Scope

namespace BastionGuard::wizard { ... }

All functions are grouped under BastionGuard::wizard, indicating their purpose is to support guided system configuration and installation tasks that may require administrative privileges.

5. Command Generation Helpers

These functions generate privileged commands and append them to an output vector. The resulting batch is intended to be executed with elevation by the wizard runtime.

void gen_resolv_commands(std::vector<std::string>& out);
void gen_firewall_commands(std::vector<std::string>& out);
void gen_cert_commands(std::vector<std::string>& out);
void gen_web_commands(std::vector<std::string>& out, int http_port, int https_port);
void gen_blacklist_commands(std::vector<std::string>& out, const std::string& packaged_blacklist);
  • gen_resolv_commands() – commands to configure resolver override and backups
  • gen_firewall_commands() – commands to open required firewall ports and install rules
  • gen_cert_commands() – commands to generate and deploy local CA/server certificates
  • gen_web_commands() – commands to configure local web warning endpoints (ports)
  • gen_blacklist_commands() – commands to deploy packaged phishing blacklist data

6. Elevated Execution and Orchestration

6.1 Batch Runner

bool run_all_elevated_steps(const std::vector<std::string>& commands,
                            std::string* out_log = nullptr);

Executes a batch of commands requiring elevation. The optional out_log can be used to collect command output for diagnostics and user feedback.

6.2 Wizard Setup Orchestrator

bool run_wizard_setup(const std::vector<std::string>& options);

Executes a selected set of setup actions based on option identifiers (e.g., {"resolv","firewall","certs"}). The orchestrator typically maps each option to one or more command generation functions and then runs the resulting batch with elevation.

7. Idempotent / Best-Effort Actions

These helper functions represent individual setup actions that are intended to be safe to re-run (idempotent) or to behave as best-effort operations with robust error handling.

7.1 Resolver Override and Restore

bool setup_resolv_override();
bool restore_resolv_backup();
  • setup_resolv_override() – redirects resolver configuration to a local resolver (e.g., 127.0.0.1) via systemd-resolved or /etc/resolv.conf; requires elevation
  • restore_resolv_backup() – restores /etc/resolv.conf from a BastionGuard backup (e.g., /etc/resolv.conf.BastionGuard.bak); requires elevation

7.2 Firewall Ports and Rules

bool setup_firewall_ports();
bool install_nftables_conf();
  • setup_firewall_ports() – opens required ports (notably DNS and warning server ports) such as 53/udp and 444/tcp; requires elevation
  • install_nftables_conf() – installs nftables configuration for persistent firewall policy

7.3 Certificate Generation and Trust Store Installation

bool setup_certificates();

Generates a local Certificate Authority (CA) and server certificate for the local warning server, then attempts to install the CA into the system trust store. This operation typically requires elevation.

8. Installation Helpers

8.1 Phishing Blacklist Deployment

bool install_phishing_blacklist(const std::string& src,
                                const std::string& dst);

Installs a phishing blacklist file by copying a source file into a target destination, typically under a BastionGuard per-user data directory (e.g., ~/.local/share/BastionGuard/phishing/blacklist.txt).

8.2 Native Messaging Host Installation

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

Installs a browser native messaging host integration by generating JSON manifests for Chromium-based browsers and Firefox under the user profile directories. Manifests point to src_host (typically /usr/bin/BastionGuard-native-host) and may restrict allowed origins/extensions via an optional extension_id.

8.3 System CA Installation

bool install_system_ca(const std::string& ca_crt_path);

Installs a CA certificate into the system trust store as a standalone action. This is useful when CA deployment is separated from certificate generation. This operation typically requires elevation.

9. Typical Wizard Execution Flow

A typical setup wizard workflow may follow this sequence:

  • Collect user-selected options (resolver, firewall, certificates, web warning, blacklist)
  • Generate privileged command batches using the gen_* helpers
  • Execute the batch via run_all_elevated_steps() and collect logs
  • Perform additional best-effort steps (e.g., manifest installation) as required
  • Report success/failure with actionable error messages

10. Security and Reliability Considerations

  • Privilege boundaries: elevated steps must be minimized, audited, and scoped to only required system changes; provide clear user prompts and consent
  • Command safety: commands generated by gen_* functions must be composed from validated inputs (ports, file paths) to prevent command injection and unsafe writes
  • Idempotency: repeated wizard runs should not corrupt system state; backups and checks should be applied consistently (e.g., resolver backups)
  • Atomic file operations: configuration file updates should use atomic write patterns (temporary file + rename) to prevent partial updates
  • Rollback strategy: provide restore paths (e.g., restore_resolv_backup()) and clearly communicate recovery steps on failure
  • Transparency: capture logs and show users exactly what succeeded or failed, including permission and service restart issues
  • Trust store impact: installing a local CA affects system-wide TLS trust; ensure the CA is protected, documented, and removable through a supported uninstall path
Published on:
Last updated on: