me0nline
860e39b360
CI Test Suite / Run Component Tests & Pipeline Verification (push) Successful in 2m2s
183 lines
9.2 KiB
Markdown
183 lines
9.2 KiB
Markdown
<p align="center">
|
|
<img src="https://gitea.eibl.tech/me0nline/LOGAR/raw/branch/main/assets/logo_banner.svg" alt="LOGAR Banner" width="750"/>
|
|
</p>
|
|
|
|
# LOGAR: Fleet Log Aggregation & Centralized Provisioning System
|
|
### *Secure Log Aggregation, PKI Fleet Licensing & Centralized Delivery for Autonomous AI Analysis*
|
|
|
|
[](RELEASE_NOTES.md)
|
|
[](tests/)
|
|
[](https://gitea.eibl.tech/me0nline/LOGAR/wiki/PKI-and-Licensing)
|
|
|
|
**LOGAR** is an enterprise-grade log aggregation, normalization, and centralized provisioning system built for heterogeneous server fleets (Windows & Linux). It pairs ultra-lightweight, zero-state edge forwarders with a secure centralized server hub that enforces mutual TLS 1.3 (**mTLS**) authentication, dynamic PKI fleet licensing with cryptographic seat leasing, 12-hour temporal persistence tracking, and direct anomaly pass-through—delivering clean, structured, verified log telemetry directly to **Hermes AI** for autonomous deep reasoning, contextual root-cause analysis, and operational decision-making.
|
|
|
|
> 📚 **Comprehensive Technical Documentation**: Full architectural specifications, state machines, PKI X.509 OID definitions, branding assets, and complete REST API references are maintained on the **[LOGAR Gitea Wiki](https://gitea.eibl.tech/me0nline/LOGAR/wiki)**.
|
|
|
|
---
|
|
|
|
## Key Capabilities
|
|
|
|
- **Zero-State Edge Forwarders**: Windows (`Win_Client`) and Linux (`Linux_Client`) agents maintain zero local databases, zero cache files, and minimal memory footprint.
|
|
- **Mutual TLS 1.3 (`:9443`)**: Enforces bidirectional cryptographic identity verification (`ssl.CERT_REQUIRED`) for all streaming log frames.
|
|
- **Hierarchical PKI & Seat Licensing**: Subordinate CAs automatically enroll and sync seat quotas with the Master Authority (`logar.eibl.tech`) over WebSockets.
|
|
- **12-Hour Temporal Persistence**: Evaluates anomalies over a rolling 12-hour temporal window, tracking occurrence velocity and first/last seen metrics.
|
|
- **Direct Hermes AI Provisioning (`:8443`)**: Exposes verified anomalous telemetry directly to Hermes AI via `/api/hermes/report` without heuristic bottlenecks.
|
|
- **WebUI Dashboard**: Authenticated, 2-tab management console for live anomaly telemetry, client seat leasing, and Sub-CA lifecycle management.
|
|
|
|
---
|
|
|
|
## System Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph Authority [Master License Authority - logar.eibl.tech]
|
|
M_CA[Master Root CA]
|
|
AUTH_WS[WebSocket Licensing Hub]
|
|
end
|
|
|
|
subgraph ServerHub [LOGAR Server Hub]
|
|
SUB_CA[Subordinate CA]
|
|
SEAT_MGR[Dynamic Seat Manager]
|
|
MTLS_SRV[mTLS 1.3 Ingestion Server<br/>Port 9443]
|
|
TEMP_ENG[12h Temporal Persistence Engine]
|
|
PROV_API[Hermes Provisioning & WebUI API<br/>Port 8443]
|
|
|
|
SUB_CA --> SEAT_MGR
|
|
SEAT_MGR --> MTLS_SRV
|
|
MTLS_SRV --> TEMP_ENG
|
|
TEMP_ENG --> PROV_API
|
|
end
|
|
|
|
subgraph EdgeNodes [Heterogeneous Edge Forwarders]
|
|
WIN[Win_Client.exe<br/>Windows Event Logs]
|
|
LIN[Linux_Client.bin<br/>systemd journalctl]
|
|
end
|
|
|
|
subgraph Downstream [Hermes AI Layer]
|
|
HERMES[Hermes AI Engine]
|
|
end
|
|
|
|
M_CA -->|Signs Sub-CA Cert| SUB_CA
|
|
AUTH_WS <==>|Live WebSocket Sync| SUB_CA
|
|
|
|
WIN -->|1. Auto-Enrollment| SUB_CA
|
|
LIN -->|1. Auto-Enrollment| SUB_CA
|
|
WIN ==>|2. mTLS 1.3 Stream :9443| MTLS_SRV
|
|
LIN ==>|2. mTLS 1.3 Stream :9443| MTLS_SRV
|
|
PROV_API ==>|3. GET /api/hermes/report| HERMES
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Start & Automated Installers
|
|
|
|
LOGAR provides automated production service installers for both Linux (`systemd`) and Windows (`services.msc` via NSSM):
|
|
|
|
### 1. Server Hub Installation
|
|
|
|
- **Linux (Automated systemd Installer)**:
|
|
```bash
|
|
sudo ./compilation/install_linux_server.sh
|
|
```
|
|
*Deploys standalone `Server.bin` to `/opt/logar-server`, initializes PKI, and enables `logar-server.service`.*
|
|
|
|
- **Windows (Inno Setup / NSIS Installer)**:
|
|
Download and execute `LOGAR-Server-Setup.exe` from [Releases](https://gitea.eibl.tech/me0nline/LOGAR/releases). Installs `Server.exe` into `C:\Program Files\LOGAR-Server` and registers `LOGAR_Server` Windows service.
|
|
|
|
#### Default WebUI Management Credentials
|
|
Once installed or executed, access the web console:
|
|
- **URL**: `http://<server-ip>:8443/webui`
|
|
- **Default Username**: `admin`
|
|
- **Default Password**: `admin_logar_2026!` *(Configurable via `LOGAR_ADMIN_USER` / `LOGAR_ADMIN_PASS` or in the WebUI user settings)*
|
|
|
|
### 2. Edge Forwarder Installation
|
|
|
|
- **Linux Client (1-Line Non-Interactive Installer)**:
|
|
```bash
|
|
sudo ./compilation/install_linux_client.sh "http://<HUB_HOST>:8443" "<ENROLLMENT_SECRET>"
|
|
```
|
|
*Auto-enrolls mTLS certificates to `/etc/logar/certs` (`chmod 700`), generates configuration, and activates `logar-client.service`.*
|
|
|
|
- **Windows Client (Inno Setup Installer)**:
|
|
1. Download and run `LOGAR-Client-Setup.exe` (supports silent install `/VERYSILENT`).
|
|
2. Place `client_config.json` (exported from Server WebUI) into `C:\Program Files\LOGAR\client_config.json`.
|
|
3. The `LOGAR_Client` service starts and auto-enrolls immediately.
|
|
|
|
*(Alternatively, standalone binaries `./Server.bin` / `./Linux_Client.bin` / `.\Server.exe` / `.\Win_Client.exe` can be executed directly without service installation).*
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
LOGAR/
|
|
├── assets/ # Official vector SVGs, PNGs, ICOs, and branding bitmaps
|
|
│ ├── logo.svg # Master vector emblem
|
|
│ ├── logo_transparent.svg # Transparent WebUI emblem
|
|
│ ├── logo_banner.svg # Full brand banner
|
|
│ ├── logo.ico / favicon.ico # Application & web icons
|
|
│ └── wizard_*.bmp # Installer dialog bitmaps
|
|
├── .gitea/workflows/ # CI/CD pipelines (ci.yml, release.yml)
|
|
├── compilation/ # Build scripts, Linux installers & Inno Setup scripts
|
|
│ ├── generate_branding_assets.py # Asset & bitmap generator
|
|
│ ├── install_linux_client.sh # Linux client systemd auto-installer
|
|
│ ├── install_linux_server.sh # Linux server systemd auto-installer
|
|
│ ├── package_dist.py # Standalone binary cross-compiler
|
|
│ └── upload_release.py # Gitea release asset publisher
|
|
├── src/ # Application source code
|
|
│ ├── Server.py # Central mTLS hub, temporal engine & REST API
|
|
│ ├── server_enrollment.py # Sub-CA PKI and certificate generator
|
|
│ ├── Win_Client.py # Windows edge forwarder
|
|
│ └── Linux_Client.py # Linux edge forwarder
|
|
├── tests/ # Automated test suites (42 unit & integration tests)
|
|
├── LOGAR-LICENSING/ # Standalone Master License Authority (Git submodule)
|
|
├── RELEASE_NOTES.md # Version history and security changelog
|
|
└── README.md # Repository overview
|
|
```
|
|
|
|
---
|
|
|
|
## Ports & REST API Summary
|
|
|
|
| Port | Protocol | Service | Description |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **`9443`** | `TCP / TLS 1.3` | **mTLS Log Ingestion** | Mutual TLS socket listener for edge forwarders |
|
|
| **`8443`** | `HTTP / REST` | **Management & Hermes API** | WebUI, forwarder enrollment, seat management, and AI reports |
|
|
|
|
### Core Endpoints
|
|
|
|
- **`POST /api/client/enroll`**: Forwarder auto-enrollment and proactive certificate renewal.
|
|
- **`GET /api/clients`**: Returns active seat quota and registered edge forwarder telemetry *(Admin Auth)*.
|
|
- **`GET /api/hermes/report`**: Structured JSON anomaly stream for Hermes AI reasoning.
|
|
- **`POST /api/license/sync`**: Triggers immediate WebSocket sync with `logar.eibl.tech` *(Admin Auth)*.
|
|
- **`GET /health`**: Server health, encryption fingerprint, and mTLS status.
|
|
|
|
---
|
|
|
|
## Testing & Cross-Compilation
|
|
|
|
```bash
|
|
# Run full unit test suite (42 tests)
|
|
python -m unittest discover -s tests -v
|
|
|
|
# Run end-to-end mTLS pipeline integration test
|
|
python tests/test_pipeline.py
|
|
|
|
# Cross-compile native Linux and Windows binaries on Linux runner
|
|
python compilation/package_dist.py --target all
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation & Deep Dives
|
|
|
|
For in-depth operational guides, lifecycle state machines, and PKI specifications, consult the **[LOGAR Gitea Wiki](https://gitea.eibl.tech/me0nline/LOGAR/wiki)**:
|
|
|
|
* [Architecture & Design Details](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Architecture-and-Design)
|
|
* [System State Machines & Subsystem Lifecycles](https://gitea.eibl.tech/me0nline/LOGAR/wiki/State-Machines-and-Lifecycles)
|
|
* [PKI Architecture & Custom X.509 Seat OIDs](https://gitea.eibl.tech/me0nline/LOGAR/wiki/PKI-and-Licensing)
|
|
* [Complete REST API Specification](https://gitea.eibl.tech/me0nline/LOGAR/wiki/API-Reference)
|
|
* [Production Deployment & Service Management](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Deployment-and-Installation)
|
|
* [CI/CD Pipeline & Cross-Compilation Workflow](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Testing-and-Releases)
|
|
* [Branding & Design System Guide](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Branding-Guide)
|