LeakRecord.hpp

1. Overview

The LeakRecord.hpp header defines the LeakRecord data structure, which represents a normalized identity breach or data leak event within the BastionGuard identity protection subsystem.

This structure serves as the canonical data model for storing, processing, and presenting information about compromised personal accounts and exposed datasets.

Functionally, LeakRecord provides:

  • Standardized representation of breach metadata
  • Unified severity classification model
  • Support for multi-provider aggregation
  • Compatibility with normalization and reporting pipelines
  • Type-safe handling of incident criticality

2. Dependencies and Includes

#include <string>
#include <vector>
  • <string> – textual breach metadata and descriptions
  • <vector> – container for exposed data categories

3. Structure Declaration and Scope

struct LeakRecord

LeakRecord is defined as a plain data structure (POD-style design) with public members, facilitating serialization, aggregation, and cross-module interoperability.

4. Severity Classification

4.1 Severity Enumeration

enum class Severity {
    INFO,
    LOW,
    MEDIUM,
    HIGH,
    CRITICAL
};

The Severity enumeration defines a standardized risk scale used to classify the impact of a data breach.

  • INFO – informational event with minimal risk
  • LOW – limited exposure, low immediate impact
  • MEDIUM – moderate risk, requires attention
  • HIGH – serious compromise with potential abuse
  • CRITICAL – severe breach with high likelihood of exploitation

5. Data Fields

5.1 Provider Metadata

std::string provider;

Identifies the external service or data source that reported the breach.

5.2 Breach Identification

std::string breachName;
std::string breachDate;

Provide the name and discovery date of the security incident.

  • breachName – human-readable breach identifier
  • breachDate – date of the incident (ISO 8601 recommended)

5.3 Breach Description

std::string description;

Contains a narrative summary of the incident, including affected systems, attack vectors, and known consequences.

5.4 Exposed Data Classes

std::vector<std::string> dataClasses;

Lists categories of personal or sensitive data exposed in the breach.

Typical examples include:

  • Email addresses
  • Passwords (hashed/plaintext)
  • Phone numbers
  • Financial identifiers
  • Geolocation data

5.5 Severity Indicator

Severity severity = Severity::INFO;

Stores the computed risk level associated with the breach record. Defaults to INFO when not explicitly assigned.

6. Usage Context

LeakRecord is used throughout the identity monitoring pipeline, including:

  • Provider implementations (ILeakProvider)
  • LeakAggregator result aggregation
  • LeakNormalizer consolidation logic
  • User-facing breach dashboards
  • Alerting and notification services

7. Serialization and Persistence

The structure is designed to be easily serializable into common formats such as JSON, YAML, or Protobuf by external adapters.

Field naming and typing facilitate long-term compatibility with reporting and storage systems.

8. Data Lifecycle and Normalization

LeakRecord instances typically undergo:

  • Creation by provider adapters
  • Aggregation across sources
  • Normalization and deduplication
  • Severity escalation
  • Presentation and archival

9. Auto-Update (Scheduled Refresh)

This data structure does not implement runtime behavior and does not participate directly in update scheduling.

10. Compatibility and Versioning

Future extensions to this structure should preserve backward compatibility where serialized forms are persisted.

  • New fields should be optional
  • Enumeration extensions should be additive
  • Deprecated fields should be maintained during transition periods

11. Privacy and Compliance Considerations

  • Data minimization: only essential breach metadata should be stored.
  • Regulatory compliance: handling of leak data must align with GDPR and similar regulations.
  • Access control: breach records should be accessible only to authorized components.
  • Retention policies: historical breach data should be retained only as long as necessary.

12. Runtime and Security Considerations

  • Integrity validation: incoming provider data should be verified before populating records.
  • Consistency: severity values should be assigned according to standardized scoring policies.
  • Defensive defaults: default severity (INFO) prevents overstating risk.
  • Auditability: modifications to records should be traceable when persisted.
Published on:
Last updated on: