logcrux

Licensed under the Apache License 2.0. Copyright © 2026 Ravipati. Redistributions must keep the attribution in NOTICE.

📖 Full documentation: logcrux.com

logcrux is an intelligent, fully local log analyzer. Point it at a log file and it tells you what's actually wrong: error bursts, brute-force attacks, resource exhaustion, service failures, and more, using statistical analysis plus a small local inference step for classification. Nothing leaves your machine: no cloud, no telemetry, no API calls, no accounts.

Works on any text log, and natively covers 200+ formats: Linux/Unix system logs plus web servers, databases, containers, cloud infrastructure, and security tooling, most of which are the same regardless of what OS is running logcrux itself.

Test Results at a Glance

Verdicts on real failures — the number that matters. Faults were induced on real systems (54 cloud VMs across 4 campaigns: Debian, Ubuntu, RHEL, Rocky, AlmaLinux, CentOS Stream, SLES, openSUSE, x86_64 and arm64; plus docker logs of 32 common images and a real Kubernetes cluster), each capture labelled with what an operator should have been told before logcrux saw it:

Read that as a development-set number: these captures drove the fixes. The honest estimate for software logcrux has never seen is the held-out rounds, each scored before any fix it prompted: 42 of 77 faults (55%) on first contact, 76 of 77 after, with no false alarms on the healthy captures. Rounds: web/db/cache/queue images 13/18, proxies and app servers 4/4, Kubernetes 4/6, Tomcat/Kafka/kopia 3/7, PHP-FPM/Keycloak/OpenLDAP 0/3, Prometheus/CoreDNS/Mosquitto/Envoy 2/4, resource limits/TLS/borg/Postfix 1/7, structured JSON apps 3/3, OS-level incidents on real VMs 8/13, capacity limits 3/4, BIND/Samba 0/2, Go/Rust panics 1/2, Kubernetes scheduling and probes 0/4. The misses are almost always a single failure line in a vocabulary logcrux does not know yet; a wrong-verdict report with the redacted lines is the fastest way to get one fixed.

On the 12-OS VM campaign of 2026-10-20 logcrux 0.9.0 detected 67% of the same faults; most misses were single-line failures — a crashed backend, a failed backup, an SELinux denial — that a burst detector cannot see. The captures, labels and scorer live in the project's lab repository and are re-run against every release candidate.

Unit and integration tests, actual output of pytest --cov=logcrux:

$ pytest -q --cov=logcrux
...
TOTAL                                 11476   1025    91%
Required test coverage of 80% reached. Total coverage: 91.07%
1267 passed

See docs/06-supported-log-types.md for the full breakdown by category and a complete alphabetical index of every parser (the canonical count lives there).

Features

• Findings with evidence: every incident names what it is about (the attacking IPs and users, the process the OOM killer chose, the crashed unit or pod, the 5xx status and path, the exception that killed a process) and cites the log lines, by number, that prove it
• Single-line failures: a failed backup job (restic, kopia, borg), a backend crash, an uncaught exception or fatal exit, a proxy with no live backend, an SELinux/AppArmor denial, a degraded RAID array, a rejected config, an expired certificate, an exhausted file-descriptor or process limit, a jumped clock, a held package-manager lock — not only bursts
• 200+ log format parsers with automatic format detection; docker logs streams that interleave formats are parsed line by line; a generic fallback so any text log still analyzes
• Files, directories, stdin: logcrux /var/log/nginx/, rotated .gz, journalctl/kubectl logs/docker logs piped in
• Local classification: 7 incident categories (OOM, auth brute-force, HTTP overload, disk full, service crash, config error, network issue)
• Fully local: no cloud, no telemetry, no external API calls
• JSON output with a versioned schema for scripts, CI gates (--fail-on) and agents
• Temporal filtering via --last 1h, --last 30m, etc.
• Baseline tracking: compares current runs against historical norms (SQLite)

Installation

# Recommended: isolated install, no venv to manage
uv tool install --python 3.12 logcrux     # or one-off: uvx --python 3.12 logcrux ...
pipx install logcrux

# Into an existing environment
pip install logcrux
uv pip install logcrux

# Development install
git clone https://github.com/ravipatip/logcrux
cd logcrux
pip install -e ".[dev]"

Requires Python 3.11+ and, for the full tool, glibc ≥2.28 (Alpine/musl runs without the AI naming step, see below).

Why --python 3.12: with no compatible system Python, uv installs the newest one (3.15 as of October 2026), and onnxruntime — which runs the small classification models — has no wheel for it yet. logcrux still installs and detects incidents without it, but names them less precisely (on the 1,191-capture scorecard: detection unchanged, incident category right 77% of the time instead of 100%) and says so on stderr ("AI classification unavailable"). Pinning 3.11–3.14 gets the full tool. uv downloads a matching interpreter automatically if your system doesn't have one, handy on distros whose default system Python is older (RHEL/Rocky 9, Ubuntu 22.04, Amazon Linux 2023 and SLES 15 ship 3.6-3.10 by default). pipx uses whatever Python is already on your PATH, so install 3.11+ first if needed (sudo dnf install python3.11 / sudo apt install python3.11). Inference models are embedded, no separate download needed. uv/uvx work out of the box since logcrux ships a standard [project.scripts] entry point; no special packaging is needed for either.

