WebProbe.hpp

1. Overview

The WebProbe.hpp header defines the WebProbe class, a URL inspection and policy-enforcement component responsible for evaluating web requests against a configurable blocklist and redirecting unsafe destinations to a local warning service. The class acts as a coordination layer between URL filtering logic, user notification mechanisms, and the local warning server.

Functionally, WebProbe provides:

  • Runtime URL inspection and decision making
  • Dynamic loading and reloading of domain blocklists
  • Generation of local warning redirection URLs
  • Callback-based notification of security events
  • Thread-safe access to shared policy state

2. Dependencies and Includes

#include <string>
#include <functional>
#include <shared_mutex>
  • <string> – handling of URLs, hostnames, and redirect targets
  • <functional> – storage of user-defined notification callbacks
  • <shared_mutex> – reader/writer synchronization for concurrent access

3. Class Declaration and Scope

class WebProbe

The WebProbe class encapsulates URL validation logic and policy enforcement mechanisms. It is designed to be safely used in multi-threaded environments where multiple URL checks may occur concurrently.

4. Callback Interface

using NotifyCb = std::function<void(const std::string&,
                                   const std::string&,
                                   bool)>;

Defines the signature for security event notifications. The callback receives:

  • The original URL
  • The resolved or redirected URL
  • A boolean indicating whether the URL was blocked

5. Construction and Destruction

5.1 Constructor

explicit WebProbe(const std::string& blocklist_path_hint = "",
                  int warning_port = 81);

Initializes the probe with an optional hint for locating the blocklist file and the TCP port used by the local warning server.

5.2 Destructor

~WebProbe();

Releases internal resources and unregisters callbacks as part of object teardown.

6. Public Interface

6.1 URL Evaluation

std::string check_url(const std::string& url);

Analyzes the specified URL against the active blocklist and security policies. If the URL is allowed, it is returned unchanged. If blocked, the method returns a redirect URL pointing to the local warning server.

6.2 Blocklist Reload

void reload_blocklist(const std::string& path_hint);

Reloads the domain blocklist from the specified location. This allows runtime updates without restarting the application.

6.3 Callback Registration

void register_callback(NotifyCb cb);

Registers a notification callback that is invoked when URLs are evaluated and enforcement actions are taken.

7. Internal Helpers

7.1 Host Extraction

std::string extract_host(const std::string& raw);

Extracts and normalizes the hostname from a raw URL string for policy evaluation.

7.2 Warning Redirect Builder

std::string build_local_warning_redirect(const std::string& url) const;

Constructs a redirect URL pointing to the local warning server, embedding or referencing the original destination as needed for user context.

8. Synchronization and Internal State

int warning_port_;
mutable std::shared_mutex mutex_;
NotifyCb notify_cb_;
  • warning_port_ – TCP port of the local warning server
  • mutex_ – shared mutex protecting internal policy and callback state
  • notify_cb_ – currently registered notification callback

9. Execution Flow

A typical URL check cycle includes:

  • Acquire a shared lock for read access
  • Extract and normalize the host
  • Evaluate the host against the loaded blocklist
  • If blocked, build a local warning redirect
  • Invoke the registered callback (if present)
  • Return the final URL (original or redirected)

10. Security and Reliability Considerations

  • Thread safety: shared mutex ensures that blocklist reloads and URL checks do not race; writers should use exclusive locks
  • Input normalization: URLs must be canonicalized to prevent bypass via encoding tricks, mixed case, or embedded credentials
  • Redirect integrity: generated warning URLs must not be exploitable for open redirect or injection attacks
  • Callback isolation: notification callbacks should be resilient to errors and should not throw exceptions into the enforcement path
  • Hot reload safety: blocklist updates should use atomic file replacement to avoid partial reads during reload
  • Fail-safe policy: when blocklist state is unavailable or corrupted, the component should default to conservative (blocking) behavior
Published on:
Last updated on: