Skip to content

ARCHITECTURE_DIAGRAM.md

Latest commit

 

History

History
346 lines (317 loc) · 11.6 KB

ARCHITECTURE_DIAGRAM.md

File metadata and controls

346 lines (317 loc) · 11.6 KB
Raw

Certificate Enumeration Architecture

Data Flow Diagram

???????????????????????????????????????????????????????????????
?          Windows Device (Client) ?
?          ?
?  ?????????????????????????????????????????????????????????? ?
?  ?         ReportBuilder.BuildAsync() ? ?
?  ?????????????????????????????????????????????????????????? ?
?  ?   ?
?         ???????????????????????????????????????             ?
?    ?            ?     ?              ?
?         ?  ?          ?   ?
????????????????  ????????????????  ????????????????       ?
?  ?  Registry   ?  ? Event Logs ?  ? Certificates ? ?NEW ?
?  ?  Snapshot   ?  ?    Reader    ?  ?  Enumerator  ?       ?
?  ???????????????  ????????????????  ????????????????       ?
?         ?           ?   ?     ?
?         ?       ? ?        ?
?         ?        ?        ?              ?
?  ???????????????????????????????????????????????????????    ?
?  ?         SecureBootStatusReport           ?    ?
?  ?  ??????????????????????????????????????????????    ?    ?
?  ?  ? DeviceIdentity: Hardware & Org Tags        ?    ?    ?
?  ?  ??????????????????????????????????????????????    ?    ?
?  ?? SecureBootRegistrySnapshot: Deploy Status  ?    ?    ?
?  ?  ??????????????????????????????????????????????    ?    ?
?  ?  ? SecureBootCertificateCollection ? NEW  ?    ?    ?
?  ?  ?  • SignatureDatabase (db)                  ?    ?    ?
?  ?  ?  • ForbiddenDatabase (dbx)            ?    ?    ?
?  ?  ?  • KeyExchangeKeys (KEK)    ?    ?    ?
?  ?  ?  • PlatformKeys (PK)    ?    ?    ?
?  ?  ?  • Statistics (total, expired, expiring)   ?    ?    ?
?  ?  ??????????????????????????????????????????????    ?    ?
?  ?  ? Events: Windows Event Log Records   ?    ?    ?
?  ?  ??????????????????????????????????????????????    ?    ?
?  ?  ? Alerts: Generated Warnings      ?    ?    ?
?  ?  ??????????????????????????????????????????????    ?    ?
?  ???????????????????????????????????????????????????????    ?
?            ?  ?
?????????????????????????????????????????????????????????????????
      ? HTTP POST / Azure Queue
      ?
???????????????????????????????????????????????????????????????
?         Dashboard API (.NET 8)       ?
?       ?
?  ?????????????????????????????????????????????????????????? ?
?  ?         IReportStore (EfCore or File)          ? ?
?  ?????????????????????????????????????????????????????????? ?
?          ?       ?
?     ???????????????????????????????????????    ?
?         ??          ?
?  ???????????????????       ????????????????      ?
?  ?  SQL Database   ?      ?  File Store  ?      ?
?  ?        ?        ?    (JSON)    ?      ?
?  ?  SecureBootReports     ?     ?      ?
?  ?  ?? RegistryStateJson         ?           ?      ?
?  ?  ?? CertificatesJson ? NEW ?         ?      ?
?  ?  ?? AlertsJson     ?     ?    ?
?  ?  ?? Events (FK)            ??      ?
?  ???????????????????         ????????????????      ?
???????????????????????????????????????????????????????????????
     ? REST API
   ?
???????????????????????????????????????????????????????????????
?         Dashboard Web (Razor Pages)         ?
? ?
?  ????????????????  ????????????????  ????????????????      ?
?  ?  Devices     ?  ?   Reports    ?  ? Certificates ? ?NEW?
?  ?   List     ?  ?    List      ?  ?   Details    ?      ?
?  ????????????????  ????????????????  ????????????????      ?
???????????????????????????????????????????????????????????????

Certificate Enumeration Flow

PowerShellSecureBootCertificateEnumerator.EnumerateAsync()
    ?
    ??? Confirm-SecureBootUEFI
    ?       ??? Returns: True/False/Error
    ?
    ??? For each database (db, dbx, KEK, PK):
    ?   ?
    ? ??? Get-SecureBootUEFI -Name <database>
    ?   ?       ??? Returns: Base64-encoded EFI_SIGNATURE_LIST
    ?   ?
