# Mail Stats - Postfix Summary Tool (v2026.1.1)

![License](https://img.shields.io/badge/license-MIT-green)
![Bash](https://img.shields.io/badge/Bash-4.x+-blue)
![Postfix](https://img.shields.io/badge/Postfix-Logs-lightgrey)

---

## 📋 Table of Contents

1. [Overview](#overview)
2. [Features](#features)
3. [Requirements](#requirements)
4. [Installation](#installation)
5. [Usage](#usage)
6. [Options](#options)
7. [Examples](#examples)
8. [Security & Hardening](#security--hardening)
9. [Notes](#notes)
10. [License](#license)
11. [Author](#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.

![Postfix Mail Summary](https://via.placeholder.com/900x200.png?text=Mail+Stats+Overview)

---

## ✨ 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:

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

No additional dependencies required.

---

## 🛠 Usage

```bash
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:

```bash
mail-stats -l 20
```

Filter by sender:

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

Filter by recipient:

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

Detailed view for Queue ID:

```bash
mail-stats -i 3F2A4B1C0
```

Filter by date:

```bash
mail-stats -d "Mar 27"
```

Search all logs:

```bash
mail-stats -d ""
```

---

## 🛡 Security & Hardening

1. **Resource Limits**

```bash
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

![Detail View](https://via.placeholder.com/900x200.png?text=Detailed+Mail+View)

---

## 📜 License

MIT License – free to use, modify, and distribute

---

## 👤 Author

**robott** – [GitHub](https://git.robott.sk/robott)