You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+18Lines changed: 18 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,23 @@
1
1
# Changelog
2
2
3
+
## [2025-07-18] Improved performance
4
+
5
+
### Added
6
+
- Grouping mode for bounce report: entries can now be grouped by sender address (`mailfrom`) when `GROUP_BY_FROM="true"` is set in config.
7
+
- HTML group headers include sender and bounce count, styled with `.grouphead` class.
8
+
- Visual improvement: added light gray background (`#e9e9e9`) to `.grouphead` rows for better readability.
9
+
- Fully consistent HTML escaping of all dynamic content to avoid rendering issues.
10
+
- New sender marking logic to identify bounced emails as **resent** (known senders sending from external domains) or **spoofing** (possible impersonation from internal domains).
11
+
- Introduced configuration flags `RECIPIENTS_CHECK` and `SPOOFING_CHECK` to control sender verification and spoofing detection.
12
+
- Added support for maintaining a known senders list via the helper script `postfix-build-submission-recipients.sh`.
13
+
- Added separate documentation file `SENDER_MARKING.md` explaining the marking logic and setup in detail.
14
+
15
+
### Changed
16
+
- Improved performance of postfix log parsing by replacing external `date` calls with inline `Time::Piece` Perl code.
17
+
- Added explicit year handling in log timestamp parsing to ensure correct epoch comparison.
18
+
- Optimized `generate_html_report()` function: moved all log parsing and HTML generation to a single `awk` block.
19
+
- Report generation time reduced from **several minutes to a few seconds** for large log files.
@@ -35,7 +37,7 @@ This script generates an HTML report based on rejected messages. Another script
35
37
- The default subject is "[INFO] Postfix Bounce Report". A threshold can be set to change the subject to [WARNING]. If there is a match with the submission recipient list, [CRITICAL] is set.
36
38
37
39
> ⚠️ **Important Notice**
38
-
> This script has undergone **significant changes** in the latest version (2025-07-11).
40
+
> This script has undergone **significant changes** in the latest version (2025-07-18).
39
41
> If you have used a previous version, please consult the updated [CHANGELOG.md](./CHANGELOG.md) before upgrading.
40
42
> Existing setups may require adaptation to the new format and template handling.
41
43
@@ -105,25 +107,39 @@ Using a `.conf` file eliminates the need for additional XML parser dependencies.
105
107
106
108
The script reads its settings from a configuration file. Below is a list of supported options:
|`ONELINE="true"`| Displays each bounce in a **single unwrapped row**. Long lines are not broken – horizontal scrolling may be required. Useful for **fast scanning** or **compact overviews**. |
136
+
|`GROUP_BY_FROM="true"`| Groups all bounces by **sender address** (`from`). Each sender is shown with the **total number of bounces**, followed by a detailed list of individual bounces including **timestamp**, **recipient**, **IP**, and **rejection reason**. Ideal for **clustered analysis** of problematic senders. |
137
+
138
+
Example Use Cases:
139
+
140
+
- Set `ONELINE="true"` to review a high number of bounces quickly in a compact layout.
141
+
- Set `GROUP_BY_FROM="true"` to identify which senders cause the most issues and inspect grouped bounce details.
142
+
- Combine both for a condensed, grouped summary view – or set both to `false` for the full expanded format.
127
143
128
144
## Scheduled Execution (Cron)
129
145
@@ -192,6 +208,10 @@ Or if your system uses systemd timers:
192
208
systemctl list-timers --all | grep logrotate
193
209
```
194
210
211
+
## Sender Marking (optional)
212
+
213
+
For detailed information about how bounced emails are marked as **resent** or **spoofing**, and how the known senders list is generated and used, see the separate documentation file [SENDER_MARKING.md](./SENDER_MARKING.md).
214
+
195
215
## Contributions
196
216
197
217
Contributions are welcome! If you would like to improve this project, please feel free to submit a pull request. All contributions, bug reports, and feature suggestions are appreciated.
This document explains the logic behind marking bounced emails as **resent** or **spoofing** in the postfix bounce report script, and how related configuration and helper scripts work together.
4
+
5
+
## Purpose of Markings
6
+
7
+
-**Resent**: Marks emails from senders that you have previously sent mail to (i.e., known recipients), but where the sending domain is **outside** your trusted domain list.
8
+
These addresses are potentially trustworthy due to prior communication, but replies from external domains can cause false positives in bounce detection.
9
+
10
+
-**Spoofing**: Marks emails where the sender claims to be from one of your trusted internal domains but is **not recognized** as a known sender.
11
+
This signals possible spoofing attempts aiming to impersonate legitimate internal users or domains.
12
+
13
+
## Configuration Flags
14
+
15
+
-`RECIPIENTS_CHECK`
16
+
Enables checking if the sender is a known recipient based on an authenticated senders list. Necessary for correct **resent** marking.
17
+
18
+
-`SPOOFING_CHECK`
19
+
Enables detection of spoofing attempts by marking emails with sender domains in your trusted list, regardless of sender recognition.
20
+
21
+
-`DOMAINS`
22
+
A pipe-separated list of trusted internal email domains used to differentiate internal vs external domains.
23
+
24
+
## Known Senders List and Its Generation
25
+
26
+
The **known senders list** (`RECIPIENTS_LIST`) is a crucial data source used to identify trusted senders for the **resent** marking. This list is **continuously built and updated** by a separate helper script called `postfix-build-submission-recipients.sh`.
27
+
28
+
### Role of the Helper Script
29
+
30
+
- It parses the postfix mail logs for authenticated outbound emails (submission via SASL).
31
+
- Extracts sender addresses who have legitimately sent mail through your system.
32
+
- Normalizes and deduplicates these addresses.
33
+
- Updates the `RECIPIENTS_LIST` file.
34
+
35
+
Maintaining this list is essential because without it, the bounce report script cannot reliably distinguish known senders from unknown ones, reducing the accuracy of the **resent** marking.
36
+
37
+
## Marking Logic
38
+
39
+
- If the sender is known (a recipient you have previously sent mail to) and their domain is **not** in the trusted domains list → mark as **resent**.
40
+
This indicates mail coming from external domains tied to previously contacted addresses and can sometimes produce false positives.
41
+
42
+
- If the sender’s domain **is** in the trusted domains list → mark as **spoofing** (regardless of known status).
43
+
This helps detect impersonation attempts using your internal domains.
44
+
45
+
## Summary
46
+
47
+
To use the marking effectively:
48
+
49
+
- Enable `RECIPIENTS_CHECK` for known recipient verification.
50
+
- Enable `SPOOFING_CHECK` to detect spoofing attempts.
51
+
- Keep the known senders list updated regularly with the helper script `postfix-build-submission-recipients.sh`.
52
+
- Define your trusted domains clearly in the configuration.
53
+
54
+
Together, these mechanisms help you monitor and flag suspicious email activity in postfix bounce reports, while being aware that some resent markings may be false positives due to legitimate external replies.
0 commit comments