SurePassID Compliance Manager Architecture Overview

SurePassID Authentication Server

Architecture Overview

Last Updated: June 2025

This document describes the architecture of the SurePassID Compliance Monitoring and Reporting system.

Project Structure

Solution Overview

System Architecture

+-----------------------------------------------------------------------------+
|                             Deployment Options                              |
+------------------+------------------+------------------+--------------------+
|  CLI Tool        |  Windows Service |  systemd Daemon  |  AI Agent Tools    |
|  (compliance-cli)|  (.exe)          |  (Linux)         |  (MCP Protocol)    |
+------------------+------------------+------------------+--------------------+
         |                 |                  |                    |
         +-----------------+---------+--------+--------------------+
                                     |
                                     v
                    +--------------------------------+
                    |  SurePassID.Compliance.Runner  |
                    |  (Orchestration Layer)         |
                    +--------------------------------+
                                     |
         +---------------------------+---------------------------+
         |                           |                           |
         v                           v                           v
+--------------------+  +--------------------------+  +----------------------+
|   Event Sources    |  |    Identity Providers    |  |       Reporting      |
|                    |  |                          |  |                      |
|  - JsonFile        |  |  - Active Directory      |  |  - JSON Export       |
|  - Syslog          |  |  - SurePassID            |  |  - CSV Export        |
|  - WindowsEventLog |  |                          |  |  - PDF Export        |
|  - REST API        |  |  Abstraction Layer:      |  |  - Evidence Packs    |
|  - EntraId         |  |  IIdentityProvider       |  |                      |
|                    |  +--------------------------+  +----------------------+
|  Abstraction:      |               |
|  IAuthEventSource  |               |
+--------------------+               |
           |                         |
           +------------+------------+
                        |
                        v
           +---------------------------+
           |  Correlation Engine       |
           |  (Event -> Identity)      |
           +---------------------------+
                        |
                        v
           +---------------------------+
           |  Privilege Drift          |
           |  Analyzer                 |
           |  (SurePassID Client)      |
           +---------------------------+

Core Components

1. Event Sources (SurePassID.Compliance.Events.)

Event sources implement IAuthEventSource and provide authentication events from various systems:

2. Identity Providers (SurePassID.Compliance.Identity.)

Identity providers implement IIdentityProvider and resolve users to privilege status:

3. Correlation Engine (SurePassID.Compliance.Correlation)

Correlates authentication events with identity/privilege data:

• Match by UPN (user@domain.com)
• Match by sAMAccountName
• Match by SSO Identity
• Case-insensitive, domain-prefix handling

4. Compliance Runner (SurePassID.Compliance.Runner)

Orchestrates the compliance check workflow:

1. Fetch events from configured sources (parallel when multiple enabled)
2. Get privilege snapshot from identity provider
3. Correlate events with identities
4. MFA coverage analysis (match Windows SFA logons to SurePassID MFA events)
5. Generate requested reports
6. Build evidence pack (optional)

5. Reporting (SurePassID.Compliance.Reporting)

Generates compliance reports:

Export formats: JSON, CSV, PDF, HTML

6. Monitoring (SurePassID.Compliance.Monitoring)

Real-time event streaming with alerts:

• Alert on privileged user SFA
• Alert on brute force detection
• Webhook and email notifications
• Prometheus-compatible metrics

7. CLI Tool (SurePassID.Compliance.Cli)

Command-line interface with:

8. Agent Tools (SurePassID.Compliance.Agent.Tools)

MCP-compatible tool definitions for AI agent integration:

Configuration

Configuration Methods

Configuration Flow

+-------------------+   +-------------------+   +-------------------+
|   CLI Wizard      |   |   PowerShell      |   |    Template       |
|   configure       |   |   Setup Script    |   |     File          |
+-------------------+   +-------------------+   +-------------------+
          |                       |                       |
          +-----------------------+-----------------------+
                                  |
                                  v
                     +--------------------------+
                     |    appsettings.json      |
                     +--------------------------+
                                  |
                                  v
                     +--------------------------+
                     |  Environment Variables   |
                     |  (override config)       |
                     +--------------------------+
                                  |
                                  v
                     +--------------------------+
                     |   Application Starts     |
                     +--------------------------+

Event Source Configuration

The system supports multiple simultaneous event sources via the EventSources section. When multiple sources are enabled, events are fetched in parallel and merged using AggregateEventSource.

{
  "EventSources": {
    "SurePassID": { "Enabled": true },
    "WindowsEventLog": { "Enabled": true },
    "JsonFile": { "Enabled": false, "DirectoryPath": "./Events", "FilePattern": "*.json" },
    "Syslog": { "Enabled": false }
  },
  "SurePassID": {
    "Endpoint": "https://mfa.company.com/api/mfa/v1",
    "ApiKeyId": "api-account",
    "ApiKey": "your-api-key",
    "UseHttpHeader": true,
    "MaxEventsPerRequest": 1000,
    "IgnoreSyncStatus": true,
    "PreferJsonBulkFormat": true
  },
  "WindowsEventLog": {
    "LogName": "Security",
    "ComputerNames": [],
    "IncludeSuccessfulLogons": true,
    "IncludeFailedLogons": true,
    "ExcludeMachineAccounts": true,
    "ExcludeSystemAccounts": true,
    "MaxEventsPerQuery": 10000
  }
}