Supported platforms

Both x86_64 and arm64 are supported, on Linux and macOS. The rows marked verified were installed and run on real cloud VMs (2026-10-13): uv tool install worked on every one of them, x86_64 and arm64. A stock cloud image ships no pip at all, and several ship a system Python older than 3.11 — which is why uv (it fetches its own interpreter) is the recommended route.

The blocker on older enterprise distros is glibc, not Python: onnxruntime only ships modern manylinux_2_27/manylinux_2_28 wheels, and below glibc 2.28 the uv installer silently falls back to a musl build, which then can't find a matching onnxruntime wheel either. RHEL/Rocky/AlmaLinux 8+, Ubuntu 20.04+, Debian 10+, Amazon Linux 2023, any current Fedora, and openSUSE Leap 15.3+/SLES 15 SP3+ all clear the glibc 2.28 floor. RHEL/CentOS 7, Amazon Linux 2, Ubuntu 18.04 and older, and SLES 12 do not; run logcrux from outside those hosts instead (ssh oldbox 'cat /var/log/secure' | logcrux, or a sidecar container on a glibc 2.28+ base).

On Alpine/musl onnxruntime publishes no wheel, so only the degraded mode is available (plain uv tool install logcrux, which picks a Python without onnxruntime): detection works, incident naming is less precise. For the full tool use a glibc base image, or docker logs <container> | logcrux from outside it.

See docs/21-troubleshooting.md for distro-specific fixes (PEP 668 externally-managed-environment, uv PATH/tar issues, RHEL-family Python upgrades, etc).

Quick Start

# A file, several files, or a whole directory (one level; binaries skipped)
logcrux /var/log/secure
logcrux /var/log/nginx/
logcrux /var/log/syslog /var/log/auth.log

# What a container or pod said before it died
docker logs myapp 2>&1 | logcrux
docker logs --timestamps myapp 2>&1 | logcrux
docker compose logs --no-color | logcrux
kubectl logs deploy/api --previous | logcrux
kubectl get events -A | logcrux

# The systemd journal (as root, or in the systemd-journal group)
journalctl -b | logcrux
journalctl -u nginx --since "1 hour ago" | logcrux

# Rotated and compressed logs are read directly
logcrux /var/log/syslog.2.gz

# Only the last hour of a long log
logcrux /var/log/nginx/access.log --last 1h

# JSON for scripts, CI gates and agents (a list when several files are given)
logcrux /var/log/syslog --json

# Every evidence line, full width, plus debug detail on stderr
logcrux /var/log/syslog --verbose

# Check the install itself (Python, models, state DB) — paste this in bug reports
logcrux --doctor

stdin is read to the end before analysis, so pipe a bounded slice (journalctl -b, tail -n 20000 file), not a stream that never ends (tail -f).

What you get — a real SSH brute force on Rocky Linux 9 (/var/log/secure):

╭───────────────────────   WARNING    Auth Brute Force ────────────────────────╮
│ ● Authentication failure cluster  (80 events)                                │
│     2026-10-13 10:03:19 → 10:04:50 (1m31s)                                   │
│     source: 127.0.0.1 ×74 · user: root ×8, admin ×8, oracle ×4               │
│     line 98: sshd-session: Invalid user admin from 127.0.0.1 port 42412      │
│     line 100: sshd-session: pam_unix(sshd:auth): authentication failure; l…  │
│                                                                              │
│ Confidence: 96%                                                              │
│                                                                              │
│ Remediation: Block offending IPs with `firewall-cmd --add-rich-rule` or      │
│ fail2ban. Review /var/log/secure for source IPs and consider disabling       │
│ password auth in sshd_config.                                                │
╰──────────────────────────────────────────────────────────────────────────────╯
Checked 223 events as syslog  │  100% of 223 lines parsed  │  2026-10-13
08:45:48 → 10:04:53 (1h19m)  │  61 error · 0 warning

Every finding says what it is about (attacking IPs and users, the process the OOM killer chose, the unit that crashed, the HTTP status and path of a 5xx flood, the exception that killed a process) and points at the lines, by number, that prove it. A clean result says what was checked, so "CLEAN" never just means "didn't work". --json carries the same evidence (findings[].subjects, findings[].evidence[].line) plus schema_version; every key is described in docs/23-json-output.md.

Exit codes: 0 = clean, 3 = info/warning found, 4 = critical incident found (with several files, the worst of them), 1 = bad option or config, 2 = unreadable, missing or binary input. In CI, --fail-on critical exits non-zero only for CRITICAL, and --fail-on never always exits 0 on a completed analysis.

How you invoke it

The examples above assume logcrux is on your PATH. Whether it is depends on how you installed it:

Everything else (flags, stdin, exit codes) is identical regardless of which form you use; substitute your invocation for the literal logcrux.

Shell completion

Enable tab-completion for your shell (bash, zsh, fish, PowerShell):

logcrux --install-completion       # install for the current shell
logcrux --show-completion          # print the script to inspect/customize

Permissions

logcrux is an on-demand CLI, not a daemon or agent: installing it via pip does not create a logcrux system user or group, open a port, or run anything in the background. It runs with the caller's privileges and reads only what the caller can read, for the duration of one analysis, then exits.

That matters on locked-down hosts (e.g. a fresh RHEL EC2 box), where the interesting logs are root-only: /var/log/secure is root:root mode 0600, and /var/log/messages is typically unreadable to normal users. A plain logcrux /var/log/secure will simply get permission-denied: logcrux has no special powers. To analyze them, pick whichever fits your setup:

# 1. Run as root for ad-hoc analysis
sudo logcrux /var/log/secure

# 2. Least-privilege for the journal: join systemd-journal, pipe journalctl
#    (logcrux parses `journalctl -o short-iso` from stdin)
sudo usermod -aG systemd-journal "$USER"     # then re-login
journalctl -o short-iso | logcrux

# 3. Grant a read-only user access to specific files via ACLs
sudo setfacl -m u:loguser:r /var/log/secure

Supported Log Formats

logcrux auto-detects the log format from the file path and content. You can also override with --format <name>.

200+ formats. Below are representative examples from each category. Use logcrux --help or check docs/06-supported-log-types.md for the complete list.

System & Auth

Web Servers & Proxies

Databases

Containers & Orchestration

Mail & FTP

Infrastructure, Network, DNS & HA

App Servers, Queues & Service Managers

Cloud-Native & DevOps

Security & SIEM

Identity & Access Management (Ping Identity)

Observability & Logging Agents

Databases (Extended)

Mail (Extended)

Storage, Virtualization & Linux Daemons

Application Frameworks

Network & Infrastructure (Extended)

Package Management, Build & CI

Fallback

Incident Categories

The AI classifier maps detected signals to one of seven categories:

Configuration

Config files are loaded from (in order):

1. --config <path> CLI flag
2. ~/.config/logcrux/logcrux.yaml
3. /etc/logcrux/logcrux.yaml

analysis:
  window_size_minutes: 5        # Time window for burst/rate analysis
  burst_multiplier: 3.0          # Burst threshold = baseline × multiplier
  auth_failure_threshold: 10     # Events to trigger auth_failure_cluster signal
  spike_factor: 3.0              # Error rate spike threshold
  correlation_gap_seconds: 120   # Max gap between correlated signals

inference:
  enabled: true                  # Enable AI classification
  threshold: 0.35                # Min confidence to report a finding (softmax threshold)

state:
  db_path: ~/.local/share/logcrux/state.db
  baseline_alpha: 0.2            # Exponential smoothing for baseline updates

security:
  allowed_log_paths:
    - /var/log/
    - /tmp/
  max_file_size_mb: 2048

output:
  color: true
  show_remediation: true

Architecture

Log file / stdin
     │
     ▼
┌─────────────┐    Auto-detect format
│   Parsers   │  ──────────────────────▶  ParsedEvent[]
│ (200+ types)│
└─────────────┘
     │
     ▼
┌──────────────────┐
│ Statistical      │    error_rate · burst · anomaly · correlation
│ Analysis Engine  │  ──────────────────────────────────────────▶  AnomalySignal[]
└──────────────────┘
     │
     ▼
┌─────────────────┐
│ Local Inference │    groups related events, names the
│ (offline)       │    likely incident category                  InferenceResult
└─────────────────┘
     │
     ▼
┌─────────────────┐
│  Summarizer     │  ──────────────────────────────────────────▶  IncidentSummary
└─────────────────┘
     │
     ▼
  Rich terminal output  /  JSON

Performance

Measured with logcrux 0.10.0 on an Apple M-series laptop (nginx access logs; the real-VM campaign saw 38-65 s for 510 K lines on 2 vCPUs):

The whole input is held in memory while it is analysed (~1.3 KB per line, plus ~250 MB for the classification models, loaded only when there is something to classify). For multi-gigabyte logs, analyse a slice: tail -n 200000, journalctl --since "2 hours ago", or grep the service first. --last filters after parsing, so it reduces memory less than slicing the input does.

Running Tests

# All tests with coverage report
pytest

# Parser tests only
pytest tests/unit/test_parsers/ -v

# Integration tests
pytest tests/integration/

# Specific parser
pytest tests/unit/test_parsers/test_haproxy.py -v

Current coverage: 89% across all modules (1050 tests).

License

logcrux is licensed under the Apache License 2.0: free to use, modify, and redistribute, including commercially, with attribution: keep the LICENSE and the NOTICE file (Copyright 2026 Ravipati) with any copy or derivative work.

📖 Docs: logcrux.com · 🐛 Issues: GitHub · 📦 PyPI