?   ??? Parse EFI_SIGNATURE_LIST binary structure
    ?   ?   ?? Read Signature Type GUID
    ?   ?   ?? Read List/Header/Signature sizes
    ?   ?   ?? Skip header
    ?   ?   ?? For each signature entry:
 ?   ?       ?? Read Owner GUID (16 bytes)
    ??       ?? Read Certificate Data
    ?   ?
    ?   ??? Parse X.509 Certificates
    ?       ?? Create X509Certificate2 object
    ?       ?? Extract: Thumbprint, Subject, Issuer, Dates
    ?       ?? Calculate: IsExpired, DaysUntilExpiration
    ?       ?? Detect: IsMicrosoftCertificate
    ?       ?? Store: Base64-encoded raw data
  ?
    ??? Calculate Statistics
  ?   ?? TotalCertificateCount
    ?   ?? ExpiredCertificateCount
    ?   ?? ExpiringCertificateCount (within 90 days)
    ?
    ??? Return SecureBootCertificateCollection

Certificate Data Model

SecureBootCertificate
??? Database: string        // "db", "dbx", "KEK", "PK"
??? Thumbprint: string         // SHA-1 hash (e.g., "ABC123...")
??? Subject: string         // "CN=Microsoft Windows..."
??? Issuer: string             // "CN=Microsoft Root CA..."
??? SerialNumber: string                 // Certificate serial
??? NotBefore: DateTimeOffset     // Valid from
??? NotAfter: DateTimeOffset       // Expires on
??? SignatureAlgorithm: string           // "sha256RSA"
??? PublicKeyAlgorithm: string     // "RSA", "ECC"
??? KeySize: int          // 2048, 4096
??? IsExpired: bool        // true/false
??? DaysUntilExpiration: int           // Positive=future, Negative=past
??? Version: int        // X.509 version (usually 3)
??? IsMicrosoftCertificate: bool    // Detected by Subject/Issuer
??? RawData: string      // Base64-encoded DER format

SecureBootCertificateCollection
??? SignatureDatabase: SecureBootCertificate[]        // db
??? ForbiddenDatabase: SecureBootCertificate[] // dbx
??? KeyExchangeKeys: SecureBootCertificate[]          // KEK
??? PlatformKeys: SecureBootCertificate[]      // PK
??? CollectedAtUtc: DateTimeOffset
??? SecureBootEnabled: bool?
??? TotalCertificateCount: int (calculated)
??? ExpiredCertificateCount: int
??? ExpiringCertificateCount: int
??? ErrorMessage: string?

UEFI Database Roles

???????????????????????????????????????????????????????????????
?  UEFI Secure Boot Chain          ?
???????????????????????????????????????????????????????????????

PK (Platform Key)
??? Owner of the platform
    ??? Can update KEK
        ?
 ?
    KEK (Key Exchange Keys)
    ??? Trusted by platform owner
        ??? Can update db and dbx
    ?
        ?????????????????????????????????????????????
    ?            ?       ?
     db (Authorized)       dbx (Forbidden)       [Boot Loader]
    ??? Signatures        ??? Blocked            ??? If signed by db
    allowed to            signatures              AND NOT in dbx
            boot        (revoked)   ? Boot allowed
           ? else BLOCKED

Database Descriptions

Database Purpose Typical Contents
PK Platform ownership 1 certificate (OEM or organization)
KEK Update authorization 2-5 certificates (Microsoft, OEM)
db Boot authorization 10-20 certificates (OS vendors, hardware)
dbx Revocation list 100-300 entries (hashes + revoked certs)

Alert Generation Logic

ReportBuilder.PopulateAlerts()
    ?
    ??? Registry Alerts
    ?   ?? DeploymentState == Error ? "Error code X"
    ?   ?? DeploymentState == NotStarted ? "Update not started"
    ?   ?? HighConfidenceOptOut ? "Opted out"
    ?   ?? MicrosoftUpdateManagedOptIn ? "CFR enrolled"
    ?
    ??? Event Alerts
    ?   ?? Events.Count == 0 && !Updated ? "No events detected"
    ?
    ??? Certificate Alerts ? NEW
?? SecureBootEnabled == false ? "Secure Boot not enabled"
    ?? ExpiredCertificateCount > 0 ? "X expired certificate(s)"
        ?? ExpiringCertificateCount > 0 ? "X expiring within 90 days"
        ?? ErrorMessage != null ? "Enumeration error: ..."

Storage Schema

-- Database Table Structure

