LeakMonitor (Identity Leak Page)

1. Overview

The LeakMonitor module implements the background monitoring loop for BastionGuard’s Identity Leak feature. It periodically queries leak/breach intelligence providers for a configured email identity and emits user-facing notifications when new exposure is detected.

The monitor is designed with:

  • Pluggable providers (via LeakAggregator)
  • Optional integration with Have I Been Pwned (HIBP) when an API key is configured
  • Always-available fallback provider (LeakCheck)
  • A conservative 24-hour polling interval implemented as an interruptible sleep loop

To reduce direct disclosure of sensitive identity information in notifications, the module uses a SHA256 hash of the email address when HIBP is enabled.

2. Components and Dependencies

The monitor integrates the following internal components:

  • LeakAggregator – provider orchestration and result normalization
  • HibpProvider – provider implementation for Have I Been Pwned (optional)
  • LeakCheckProvider – fallback provider (always used)
  • IdentityLeakConfig – configuration loader for HIBP API key
  • HashUtil – SHA256 hashing for identity anonymization in notifications

External dependencies include:

  • glib/gi18n – localization via _()
  • C++ standard threading – std::thread, std::chrono

3. Public API

3.1 Construction

The monitor is created with:

  • The identity to monitor (email)
  • A notification callback (NotifyFn)
LeakMonitor::LeakMonitor(const std::string& e, NotifyFn n)

The callback is stored using move semantics to allow flexible integration with UI or system notification backends.

3.2 start()

Starts the monitoring thread if not already running:

  • Checks running guard to prevent duplicate threads
  • Sets running = true
  • Spawns a worker thread executing LeakMonitor::loop()

3.3 stop()

Stops the monitoring loop and joins the worker thread:

  • Sets running = false
  • If the worker is joinable, joins it to ensure clean teardown

This makes the monitor deterministic and prevents detached thread lifetimes.

3.4 Destructor Behavior

The destructor calls stop() to ensure the monitoring thread is terminated before object destruction, preventing use-after-free issues.

4. Provider Setup and Capability Modes

4.1 HIBP Enablement

HIBP integration is conditional based on whether a configured API key is available:

const std::string hibpApiKey = IdentityLeakConfig::hibpApiKey();
const bool hibpEnabled = !hibpApiKey.empty();

If enabled, the monitor registers a HIBP provider:

aggregator.addProvider(std::make_unique<HibpProvider>(hibpApiKey));

4.2 LeakCheck Fallback Provider

The LeakCheckProvider is always added and serves as a baseline fallback capability:

aggregator.addProvider(std::make_unique<LeakCheckProvider>());

This ensures the monitoring feature remains operational even when the HIBP API key is missing.

4.3 Capability Signaling

Upon startup, the monitor emits a notification describing its operating mode:

  • Full mode: HIBP + LeakCheck
  • Limited mode: LeakCheck only (HIBP key missing)

This improves user transparency and supports troubleshooting.

5. Identity Anonymization

5.1 Email Hashing

The module computes a SHA256 hash of the monitored email:

const std::string emailHash = HashUtil::sha256(email);

When HIBP is enabled and a leak is detected, the notification includes the hash (not the raw email), reducing inadvertent exposure of personally identifiable information through UI notifications or logs.

5.2 Mode-Specific Messaging

When operating in limited mode (LeakCheck only), the monitor intentionally avoids presenting identity hash context and instead prompts the user to perform manual verification.

6. Monitoring Loop

6.1 Periodic Query Execution

The main loop runs while running remains true:

  • Queries all providers via aggregator.queryAll(email)
  • If the resulting leak list is non-empty, emits a notification
  • Exceptions are caught and reported via the notification callback

The module treats any non-empty leak set as a signal to notify. Detection of “new vs known” leaks is not performed at this layer.

6.2 Error Handling

Any exception thrown by provider calls or normalization is caught and reported:

notify("Error monitor Identity Leak: " + ex.what());

This prevents thread termination due to unhandled exceptions and keeps the monitoring process resilient.

6.3 Interruptible 24-hour Sleep

After each check, the loop sleeps for approximately 24 hours using an interruptible minute-based loop:

  • Iterates for 24 * 60 minutes
  • Sleeps std::chrono::minutes(1) per iteration
  • Checks running between iterations to allow quick stop responsiveness

This approach prevents the monitor from being stuck in a single long sleep when stop is requested.

7. Shutdown Semantics

When the loop terminates (due to running becoming false), the monitor emits a final notification:

"Monitor Identity Leak stopped"

This confirms termination to the user/UI layer.

8. Runtime and Security Considerations

  • PII minimization: notifications use SHA256(email) in full mode to reduce exposure of personal identifiers
  • Provider privacy: provider implementations may transmit the email (or derived data) to third-party services; user consent and privacy policy alignment should be enforced at the configuration/UI layer
  • Fallback transparency: limited mode explicitly warns users when HIBP is not configured
  • Thread safety: the monitor uses a simple running flag; if accessed concurrently from multiple threads, the flag should be atomic or guarded (current design assumes start/stop are called from a single controller thread)
  • Notification abstraction: NotifyFn decouples monitoring from UI details, enabling reuse in headless service contexts
  • Polling model: 24-hour polling reduces API load and aligns with typical breach data update cadence, but does not provide real-time guarantees
  • “New leak” semantics: the current logic notifies on any non-empty result set; tracking of previously seen breaches should be implemented if repetitive alerts must be suppressed
Published on:
Last updated on: