robott/mail-status
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update README.md

Browse Source
This commit is contained in:
robott
2026-03-27 18:54:15 +01:00
parent 2c4ac98ff8
commit 584e0ffe3f
1 changed files with 89 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
README.md
View File

@@ -1,6 +1,6 @@
# 📬 Postfix Mail Summary Script # 📬 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. Designed with **security, performance, and portability** in mind.
@@ -8,36 +8,33 @@ Designed with **security, performance, and portability** in mind.
## 🚀 Features ## 🚀 Features
* 📊 Clean, formatted output (with optional colors) - 📊 **Clean, formatted output** (with optional colors)
* 🔍 Filter by: - 🔍 **Filter by**:
- Sender (`--from`)
* Sender (`--from`) - Recipient (`--to`)
* Recipient (`--to`) - Queue ID (`--id`)
* Queue ID (`--id`) - Date (`--date`)
* Date (`--date`) - ⚡ **Optimized log reading** (avoids full log parsing when possible)
* ⚡ Optimized log reading (avoids full log parsing when possible) - 🛡️ **Hardened against**:
* 🛡️ Hardened against: - Command injection
- Regex/ReDoS attacks
* Command injection - Memory leaks
* Regex/ReDoS attacks - Log-based DoS
* Memory leaks - 🧠 **Smart parsing** of Postfix logs (including `NOQUEUE` rejects)
* Log-based DoS - 🎯 **Portable** across Linux distributions
* 🧠 Smart parsing of Postfix logs (including NOQUEUE rejects)
* 🎯 Portable across Linux distributions
--- ---
## 📦 Requirements ## 📦 Requirements
* Bash (>= 4.x recommended) - Bash (>= 4.x recommended)
* Standard Linux utilities: - Standard Linux utilities:
- `awk`
* `awk` - `grep`
* `grep` - `sed`
* `sed` - `tail`
* `tail` - `find`
* `find` - `zcat`
* `zcat`
--- ---
@@ -47,150 +44,98 @@ Designed with **security, performance, and portability** in mind.
git clone https://git.robott.sk/robott/mail-status.git git clone https://git.robott.sk/robott/mail-status.git
cd mail-status cd mail-status
chmod +x mail-status.sh 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 Or search for a specific date:
sudo ./script.sh [OPTIONS]
```
--- sudo ./mail-status.sh -f user@example.com -d "Mar 23"
📌 Examples
## 📖 Options Show last 10 records
| Option | Description | sudo ./mail-status.sh
| ------------------- | -------------------------------------------- |
| `-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"`) |
--- Show last 50 records
## 📌 Examples sudo ./mail-status.sh -l 50
### Show last 10 records Filter by sender
```bash sudo ./mail-status.sh -f gmail.com
sudo ./script.sh
```
### Show last 50 records Filter by recipient
```bash sudo ./mail-status.sh -t example.com
sudo ./script.sh -l 50
```
### Filter by sender Filter by Queue ID
```bash sudo ./mail-status.sh -i 3F2A12345
sudo ./script.sh -f gmail.com
```
### Filter by recipient Filter by date
```bash sudo ./mail-status.sh -d "Mar 27"
sudo ./script.sh -t example.com 🖥️ Output Example
```
### 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 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: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] 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 Input length limiting
* AWK injection Substring matching (index() instead of regex)
* Regex-based DoS (ReDoS) Safe file handling (find -print0, arrays)
* Malicious filenames Temporary file isolation (mktemp)
* Memory exhaustion Automatic cleanup (trap)
* Log flooding No use of eval
⚡ Performance Optimizations
### 🔒 Key Techniques Reads only last 50,000 lines by default
Full log scan only when necessary (--date, --id)
* Input length limiting Avoids unnecessary process spawning
* Substring matching (`index()` instead of regex) Efficient AWK parsing with memory cleanup
* Safe file handling (`find -print0`, arrays) 🎨 Color Output
* Temporary file isolation (`mktemp`) Automatically enabled when running in a terminal
* Automatic cleanup (`trap`) Disabled when piping output (e.g., | less, | grep)
* No use of `eval` ⚠️ Notes
Must be run as root (required for log access)
--- Works with standard Postfix logs:
/var/log/maillog
## ⚡ Performance Optimizations Rotated logs (maillog.*, .gz)
🛠️ Future Improvements (Optional)
* Reads only last **50,000 lines** by default Real-time monitoring (tail -f)
* Full log scan only when necessary (`--date`, `--id`) JSON export for SIEM tools (ELK, Splunk)
* Avoids unnecessary process spawning Fail2ban integration (auto-block IPs)
* Efficient AWK parsing with memory cleanup Spam pattern detection
📄 License
---
## 🎨 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 MIT License
--- 👨‍💻 Author
## 👨‍💻 Author robott GitHub: https://github.com/robott
robott
GitHub: https://github.com
---
Powered by Gitea