🔍 Log Monitoring and Alert System

Overview

The Log Monitoring and Alert System is a flexible, high-performance tool designed for DevOps engineers, sysadmins, and SREs. It continuously scans log files to detect anomalies and security events, triggering alerts via various output formats and integrated email notifications.

Developed primarily in C and Bash, the system leverages the efficiency and low-overhead of C for high-speed log parsing while utilizing Bash for orchestration, automation, and external integrations such as email alerting. This dual-language approach ensures that both real-time and scheduled log monitoring environments are catered for, making it ideal for both production environments and testing scenarios.

Dependencies

• GCC (tested with gcc 9+)
• swaks (for email sending)
• Bash 4.0+
• cron (optional, for scheduled runs)

Table of Contents

• Features
• Architecture Diagram
• Configuration Files
• Script and Binary Documentation
• Usage Examples
• Setup, Compilation, and Makefile Instructions
• Troubleshooting & Debugging
• Contribution, License, and Contact

Features

• Real-time Log Monitoring: Constantly scans log files and processes new entries as they are appended.
• Configurable Alert Rules: Use a simple key=value configuration file (config.txt) to set thresholds, deduplication periods, and alert criteria.
• Dual-format Alert Output: Simultaneously outputs alerts in human-readable text and structured JSON format.
• Interactive Bash Menu: Provides an automation interface via an interactive menu (monitor.sh) for on-demand operations.
• Email Alerting: Alerts can be sent via an external script (send_email.sh) using Gmail SMTP with TLS encryption.
• Fake Log Generation: Includes a script (generate_fake_logs.sh) for generating synthetic logs for testing.
• Cron Integration: Easily schedule the log parser using cron to run at defined intervals.
• Log Rotation and Deduplication: Supports log rotation and suppresses repeated alerts within a configurable deduplication interval.

Architecture Diagram

Below is a simplified architecture diagram using Mermaid syntax:

flowchart LR
    G[generate_fake_logs.sh] --> L[(logs/fake_syslog.log)]
    M[monitor.sh menu] -->|run parser| P[logParser]
    CR[cron] -.->|scheduled run| P
    C[config.txt] --> P
    L --> P
    P --> T[alerts.txt]
    P --> J[alerts.json]
    P -->|external_alert_command| E[send_email.sh]
    E -->|swaks over TLS| S[Gmail SMTP]

Loading

Configuration Files

INI Configuration (config.txt)

# Log file path (supports wildcards if needed)
log_path=logs/fake_syslog.log

# Output alert files
alert_output_path=alerts.txt
alert_output_json=alerts.json

# External command for alerts (e.g., email script)
external_alert_command=./send_email.sh -r admin@example.com

# Alert thresholds
failed_login_threshold=3
error_repeat_threshold=5
port_scan_threshold=10
suspicious_time_threshold=7
burst_threshold=5
dedup_interval_seconds=60

# Enable or disable specific rules (1 to enable, 0 to disable)
enable_failed_login=1
enable_error=1
enable_unauth=1
enable_port_scan=1
enable_suspicious_time=1
enable_burst=1

config.json (reference only)

logParser only reads the key=value format shown above: lines starting with # or [ are skipped, and every other line is parsed as key=value. Passing config.json to logParser will not load any settings. The repository's config.json groups the same keys into sections (General, Thresholds, Anomalies, Deduplication, Enable) and is kept as a reference for tools that prefer JSON; always run the parser with config.txt.

Explanation of Keys:

• log_path: Path to the system log file or directory containing logs.
• alert_output_path / alert_output_json: Files where alert messages are stored in text and JSON formats.
• external_alert_command: Command to run when an alert is triggered. Use -r to specify the recipient email.
• Threshold keys: Numeric values determining when to trigger specific alerts.
• enable_*: 1 to enable or 0 to disable each alert rule.

Script and Binary Documentation

logParser.c

Description:
A high-performance C program that scans log files and processes entries based on defined alert rules. Supports both file input and real-time monitoring.

CLI Usage:

./logParser config.txt logs/fake_syslog.log [options]

Options:

