# mootzen/wazuhmailreport architecture

> Architecture diagram of the GitHub repository mootzen/wazuhmailreport, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mootzen/wazuhmailreport
- Repository: https://github.com/mootzen/wazuhmailreport

## Overview

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

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Setup"
        A["Installer (install.sh)"]:::component
        B["Cron Job (Scheduled Execution)"]:::scheduler
    end

    subgraph "Runtime Processing"
        D["Configuration (report.conf & script variables)"]:::component
        C["Core Reporting Script (wazuh_alert_report.sh)"]:::component
        G["System Metrics (disk & swap usage)"]:::component
    end

    subgraph "External Systems"
        E["Wazuh Instance / Alerts Source (alerts.json)"]:::external
        F["Email Delivery (mailutils & Mail Server)"]:::external
    end

    A -->|"sets-up"| B
    B -->|"triggers"| C
    D -->|"loads"| C
    E -->|"extracts-alerts(with_jq)"| C
    C -->|"collects-metrics"| G
    C -->|"sends-report"| F

    click A "https://github.com/mootzen/wazuhmailreport/blob/main/install.sh"
    click D "https://github.com/mootzen/wazuhmailreport/blob/main/report.conf"
    click C "https://github.com/mootzen/wazuhmailreport/blob/main/wazuh_alert_report.sh"

    classDef component fill:#bbf,stroke:#000,stroke-width:1px;
    classDef scheduler fill:#f9d,stroke:#000,stroke-width:1px;
    classDef external fill:#cfc,stroke:#000,stroke-width:1px;
```
