diff --git a/README.md b/README.md index a1ff86c..b8354f3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 📬 Postfix Mail Summary Script -A **hardened, production-ready Bash script** for analyzing Postfix mail logs with a clean, readable output format. +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. @@ -8,36 +8,33 @@ 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 +- 📊 **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` +- Bash (>= 4.x recommended) +- Standard Linux utilities: + - `awk` + - `grep` + - `sed` + - `tail` + - `find` + - `zcat` --- @@ -47,150 +44,98 @@ Designed with **security, performance, and portability** in mind. git clone https://git.robott.sk/robott/mail-status.git cd mail-status chmod +x mail-status.sh -``` +▶️ Usage +sudo ./mail-status.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 "MMM DD" Filter by date (e.g. "Mar 27") ---- +Search across all logs for a specific user: -## ▶️ Usage +sudo ./mail-status.sh -f user@example.com -d "" -```bash -sudo ./script.sh [OPTIONS] -``` +Or search for a specific date: ---- +sudo ./mail-status.sh -f user@example.com -d "Mar 23" +📌 Examples -## 📖 Options +Show last 10 records -| 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"`) | +sudo ./mail-status.sh ---- +Show last 50 records -## 📌 Examples +sudo ./mail-status.sh -l 50 -### Show last 10 records +Filter by sender -```bash -sudo ./script.sh -``` +sudo ./mail-status.sh -f gmail.com -### Show last 50 records +Filter by recipient -```bash -sudo ./script.sh -l 50 -``` +sudo ./mail-status.sh -t example.com -### Filter by sender +Filter by Queue ID -```bash -sudo ./script.sh -f gmail.com -``` +sudo ./mail-status.sh -i 3F2A12345 -### Filter by recipient +Filter by date -```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 - -``` +sudo ./mail-status.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: -## 🔐 Security Design +✅ Protected Against: -This script is designed with **security-first principles**: +Command injection +AWK injection +Regex-based DoS (ReDoS) +Malicious filenames +Memory exhaustion +Log flooding -### ✅ Protected Against +🔒 Key Techniques: -* 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 +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 -## 👨‍💻 Author - -robott -GitHub: https://github.com - ---- +robott GitHub: https://github.com/robott +Powered by Gitea \ No newline at end of file