From 5fe74325ec2d2ac4b37c354632242cf3a904649d Mon Sep 17 00:00:00 2001 From: max Date: Fri, 25 Sep 2026 22:10:50 +0200 Subject: [PATCH] Simplify main state machine and add dedicated subsections for licensing, forwarder, and temporal state machines --- README.md | 195 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 158 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 83b3a64..e9dde46 100644 --- a/README.md +++ b/README.md @@ -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 <> - 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 <> + 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 ``` ---