Email Header Report Tool - directorcia/Office365 GitHub Wiki
Overview
The Email Header Report Tool is a PowerShell script that analyzes email headers to identify potential spam, phishing, and security concerns in messages processed by Exchange Online and Microsoft 365. This tool provides security administrators and email analysts with a comprehensive report of authentication results, spam filtering decisions, and other security-related information embedded in email headers.
Features
- Authentication Analysis: Evaluates SPF, DKIM, and DMARC authentication results
- Spam Filter Analysis: Examines SCL (Spam Confidence Level) and other spam indicators
- Defender for Office 365 Analysis: Analyzes Safe Links and Safe Attachments processing results
- Transport Rule Detection: Identifies if mail flow rules were applied to the message
- Risk Assessment: Provides an overall verdict with color-coded risk indicators
- Recommendations: Suggests appropriate actions based on analysis results
Requirements
- PowerShell 5.0 or higher
- Access to email headers from Exchange Online/Microsoft 365 environment
- Windows with support for color console output (for optimal viewing experience)
Usage
.\email-header-report.ps1 -HeaderFilePath "C:\path\to\email_header.txt"
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| HeaderFilePath | String | Yes | Path to the text file containing the raw email header |
How to Extract Email Headers
From Outlook Desktop
- Open the email message
- Click File > Properties
- The headers appear in the "Internet headers" box
- Select all and copy to a text file
From Outlook Web App (OWA)
- Open the email message
- Click the three dots (⋯) in the top-right corner
- Select "View message details" or "View > Message details"
- Copy the headers to a text file
From Microsoft 365 Security Portal
- Navigate to the message in quarantine or Explorer view
- Select the message and view details
- Find and copy the headers to a text file
Understanding the Report
The report is divided into several sections:
Authentication Analysis
Shows the results of email authentication protocols:
- SPF (Sender Policy Framework): Verifies if the sending server is authorized to send email for the domain
- DKIM (DomainKeys Identified Mail): Validates the digital signature attached to the message
- DMARC (Domain-based Message Authentication, Reporting, and Conformance): Evaluates alignment between the sender's domain and the authenticated domain
- CompAuth: Microsoft's composite authentication result
Spam Filtering Analysis
Details how Exchange Online Protection and Microsoft 365 evaluated the message:
- SCL (Spam Confidence Level): Score from -1 to 9 indicating spam probability
- BCL (Bulk Complaint Level): Score from 0 to 9 for bulk email
- Forefront Anti-Spam Report: Detailed anti-spam processing information
- Delivery Destination: Where the message was delivered (Inbox, Junk, Quarantine, etc.)
Safe Attachments Analysis
Shows results from Defender for Office 365 attachment scanning:
- Clean: No malicious content detected
- Block: Malicious content detected and blocked
- Replace: Malicious attachment replaced with a placeholder
- DynamicDelivery: Attachment analysis performed with temporary placeholder
Safe Links Analysis
Shows results from Defender for Office 365 URL scanning:
- Clean: No malicious URLs detected
- Block: Malicious URLs detected and rewritten/blocked
- Pending: Analysis in progress
- Not Scanned: URLs were not evaluated
General Message Analysis
Provides additional information about the message:
- Originating IP: Source IP address of the sender
- Message ID: Unique identifier for the message
- Return-Path vs From: Compares the envelope sender with the display sender
Analysis Summary
Provides an overall verdict based on all factors:
- High Risk / Spam Detected: Strong indicators of being spam or malicious
- Potential Risk / Likely Spam: Several characteristics of spam or unwanted mail
- Likely Legitimate: Message appears to be legitimate based on key checks
- Mixed Results / Caution Advised: Some checks passed, others raised concerns
Interpreting Key Values
SCL (Spam Confidence Level)
| Value | Meaning | Typical Action |
|---|---|---|
| -1 | Trusted sender | Bypasses spam filtering |
| 0-1 | Not spam | Delivered to inbox |
| 2-4 | Low spam probability | Usually delivered to inbox |
| 5-6 | Spam | Usually delivered to junk folder |
| 7-9 | High confidence spam | Quarantined or rejected |
Authentication Results
| Result | Meaning |
|---|---|
| Pass | Authentication successful |
| Fail | Authentication failed |
| SoftFail | Weak failure (typically for SPF) |
| Neutral | No policy assertion |
| None | No policy found |
| PermError | Permanent error in policy |
| TempError | Temporary error during lookup |
Examples
Legitimate Message Example
AUTHENTICATION ANALYSIS
-----------------------
[SPF] PASS
[DKIM] PASS
[DMARC] PASS
[Composite Auth (CompAuth)] PASS
EXCHANGE ONLINE SPAM FILTERING ANALYSIS
--------------------------------------
[SCL (Spam Confidence Level)] 0 - Not spam (message determined to be clean by EOP content filter).
MESSAGE VERDICT:
──────────────────────────────────────────────────
✅ LIKELY LEGITIMATE
This message appears to be legitimate based on key checks.
Spam Message Example
AUTHENTICATION ANALYSIS
-----------------------
[SPF] FAIL
[DKIM] FAIL
[DMARC] FAIL
[Composite Auth (CompAuth)] FAIL
EXCHANGE ONLINE SPAM FILTERING ANALYSIS
--------------------------------------
[SCL (Spam Confidence Level)] 9 - Definite spam (highest confidence, typically quarantined or rejected).
MESSAGE VERDICT:
──────────────────────────────────────────────────
🚨 HIGH RISK / SPAM DETECTED
This message shows strong indicators of being spam or malicious.
Troubleshooting
Script Errors
- Ensure you're using PowerShell 5.0 or higher
- Verify the header file exists and is readable
- Check that the header file contains valid email headers
Missing Information
- Some headers might not be present depending on:
- Email routing path
- Microsoft 365 subscription level
- Security features enabled in your tenant
- Age of the message (older messages might use different headers)
False Positives/Negatives
- The tool analyzes only what's present in the headers
- It doesn't re-evaluate the message content
- Discrepancies may occur if policies changed after message delivery
Advanced Usage
Piping Output
You can redirect the output to a file:
.\email-header-report.ps1 -HeaderFilePath "C:\path\to\header.txt" > "report.txt"
Incorporating into Other Scripts
The script can be called from other PowerShell scripts or functions:
& "C:\path\to\email-header-report.ps1" -HeaderFilePath $headerPath
References
- Microsoft 365 Security Documentation
- Exchange Online Protection (EOP)
- Anti-spam message headers in Microsoft 365
- Spam confidence levels (SCL)
- Bulk Complaint Level (BCL) values
- How Microsoft 365 uses SPF
- How Microsoft 365 uses DKIM
- How Microsoft 365 uses DMARC
- RFC 5322 (Internet Message Format)
- RFC 7208 (SPF)
- RFC 6376 (DKIM)
- RFC 7489 (DMARC)
Version History
| Version | Date | Changes |
|---|---|---|
| 1.1 | 2025-05-27 | Added support for improved DMARC analysis, enhanced result display, and expanded recommendations |
| 1.0 | 2024-04-15 | Initial release |
License
This script is provided as-is with no warranties. Use at your own risk.