Skip to content

ASD Mail Flow Configuration Check

Jump to bottom
directorcia edited this page Nov 12, 2025 · 2 revisions

ASD Mail Flow Settings Compliance Check

Overview

The asd-mailflow-get.ps1 script validates Exchange Online mail flow configuration against the Australian Signals Directorate (ASD) Blueprint for Secure Cloud requirements. It performs automated compliance checks and generates detailed reports.

Version: 1.0
Author: CIAOPS
Date: 11-12-2025

Features

  • ✅ 13 Automated Compliance Checks - Validates all mail flow settings against ASD Blueprint
  • 📊 Interactive HTML Report - Professional compliance dashboard with visual indicators
  • 📁 CSV Export - Optional structured data export for further analysis
  • 📝 Detailed Logging - Optional verbose logging for troubleshooting
  • 🔄 Live Baseline Updates - Downloads latest requirements from GitHub
  • 🎨 Color-Coded Console Output - Easy-to-read terminal feedback
  • 🔒 Permission Validation - Checks user permissions before execution

Requirements

PowerShell Modules

  • ExchangeOnlineManagement - Microsoft's official Exchange Online module
# Install if not already present
Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser

Required Permissions

The script requires read-only access to Exchange Online organization configuration. One of the following roles is required:

  • Exchange Administrator
  • Global Administrator
  • Global Reader
  • View-Only Organization Management
  • Compliance Administrator

System Requirements

  • PowerShell 5.1 or PowerShell 7.x
  • Internet connection (for baseline download)
  • Windows, macOS, or Linux

Compliance Checks

The script validates the following 13 settings:

General Settings (2 checks)

  1. PlusAddressingEnabled - Plus addressing feature ([email protected])
  2. SendFromAliasesEnabled - Sending from email aliases

Security Settings (2 checks)

  1. SmtpClientAuthenticationDisabled - SMTP client authentication protocol
  2. AllowLegacyTLSClients - Legacy TLS (1.0/1.1) client support

Reply All Storm Protection (4 checks)

  1. ReplyAllStormProtectionEnabled - Storm protection feature
  2. ReplyAllStormProtectionMinimumRecipients - Minimum recipient threshold (2500)
  3. ReplyAllStormProtectionMinimumReplies - Minimum reply-all threshold (10)
  4. ReplyAllStormBlockDurationHours - Block duration (6 hours)

Message Recall Settings (5 checks)

  1. MessageRecallEnabled - Message recall feature
  2. RecallReadMessagesEnabled - Allow recalling read messages
  3. MessageRecallAlertRecipientsEnabled - Recipient alerts for recalls
  4. MessageRecallAlertRecipientsReadMessagesOnlyEnabled - Alert only for read messages
  5. MessageRecallMaxAgeInDays - Maximum age for recallable messages (1 day)

Usage

Basic Execution

.\asd-mailflow-get.ps1

Behavior:

  • Connects to Exchange Online (prompts for authentication if needed)
  • Downloads latest baseline from GitHub
  • Performs 13 compliance checks
  • Generates HTML report in parent directory
  • Opens report in default browser

With CSV Export

.\asd-mailflow-get.ps1 -ExportToCSV

Output:

  • HTML report (automatic)
  • CSV file with compliance data

With Detailed Logging

.\asd-mailflow-get.ps1 -DetailedLogging

Generates:

  • HTML report
  • Detailed log file with timestamps and diagnostic information

Custom Baseline File

.\asd-mailflow-get.ps1 -BaselinePath "C:\Baselines\custom-mailflow.json"

Use a local baseline file instead of downloading from GitHub.

Custom Output Paths

.\asd-mailflow-get.ps1 -ExportToCSV -CSVPath "C:\Reports\compliance.csv" -DetailedLogging -LogPath "C:\Logs\mailflow.log"

Specify custom locations for all output files.

Combined Options

.\asd-mailflow-get.ps1 -ExportToCSV -DetailedLogging -BaselinePath ".\baselines\production.json"

Parameters

Parameter Type Required Description
-ExportToCSV Switch No Export results to CSV file
-CSVPath String No Custom path for CSV export (default: parent directory with timestamp)
-BaselinePath String No Path or URL to baseline JSON file (default: GitHub URL)
-DetailedLogging Switch No Enable detailed logging to file
-LogPath String No Custom path for log file (default: parent directory with timestamp)

Output Files

All files are created in the parent directory by default (one level up from script location).

HTML Report (Always Generated)

Filename: asd-mailflow-get-YYYYMMDD-HHMMSS.html

Contents:

  • Executive summary with compliance percentage
  • Visual status cards (Total, Passed, Failed, Compliance %)
  • Organization information
  • Detailed results table with color-coded status
  • Links to ASD Blueprint documentation

CSV Export (Optional)

Filename: asd-mailflow-get-YYYYMMDD-HHMMSS.csv

Columns:

  • Setting
  • Description
  • CurrentValue
  • RequiredValue
  • Status (PASS/FAIL)

Log File (Optional)

Filename: asd-mailflow-get-YYYYMMDD-HHMMSS.log

Contents:

  • Timestamped events
  • Baseline loading details
  • Check results
  • Error messages and stack traces

Baseline Configuration

Default GitHub Baseline

The script downloads the latest baseline from:

https://raw.githubusercontent.com/directorcia/bp/main/ASD/Exchange-Online/Settings/mailflow.json

Baseline JSON Structure

{
  "metadata": {
    "sourceUrl": "https://blueprint.asd.gov.au/configuration/exchange-online/settings/mail-flow/",
    "generatedAt": "2025-11-12"
  },
  "general": {
    "plusAddressingEnabled": false,
    "sendFromAliasesEnabled": false
  },
  "security": {
    "smtpAuthProtocolEnabled": false,
    "legacyTlsClientsAllowed": false
  },
  "replyAllStormProtection": {
    "enabled": true,
    "minimumRecipients": 2500,
    "minimumReplyAlls": 10,
    "blockDurationHours": 6
  },
  "messageRecall": {
    "enabled": true,
    "allowRecallReadMessages": true,
    "enableRecipientAlerts": true,
    "alertReadMessagesOnly": true,
    "maxAgeDays": 1
  }
}

Custom Baselines

You can create custom baseline files for different environments:

Development Environment:

{
  "messageRecall": {
    "maxAgeDays": 7
  }
}

Production Environment:

{
  "messageRecall": {
    "maxAgeDays": 1
  }
}

Execution Flow

1. Initialization Phase

  • Loads script parameters
  • Sets default file paths
  • Initializes logging (if enabled)
  • Displays script banner

2. Baseline Loading Phase

  • Downloads baseline from GitHub (or loads local file)
  • Validates JSON schema
  • Falls back to built-in defaults if download fails
  • Maps JSON properties to PowerShell requirements

3. Module & Connection Phase

  • Checks for ExchangeOnlineManagement module
  • Tests existing Exchange Online connection
  • Connects to Exchange Online if needed
  • Validates user permissions

4. Data Collection Phase

  • Retrieves Get-OrganizationConfig data
  • Retrieves Get-TransportConfig data (for Reply-All Storm Protection)
  • Extracts all 13 mail flow settings
  • Stores current values for comparison

Important: Reply-All Storm Protection settings are retrieved from Get-TransportConfig, not Get-OrganizationConfig. The property names use "Detection" rather than "Protection":

  • ReplyAllStormProtectionEnabled
  • ReplyAllStormDetectionMinimumRecipients
  • ReplyAllStormDetectionMinimumReplies
  • ReplyAllStormBlockDurationHours

5. Compliance Check Phase

  • Compares each setting against baseline
  • Evaluates boolean, integer, and string values
  • Handles null values appropriately:
    • null boolean values treated as false (disabled)
    • null numeric values treated as 0
    • Exception: SmtpClientAuthenticationDisabled null treated as true
  • Records PASS/FAIL status for each check
  • Logs results (if detailed logging enabled)

6. Reporting Phase

  • Calculates compliance percentage
  • Displays results in console (color-coded)
  • Generates HTML report
  • Exports CSV (if requested)
  • Opens HTML report in browser

7. Cleanup Phase

  • Completes progress indicators
  • Writes final log entries
  • Returns results object

Technical Implementation Details

Configuration Sources

The script retrieves settings from two different Exchange Online cmdlets:

Setting Category Cmdlet Notes
General Settings Get-OrganizationConfig Plus addressing, aliases
Security Settings Get-TransportConfig SMTP auth (uses OrganizationConfig for legacy TLS)
Reply-All Storm Protection Get-TransportConfig Critical: Uses "Detection" in property names
Message Recall Get-OrganizationConfig All message recall settings

Null Value Handling

Exchange Online may return null for settings that are not explicitly configured but have default behavior:

# Boolean settings - null treated as False (disabled)
$plusAddressingValue = if ($null -eq $orgConfig.PlusAddressingEnabled) { $false } else { $orgConfig.PlusAddressingEnabled }

# Exception: SMTP Auth Disabled - null treated as True (auth is disabled by default)
$smtpAuthDisabledValue = if ($null -eq $orgConfig.SmtpClientAuthenticationDisabled) { $true } else { $orgConfig.SmtpClientAuthenticationDisabled }

# Numeric settings - null treated as 0
$replyAllStormMinRecipientsValue = if ($null -eq $transportConfig.ReplyAllStormDetectionMinimumRecipients) { 0 } else { $transportConfig.ReplyAllStormDetectionMinimumRecipients }

