What This Script Does
Configures Microsoft 365 to allow CyberHoot phishing simulation emails to bypass security filters while maintaining protection for real threats. It handles two critical configurations:
- Advanced Delivery – Allows CyberHoot simulation emails through spam/phishing filters
- Safe Links – Prevents Microsoft from rewriting/clicking simulation URLs (eliminates false click reports)
Prerequisites
- PowerShell: Windows PowerShell 5.1+ or PowerShell 7+ (pwsh)
- Permissions: Exchange Online administrator role
- Module: ExchangeOnlineManagement (script will install if missing)
Installation
Windows
- Download
CyberHoot-M365.ps1to a working directory - Open PowerShell as Administrator
- Navigate to the directory:
cd C:pathtoscript
macOS/Linux
- Download
CyberHoot-M365.ps1to a working directory - Open Terminal
- Navigate to the directory:
cd /path/to/script - Make executable:
chmod +x CyberHoot-M365.ps1
How to Allow-List Link Protection
PowerShell Script to Bypass Link Protection in M365
Save this text file as a .ps1 file and then run as a PowerShell script with appropriate permissions.
Recommended Workflow
Step 1: Validate Current Configuration (Optional but Recommended)
Check what’s currently configured and what will be added:
./CyberHoot-M365.ps1 -Mode Validate
```
**What it does:**
- Shows which CyberHoot entries are missing
- Reports on existing configuration
- **Makes no changes** to your environment
- Creates JSON snapshots in current directory
**Sample Output:**
```
Validation report:
Advanced Delivery:
Rule exists: False
Missing domains: 10
Missing IP ranges: 9
Missing simulation URLs: 10
Safe Links:
Policy exists: False
Rule exists: False
Missing DoNotRewriteUrls: 10Step 2: Apply Configuration
Deploy the CyberHoot configuration:
./CyberHoot-M365.ps1 -Mode Apply
```
**What it does:**
- Creates/updates Advanced Delivery phishing simulation rules
- Creates/updates Safe Links exclusions
- **Preserves existing vendor entries** (KnowBe4, Proofpoint, etc.)
- Creates before/after JSON snapshots
- Shows summary of what was added
**Sample Output:**
```
Apply completed.
Summary:
Mode: Apply
Domains added: 10
IPs added: 9
Simulation URLs added: 10
DoNotRewriteUrls added: 10
Step 3: Verify (Optional)
Re-run validation to confirm everything applied:
./CyberHoot-M365.ps1 -Mode ValidateShould show all missing counts at 0.
Advanced Usage
Verbose Logging
Get detailed output during execution:
./CyberHoot-M365.ps1 -Mode Apply -VerboseCustom Output Directory
Save snapshots to a specific folder:
./CyberHoot-M365.ps1 -Mode Apply -OutputDir "C:M365-Snapshots"Rollback Configuration
Remove only CyberHoot entries (preserves other vendors):
./CyberHoot-M365.ps1 -Mode RollbackWarning: This removes CyberHoot’s configuration. Only use if you’re discontinuing CyberHoot or troubleshooting.
Understanding the Output
JSON Snapshots
The script creates timestamped JSON files:
cyberhoot-m365-Apply-before-YYYYMMDD-HHMMSS.json– State before changescyberhoot-m365-Apply-after-YYYYMMDD-HHMMSS.json– State after changes
Use these for:
- Audit trails
- Change documentation
- Troubleshooting
- Compliance reporting
Troubleshooting
“Missing required cmdlets”
Cause: Insufficient permissions or tenant licensing
Solution: Ensure you have Exchange Online administrator role and Advanced Delivery is available in your tenant
“Pre-flight read check failed”
Cause: Connectivity or permission issues
Solution: Verify you can access Exchange Online admin center manually
Script shows 0 items added on second run
Expected behavior: Script is idempotent – safe to run multiple times without duplicating entries
Safe Links still rewriting URLs after running script
Cause: Configuration propagation delay
Solution: Wait 15-30 minutes, then send a test simulation email
Important Notes
- Multi-vendor safe: This script merges with existing phishing simulation vendors (doesn’t overwrite)
- Idempotent: Safe to run multiple times
- Tenant-wide scope: Safe Links rule applies to all accepted domains
- Propagation time: Allow 15-30 minutes for Safe Links changes to take effect
Support
For issues with the script, review:
- Before/after JSON snapshots
- Verbose output:
./CyberHoot-M365.ps1 -Mode Validate -Verbose - Microsoft 365 Admin Center → Security → Advanced Delivery
The post HowTo: PowerShell Script for Safe Links Configuration in M365 appeared first on CyberHoot.