AntiPhishingEngine.hpp

1. Overview

The AntiPhishingEngine.hpp header defines the AntiPhishingEngine class, a lightweight anti-phishing component intended to run background monitoring and provide URL analysis capabilities to the BastionGuard UI.

The engine is designed around:

  • Asynchronous execution via a dedicated worker thread (std::thread)
  • Thread-safe lifecycle control through an atomic run flag (std::atomic<bool>)
  • GUI integration through sigc::signal to publish events/messages to GTKmm widgets
  • List-based detection with an in-memory blacklist loaded from file/data sources

2. Dependencies and Includes

#include <sigc++/sigc++.h>
#include <string>
#include <thread>
#include <atomic>
#include <vector>
  • sigc++ – provides the signal mechanism used to emit events to the GUI layer
  • <thread> – worker thread used for monitoring/periodic activity
  • <atomic> – atomic run flag used to stop the thread safely
  • <vector> – storage for the in-memory blacklist entries
  • <string> – URL and message manipulation

3. Class Responsibilities

AntiPhishingEngine provides a clear separation of concerns between:

  • Lifecycle management of the monitoring thread (start()/stop())
  • On-demand URL inspection through check_url()
  • Detection primitives (blacklist and heuristic suspicion checks)
  • Event reporting to the GUI layer via a signal

4. Public Interface

4.1 Constructor and Destructor

AntiPhishingEngine();
~AntiPhishingEngine();
  • The constructor initializes internal state and prepares the engine for execution. Typical tasks include initializing running_ and preparing blacklist storage.
  • The destructor is expected to guarantee clean shutdown semantics, ensuring the worker thread does not outlive the object (e.g., by invoking stop() and joining the thread).

4.2 start()

void start();

Starts the engine execution by setting the run flag and launching the internal monitoring thread. The worker thread entrypoint is run().

Expected behavior:

  • Sets running_ to true
  • Creates worker_ and begins the monitoring loop
  • Optionally emits an informational event via sig_event_

4.3 stop()

void stop();

Stops the engine execution and terminates the worker thread in a controlled manner.

Expected behavior:

  • Sets running_ to false
  • Requests termination of the monitoring loop
  • Joins worker_ if joinable, preventing resource leaks and undefined behavior

4.4 check_url()

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

Performs analysis of a single URL and returns whether it should be considered safe or unsafe, depending on the internal detection logic.

Typical evaluation flow:

  1. Normalize or parse the input URL (implementation-dependent)
  2. Check against the in-memory blacklist via is_blacklisted()
  3. Apply heuristic detection via is_suspicious()
  4. Emit a GUI event (optional) describing the outcome

Return value: A boolean indicating match status according to the implementation policy (e.g., true = blocked/suspicious or true = safe). The concrete meaning should be documented in the implementation (.cpp) and reflected consistently in the UI.

4.5 signal_event()

sigc::signal<void(const std::string&)>& signal_event();

Exposes a signal to allow the GUI layer to subscribe to engine events/messages. This is commonly used to display status updates, detections, or operational diagnostics.

  • Signal payload: std::string (human-readable message)
  • Subscribers: GTKmm views/controllers that update labels, logs, or notifications

5. Private Implementation Details

5.1 run()

void run();

Worker thread function implementing the monitoring loop. The loop is expected to run while running_ remains true.

Typical responsibilities:

  • Periodic refresh of phishing data sources (if applicable)
  • Continuous or scheduled checks based on application workflow
  • Event emission to the GUI via sig_event_

5.2 is_blacklisted()

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

Checks whether the supplied URL matches the in-memory blacklist stored in blacklist_. The match policy can be exact, host-based, suffix-based, or pattern-based depending on the implementation.

5.3 is_suspicious()

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

Applies heuristic detection rules to identify suspicious URLs not present in the blacklist. Typical heuristics might include suspicious TLDs, punycode/IDN anomalies, excessive subdomains, IP-literal hosts, or lookalike patterns.

6. Internal State

std::thread worker_;
std::atomic<bool> running_;
sigc::signal<void(const std::string&)> sig_event_;
std::vector<std::string> blacklist_;
  • worker_ – background thread executing run()
  • running_ – atomic run flag controlling thread termination
  • sig_event_ – signal used to publish events to the GUI
  • blacklist_ – in-memory list of blocked entries loaded from file/data

7. Concurrency and Safety Considerations

  • Thread lifecycle: start() and stop() must ensure that worker_ is created and joined safely to avoid detached execution and use-after-free.
  • Signal thread-safety: if sig_event_ is emitted from the worker thread, GTK UI updates must be marshaled onto the main loop (e.g., using Glib::signal_idle() or an equivalent dispatcher), to respect GTK threading rules.
  • Blacklist access: if blacklist_ can be modified while checks are running, the implementation should protect access (e.g., mutex or copy-on-write strategy). If it is immutable after initialization, document that assumption explicitly.
  • Deterministic stop: run() should include a bounded wait strategy (sleep intervals or condition variables) to ensure stop() completes promptly.

8. Integration Notes

  • UI integration: the GUI should connect to signal_event() once and route messages into logs/status labels, optionally with severity encoding in the message format.
  • Policy clarity: ensure the boolean semantics of check_url() are consistent across callers (recommended: true = blocked/suspicious, false = allowed) and document it in both header comments and UI logic.
Published on:
Last updated on: