mail-status/README.md

Mail Stats - Postfix Summary Tool (v2026.1.1)

---

📋 Table of Contents

1. Overview
2. Features
3. Requirements
4. Installation
5. Usage
6. Options
7. Examples
8. Security & Hardening
9. Notes
10. License
11. Author

---

🌟 Overview

Mail Stats is a secure, hardened, memory-safe Bash tool for summarizing Postfix mail logs. It provides:

• Filtering by sender, recipient, queue ID, and date
• Concise summary tables or detailed per-message views
• Automatic processing of compressed logs (.gz)
• Color-coded terminal output for easier readability

This tool is ideal for server administrators who need fast insights into sent, rejected, or deferred emails.

---

✨ Features

• Color-coded output for quick status recognition

• Filter by:

  • Sender (from)

  • Recipient (to)

  • Queue ID (id)

  • Date (date)

    • Use -d "" to search across all logs

• Summary or detailed per-message view

• Handles .gz compressed logs automatically

• Excludes local deliveries (127.0.0.1) unless filtered

• Limits CPU, memory, and file usage for safety

---

🖥 Requirements

• Linux/Unix system
• Bash 4.x+
• Postfix logs in /var/log/ (e.g., maillog*, mail.log*)
• awk, zcat, grep, find, sed installed

---

⚡ Installation

Copy or clone the script:

sudo cp mail-stats /usr/local/bin/mail-stats
sudo chmod +x /usr/local/bin/mail-stats

No additional dependencies required.

---

🛠 Usage

mail-stats [OPTIONS]

By default, it displays the last 10 mail log entries for today.

---

🔧 Options

Option	Description
-h, --help	Show help message
-l, --list NUMBER	Number of records (default 10, max 1000)
-f, --from EMAIL/DOMAIN	Filter by sender
-t, --to EMAIL/DOMAIN	Filter by recipient
-i, --id QUEUE_ID	Show detailed view of specific queue ID
-d, --date "MMM DD"	Filter by date (e.g., "Mar 27")

---

📝 Examples

Show last 20 emails:

mail-stats -l 20

Filter by sender:

mail-stats -f "example@domain.com"

Filter by recipient:

mail-stats -t "recipient@domain.com"

Detailed view for Queue ID:

mail-stats -i 3F2A4B1C0

Filter by date:

mail-stats -d "Mar 27"

Search all logs:

mail-stats -d ""

---

🛡 Security & Hardening

1. Resource Limits

ulimit -t 15        # CPU time
ulimit -v 500000    # Virtual memory (kB)
ulimit -f 102400    # Max file size

2. Single Instance Locking

• Prevents simultaneous executions via /tmp/mail-stats.lock

3. Temporary File Safety

• Uses mktemp and cleans files on exit

4. Safe Argument Handling

• Limits input length and validates required arguments

5. Memory-Safe Log Parsing

• Skips overly long/short lines

6. Old Temp File Cleanup

• Deletes stale files older than 10 minutes

This script (version 4.0.9) is exceptionally secure and, from a Bash programming perspective, is among the best you can use for a production environment. It actively handles the vast majority of known vulnerabilities and security flaws.

Here is a summary of how the script protects the system against specific types of attacks:

Command Injection: Secure. No user input (-f, -t, -s) is directly interpolated into a command execution string. All inputs are safely passed to AWK via variables (-v f_filt="$FROM_FILTER").

Directory Traversal: Handled. A user cannot exploit the --log-dir parameter to process arbitrary system files (e.g., --log-dir /etc). The script strictly whitelists only the /var/log and /var/log/mail paths.

Symlink Attacks: Handled. The script uses the secure system command mktemp to create temporary files. The temporary file is immediately deleted upon script completion using the trap command, even if the script is forcefully terminated (Ctrl+C).

ReDoS (Regular Expression Denial of Service): Handled. The script includes ulimit -t 15, meaning if someone enters an extremely complex regular expression that overwhelms the CPU, the Linux kernel will safely kill the script after 15 seconds. In "Live Watch" mode, regex is completely disabled just to be safe.

Terminal Escape Injection: Handled. If an attacker sends an email with special non-printable characters in the subject (which could, for example, clear the screen or change terminal colors), the AWK function sanitize() strips these characters before they are printed to your screen.

Cross-User DoS (Blocking by other users): Handled. The Lock file includes the user ID (${UID}). This means if the system has multiple administrators, one administrator cannot intentionally or unintentionally block the script from running for another administrator.

The only final security recommendation: Bash scripts themselves have no inherent security privileges—they only have the rights of the user executing them. Since /var/log/mail.log logs typically require elevated read permissions, ideally run this script as a user in the adm group (on Debian/Ubuntu systems, this is sufficient to read logs) so you don't have to run it directly as root every time.

⚠ Notes

• Ignores local Postfix deliveries (127.0.0.1) by default

• Supports .gz compressed logs

• Detailed view (--id) shows:

  • Date/Time
  • Client IP
  • Sender
  • Recipient
  • Status
  • Reason

---

📜 License

MIT License – free to use, modify, and distribute

---

👤 Author

robott – GitHub