Simplify main state machine and add dedicated subsections for licensing, forwarder, and temporal state machines

2026-09-25 22:10:50 +02:00
parent 871d3c15ab
commit 5fe74325ec
1 changed files with 158 additions and 37 deletions
@@ -8,7 +8,11 @@
 ## Table of Contents
 1. [Core Purpose & Philosophy (Log-Zusammenführung & Bereitstellung)](#core-purpose--philosophy)
 2. [End-to-End System Architecture](#end-to-end-system-architecture)
-3. [System State Machine & Enrollment Lifecycle](#system-state-machine--enrollment-lifecycle)
+3. [System State Machines & Subsystem Lifecycles](#system-state-machines--subsystem-lifecycles)
+   - 3.1 [High-Level Overview State Machine](#31-high-level-system-state-machine)
+   - 3.2 [Master License Authority & WebSocket Enrollment State Machine](#32-master-license-authority--websocket-enrollment-state-machine)
+   - 3.3 [Edge Forwarder Auto-Enrollment & mTLS Lifecycle State Machine](#33-edge-forwarder-auto-enrollment--mtls-lifecycle-state-machine)
+   - 3.4 [Fleet Log Aggregation, 12h Temporal Window & AI Provisioning State Machine](#34-fleet-log-aggregation-12h-temporal-window--ai-provisioning-state-machine)
 4. [Master License Authority & PKI Fleet Licensing](#master-license-authority--pki-fleet-licensing)
 5. [mTLS 1.3 Transport Security & Forwarder Auto-Enrollment](#mtls-13-transport-security--forwarder-auto-enrollment)
 6. [Cloud-Side Temporal Persistence & Direct Hermes Reasoning](#cloud-side-temporal-persistence--direct-hermes-reasoning)
@@ -97,53 +101,170 @@ graph TB

 ---

-## System State Machine & Enrollment Lifecycle
+## System State Machines & Subsystem Lifecycles

-### 1. Hierarchical Licensing & Forwarder Enrollment State Machine
+### 3.1 High-Level System State Machine
+A simplified macroscopic view of the end-to-end LOGAR lifecycle:

 ```mermaid
 stateDiagram-v2
-    [*] --> AuthorityBootstrap: Operator creates Bootstrap .lic
+    [*] --> 1_PKI_Licensing: Master Authority generates Bootstrap .lic Package
+    1_PKI_Licensing --> 2_Hub_Ready: Server Hub imports .lic & signs Sub-CA over WebSocket
+    2_Hub_Ready --> 3_Edge_Enrollment: Edge Forwarders auto-enroll & lease licensed seats
+    3_Edge_Enrollment --> 4_mTLS_Streaming: Forwarders stream framed logs over mTLS 1.3 (:9443)
+    4_mTLS_Streaming --> 5_Temporal_Aggregation: Server Hub normalizes & correlates logs in 12h window
+    5_Temporal_Aggregation --> 6_AI_Provisioning: Logs provisioned to Hermes AI via GET /api/hermes/report
+    6_AI_Provisioning --> 4_mTLS_Streaming: Continuous operational loop
+```
+
+---
+
+### 3.2 Master License Authority & WebSocket Enrollment State Machine
+Details the bidirectional cryptographic enrollment, seat leasing, and hot-reload lifecycle between `logar.eibl.tech` and the LOGAR Server Hub:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle_Unlicensed: Server Hub initial launch (no active license)
    
-    state "Master License Authority (logar.eibl.tech)" as AuthState {
-        AuthorityBootstrap --> PackageGenerated: Generates Communication Keypair + CSR Template + Tenant ID
-        PackageGenerated --> WebSocketListening: Authority awaits Server Hub on /ws/license
+    state "Master Authority (logar.eibl.tech)" as MasterAuth {
+        BootstrapGenerated: Generates Bootstrap .lic with Comm Cert & CSR Template
+        WS_Listening: WebSocket Hub listening on /ws/license
+        ValidateCSR: Validates Server CSR & Hardware Fingerprint
+        SignSubCA: Signs Sub-CA with OID_LOGAR_SEATS (1.3.6.1.4.1.59999.1.1)
    }
-    
-    state "LOGAR Server Hub" as HubState {
-        PackageGenerated --> ServerImportLic: Admin imports .lic package on Server Hub
-        ServerImportLic --> ServerCSRGenerated: Server generates local Sub-CA Keypair & CSR
-        ServerCSRGenerated --> WSConnecting: Connects to Authority via wss://logar.eibl.tech/ws/license
-        WSConnecting --> SubCASigned: Authority signs Sub-CA with embedded Seat OID & returns Master CA
-        SubCASigned --> HubReady: Hub starts mTLS Listener (Port 9443) & Provisioning API (Port 8443)
+
+    state "LOGAR Server Hub PKI Engine" as ServerPKI {
+        ImportLic: Admin imports .lic file via CLI or WebUI
+        GenerateLocalCSR: Server generates local Sub-CA Keypair & CSR
+        WS_Connecting: Opens WebSocket to wss://logar.eibl.tech/ws/license
+        InstallSubCA: Installs signed Sub-CA Cert & Master Root Trust
+        ActivateSeatQuota: Parses Seat OID & initializes SQLite seat quota
+        mTLS_Listening: Starts mTLS 1.3 Listener on Port 9443
        
-        HubReady --> SeatLeaseRequested: Edge Forwarder sends Enrollment Request
-        state SeatLeaseRequested <<choice>>
-        SeatLeaseRequested --> SeatGranted: Active Seats < Max Seats
-        SeatLeaseRequested --> SeatRejected: Active Seats >= Max Seats
+        HeartbeatSync: Sends periodic check_updates heartbeat over WebSocket
+        InFlightReload: Hot-reloads ssl.SSLContext without restarting service
        
-        SeatGranted --> ClientCertIssued: Server signs Client Cert (CN=client_id) & registers in clients table
-        SeatRejected --> HubReady: Drops enrollment with HTTP 403 Seat Limit Exceeded
+        RevokedState: License revoked by Master Authority
+        DropConnections: Drops all incoming mTLS connections immediately
+    }
+
+    BootstrapGenerated --> ImportLic: Operator deploys .lic
+    ImportLic --> GenerateLocalCSR
+    GenerateLocalCSR --> WS_Connecting
+    WS_Connecting --> WS_Listening: action="enroll_or_sync"
+    WS_Listening --> ValidateCSR
+    ValidateCSR --> SignSubCA
+    SignSubCA --> InstallSubCA: status="success", ca_cert, master_root_ca
+    InstallSubCA --> ActivateSeatQuota
+    ActivateSeatQuota --> mTLS_Listening
+    
+    mTLS_Listening --> HeartbeatSync: Scheduled or manual sync
+    HeartbeatSync --> WS_Listening: action="check_updates"
+    WS_Listening --> InFlightReload: Updated seat quota / renewed cert
+    InFlightReload --> mTLS_Listening
+    
+    WS_Listening --> RevokedState: Authority revokes license_id
+    RevokedState --> DropConnections
+```
+
+---
+
+### 3.3 Edge Forwarder Auto-Enrollment & mTLS Lifecycle State Machine
+Details how edge nodes discover their identity, bootstrap mTLS trust, and stream logs without local state:
+
+```mermaid
+stateDiagram-v2
+    [*] --> HostDiscovery: Edge Client (Win_Client / Linux_Client) launches
+    
+    state "Machine & Domain Identification" as Disc {
+        HostDiscovery --> QueryFQDN: socket.getfqdn()
+        QueryFQDN --> OS_DomainDiscovery: Windows AD env / Linux resolv.conf
+        OS_DomainDiscovery --> BuildClientID: Computes FQDN client_id & Site Attribution
+    }
+
+    state "Zero-Touch Enrollment" as Enroll {
+        CheckLocalCert: Inspects certs/client.crt & certs/ca.crt
+        EnrollRequest: POST /api/client/enroll with enrollment_secret
+        VerifyQuota: Server verifies secret & active_seats < max_seats
+        StoreCerts: Saves client.crt, client.key, ca.crt
+    }
+
+    state "Secure Streaming & Self-Healing" as Stream {
+        mTLS_Handshake: Mutual TLS 1.3 Handshake (Port 9443)
+        ValidateClientCN: Server checks client_id status in clients table
+        ActiveStreaming: Streams candidate log frames (INFO..CRITICAL)
+        CertExpiryCheck: Checks client cert validity before each run
+        ProactiveRenew: Renews cert when expiring in < 30 days
+        ReactiveSelfHeal: Re-enrolls automatically on CA rotation / handshake error
+    }
+
+    BuildClientID --> CheckLocalCert
+    CheckLocalCert --> mTLS_Handshake: Valid local certificates exist
+    CheckLocalCert --> EnrollRequest: Certificates missing or expired
+    EnrollRequest --> VerifyQuota
+    VerifyQuota --> StoreCerts: 200 OK (Certificate Issued)
+    VerifyQuota --> [*]: 403 Forbidden (Seat Quota Full / Bad Secret)
+    StoreCerts --> mTLS_Handshake
+    
+    mTLS_Handshake --> ValidateClientCN
+    ValidateClientCN --> ActiveStreaming: Client active in DB
+    ValidateClientCN --> [*]: Client seat revoked
+    
+    ActiveStreaming --> CertExpiryCheck
+    CertExpiryCheck --> ProactiveRenew: Expiry < 30 days
+    ProactiveRenew --> EnrollRequest
+    ActiveStreaming --> ReactiveSelfHeal: Handshake failure / CA changed
+    ReactiveSelfHeal --> EnrollRequest
+```
+
+---
+
+### 3.4 Fleet Log Aggregation, 12h Temporal Window & AI Provisioning State Machine
+Details how log events are extracted, deduplicated, temporally tracked, and provisioned directly to Hermes AI:
+
+```mermaid
+stateDiagram-v2
+    [*] --> EventCaptured: Windows Event Log / Linux journalctl event
+    
+    state "Edge Filtering (Zero State)" as EdgeFilter {
+        EventCaptured --> NoiseStripping: Discards DEBUG, trace logs & events > 24h old
+        NoiseStripping --> FrameEncoding: Normalizes to JSON frame (severity, site, server, signature)
+    }
+
+    state "Server Ingestion & 12h Temporal Window" as ServerIngest {
+        FrameIngested: mTLS Socket reads length-prefixed frame
+        ComputeFingerprint: Fingerprint = {site}:{server}:{signature}
+        EvaluateTemporalWindow: Compares (now - last_seen) against 12h window
        
-        HubReady --> LiveSeatUpdate: Authority pushes quota change via WebSocket
-        LiveSeatUpdate --> InFlightReload: Hub updates DB and reloads SSLContext in-flight
-        InFlightReload --> HubReady
+        state EvaluateTemporalWindow <<choice>>
+        WithinWindow: (now - last_seen) <= 12 hours
+        WindowExpired: (now - last_seen) > 12 hours (First run in new window)
+        
+        UpdatePersistence: Increment consecutive_runs, update last_seen
+        ResetWindow: Set consecutive_runs = 1, update first_seen & last_seen
+        
+        UpsertSQLite: Upserts active_issues with status="VERIFIED"
    }
+
+    state "Centralized Provisioning & Hermes AI" as AIProvision {
+        API_Report: GET /api/hermes/report (Port 8443)
+        JSON_Payload: Delivers structured verified anomalies with temporal metadata
+        HermesThinking: Hermes AI executes multi-factor reasoning & autonomous decisions
+    }
+
+    FrameEncoding --> FrameIngested: Streamed over mTLS 1.3
+    FrameIngested --> ComputeFingerprint
+    ComputeFingerprint --> EvaluateTemporalWindow
+    EvaluateTemporalWindow --> WithinWindow: Existing issue seen recently
+    EvaluateTemporalWindow --> WindowExpired: New issue or inactive > 12h
+    WithinWindow --> UpdatePersistence
+    WindowExpired --> ResetWindow
+    UpdatePersistence --> UpsertSQLite
+    ResetWindow --> UpsertSQLite
    
-    state "Edge Forwarders (Windows / Linux)" as ClientState {
-        ClientCertIssued --> ClientStoreCert: Saves client.crt, client.key, ca.crt
-        ClientStoreCert --> mTLSHandshake: Initiates TLS 1.3 Handshake (Port 9443)
-        mTLSHandshake --> LogStreaming: Streams candidate log frames (INFO..CRITICAL)
-        LogStreaming --> HealthCheck: Proactive cert check (<30d) or connection drop
-        HealthCheck --> ClientStoreCert: Auto-renews or self-heals
-    }
-    
-    state "Log Provisioning & Hermes AI" as ProvisionState {
-        LogStreaming --> TemporalCorrelation: Hub ingests frame & evaluates 12h rolling window
-        TemporalCorrelation --> IssuePersisted: Upserts active_issues in logar_state.db
-        IssuePersisted --> HermesReport: Provisioned via GET /api/hermes/report
-        HermesReport --> HermesThinking: Hermes AI executes multi-factor reasoning & alerting
-    }
+    UpsertSQLite --> API_Report
+    API_Report --> JSON_Payload
+    JSON_Payload --> HermesThinking
 ```

 ---