LeakNormalizer (Identity Leak Page)

1. Overview

The LeakNormalizer module provides canonicalization logic for BastionGuard’s Identity Leak feature. It merges and normalizes leak records collected from multiple providers (via LeakAggregator) into a single consolidated list suitable for deterministic UI rendering.

The normalizer focuses on:

  • Deduplicating records referring to the same breach
  • Merging severity in a conservative (max-impact) manner
  • Combining data class indicators across provider results

2. Data Model

2.1 LeakRecord Contract

The normalizer operates on a collection of LeakRecord objects. The implementation assumes at minimum the following fields exist:

  • breachName – canonical identifier/name of the breach
  • severity – an enum representing impact level (LeakRecord::Severity)
  • dataClasses – a list of exposed data categories (e.g., emails, passwords, IPs)

Deduplication is performed exclusively on breachName.

3. Severity Merge Policy

3.1 maxSeverity(a, b)

The normalizer defines a helper to select the highest severity value:

LeakRecord::Severity LeakNormalizer::maxSeverity(
    LeakRecord::Severity a,
    LeakRecord::Severity b
)

Implementation details:

  • Severity values are compared by converting the enum to an integer
  • The higher numeric value is treated as the higher severity

This implies an ordering contract for LeakRecord::Severity: higher enum values must represent more severe outcomes.

4. Normalization and Deduplication

4.1 normalize(input)

The main normalization entry point is:

std::vector<LeakRecord> LeakNormalizer::normalize(
    const std::vector<LeakRecord>& input
)

The function returns a consolidated list of LeakRecord objects.

4.2 Merge Strategy

The normalization routine processes input records sequentially and builds an output list (out).

For each input record (rec):

  1. Search for an existing record in out where breachName matches
  2. If none exists: append the record as-is
  3. If a match exists:
    • Update severity using maxSeverity(existing, rec)
    • Append rec.dataClasses to the existing record’s dataClasses

This approach ensures the final record for a given breach reflects the maximum severity observed across all providers and includes the union (concatenated set) of all reported data classes.

4.3 Deduplication Semantics

Deduplication is based on exact string equality of breachName. The implementation does not perform:

  • Case folding or canonicalization of breach names
  • Fuzzy matching
  • Provider-specific alias mapping

Therefore, upstream provider implementations should standardize breach naming as much as possible to maximize deduplication effectiveness.

5. Output Characteristics

5.1 Ordering

The output list preserves first-seen ordering:

  • The first occurrence of a breachName determines its position in out
  • Subsequent merges update that existing entry in place

No explicit sorting is applied by this normalizer.

5.2 Data Class Aggregation

Data classes are appended without uniqueness filtering. As a result, the output may include duplicates if multiple providers report the same data class for the same breach.

If strict uniqueness is required for UI presentation, a downstream step (or an enhanced normalizer) should:

  • Convert data classes into a set and re-materialize a unique list
  • Optionally apply canonical naming for data class labels

6. Runtime and Security Considerations

  • Conservative severity: using max severity ensures the final UI does not understate impact when providers disagree
  • Provider normalization dependency: exact-match breach names require providers to emit consistent identifiers to avoid duplicate breach entries
  • Complexity: current implementation uses a linear search over out for each record, yielding worst-case O(n²) behavior when many distinct breaches exist
  • Scalability option: if breach volume becomes large, replace the linear lookup with an index map (e.g., unordered_map<breachName, index>)
  • Data class duplication: duplicates may occur; UI layers should consider deduplication to improve clarity
  • PII context: while normalization operates on breach metadata rather than raw email inputs, output may still be sensitive and should be handled consistently with privacy policy
Published on:
Last updated on: