# 📬 Postfix Mail Summary Script

A **hardened, production-ready Bash script** for analyzing Postfix mail logs with a clean, readable output format.

Designed with **security, performance, and portability** in mind.

---

## 🚀 Features

* 📊 Clean, formatted output (with optional colors)
* 🔍 Filter by:

  * Sender (`--from`)
  * Recipient (`--to`)
  * Queue ID (`--id`)
  * Date (`--date`)
* ⚡ Optimized log reading (avoids full log parsing when possible)
* 🛡️ Hardened against:

  * Command injection
  * Regex/ReDoS attacks
  * Memory leaks
  * Log-based DoS
* 🧠 Smart parsing of Postfix logs (including NOQUEUE rejects)
* 🎯 Portable across Linux distributions

---

## 📦 Requirements

* Bash (>= 4.x recommended)
* Standard Linux utilities:

  * `awk`
  * `grep`
  * `sed`
  * `tail`
  * `find`
  * `zcat`

---

## ⚙️ Installation

```bash
git clone https://git.robott.sk/robott/mail-status.git
cd mail-status
chmod +x mail-status.sh
```

---

## ▶️ Usage

```bash
sudo ./script.sh [OPTIONS]
```

---

## 📖 Options

| Option              | Description                                  |
| ------------------- | -------------------------------------------- |
| `-h, --help`        | Show help message                            |
| `-l, --list NUMBER` | Show last X records (default: 10, max: 1000) |
| `-f, --from`        | Filter by sender (substring match)           |
| `-t, --to`          | Filter by recipient (substring match)        |
| `-i, --id`          | Filter by Queue ID                           |
| `-d, --date`        | Filter by date (e.g. `"Mar 27"`)             |

---

## 📌 Examples

### Show last 10 records

```bash
sudo ./script.sh
```

### Show last 50 records

```bash
sudo ./script.sh -l 50
```

### Filter by sender

```bash
sudo ./script.sh -f gmail.com
```

### Filter by recipient

```bash
sudo ./script.sh -t example.com
```

### Filter by Queue ID

```bash
sudo ./script.sh -i 3F2A12345
```

### Filter by date

```bash
sudo ./script.sh -d "Mar 27"
```

---

## 🖥️ Output Example

```
DATE-TIME        ID           CLIENT_IP       SENDER                             RECIPIENT                        STATUS       REASON
Mar-27-12:00:01  3F2A12345    192.168.1.10    user@gmail.com                     admin@example.com               sent         [OK]
Mar-27-12:01:05  NOQUEUE      45.12.34.56     spam@bad.com                       user@example.com                REJECT       [Policy]
```

---

## 🔐 Security Design

This script is designed with **security-first principles**:

### ✅ Protected Against

* Command injection
* AWK injection
* Regex-based DoS (ReDoS)
* Malicious filenames
* Memory exhaustion
* Log flooding

### 🔒 Key Techniques

* Input length limiting
* Substring matching (`index()` instead of regex)
* Safe file handling (`find -print0`, arrays)
* Temporary file isolation (`mktemp`)
* Automatic cleanup (`trap`)
* No use of `eval`

---

## ⚡ Performance Optimizations

* Reads only last **50,000 lines** by default
* Full log scan only when necessary (`--date`, `--id`)
* Avoids unnecessary process spawning
* Efficient AWK parsing with memory cleanup

---

## 🎨 Color Output

* Automatically enabled when running in a terminal
* Disabled when piping output (e.g. `| less`, `| grep`)

---

## ⚠️ Notes

* Must be run as **root** (required for log access)
* Works with standard Postfix logs:

  * `/var/log/maillog`
  * rotated logs (`maillog.*`, `.gz`)

---

## 🛠️ Future Improvements (Optional)

* Real-time monitoring (`tail -f`)
* JSON export for SIEM tools (ELK, Splunk)
* Fail2ban integration (auto-block IPs)
* Spam pattern detection

---

## 📄 License

MIT License

---

## 👨‍💻 Author

robott
GitHub: https://github.com

---