Legacy support: The single-source EventSource:Type configuration is still supported for backward compatibility. When both sections exist, EventSources takes priority.

Identity Provider Configuration

{
  "ActiveDirectory": {
    "Server": "dc01.contoso.com",
    "BaseDn": "DC=contoso,DC=com",
    "UseIntegratedAuth": true,
    "UseSsl": false
  }
}

Data Flow

Compliance Check Flow

1. ComplianceRunRequest
   +-- Time range (start, end)
   +-- Privileged groups
   +-- Event source config
   \-- Report types

2. Event Ingestion
   \-- IAuthEventSource.FetchAsync(query)
       \-- Returns: List<AuthEvent>

3. Privilege Snapshot
   \-- IIdentityProvider.GetPrivilegeSnapshotAsync(query)
       \-- Returns: List<PrivilegeSnapshot>

4. Correlation
   \-- ICorrelationEngine.CorrelateAsync(events, snapshots)
       \-- Returns: List<CorrelatedAuthEvent>

4.5. MFA Coverage Analysis (optional)
   \-- IMfaCoverageCorrelator.AnalyzeMfaCoverageAsync(correlated, allEvents)
       +-- Match Windows SFA logons to SurePassID MFA events
       +-- Normalize usernames (DOMAIN\user, UPN -> login name)
       +-- Optional FindUser enrichment via REST API
       +-- Optional same-IP matching
       \-- Tags: MfaVerified, NoMfaCoverage, IntrinsicMfa

5. Report Generation
   \-- For each requested report type:
       +-- Filter correlated events
       +-- Calculate statistics
       \-- Generate report model

6. Evidence Pack (optional)
   \-- EvidencePackBuilder.BuildPackAsync(reports, options)
       +-- Write JSON reports
       +-- Generate manifest
       +-- Calculate SHA-256 hashes
       \-- Create ZIP archive

7. ComplianceRunResult
   +-- Success/failure status
   +-- Summary statistics
   +-- Report objects
   \-- Evidence pack path

Extension Points

Adding a New Event Source

1. Create a new project SurePassID.Compliance.Events.{Name}
2. Implement IAuthEventSource
3. Add DI extension method AddXxxEventSource()
4. Add enum value to EventSourceType

Adding a New Identity Provider

1. Create a new project SurePassID.Compliance.Identity.{Name}
2. Implement IIdentityProvider
3. Add DI extension method AddXxxIdentityProvider()

Adding a New Report Type

1. Add enum value to ReportType
2. Create report model in Reporting.Models
3. Add generation logic to ComplianceRunner

Dependencies

SurePassID.Compliance.Runner
+-- Events.Abstractions
+-- Identity.Abstractions
+-- Correlation
\-- Reporting

Runner.Service
+-- Runner
+-- Events.FileIngest
+-- Events.Syslog
+-- Events.RestApi
+-- Events.WindowsEventLog
\-- Identity.ActiveDirectory

Cli (with ConfigureCommand)
+-- Runner
+-- Events.FileIngest
+-- Events.RestApi
+-- Events.WindowsEventLog
\-- Identity.ActiveDirectory

Agent.Tools
+-- Runner
+-- Identity.Abstractions
+-- Events.Abstractions
\-- Reporting

McpServer
+-- Agent.Tools
+-- Runner
+-- Events.FileIngest
+-- Events.RestApi
+-- Events.WindowsEventLog
+-- Events.Syslog
+-- Events.EntraId
+-- Identity.ActiveDirectory
+-- Identity.SurePassId
\-- Correlation (MfaCoverageCorrelator)

Threading Model

• Event fetching: Async I/O
• Correlation: Single-threaded (CPU-bound, fast)
• Report generation: Single-threaded
• Evidence pack: Async file I/O
• Service: BackgroundService with cron-based scheduling
• CLI Configure: Interactive console I/O

Security Considerations

1. API Credentials: Store in user secrets, environment variables, or Azure Key Vault
2. AD Credentials: Use integrated authentication when possible
3. Evidence Packs: Include SHA-256 hashes for integrity verification
4. Logging: Avoid logging sensitive data (passwords, API keys)
5. CLI Wizard: Masks password/secret input with asterisks

SurePassID REST API Sync Behavior

The REST API event source uses SyncEventLogAsync() with three key parameters that control server-side behavior:

Server-Side Date Filtering

The startDateUtc and endDateUtc parameters are sent to the MFA server, which filters events before returning them. This reduces bandwidth compared to fetching all events and filtering client-side.

Sync Status Control (IgnoreSyncStatus)

Format Negotiation (PreferJsonBulkFormat)

The client requests JSON bulk format (format=json) which returns a structured records array with additional fields not available in the legacy piped format:

Automatic fallback: If the server does not support JSON format (older MFA server versions), it returns the SyncEventLogFormatNotSupported error code. The client:

1. Parses the piped data into records (data is not lost)
2. Caches that the server does not support JSON
3. Omits the format parameter on subsequent calls
4. Logs a warning recommending a server upgrade