PowerShell Script

PowerShell Mastery: Configuring Safe Links in Microsoft 365 Like a Pro

Discover how to set up Microsoft 365 to let CyberHoot phishing simulation emails bypass security filters, all while keeping strong protection against real threats. This guide walks you through two key configurations:

  • Advanced Delivery: Lets CyberHoot simulation emails get through spam and phishing filters.
  • Safe Links: Stops Microsoft from rewriting or clicking on simulation URLs, getting rid of false click reports.

What You Need Before Starting

  • PowerShell: Windows PowerShell 5.1+ or PowerShell 7+ (pwsh)
  • Permissions: Exchange Online administrator role
  • Module: ExchangeOnlineManagement (don’t worry, the script will install this if it’s missing)

Installation

Windows

  1. Download CyberHoot-M365.ps1 to a working directory.
  2. Open PowerShell as Administrator.
  3. Navigate to the directory: cd C:pathtoscript

macOS/Linux

  1. Download CyberHoot-M365.ps1 to a working directory.
  2. Open Terminal.
  3. Navigate to the directory: cd /path/to/script
  4. Make executable: chmod +x CyberHoot-M365.ps1

How to Allow-List Link Protection

Save the provided text file as a .ps1 file and run it as a PowerShell script with the 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 the existing configuration.
  • Makes no changes to your environment.
  • Creates JSON snapshots in the 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: 10

Step 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 a 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 was applied:

./CyberHoot-M365.ps1 -Mode Validate

This should show all missing counts at 0.

Advanced Usage

Verbose Logging

Get detailed output during execution:

./CyberHoot-M365.ps1 -Mode Apply -Verbose

Custom 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 Rollback

Warning: This removes CyberHoot’s configuration. Use this only 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 changes.
  • cyberhoot-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 the Exchange Online administrator role and that Advanced Delivery is available in your tenant.

“Pre-flight read check failed”

Cause: Connectivity or permission issues.

Solution: Verify you can access the Exchange Online admin center manually.

Script shows 0 items added on second run

Expected behavior: The script is idempotent and 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

Similar Posts