This ensures accurate reporting instead of showing "Not set" when values have default behaviors.

Console Output

Success Output Example

========================================
  ASD Mail Flow Settings Check
========================================
Baseline: GitHub (latest)
Location: https://raw.githubusercontent.com/directorcia/bp/main/ASD/Exchange-Online/Settings/mailflow.json
Output:   C:\downloads\source

Downloading baseline settings from: https://...
✓ Baseline loaded successfully from GitHub.

Checking for ExchangeOnlineManagement module...
ExchangeOnlineManagement module already loaded.

Checking Exchange Online connection...
Already connected to Exchange Online.

Validating Exchange Online permissions...
Permission validation passed.

Retrieving organization mail flow configuration...
Organization configuration retrieved: Contoso Ltd
Retrieving transport configuration...
Transport configuration retrieved.

Checking settings against ASD Blueprint requirements...

========================================
  CHECK RESULTS
========================================

[✓] PlusAddressingEnabled
    Description : Allow plus addressing ([email protected])
    Current     : False
    Required    : False
    Status      : PASS

[✓] ReplyAllStormProtectionEnabled
    Description : Enable reply all storm protection
    Current     : True
    Required    : True
    Status      : PASS

[✓] ReplyAllStormProtectionMinimumRecipients
    Description : Minimum recipients to trigger protection
    Current     : 2500
    Required    : 2500
    Status      : PASS

========================================
  SUMMARY
========================================
Total Checks    : 13
Passed          : 13
Failed          : 0
Compliance      : 100%

Status          : COMPLIANT ✓
========================================

Generating HTML report...
HTML report generated: C:\downloads\asd-mailflow-get-20251112-143022.html
Opening report in default browser...

Script completed successfully.

Failure Output Example

[✗] SmtpClientAuthenticationDisabled
    Description : SMTP client authentication (should be disabled)
    Current     : False
    Required    : True
    Status      : FAIL

========================================
  SUMMARY
========================================
Total Checks    : 13
Passed          : 11
Failed          : 2
Compliance      : 84.62%

Status          : NON-COMPLIANT ✗
========================================

HTML Report

Report Sections

  1. Header

    • Report title
    • Subtitle
    • Generation timestamp

  2. Summary Cards

    • Total Checks (blue)
    • Passed Checks (green)
    • Failed Checks (red)
    • Compliance Percentage (green/red based on status)

  3. Organization Information

    • Organization display name
    • Organization identity
    • Baseline source (GitHub/Local/Built-in)

  4. Detailed Results Table

    • Status badge (✓ PASS / ✗ FAIL)
    • Setting name
    • Description
    • Current value
    • Required value

  5. Overall Status Banner

    • COMPLIANT (green) or NON-COMPLIANT (red)
    • Summary text

  6. Footer

    • Link to ASD Blueprint documentation
    • Link to security controls explanation

Report Features

  • Responsive Design - Adapts to screen size
  • Print-Friendly - Clean layout for PDF generation
  • Hover Effects - Interactive card animations
  • Color Coding - Visual status indicators
  • Professional Styling - Gradient backgrounds and shadows

Troubleshooting

Module Not Found

Error: ExchangeOnlineManagement module not found!

Solution:

Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser

Connection Failure

Error: Failed to connect to Exchange Online

Solutions:

  • Ensure internet connectivity
  • Verify Microsoft 365 credentials
  • Check for service outages
  • Disable proxy if causing issues

Permission Denied

Error: ❌ INSUFFICIENT PERMISSIONS

Solution:

  1. Contact Exchange Online administrator
  2. Request one of the required roles:
    • Exchange Administrator
    • Global Administrator
    • Global Reader
    • View-Only Organization Management
    • Compliance Administrator
  3. Wait 5-10 minutes for role assignment propagation
  4. Re-run the script

Baseline Download Failure

Error: Failed to download or parse baseline from URL

Behavior:

  • Script continues with built-in ASD Blueprint defaults
  • Warning message displayed
  • No impact on script execution

Manual Solution:

# Download baseline manually and use local file
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/directorcia/bp/main/ASD/Exchange-Online/Settings/mailflow.json" -OutFile ".\mailflow.json"
.\asd-mailflow-get.ps1 -BaselinePath ".\mailflow.json"

Settings Show "Not set" Instead of Actual Values

Issue: Report shows "Not set" for configured settings

Cause: Exchange Online returns null for settings with default values rather than explicit false or 0.

Resolution: Script now handles null values appropriately:

  • Boolean settings: null → false
  • Numeric settings: null → 0
  • Exception: SmtpClientAuthenticationDisabled treats null → true

This was fixed in version 1.0 to ensure accurate compliance reporting.

Reply-All Storm Protection Settings Not Detected

Issue: Reply-All Storm Protection settings show as "Not set" even when configured

Cause: These settings are in Get-TransportConfig, not Get-OrganizationConfig

Property Names:

  • ReplyAllStormProtectionEnabled (in TransportConfig)
  • ReplyAllStormDetectionMinimumRecipients (note: "Detection" not "Protection")
  • ReplyAllStormDetectionMinimumReplies (note: "Detection" not "Protection")
  • ReplyAllStormBlockDurationHours (in TransportConfig)

Resolution: Script now correctly retrieves these settings from Get-TransportConfig with the correct property names.

Log File Not Created

Issue: Detailed logging enabled but no log file

Check:

  • Verify write permissions to output directory
  • Check disk space
  • Review any error messages in console

Advanced Usage

Scheduled Compliance Checks

Run automated compliance checks using Windows Task Scheduler or cron:

# Windows Task Scheduler command
powershell.exe -ExecutionPolicy Bypass -File "C:\Scripts\asd-mailflow-get.ps1" -ExportToCSV -DetailedLogging

Integration with Monitoring Systems

Export CSV data for ingestion into monitoring platforms:

$results = .\asd-mailflow-get.ps1 -ExportToCSV
$failed = Import-Csv ".\asd-mailflow-get-*.csv" | Where-Object { $_.Status -eq "FAIL" }
if ($failed) {
    # Send alert to monitoring system
    Send-Alert -Message "Mail flow compliance failures detected" -Data $failed
}

Multiple Tenant Checks

Check multiple Exchange Online tenants:

$tenants = @("tenant1.onmicrosoft.com", "tenant2.onmicrosoft.com")

foreach ($tenant in $tenants) {
    Write-Host "Checking tenant: $tenant"
    Connect-ExchangeOnline -UserPrincipalName "admin@$tenant" -ShowBanner:$false
    .\asd-mailflow-get.ps1 -ExportToCSV
    Disconnect-ExchangeOnline -Confirm:$false
}

Custom Compliance Standards

Create organization-specific baselines:

# Create custom baseline
$customBaseline = @{
    messageRecall = @{
        enabled = $true
        maxAgeDays = 3  # Organization-specific requirement
    }
} | ConvertTo-Json -Depth 5

$customBaseline | Out-File ".\custom-baseline.json"

# Use custom baseline
.\asd-mailflow-get.ps1 -BaselinePath ".\custom-baseline.json"

Script Architecture

Functions

Function Purpose
Write-Log Writes timestamped entries to log file
Write-ColorOutput Displays color-coded console messages
Get-BaselineValue Safely extracts values from JSON baseline
Test-BaselineSchema Validates JSON structure
Get-BaselineSettings Loads and parses baseline configuration
Test-ExchangeModule Checks and loads Exchange Online module
Connect-EXO Establishes Exchange Online connection
Test-ExchangePermissions Validates user permissions
Test-Setting Compares individual setting against baseline
New-HTMLReport Generates professional compliance report
Invoke-MailFlowCheck Main orchestration function

Script Variables

Variable Scope Description
$script:BaselinePath Script Baseline file path or URL
$script:baselineLoaded Script Baseline load success indicator
$script:HTMLPath Script HTML report output path
$script:LogPath Script Log file path
$script:DetailedLogging Script Logging enabled flag

Error Handling

  • Try-Catch Blocks - Wrap all external operations
  • ErrorAction Stop - Explicit error handling
  • Graceful Degradation - Falls back to defaults when possible
  • User-Friendly Messages - Clear error descriptions with solutions
  • Detailed Stack Traces - Available in log files

Best Practices

Regular Compliance Checks

  • Run weekly or monthly compliance checks
  • Schedule checks after configuration changes
  • Document compliance trends over time

Baseline Management

  • Review baseline updates quarterly
  • Test baseline changes in non-production first
  • Version control custom baselines

Security Considerations

  • Use service accounts with minimal permissions
  • Store credentials securely (not in scripts)
  • Review logs for unauthorized changes
  • Audit compliance check results

Reporting

  • Archive HTML reports for compliance audits
  • Share reports with security teams
  • Track remediation of failed checks
  • Export CSV for long-term analysis

References

Documentation Links

Exchange Online PowerShell

Version History

Version Date Changes
1.0 2025-11-12 Initial release with 13 compliance checks, HTML reporting, CSV export, and detailed logging. Fixed null value handling and Reply-All Storm Protection detection.

Support

For issues, questions, or contributions:

License

This script is provided as-is for use in compliance checking and auditing of Exchange Online mail flow configurations against ASD Blueprint requirements.

Last Updated: November 12, 2025
Script Version: 1.0
Author: CIAOPS

Clone this wiki locally