From 3b2c3e0fd707364ef94067bdc6c219ac23c2c07b Mon Sep 17 00:00:00 2001 From: max Date: Fri, 25 Sep 2026 16:16:07 +0200 Subject: [PATCH] Update README.md to describe direct Hermes anomaly reasoning --- README.md | 42 ++++++++++++++++++------------------------ 1 file changed, 18 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index cd06dbd..be250db 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # LOGAR: Edge-Thin Log Analysis & Temporal Verification System -**LOGAR** is an enterprise log aggregation, verification, and anomaly detection architecture designed for heterogeneous server fleets (Windows & Linux). It combines lightweight zero-state edge forwarders with a centralized cloud hub that applies mutual TLS 1.3 (**mTLS**) authentication, dynamic PKI licensing and quota management, temporal persistence tracking across 12-hour evaluation windows, an automated 4-run rule to filter transient warnings, and immediate pass-through for critical errors before reporting verified anomalies to **Hermes**. +**LOGAR** is an enterprise log aggregation, verification, and anomaly detection architecture designed for heterogeneous server fleets (Windows & Linux). It combines lightweight zero-state edge forwarders with a centralized cloud hub that applies mutual TLS 1.3 (**mTLS**) authentication, dynamic PKI licensing and quota management, temporal persistence tracking across 12-hour evaluation windows, and direct anomaly pass-through enabling **Hermes AI** to perform all deep reasoning, anomaly evaluation, and autonomous decision-making. --- @@ -8,7 +8,7 @@ 1. [Core Philosophy](#core-philosophy) 2. [Architecture & Data Flow](#architecture--data-flow) 3. [mTLS Security, Dynamic PKI & Licensing](#mtls-security-dynamic-pki--licensing) -4. [Cloud-Side Temporal Persistence & 4-Run Rule](#cloud-side-temporal-persistence--4-run-rule) +4. [Cloud-Side Temporal Persistence & Direct Hermes Reasoning](#cloud-side-temporal-persistence--direct-hermes-reasoning) 5. [Agentic Hermes & Client Management API](#agentic-hermes--client-management-api) 6. [Dynamic Machine & Domain Identification](#dynamic-machine--domain-identification) 7. [Automated Service Installers (Linux & Windows)](#automated-service-installers-linux--windows) @@ -28,15 +28,14 @@ Site agents running on Windows and Linux act strictly as lightweight forwarders: - **Transport Security (mTLS 1.3)**: Logs are streamed directly over mutual TLS 1.3 sockets with hardware-bound / machine-unique client certificates. - **Zero Configuration Overhead**: Clients auto-bootstrap certificate enrollment on first run if configured with an enrollment secret. -### 2. Cloud-Side Temporal Persistence & Severity Routing -The central Python hub handles state and verification: +### 2. Cloud-Side Temporal Persistence & Direct Hermes Reasoning +The central Python hub handles state and temporal tracking: - State tracking is managed centrally in SQLite (`logar_state.db`). -- Candidate issues are evaluated over a **12-hour temporal evaluation window**. -- **Warning Persistence (4-Run Rule)**: `WARNING` issues must persist across **at least 4 consecutive runs / cycles** within the 12-hour window to be confirmed as genuine anomalies, automatically filtering transient infrastructure blips. -- **Immediate Error Pass**: Critical errors (`ERROR`, `CRITICAL`, `FATAL`) bypass the 4-run threshold and are promoted immediately to `VERIFIED` on their first occurrence. +- Candidate issues are tracked over a **12-hour temporal evaluation window** with consecutive run counts and first/last-seen timestamps. +- **Direct Hermes Intelligence**: All ingested actionable anomalies (`WARNING`, `ERROR`, `INFO`) are immediately promoted to `VERIFIED` and surfaced directly to Hermes. Hermes performs all multi-factor reasoning, pattern evaluation, and contextual thinking rather than relying on arbitrary hardcoded threshold rules. ### 3. Agentic Integration with Hermes -Instead of engineers manually sifting through logs, **Hermes** ingests pre-filtered anomalies directly from the cloud hub (`GET /api/hermes/report`), treating verified errors and 4-run validated warnings as actionable system artifacts to trigger precise notifications and remediations. +Instead of engineers manually sifting through logs, **Hermes** ingests verified anomalies directly from the cloud hub (`GET /api/hermes/report`), treating errors and warnings with full temporal metadata (run counts, timestamps) as actionable system artifacts to trigger precise notifications and remediations. --- @@ -62,7 +61,7 @@ graph TB subgraph Hub [LOGAR Server Hub] INGEST[Length-Prefixed Frame Ingestion] DB[(SQLite Persistence
active_issues, clients, license_config)] - RULE{12h Window &
4-Run Rule} + RULE{12h Window &
Temporal Ingestion} end subgraph Downstream [Hermes Agent & Monitoring] @@ -139,21 +138,16 @@ graph TB --- -## Cloud-Side Temporal Persistence & 4-Run Rule +## Cloud-Side Temporal Persistence & Direct Hermes Reasoning Incoming candidate logs are tracked in SQLite table `active_issues`: - **Issue Fingerprint**: Formatted as `{site_name}:{server}:{signature}`. - **12-Hour Evaluation Window**: - The hub compares `(now - last_seen)`. - If more than 12 hours have elapsed since the issue was last recorded, the previous window expires and the cycle resets to `run_count = 1`. -- **4-Run Rule for Warnings**: - - The 4-run persistence threshold applies to `WARNING` (and `INFO`) events to eliminate transient operational noise. - - Each distinct run batch increments `run_count`. - - Warnings with `run_count < 4` are marked as `TRANSIENT` and excluded from Hermes reports. - - When `run_count >= 4` within the active 12-hour window, the warning transitions to `VERIFIED`. -- **Immediate Verification for Errors**: - - High-severity events (`ERROR`, `CRITICAL`, `FATAL`) **always pass immediately**. - - On their very first ingestion (`run_count = 1`), errors are promoted directly to `VERIFIED` and surfaced to Hermes without waiting for 4 runs. +- **Direct Verification & Temporal Telemetry**: + - Ingested anomalies are immediately promoted to `VERIFIED` and made available to Hermes with complete temporal metadata (first seen, last seen, consecutive run counts). + - Hermes performs all contextual analysis, pattern recognition, and alerting logic. --- @@ -202,7 +196,7 @@ Returns seat quota status and registered client telemetry: ``` ### `GET /api/hermes/report` -Returns all **verified anomalies** (immediate critical errors and warnings verified after 4 consecutive runs within the 12-hour window): +Returns all **verified anomalies** within the active 12-hour evaluation window with full temporal metadata for direct Hermes reasoning: ```json [ { @@ -211,7 +205,7 @@ Returns all **verified anomalies** (immediate critical errors and warnings verif "server": "web-worker-01.corp.internal", "signature": "PostgresPoolExhausted", "severity": "WARNING", - "message": "Connection pool saturated (>95%) across 4 runs", + "message": "Connection pool saturated (>95%)", "os_type": "linux", "first_seen": "2026-09-04T07:00:00+00:00", "last_seen": "2026-09-04T19:00:00+00:00", @@ -224,7 +218,7 @@ Returns all **verified anomalies** (immediate critical errors and warnings verif ``` ### `GET /api/hermes/all` -Diagnostic endpoint listing all candidate issues (`TRANSIENT` and `VERIFIED`). +Diagnostic endpoint listing all tracked anomalies in SQLite. ### `GET /health` Returns hub health, encryption fingerprint, listener ports, and mTLS status. @@ -296,7 +290,7 @@ LOGAR/ │ └── Linux_Client.py # Linux edge forwarder with auto-enrollment ├── tests/ # Automated test suites │ ├── test_linux_client.py # Linux client unit tests & mTLS certificate validation -│ ├── test_pipeline.py # End-to-end mTLS integration & 4-run verification test +│ ├── test_pipeline.py # End-to-end mTLS integration & direct anomaly verification test │ ├── test_server.py # Server unit tests, PKI generation, and seat quota tests │ └── test_win_client.py # Windows client unit tests & mTLS certificate validation ├── .gitignore # Ignores venv, caches, DBs, and private keys @@ -362,7 +356,7 @@ Runs all **25 unit tests**, covering: - Enrollment secret authentication, seat limits, and certificate revocation. - Proactive certificate validity checks, Root CA auto-renewal, and in-flight server SSLContext reload. - Windows & Linux event log collection, deduplication, and mTLS certificate verification. -- 12-hour evaluation window and 4-run rule progression. +- 12-hour evaluation window and direct Hermes anomaly verification. ### 2. End-to-End Pipeline Integration Test ```bash @@ -375,7 +369,7 @@ python src/Server.py & # 3. Run integration test python tests/test_pipeline.py ``` -Tests client enrollment, secret rejection, mTLS TLS 1.3 socket handshake, warning 4-run rule promotion, immediate error promotion, and Hermes report output. +Tests client enrollment, secret rejection, mTLS TLS 1.3 socket handshake, direct warning promotion, immediate error promotion, and Hermes report output. ---