me0nline
56844983e2
CI Test Suite / Run Component Tests & Pipeline Verification (push) Successful in 1m39s
162 lines
7.5 KiB
Markdown
162 lines
7.5 KiB
Markdown
# 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, 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
|
|
|
|
### 1. Central Server Hub
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -r compilation/requirements.txt
|
|
|
|
# Start Server (Generates initial keys and server_config.json on first run)
|
|
python src/Server.py
|
|
|
|
# WebUI available at: http://<server-ip>:8443/webui (Default: admin / admin_logar_2026!)
|
|
```
|
|
|
|
### 2. Linux Client Deployment
|
|
|
|
```bash
|
|
sudo ./compilation/install_linux_client.sh "http://<HUB_HOST>:8443" "<ENROLLMENT_SECRET>"
|
|
```
|
|
*Enrolls client certificates to `/etc/logar/certs`, writes configuration, and enables `logar-client.service`.*
|
|
|
|
### 3. Windows Client Deployment
|
|
|
|
1. Download and run `LOGAR-Client-Setup.exe` from [Releases](https://gitea.eibl.tech/me0nline/LOGAR/releases).
|
|
2. Place `client_config.json` (exported from Server WebUI) into `C:\Program Files\LOGAR\client_config.json`.
|
|
3. The `LOGAR_Client` Windows service starts and auto-enrolls immediately.
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
LOGAR/
|
|
├── .gitea/workflows/ # CI/CD pipelines (ci.yml, release.yml)
|
|
├── compilation/ # Build scripts, Linux installers & Inno Setup scripts
|
|
│ ├── 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 (35 unit tests + pipeline test)
|
|
├── 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 (35 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)
|