add readme file

README.md

@@ -0,0 +1,196 @@
+# 📬 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
+
+---
+