logcrux

Licensed under the Apache License 2.0. Copyright © 2026 Ravipati.

📖 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.

Covers 209 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

Actual output of pytest --cov=logcrux against this codebase (reproduce it yourself — nothing here is hand-typed):

$ pytest -q
...
TOTAL                                9748   1034    89%
Required test coverage of 80% reached. Total coverage: 89.39%
1050 passed in 3.16s

209 Log Format Parsers by Category

Real counts, pulled directly from the complete parser index — every category total below is a count of actual parser files, not an estimate.

pie showData
    title 209 Parsers by Category
    "Security / SIEM (19)" : 19
    "Identity & Access Mgmt (5)" : 5
    "Application Frameworks (18)" : 18
    "Databases (17)" : 17
    "Containers & Cloud-Native (17)" : 17
    "Infrastructure, HA & DNS (17)" : 17
    "Web Servers & Proxies (16)" : 16
    "Observability / Agents (16)" : 16
    "Linux Daemons (16)" : 16
    "Other Daemons (11)" : 11
    "Storage & Virtualization (10)" : 10
    "System & Auth (12)" : 12
    "Mail (8)" : 8
    "Network / VPN (8)" : 8
    "Build & Package Mgmt (8)" : 8
    "Message Queues (6)" : 6
    "Big Data (4)" : 4
    "Fallback (1)" : 1

See docs/06-supported-log-types.md for the full breakdown and a complete alphabetical index of all 209 parsers.

Features

• 209 log format parsers with automatic format detection
• AI-powered incident classification — 7 incident categories (OOM, auth brute-force, HTTP overload, disk full, service crash, config error, network issue)
• Statistical anomaly detection — error rate spikes, burst detection, auth failure clustering
• Fully local — no cloud, no telemetry, no external API calls
• Rich terminal output with color-coded severity and remediation hints
• JSON output for scripting and pipeline integration
• Temporal filtering via --last 1h, --last 30m, etc.
• Baseline tracking — compares current runs against historical norms (SQLite)

Installation

# From PyPI (recommended)
pip install logcrux

# Or with uv
uv pip install logcrux

# Or run without installing, via uvx
uvx logcrux /var/log/syslog

# Or install as a standalone CLI tool with uv
uv tool install logcrux

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

Requires Python 3.11+. AI 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.

Quick Start

# Analyze a log file
logcrux /var/log/syslog

# Analyze only the last hour
logcrux /var/log/nginx/access.log --last 1h

# Raise the AI confidence threshold
logcrux /var/log/auth.log --threshold 0.7

# Output as JSON (for scripting)
logcrux /var/log/syslog --json

# Read from stdin
tail -f /var/log/syslog | logcrux

# Use a custom config file
logcrux /var/log/syslog --config /etc/logcrux/logcrux.yaml

# Verbose / debug output
logcrux /var/log/syslog --verbose

# Show version
logcrux --version        # or -V

Exit codes: 0 = clean, 3 = info/warning found, 4 = critical incident found.

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>.

209 formats total — 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[]
│  (209 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

For logs > 100 K events use --last to limit the time window.

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.

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