journalcheck 1.0.1

Systemd journal monitoring and notification tool with priority filtering, pattern matching and security violation detection

journalcheck

Systemd journal monitoring and notification tool with priority filtering, pattern matching and security violation detection.

Inspired by logcheck, but designed for systemd's journal with output that can be piped to other programs for notifications, monitoring, or alerting.

Key Differences from logcheck

• Priority-based filtering: Filter messages by systemd priority levels (emerg, alert, crit, err, warning, notice, info, debug) - logcheck only supports pattern matching
• Per-service priority control: Set different priority thresholds for different services without writing individual ignore patterns
• Flexible output: Pipe to any command, send via email, or output to stdout - not limited to email only
• JSON output: Machine-readable format for integration with monitoring systems
• Cursor-based tracking: Only process new entries since last run using systemd journal cursors

Features

• Priority-based filtering (emerg, alert, crit, err, warning, notice, info, debug)
• Per-identifier priority configuration
• Regex pattern matching for identifiers (case-sensitive; (?i) is supported)
• Regex pattern matching for ignore and violations patterns (always case-insensitive)
  • Ignore patterns: Must match the entire message (implicit anchors)
  • Violation patterns: Can match anywhere in the message (substring match)
• Two-level pattern hierarchy:
  • Violations: Always shown (e.g., failed logins, security events)
  • Ignore: Suppress matching messages (exact match)
• Pre-configured violation patterns for common services (sshd, sudo, su, smartd)
• Cursor-based tracking (only process new entries)
• Multiple output formats (short, json)
• Modular configuration via /etc/journalcheck.yaml and /etc/journalcheck.d/*.yaml

Installation

From PyPI

pip install journalcheck

From Debian package

Download the .deb file from the releases page and install:

sudo dpkg -i journalcheck_*.deb

via APT Repository

• download the public key:

curl -fsSL https://gms1.github.io/journalcheck/apt/public.gpg | sudo gpg --dearmor -o /usr/share/keyrings/journalcheck-archive-keyring.gpg

• register the apt repository

echo "deb [signed-by=/usr/share/keyrings/journalcheck-archive-keyring.gpg] https://gms1.github.io/journalcheck/apt ./" | sudo tee /etc/apt/sources.list.d/journalcheck.list

• install this package

sudo apt update && sudo apt install journalcheck

From source

pip install -e .

Configuration

Main config: /etc/journalcheck.yaml

Additional configs: /etc/journalcheck.d/*.yaml (merged automatically)

Example:

priority: warning
format: short

# Optional: pipe output to a command
output_command: "notify-send 'Journal Alert'"

# Optional: send output via email
email_to: "[e-mail]"
email_subject: "Journal Alerts"

identifiers:
  ssh: # Exact match
    priority: info
    ignore:
      - ".*session opened.*"   # Full match: must match entire message
      - ".*session closed.*"
    violations:
      - "Failed password"       # Substring: matches anywhere in message
  /^(?i)cron$/: # Match both "cron" and "CRON" using case-insensitive regex
    priority: notice
    ignore:
      - ".*session opened.*"
      - ".*session closed.*"

Output Options:

• If output_command is set, output will be piped to that command
• If email_to is set, output will be sent via email using the mail command
• If neither is set, output goes to stdout by (default), except if running as systemd service

Default Violations

The following identifiers have pre-configured violation patterns that are automatically included:

• sshd: Failed password, Invalid user, Connection closed by authenticating user, etc.
• sudo: authentication failure, user NOT in sudoers, incorrect password attempt
• su: FAILED su, authentication failure
• smartd: SMART Failure, Attribute.*failed, Error.*occurred
• kernel: I/O error, Buffer I/O error, end_request: I/O error

You can add additional violations to these identifiers - they will be appended to the defaults.

Usage

Basic usage

journalcheck

Filter output

journalcheck | grep ssh

Save to file

journalcheck > /var/log/journal-alerts.log

Send via email

journalcheck | mail -s "Journal Alerts" [e-mail]

Run via systemd timer

The package includes systemd service and timer units for automated checking.

Enable the timer:

sudo systemctl enable --now journalcheck.timer

Check timer status:

sudo systemctl status journalcheck.timer
sudo systemctl list-timers journalcheck.timer

Customize the schedule: The default schedule is hourly. To change it:

sudo systemctl edit journalcheck.timer

Add your custom schedule:

[Timer]
OnCalendar=daily

See systemd.time(7) for schedule syntax.

License

MIT License - see LICENSE file for details.

Repository

https://github.com/gms1/journalcheck