# Postfix Mail Summary Script

![License](https://img.shields.io/badge/license-MIT-green)

Hardened, secure, and memory-safe Bash script for summarizing **Postfix** mail logs with filtering and detail views.

---

## Table of Contents

* [Overview](#overview)
* [Features](#features)
* [Requirements](#requirements)
* [Installation](#installation)
* [Usage](#usage)
* [Options](#options)
* [Examples](#examples)
* [Preview](#preview)
* [Security & Hardening](#security--hardening)
* [Notes](#notes)
* [License](#license)

---

## Overview

This script parses and summarizes Postfix log files located in `/var/log/`. It supports filtering by sender, recipient, queue ID, and date. The output can be a concise summary table or a detailed per-message view.

The script is hardened with:

* Resource limits
* Safe temporary file handling
* Single-instance locking
* Secure parsing and memory-safe processing

---

## Features

* Summarizes Postfix logs with **color-coded output**.
* Filters by:

  * Sender (`from`)
  * Recipient (`to`)
  * Queue ID (`id`)
  * Date (`date`)

    * **Use `-d ""` to search across all logs without date filtering**
* Displays summary or detailed view per message.
* Handles compressed logs (`.gz`) automatically.
* Safely deletes old temporary files.
* Avoids displaying internal local deliveries (`127.0.0.1`) unless explicitly filtered.
* Highlights **deferred**, **rejected**, and **greylisted** emails with color.
* Limits memory, CPU time, and file usage for safety.

---

## Requirements

* Linux or Unix-like system
* Bash 4.x+
* Postfix logs under `/var/log/` (e.g., `maillog*`, `mail.log*`)
* `awk`, `zcat`, `grep`, `find`, `sed` installed

---

## Installation

Clone or copy the script to your preferred location, e.g.:

```bash
sudo cp postfix_summary.sh /usr/local/bin/postfix_summary
sudo chmod +x /usr/local/bin/postfix_summary
```

No additional dependencies are required.

---

## Usage

```bash
postfix_summary.sh [OPTIONS]
```

By default, it shows the **last 10 mail log records** from today.

---

## Options

| Option                    | Description                                      |
| ------------------------- | ------------------------------------------------ |
| `-h, --help`              | Show this help message                           |
| `-l, --list NUMBER`       | Show the last X records (default: 10, max: 1000) |
| `-f, --from EMAIL/DOMAIN` | Filter by sender email or domain                 |
| `-t, --to EMAIL/DOMAIN`   | Filter by recipient email or domain              |
| `-i, --id QUEUE_ID`       | Show detail view for a specific queue ID         |
| `-d, --date "MMM DD"`     | Filter by date (e.g., `"Mar 27"`)                |

* **Use `-d ""` to search across all logs without date filtering** |

---

## Examples

Show last 20 emails:

```bash
postfix_summary.sh -l 20
```

Filter emails from a specific sender:

```bash
postfix_summary.sh -f "example@domain.com"
```

Filter emails sent to a specific recipient:

```bash
postfix_summary.sh -t "recipient@domain.com"
```

Show detailed view of a specific queue ID:

```bash
postfix_summary.sh -i 3F2A4B1C0
```

Filter by a specific date:

```bash
postfix_summary.sh -d "Mar 27"
```

Search across all logs without date filtering:

```bash
postfix_summary.sh -f "example@domain.com" -d ""
```

---

## Preview

**Running `postfix_summary.sh` (default summary view):**

```
DATE-TIME        ID           CLIENT_IP        SENDER                               RECIPIENT                         STATUS       REASON
Mar 27 12:34:56  3F2A4B1C0   192.168.1.10     sender@example.com                    recipient@domain.com              sent         [OK]
Mar 27 12:35:10  4A1B2C3D4   203.0.113.5      admin@domain.org                       user@example.com                  deferred     [Temporary failure]
```

**Running `postfix_summary.sh -i 3F2A4B1C0` (detail view):**

```
--- Detail for ID: 3F2A4B1C0 ---
Date        : Mar 27 12:34:56
Client IP   : 192.168.1.10
Sender      : sender@example.com
Recipient   : recipient@domain.com
Status      : sent
Reason      : OK
--------------------------------
```

---

## Security & Hardening

The script applies multiple security measures:

1. **Resource Limits**
   Prevents excessive CPU or memory usage:

   ```bash
   ulimit -t 15        # CPU time
   ulimit -v 500000    # Virtual memory (kB)
   ulimit -f 102400    # Max file size
   ```

2. **Single Instance Locking**
   Prevents multiple simultaneous executions using `/tmp/postfix_summary.lock`.

3. **Temporary File Safety**
   Uses `mktemp` to create secure temporary files and cleans them on exit.

4. **Safe Argument Handling**
   Limits input length and validates required arguments.

5. **Memory-Safe Log Parsing**
   Skips overly long or short lines to prevent potential buffer abuse.

6. **Old Temp File Cleanup**
   Deletes stale files older than 10 minutes to prevent clutter or accidental data leak.

---

## Notes

* The script ignores local Postfix deliveries (`127.0.0.1`) in summary mode.
* Supports `.gz` compressed logs for backward compatibility.
* Detail view (`--id`) provides full information including:

  * Date/Time
  * Client IP
  * Sender
  * Recipient
  * Status
  * Reason

---

## License

MIT License – feel free to use, modify, and distribute.