How mootzen/wazuhmailreport works
Main Components
• Installer/Setup (install.sh): Handles installation tasks such as dependency installation, cloning the repository, setting file permissions, and setting up the cron job.
• Configuration (report.conf and inline variables in wazuh_alert_report.sh): Contains settings for email recipients, severity levels, and report parameters.
• Core Script (wazuh_alert_report.sh): The primary script that:
• Reads and filters alerts from Wazuh logs (specifically from alerts.json)
• Extracts system information (disk usage, swap usage)
• Formats the report as HTML
• Sends the report via an email client (mailutils)
• Cron Job: Scheduled task (configured during installation or manually via crontab) that triggers the core script at regular intervals.
• External Dependencies:
• Wazuh Instance: Source of alerts and system log information.
• Utilities like jq (for JSON parsing) and mailutils (for sending emails).
• A Mail Server (e.g., Postfix) for email delivery.
Relationships and Interactions
• The cron job periodically executes the wazuh_alert_report.sh script.
• The script accesses files and data generated by the Wazuh instance (alert logs) and uses jq to parse them.
• The script pulls configuration details either from inline variables in the script or from report.conf.
• After processing log data and collating system metrics, the script builds an HTML report.
• The report is then sent to the designated admin email via the system’s configured mail server.
• The installer script ensures the correct placement of files (/usr/local/wazuhMailReport) and sets up the scheduling mechanism (cron).
Architectural Patterns and Design Principles
• Separation of Concerns: Different responsibilities are clearly separated – installation/setup, configuration, log processing, report generation, and email delivery.
• Modularity: The design uses distinct files for installation (install.sh), configuration (report.conf), and execution (wazuh_alert_report.sh), making it easier to update or customize.
• Dependency Management: External tools (jq and mailutils) are required, and their installation is handled by the installer script.
• Scheduled Execution: Cron integration is used to ensure that the reporting happens regularly without manual intervention.
Technologies and Frameworks
• Shell scripting (Bash) is used for the core functionality.
• JSON parsing is handled via jq.
• Email delivery is performed using mailutils, relying on a working mail server setup.
• The report format is HTML, which may involve simple templating within the Bash script.
Elements
• Clear labels for each component:
• "Installer (install.sh)"
• "Configuration (report.conf & script variables)"
• "Core Reporting Script (wazuh_alert_report.sh)"
• "Wazuh Instance / Alerts Source (alerts.json)"
• "System Metrics (disk & swap usage)"
• "Cron Job (Scheduled Execution)"
• "Email Delivery (mailutils & Mail Server)"
• How the cron job triggers the script.
• The data flow from the Wazuh log files into the script.
• The output flow from the script to the mail server.
• Rectangles for components (Installer, Script, Configuration).
• Annotations to note that the script includes filtering, alert extraction, and report formatting.