# CyberHoot M365 Configuration Guide

This guide will walk you through configuring Microsoft 365 to allow CyberHoot phishing simulation emails using our automated PowerShell script.

---

## What This Script Does

This script automatically configures your Microsoft 365 tenant to allow CyberHoot phishing simulations by:

1. **Advanced Delivery Configuration**: Adds CyberHoot domains and IP addresses to your phishing simulation allowlist
2. **Safe Links Exclusions**: Prevents Microsoft from rewriting CyberHoot URLs in emails
3. **Organization Customization**: Enables required M365 features automatically

---

## Prerequisites

### Required Permissions
You need one of these admin roles in Microsoft 365:
- **Global Administrator**
- **Security Administrator** 
- **Exchange Administrator**

### Required Software

**For Windows Users:**
- PowerShell 7+ (recommended) or Windows PowerShell 5.1+

**For Mac Users:**
- PowerShell 7+ (required)
- Install via: `brew install --cask powershell`

**For Linux Users:**
- PowerShell 7+ (required)
- [Installation instructions](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux)

---

## Step 1: Download and Save the Script

Since WordPress doesn't allow .ps1 file uploads, the script is provided as a .txt file. You'll need to save it with the correct extension:

### Method 1: Copy and Save (Recommended)

1. **Open the script in your browser**: [CyberHoot-M365.txt](https://cyberhoot.com/wp-content/uploads/2026/02/CyberHoot-M365.txt)
2. **Select all the text** (Ctrl+A on Windows, Cmd+A on Mac)
3. **Copy the text** (Ctrl+C on Windows, Cmd+C on Mac)
4. **Open a text editor**:
   - **Windows**: Notepad (search "Notepad" in Start Menu)
   - **Mac**: TextEdit (Applications → TextEdit)
   - **Linux**: gedit, nano, or any text editor
5. **Paste the script** (Ctrl+V on Windows, Cmd+V on Mac)
6. **Save the file**:
   - **Windows**: 
     - Click File → Save As
     - Navigate to your Downloads folder
     - In "File name", type: `CyberHoot-M365.ps1` (include the quotes to force the .ps1 extension)
     - In "Save as type", select "All Files (*.*)"
     - Click Save
   - **Mac**:
     - Click Format → Make Plain Text (if using TextEdit)
     - Click File → Save
     - Name it: `CyberHoot-M365.ps1`
     - Remove the ".txt" if it tries to add it
     - Click Save
   - **Linux**:
     - Save as: `CyberHoot-M365.ps1`

### Method 2: Download and Rename

1. **Download the file**: [CyberHoot-M365.txt](https://cyberhoot.com/wp-content/uploads/2026/02/CyberHoot-M365.txt)
2. **Rename the file**:
   - **Windows**: Right-click the file → Rename → Change from `CyberHoot-M365.txt` to `CyberHoot-M365.ps1`
   - **Mac**: Click the file → Press Enter → Change the extension from `.txt` to `.ps1` → Click "Use .ps1" when warned
   - **Linux**: `mv CyberHoot-M365.txt CyberHoot-M365.ps1`

**Important:** The file MUST have the `.ps1` extension for PowerShell to recognize it as a script.

---

## Step 2: Install Required PowerShell Module

The script will automatically install the `ExchangeOnlineManagement` module if it's not present, but you can install it manually beforehand:

```powershell
Install-Module -Name ExchangeOnlineManagement -Force
```

---

## Step 3: Run the Script

### On Windows:

1. **Open PowerShell as Administrator**
   - Right-click Start Menu → "Windows PowerShell" or "PowerShell 7"
   - Select "Run as Administrator"

2. **Navigate to the script location**
   ```powershell
   cd C:\Users\YourUsername\Downloads
   ```

3. **Run the script**
   ```powershell
   pwsh -File .\CyberHoot-M365-FIXED.ps1 -Mode Apply -Verbose
   ```
   
   *If you get an execution policy error, run this first:*
   ```powershell
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   ```

### On Mac:

1. **Open Terminal**
   - Press `Cmd + Space`, type "Terminal", press Enter

2. **Navigate to the script location**
   ```bash
   cd ~/Downloads
   ```

3. **Run the script**
   ```bash
   pwsh -File ./CyberHoot-M365-FIXED.ps1 -Mode Apply -Verbose
   ```

### On Linux:

1. **Open your terminal**

2. **Navigate to the script location**
   ```bash
   cd ~/Downloads
   ```

3. **Run the script**
   ```bash
   pwsh -File ./CyberHoot-M365-FIXED.ps1 -Mode Apply -Verbose
   ```

---

## Step 4: Authenticate

1. When prompted, enter your **Microsoft 365 admin email address**
   ```
   Enter your Exchange admin email or UPN: admin@yourcompany.onmicrosoft.com
   ```

2. A browser window will open for authentication
   - Sign in with your admin credentials
   - Complete any multi-factor authentication (MFA) if required
   - Close the browser window when authentication is complete

---

## Step 5: Wait for Completion

The script will:

1. **Connect to Exchange Online** (30-60 seconds)
2. **Enable organization customization** if needed (30 seconds wait time)
3. **Configure Advanced Delivery** policy and rules
4. **Create Safe Links exclusions**
5. **Generate before/after snapshots** (saved as JSON files in the same directory)

**Expected output:**
```
Mode: Apply
VERBOSE: Organization customization enabled - waiting 30 seconds for replication...
VERBOSE: Creating Safe Links policy: CyberHoot - Safe Links Exclusions
Apply completed.

Summary:
  Mode: Apply
  Domains added:            5
  IPs added:                4
  Simulation URLs added:    5
  DoNotRewriteUrls added:   5

Disconnected.
```

**Total time:** 2-5 minutes

---

## Step 6: Verify Configuration

### Verify Advanced Delivery:

1. Go to **Microsoft 365 Defender portal**: https://security.microsoft.com
2. Navigate to: **Email & collaboration** → **Policies & rules** → **Threat policies** → **Advanced delivery**
3. Click on the **"Phishing simulation"** tab
4. Verify you see:
   - ✅ **Domains**: cyberhoot.com, docunotice.com, messagecenters.net, securedinbox.net, notificationhub.net
   - ✅ **IP addresses**: 23.20.251.170/32, 52.7.191.238/32, 52.6.6.155/32, 18.213.175.22/32

### Verify Safe Links:

1. In Microsoft 365 Defender portal, navigate to: **Email & collaboration** → **Policies & rules** → **Threat policies** → **Safe Links**
2. Click on **"CyberHoot - Safe Links Exclusions"**
3. Under **"Protection settings"**, expand **"Email"** section
4. Verify **"Do not rewrite the following URLs in email (5)"** shows all 5 CyberHoot domains

---

## Troubleshooting

### "The file is not a valid PowerShell script"

**Cause:** The file still has a .txt extension instead of .ps1

**Solution:**
1. Make sure the file is named `CyberHoot-M365.ps1` (not `CyberHoot-M365.txt` or `CyberHoot-M365.ps1.txt`)
2. In Windows File Explorer: View → Show → File name extensions (to see the real extension)
3. Rename the file to have the `.ps1` extension

### "Script execution is disabled on this system"

**Solution:**
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### "Cannot find path" or "No such file or directory"

**Solution:** Make sure you're in the correct directory where the script is saved:
```powershell
# Windows
cd C:\Users\YourUsername\Downloads

# Mac/Linux  
cd ~/Downloads
```

### "The command you tried to run isn't currently allowed"

This means organization customization is still being enabled. The script handles this automatically by:
1. Running `Enable-OrganizationCustomization`
2. Waiting 30 seconds for replication

If you still see this error after the script completes, wait 5-10 minutes and run the script again.

### "Compliance policy count limit is exceeded"

This is **normal and expected** - it means a policy already exists from a previous run. The script will automatically use the existing policy. You can ignore this message.

### "Query 1 failed" messages

These are **harmless** - they're just Microsoft's API being unreliable with GET requests. As long as the script shows "Apply completed" at the end, everything worked correctly.

### Authentication keeps failing

**Solutions:**
1. Verify you're using an account with admin permissions
2. Complete any MFA challenges that appear
3. Try using an InPrivate/Incognito browser window
4. Ensure your account isn't blocked by conditional access policies

---

## Script Modes

The script supports three modes:

### Apply Mode (Default)
Configures your M365 tenant with CyberHoot settings:
```powershell
pwsh -File ./CyberHoot-M365-FIXED.ps1 -Mode Apply -Verbose
```

### Validate Mode
Checks current configuration without making changes:
```powershell
pwsh -File ./CyberHoot-M365-FIXED.ps1 -Mode Validate -Verbose
```

### Rollback Mode
Removes CyberHoot configuration from your tenant:
```powershell
pwsh -File ./CyberHoot-M365-FIXED.ps1 -Mode Rollback -Verbose
```

---

## What Gets Configured

### Domains Allowlisted:
- cyberhoot.com
- docunotice.com
- messagecenters.net
- securedinbox.net
- notificationhub.net

### IP Addresses Allowlisted:
- 23.20.251.170/32
- 52.7.191.238/32
- 52.6.6.155/32
- 18.213.175.22/32

### Safe Links Exclusions:
All 5 domains above are excluded from URL rewriting

---

## Snapshot Files

The script creates JSON snapshot files before and after making changes:
- `cyberhoot-m365-Apply-before-YYYYMMDD-HHMMSS.json`
- `cyberhoot-m365-Apply-after-YYYYMMDD-HHMMSS.json`

These files can be used for:
- Auditing changes
- Troubleshooting
- Compliance documentation
- Rollback reference

---

## Running on Multiple Tenants

If you manage multiple M365 tenants:

1. Run the script once per tenant
2. Each time you run it, you'll be prompted to authenticate
3. The script will configure only the tenant you authenticate to
4. Snapshots are saved in the current directory with timestamps

---

## Security Notes

- ✅ The script only configures phishing simulation allowlists
- ✅ No security protections are disabled
- ✅ Your existing policies are preserved and merged with CyberHoot settings
- ✅ All changes are logged in snapshot files
- ✅ Configuration can be removed using Rollback mode

---

## Support

If you encounter issues:

1. **Check the snapshot files** - They contain detailed configuration information
2. **Run in Validate mode** - See what would change without making changes
3. **Contact CyberHoot Support** - Include:
   - The complete script output (copy/paste from terminal)
   - Your snapshot JSON files
   - Your M365 tenant type (E3, E5, Business Premium, etc.)

---

## Frequently Asked Questions

### Q: Why is the script a .txt file instead of .ps1?
**A:** WordPress security doesn't allow uploading .ps1 files. Simply copy the contents and save it as a .ps1 file following Step 1 instructions.

### Q: Will this affect my existing M365 security policies?
**A:** No. The script only adds CyberHoot domains/IPs to your allowlists. All existing security protections remain active.

### Q: Can I run this script multiple times?
**A:** Yes. The script is idempotent - running it multiple times won't create duplicates or cause errors.

### Q: What if I need to remove the CyberHoot configuration later?
**A:** Run the script in Rollback mode:
```powershell
pwsh -File ./CyberHoot-M365-FIXED.ps1 -Mode Rollback -Verbose
```

### Q: Do I need to run this for each user?
**A:** No. This is a tenant-wide configuration that applies to all users automatically.

### Q: How long does the configuration take to propagate?
**A:** Changes are typically effective immediately, but Microsoft recommends allowing up to 24 hours for full propagation across all services.

### Q: Can I use this with Microsoft 365 Government (GCC) tenants?
**A:** Yes, the script works with GCC, GCC High, and DoD tenants.

### Q: What M365 licenses are required?
**A:** You need Microsoft Defender for Office 365 (Plan 1 or Plan 2) for Safe Links policies. This is included in:
- Microsoft 365 E5
- Microsoft 365 E3 + Defender for Office 365 Plan 1/2
- Microsoft 365 Business Premium

---

## Changelog

### Version 2.0 (February 2025)
- ✅ Fixed deprecated `-PhishSimOverrideUrl` parameter
- ✅ Fixed deprecated `-IsEnabled` parameter on Safe Links policies
- ✅ Added automatic organization customization detection and enablement
- ✅ Improved error handling for existing policies and rules
- ✅ Added better detection of existing PhishSimOverrideRule
- ✅ Pre-flight checks made optional due to Microsoft API instability

### Version 1.0 (January 2025)
- Initial release

---

## Technical Details

For IT professionals who want to understand what the script does:

### Advanced Delivery Configuration:
```powershell
# Creates or updates PhishSimOverridePolicy
New-PhishSimOverridePolicy -Name "PhishSimOverridePolicy"
Set-PhishSimOverridePolicy -Identity "PhishSimOverridePolicy" -Enabled $true

# Creates or updates ExoPhishSimOverrideRule
New-ExoPhishSimOverrideRule -Name "CyberHoot - PhishSim Override Rule" `
  -Policy "PhishSimOverridePolicy" `
  -Domains @("cyberhoot.com", ...) `
  -SenderIpRanges @("23.20.251.170/32", ...)
```

### Safe Links Configuration:
```powershell
# Enables organization customization (if needed)
Enable-OrganizationCustomization

# Creates Safe Links policy with exclusions
New-SafeLinksPolicy -Name "CyberHoot - Safe Links Exclusions" `
  -EnableSafeLinksForEmail $true `
  -DoNotRewriteUrls @("cyberhoot.com", ...)

# Creates Safe Links rule (tenant-wide)
New-SafeLinksRule -Name "CyberHoot - Safe Links Exclusions Rule" `
  -SafeLinksPolicy "CyberHoot - Safe Links Exclusions" `
  -RecipientDomainIs (Get-AcceptedDomain).Name
```

---

## Additional Resources

- [Microsoft Defender Advanced Delivery Documentation](https://learn.microsoft.com/en-us/defender-office-365/advanced-delivery-policy-configure)
- [Safe Links Policy Configuration](https://learn.microsoft.com/en-us/defender-office-365/safe-links-policies-configure)
- [CyberHoot Support Portal](https://support.cyberhoot.com)
- [Exchange Online PowerShell Documentation](https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell)

---

**Document Version:** 2.0  
**Last Updated:** February 2, 2025  
**Maintained by:** CyberHoot Security Team