• --keyword "pattern": Only process log lines containing the specified keyword.
• --start "YYYY-MM-DD HH:MM:SS": Start time for filtering logs.
• --end "YYYY-MM-DD HH:MM:SS": End time for filtering logs.
• --level "LEVEL": Filter log lines by a specific severity level (e.g., ERROR, INFO).
• --realtime: Start in real-time monitoring mode.
• --json-output: Output alerts in JSON format.

Examples:

./logParser config.txt logs/fake_syslog.log --keyword "login" --level "ERROR"

monitor.sh

Description:
A Bash script that orchestrates the log monitoring system. Runs in auto mode (scheduled via cron) or interactive mode, offering a menu-driven interface.

Modes:

• Auto Mode: Execute non-interactively via cron.
• Interactive Menu Mode: Presents options for running alerts, refreshing logs, or manually triggering tests.

generate_fake_logs.sh

Description:
Generates synthetic log entries to simulate potential security or system events.

CLI Flags:

• -n: Number of fake log lines to generate.
• -o: Output file for generated logs.
• --interval: Time interval between log entries.

Example:

./generate_fake_logs.sh -n 500 -o logs/fake_syslog.log --interval 1

send_email.sh

Description:
Sends an alert email using Gmail SMTP via the swaks tool. Supports TLS encryption and allows customization of the recipient email.

SMTP Settings:

• Gmail SMTP: Uses smtp.gmail.com on port 587.
• Credentials: Uses the configured email and app password.
• Recipient Logic: Accepts the recipient email via the -r option or the RECIPIENT environment variable.

Example:

./send_email.sh -r admin@example.com "Suspicious login detected from auth"

Usage Examples

Sample Log Line:

2025-04-07 06:25:30 ERROR auth: Failed login attempt detected

Sample Alert Output (Text):

[2025-04-07 06:28:42] CRITICAL: [auth] Multiple failed login attempts from auth (3 attempts)

Sample Alert Output (JSON):

{
  "timestamp_utc": "2025-04-07 06:28:42",
  "timestamp_local": "2025-04-07 06:28:42",
  "severity": "CRITICAL",
  "source": "auth",
  "message": "Multiple failed login attempts from auth (3 attempts)"
}

Real CLI Command for Log Parsing with Email Alerting:

./logParser config.txt logs/fake_syslog.log --keyword "login" --level "ERROR"

Cron Job Example:

Add the following line to your crontab to run the parser every 5 minutes:

*/5 * * * * /path/to/logParser config.txt logs/fake_syslog.log --keyword "login" --level "ERROR" >> /var/log/logparser.log 2>&1

Setup, Compilation, and Makefile Instructions

1. Compiling the C Parser:

   Ensure you have gcc installed. Simply run:

   make

   This command builds logParser from logParser.c.

2. Folder Structure:

   /project-root
   ├── config.txt
   ├── config.json
   ├── logParser.c
   ├── monitor.sh
   ├── generate_fake_logs.sh
   ├── send_email.sh
   ├── Makefile
   └── logs/
       └── fake_syslog.log
   

3. File Permissions:

   Ensure all shell scripts are executable:

   chmod +x monitor.sh generate_fake_logs.sh send_email.sh

Troubleshooting & Debugging

• Email Alerts Not Sending:

  • Confirm that swaks is installed (sudo apt install swaks).
  • Verify your SMTP credentials and ensure "Less Secure App Access" is enabled in your Gmail account if required.

• Compilation Issues:

  • Ensure you are using the required macros (_XOPEN_SOURCE, _DEFAULT_SOURCE) to access functions like usleep.
  • Use gcc -Wall -O2 -o logParser logParser.c to compile, and fix any warnings accordingly.

• Verbose Mode:

  • Check log files (e.g., /var/log/logparser.log if using cron) for detailed error messages.

Contribution, License, and Contact

Contributions, feedback, and bug reports are welcome! Please submit pull requests or open issues on our GitHub repository.

Licensed under the MIT License.
Maintained by Mohammad Thabet Hassan – feel free to reach out via email.

---

Sample Alert JSON

{
  "timestamp_utc": "2025-04-07 06:28:42",
  "timestamp_local": "2025-04-07 06:28:42",
  "severity": "CRITICAL",
  "source": "auth",
  "message": "Multiple failed login attempts from auth (3 attempts)"
}