TABLE Devices
?? Id: uniqueidentifier (PK)
?? MachineName: nvarchar(256)
?? DomainName: nvarchar(256)
?? Manufacturer: nvarchar(256)
?? Model: nvarchar(256)
?? FirmwareVersion: nvarchar(256)
?? ... (other device metadata)

TABLE SecureBootReports
?? Id: uniqueidentifier (PK)
?? DeviceId: uniqueidentifier (FK ? Devices)
?? RegistryStateJson: nvarchar(max)
?? CertificatesJson: nvarchar(max) ? NEW
?? AlertsJson: nvarchar(max)
?? DeploymentState: nvarchar(64)
?? CreatedAtUtc: datetimeoffset
?? ... (other report metadata)

TABLE SecureBootEvents
?? Id: uniqueidentifier (PK)
?? ReportId: uniqueidentifier (FK ? SecureBootReports)
?? ProviderName: nvarchar(256)
?? EventId: int
?? ... (other event metadata)

API Response Structure

{
  "id": "guid",
  "device": {
    "machineName": "DESKTOP-ABC123",
    "domainName": "CONTOSO",
    "manufacturer": "Dell Inc.",
    "model": "OptiPlex 7090",
    "firmwareVersion": "1.2.3"
  },
  "registry": {
    "availableUpdates": 1,
    "uefiCa2023StatusRaw": "Updated",
    "deploymentState": "Updated"
  },
  "certificates": {
    "signatureDatabase": [
      {
  "database": "db",
        "thumbprint": "46DEF63B5CE61CF43BA0A95C...",
   "subject": "CN=Microsoft Windows Production PCA 2011, O=Microsoft Corporation",
        "issuer": "CN=Microsoft Root Certificate Authority 2010, O=Microsoft Corporation",
   "notBefore": "2011-10-19T18:41:42+00:00",
        "notAfter": "2026-10-19T18:51:42+00:00",
   "signatureAlgorithm": "sha256RSA",
        "publicKeyAlgorithm": "RSA",
  "keySize": 2048,
        "isExpired": false,
  "daysUntilExpiration": 731,
 "version": 3,
        "isMicrosoftCertificate": true
      }
    ],
    "forbiddenDatabase": [ /* dbx entries */ ],
"keyExchangeKeys": [ /* KEK entries */ ],
    "platformKeys": [ /* PK entry */ ],
    "totalCertificateCount": 15,
    "expiredCertificateCount": 0,
    "expiringCertificateCount": 0,
    "secureBootEnabled": true,
    "collectedAtUtc": "2024-01-15T10:30:00Z"
  },
  "events": [ /* event records */ ],
  "alerts": [],
  "createdAtUtc": "2024-01-15T10:30:00Z",
  "clientVersion": "1.0.0.0",
  "correlationId": "abc123..."
}

Deployment Architecture

Development
    ?
    ??? dotnet build
    ??? dotnet test (7 unit tests)
    ??? dotnet ef migrations add AddCertificateCollection
        ?
        ?
?????????????????????????????????????????????????????????????
?  Production          ?
?????????????????????????????????????????????????????????????
?        ?
?  1. Database Migration      ?
???? dotnet ef database update   ?
?         ??? Adds CertificatesJson column           ?
?           ?
?  2. Deploy API (Azure App Service / IIS)          ?
?     ??? dotnet publish -c Release ?
?         ??? Handles certificate JSON storage   ?
?            ?
?  3. Deploy Client (Group Policy / Intune / SCCM)          ?
?     ??? dotnet publish -r win-x86      ?
?         ??? Automatically enumerates certificates         ?
?            ?
?4. Monitor & Alerts   ?
?     ??? Dashboard shows certificate inventory         ?
?         ??? Expired certificate warnings  ?
?         ??? Expiring soon alerts    ?
?         ??? Secure Boot status        ?
?             ?
?????????????????????????????????????????????????????????????

Summary

This implementation provides:

? Complete Separation of Concerns

  • Device metadata ? DeviceIdentity
  • Deployment status ? SecureBootRegistrySnapshot
  • Certificate inventory ? SecureBootCertificateCollection
  • Event logs ? SecureBootEventRecord

? Comprehensive Certificate Data

  • All four UEFI databases (db, dbx, KEK, PK)
  • Full X.509 certificate properties
  • Expiration tracking and alerts
  • Microsoft certificate detection

? Production-Ready

  • Zero-config client deployment
  • Backward compatible API/database
  • Graceful error handling
  • Well-documented and tested

? Compliance & Security

  • Certificate lifecycle tracking
  • Early expiration warnings
  • Unauthorized certificate detection
  • Audit trail and reporting