Google Safe Browsing Module (Dnsmasq Edition)

1. Overview

The GoogleSafe module provides a compatibility layer for Google Safe Browsing integration within BastionGuard. In the dnsmasq edition, remote verification is intentionally disabled to reduce network dependencies, simplify deployment, and improve runtime performance.

The module preserves its original interface and configuration logic, allowing future reactivation of the official Google Safe Browsing API without architectural changes.

2. Design Objectives

The simplified implementation is designed to:

  • Maintain API compatibility with full-featured builds
  • Avoid external HTTP dependencies
  • Reduce latency and startup overhead
  • Improve reliability in restricted or offline environments
  • Preserve configuration file semantics

3. Configuration and Initialization

3.1 Configuration Files

The module inspects user-scoped configuration files located under:

~/.config/BastionGuard/
  • google_safe.conf – stores the API key (first line)
  • google_safe_enabled – presence-based enable flag

3.2 Constructor Initialization Logic

During construction, the module performs the following steps:

  1. Builds the configuration file path using Glib::get_home_dir()
  2. Attempts to read the API key from google_safe.conf
  3. Checks for the existence of the enable flag file
  4. Wraps all I/O operations in a try/catch block for fault tolerance
  5. Defaults to a disabled state on any exception

This approach ensures safe initialization even in partially configured environments.

4. Feature Deactivation Model

4.1 Compatibility-Only Mode

Although configuration data is loaded, the module operates in a compatibility-only mode. All runtime checks are neutralized to avoid external requests.

This allows dependent components to interact with the module without requiring conditional compilation or runtime feature checks.

4.2 Runtime Status Reporting

If the enable flag is detected, a localized informational message is printed to standard output:

[GoogleSafe] Module active but disabled in this build (dnsmasq backend)

The message is processed through glib/gi18n to support internationalization.

5. Public Interface Behavior

5.1 Enabled State

The is_enabled() method always returns:

false

This guarantees that higher-level modules treat the Google Safe Browsing feature as inactive, regardless of stored configuration.

5.2 URL Safety Verification

The is_unsafe(url, threatType) method implements a stubbed behavior:

  • Input parameters are explicitly ignored
  • No remote queries are executed
  • The function always returns false

As a result, all URLs are considered safe in this build variant.

6. Re-enablement Strategy

To restore full Google Safe Browsing functionality, the following components must be reintroduced:

  • HTTP client implementation
  • API request/response handling
  • Threat classification logic
  • Error and rate-limit management
  • Secure key handling mechanisms

The existing class interface and configuration layout allow these features to be reimplemented without breaking dependent modules.

7. Runtime and Security Considerations

  • Privacy preservation: no URLs are transmitted to external services.
  • Offline compatibility: the module functions without network connectivity.
  • Attack surface reduction: removal of HTTP and parsing logic reduces exposure.
  • Forward compatibility: interface stability enables future feature restoration.
  • Fail-safe defaults: any initialization error results in a disabled state.
Published on:
Last updated on: