PhishingPage.hpp

1. Overview

The PhishingPage.hpp header defines the PhishingPage class, a GTKmm (GTK4) UI page responsible for orchestrating a phishing URL analysis workflow. It integrates a reusable PhishingCheckCard input component with a result display area and internal parsing utilities used to retrieve, normalize, and present phishing analysis output.

Functionally, PhishingPage provides:

  • A complete page-level interface for phishing URL inspection
  • Integration with PhishingCheckCard for user-driven analysis requests
  • Remote content retrieval and response parsing helpers
  • Structured extraction of phishing classification and severity metadata
  • Text-based result rendering and operational status reporting
  • Lifecycle-aware state handling through an atomic destruction flag

2. Dependencies and Includes

#include <regex>
#include <gtkmm.h>
#include <atomic>
#include <optional>
#include "PhishingCheckCard.hpp"
  • <regex> – regular expression support for structured extraction from HTML/text responses
  • gtkmm.h – GTK4 C++ widgets, layouts, labels, text views, and scrolled containers
  • <atomic> – atomic state management for safe lifecycle checks during asynchronous or delayed operations
  • <optional> – optional return values for pattern extraction helpers
  • PhishingCheckCard.hpp – reusable phishing input card embedded in the page

3. Class Declaration and Scope

class PhishingPage : public Gtk::Box

The class derives from Gtk::Box, making it suitable as a standalone page in a notebook, stack, application window, or security dashboard layout.

PhishingPage acts as a controller/view composite: it owns the phishing input card, receives analysis requests, invokes parsing and content processing helpers, and updates the UI with the resulting report.

4. Public Interface

4.1 Constructor and Destructor

PhishingPage();
virtual ~PhishingPage();

The constructor initializes the phishing analysis page, configures its widgets, connects the request signal from PhishingCheckCard, and prepares the output area. The destructor is virtual and intended to safely finalize the component lifecycle.

Since the class stores an atomic destruction flag, destruction is expected to coordinate safely with any in-progress or deferred operations that may outlive immediate UI interactions.

5. Internal Data Model

5.1 ParsedResult Structure

struct ParsedResult {
    Glib::ustring classification;
    Glib::ustring severity;
    Glib::ustring normalized_host;
    Glib::ustring evaluation_chain;
    Glib::ustring matched_indicator;
    Glib::ustring live_probe_status;
    Glib::ustring live_probe_text;
    Glib::ustring report_text;
};

The nested ParsedResult structure encapsulates the normalized output of a phishing analysis response after parsing. It provides a structured representation of the most relevant analysis fields extracted from the remote or processed result.

  • classification – high-level phishing verdict or category
  • severity – severity level associated with the analysis result
  • normalized_host – canonicalized host/domain derived from the analyzed URL
  • evaluation_chain – textual summary of the rule or decision chain used in evaluation
  • matched_indicator – specific indicator or rule match associated with the result
  • live_probe_status – status of any live probing or remote reachability check
  • live_probe_text – human-readable detail associated with the live probe result
  • report_text – final consolidated report text suitable for UI presentation

6. User Action Handling

void on_analyze_requested(const Glib::ustring& url);

This callback is invoked when the embedded PhishingCheckCard emits an analysis request. It serves as the main entry point for the phishing inspection workflow.

The method is expected to:

  • Receive and validate the submitted URL
  • Trigger retrieval of remote or generated analysis content
  • Parse the resulting HTML/text payload
  • Format and display the extracted report inside the output view
  • Update the page status label with progress, success, or failure information

7. Parsing and Content Processing Helpers

PhishingPage declares a set of static helper methods dedicated to encoding, retrieval, normalization, and structured extraction of phishing analysis results.

7.1 URL and Remote Retrieval Helpers

static std::string url_encode(const std::string& s);
static std::string fetch_url_body(const std::string& url);
  • url_encode() – applies URL encoding to a string before remote submission or query composition
  • fetch_url_body() – retrieves the response body from a target URL; implementation-defined transport/network layer

7.2 HTML/Text Cleanup Helpers

static std::string html_entity_decode(std::string s);
static std::string strip_tags(const std::string& s);
static std::string trim_copy(const std::string& s);

These methods normalize raw response content before parsing:

  • html_entity_decode() – decodes HTML entities into plain text characters
  • strip_tags() – removes HTML/XML tags from markup content
  • trim_copy() – returns a trimmed copy of a string with surrounding whitespace removed

7.3 Pattern Extraction Helpers

static std::optional<std::string> extract_first(
    const std::string& text,
    const std::regex& re,
    int group = 1);

static std::vector<std::string> extract_all_li_after_label(
    const std::string& html,
    const std::string& label);
  • extract_first() – returns the first regex match group found in the supplied text, wrapped in std::optional to represent successful or missing extraction
  • extract_all_li_after_label() – extracts multiple list item values that appear after a specific label in an HTML fragment, useful for parsing structured phishing report sections

7.4 Result Parsing

static ParsedResult parse_result_html(const std::string& html);

Parses an HTML analysis response and converts it into a normalized ParsedResult. This method is the central transformation layer between raw phishing result markup and the structured data shown in the page UI.

The implementation is expected to combine regex extraction, HTML cleanup, and field normalization in order to produce a concise, user-readable report.

8. UI Components

PhishingPage is composed of a page title, the phishing input card, a scrollable text output area, and a status label for runtime feedback.

8.1 Header and Input Section

Gtk::Label lbl_title_;
PhishingCheckCard phishing_card_;
  • lbl_title_ – page-level heading identifying the phishing analysis section
  • phishing_card_ – embedded reusable input card that collects URLs and emits analysis requests

8.2 Output Display

Gtk::ScrolledWindow scroller_;
Gtk::TextView txt_output_;

These widgets provide a scrollable textual result area used to display phishing analysis reports, extracted metadata, or detailed formatted findings.

  • scroller_ – scroll container ensuring long reports remain accessible
  • txt_output_ – multi-line text view used to render parsed output content

8.3 Status Reporting

Gtk::Label lbl_status_;

Displays operational feedback such as waiting state, active analysis, successful parsing, network retrieval failures, invalid content handling, or unexpected processing errors.

9. Internal State and Lifecycle Safety

std::atomic<bool> destroyed_{false};

The destroyed_ flag tracks whether the page is in teardown or has already been destroyed. This is particularly relevant in contexts where analysis requests, UI updates, or background tasks may complete after the widget has begun destruction.

By using an atomic boolean, the class can implement lightweight concurrency-safe guards to prevent invalid access to GTK widgets during or after object teardown.

10. Interaction Model

The page follows a clear interaction sequence:

  • The user enters a URL through PhishingCheckCard
  • The card emits signal_analyze_requested
  • PhishingPage receives the request through on_analyze_requested()
  • The page retrieves and parses the relevant analysis content
  • The parsed result is formatted and written into txt_output_
  • lbl_status_ reflects the current processing state and final outcome

This design centralizes orchestration inside the page while delegating user input collection to a reusable card component.

11. Runtime and Security Considerations

  • Remote content trust: any HTML or text retrieved from external sources should be treated as untrusted input and sanitized before presentation.
  • HTML parsing robustness: regex-based extraction should handle partial, malformed, or unexpected response structures gracefully.
  • UI thread safety: any network retrieval or delayed processing must ensure that GTK widget updates occur safely with respect to the main thread and object lifetime.
  • Lifecycle protection: the destroyed_ atomic flag should be checked before applying late UI updates from ongoing tasks.
  • Output clarity: phishing reports should distinguish clearly between verdict, severity, matched indicators, and probe results to support rapid operator interpretation.
  • Error transparency: failures in retrieval, parsing, or empty responses should produce actionable status text rather than silent failure.
Published on:
Last updated on: