native_host.hpp

1. Overview

The native_host.hpp header defines the BastionGuard::nativehost namespace, which exposes a set of functions used to implement a native host bridge for BastionGuard. The module is designed to exchange structured messages (JSON) with an external controller (e.g., a browser extension or companion process) and to perform selected privileged or system-integrated actions such as restarting services, writing configuration, and opening URLs using platform facilities.

Functionally, this module provides:

  • Structured IPC messaging using JSON payloads (read/write)
  • A native host execution entry point (run()) coordinating the message loop
  • Language configuration persistence for localization settings
  • Controlled restart of the scanner service
  • Secure URL opening via the system handler (XDG-based)

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 <nlohmann/json.hpp>
#include <filesystem>
#include <string>
  • nlohmann/json.hpp – JSON parsing and serialization for IPC messages
  • <filesystem> – filesystem path management for configuration writing
  • <string> – storage for textual parameters and error reporting

4. Namespace Declaration and Scope

namespace BastionGuard::nativehost { ... }

All functions are scoped under BastionGuard::nativehost, indicating they are part of the BastionGuard native host integration layer rather than the UI or core scanning engine.

5. IPC Messaging Interface

5.1 Read Message

nlohmann::json read_message();

Reads an incoming message from the native host transport (implementation-defined) and returns a JSON object representing the request payload.

5.2 Send Message

void send_message(const nlohmann::json& j);

Serializes and writes a JSON message to the native host transport, typically used to return responses, status updates, or errors to the external controller.

5.3 Execution Entry Point

int run();

Executes the native host message loop. This method typically coordinates repeated read/dispatch/send cycles until termination conditions are met (EOF, shutdown command, or unrecoverable error).

6. System and Configuration Operations

6.1 Language Configuration Writer

bool write_lang_config(const std::string& lang,
                       std::string& out_path,
                       std::string& out_err);

Persists a language selection setting. On success, returns true and provides the effective configuration path in out_path. On failure, returns false and sets an actionable error message in out_err.

6.2 Scanner Service Restart

int restart_scanner_service();

Requests a restart of the scanner service (implementation-defined). The return value typically represents a process exit code or a status code indicating success/failure.

6.3 Open URL via XDG

bool open_url_xdg(const std::string& url);

Opens the specified URL using the system default handler via XDG-based mechanisms (Linux desktop environments). Returns true if the request was successfully dispatched to the OS, otherwise false.

7. Execution Flow and Responsibilities

A typical high-level workflow for this module is:

  • Initialize the native host environment
  • Continuously read_message() from the IPC channel
  • Dispatch actions based on message type/command
  • Use send_message() to report results and errors
  • Exit via run() with a meaningful status code

8. Security and Reliability Considerations

  • Input validation: all incoming JSON messages must be validated (schema, required fields, types) before dispatch to avoid command injection or unsafe filesystem operations
  • Privilege boundaries: operations such as service restart may require elevated permissions; enforce authorization checks and provide explicit error reporting when not permitted
  • URL safety: open_url_xdg() should restrict allowed schemes (e.g., https) and reject potentially dangerous inputs (e.g., file:, javascript:)
  • Transport robustness: message framing and parsing should be hardened to handle partial reads, malformed payloads, and large message sizes without blocking or crashing
  • Auditability: security-relevant actions (config writes, service restarts, URL opens) should be logged with sufficient detail for troubleshooting and compliance
  • Fail-safe behavior: on errors, return structured JSON error responses and avoid leaving the system in a partially updated state
Published on:
Last updated on: