Logarithm: Anomaly Detection Agent

Logarithm is a self-learning diagnostics agent for GNU/Linux systems that uses unsupervised machine learning to detect anomalies in system logs in real-time.

Built with Crystal for bare-metal performance, memory safety, and native multithreading, Logarithm trains neural autoencoders and linear support vector machines (SVM) on normal log baselines to identify potential regressions, zero-day threats, and unusual system behaviors without requiring labeled datasets or heavy external dependencies.

Key Features

Quick Start

1. Build

git clone https://gitlab.com/renich/logarithm.git
cd logarithm
make setup
make release

2. Train

# Train on systemd journal for 1 hour
bin/logarithm train -j -t '1h'

# Train on flat log files
bin/logarithm train /var/log/syslog /var/log/messages -t '2h'

3. Monitor

# Monitor systemd journal in real-time
bin/logarithm monitor -j

# Monitor specific files with custom sensitivity threshold
bin/logarithm monitor -T 0.85 /var/log/secure

# Monitor piped input stream
tail -f /var/log/app.log | bin/logarithm monitor -i

Documentation

Comprehensive engineering, architectural, and operational manuals are available in docs/:

• 📖 User Guide & Manual — Operator guides, deployment strategies, and runtime options.
• 🚀 Quickstart Guide — Step-by-step setup, training, and real-time monitoring walk-throughs.
• 🧪 Fakelogs & Testing Guide — Generating synthetic logs, injecting anomalies, and running simulations.
• 📋 Functional Specifications — Modular requirements ([FUNC-xxx]), ingestion modes, and ML behaviors.
• 🏗️ Technical Specifications — Internal subsystems ([TECH-xxx]), concurrency model, and storage engine.
• ⚙️ API & CLI Reference — Complete CLI flag catalog, YAML configuration schemas, and output formats.
• 🏛️ Architecture Decision Records — Architectural choices, trade-offs, and historical context.
• 🗺️ Project Roadmap — Phased roadmap tracking and milestone definitions.

Development & Verification

Logarithm enforces a zero-defect quality gate across all subsystems:

make check        # Run full verification suite (specs, Ameba, Flaw SAST, crstlint)
make test         # Run 193-spec unit & property test suite
make lint         # Run Ameba static analysis and Flaw security scanner
make doc-check    # Verify reStructuredText formatting and syntax
make coverage     # Generate kcov test coverage report

Automated Simulations

/usr/bin/bash demo/demo_anomaly_detection.bash            # End-to-end anomaly detection pipeline demo
/usr/bin/bash demo/demo_chunked_training.bash             # Chunked storage & memory-efficient training demo
/usr/bin/bash integration/test.bash                       # Integration test suite
/usr/bin/bash benchmark/profile.bash                      # Throughput profiling suite

License & Authors

• Software: GNU General Public License v3.0 (GPLv3)
• Documentation: GNU Free Documentation License v1.3 (GFDL)
• Code of Honor: Contributor standards defined in CODE_OF_HONOR.rst
• Author: Rénich Bon Ćirić <renich@woralelandia.com> | woralelandia.com | EVALinux

Support & Donations

If you find Logarithm useful and wish to support its ongoing development, please consider donating: