Add validation tests for Contoso users' allowed cities, states, and titles; update documentation for email and postal code formats

Author: DevClate

README.md

@@ -1,6 +1,6 @@
 # Custom Maester Test Collection
 
-A collection of customs tests that can be quickly dropped into [Maester](https://www.maester.dev) and customized to your enviroment where needed. 
+A collection of customs tests that can be quickly dropped into [Maester](https://www.maester.dev) and customized to your enviroment where needed.
 
 This repository is still in it's beginning stages and I plan to add many more tests to this repository that just aren't 365 focused as well. I welcome any contributions, please make sure you create all 3 files per test so that it works smoothly for everyone - [Creating Tests](https://devclate.github.io/Custom-Maester-Tests/docs/Getting-Started/create-a-test/)
 
@@ -9,6 +9,7 @@ There is also a webversion at [Custom Maester Tests](https://devclate.github.io/
 ## Introduction
 
 ### What are custom Maester tests?
+
 Custom Maester tests are tests that fully integrate into Maester's framework to test your Microsoft 365 tenant and anything else you want to using Pester tests. Also providing PowerShell scripts to resolve any issues where possible.
 
 ### Why custom Maester tests?
@@ -37,3 +38,20 @@ Now when you run your custom tests folder these tests should show
 
 For all files, run the Find and Replace in VSCode for "Contoso" with your company name. I have this as the last step to ensure the test works correctly in your enviroment before changing the name.
 
+## Using your own company standards
+
+### Step 1: Locate validation.json
+
+By default, the validation.json is location in the `tests/Entra/Validating` folder
+
+### Step 2: Update config file
+
+Update and or remove any fields that aren't necessary, or you can add more as well.
+
+### Step 3: Save config file
+
+Save the config file
+
+### Step 4: Run tests
+
+Run your tests again and see how the results change.

…osoUsersFormattingCapitolInitialEmail.md …osoUsersFormattingCapitalInitialEmail.mdtests/Entra/Formatting/Test-ContosoUsersFormattingCapitolInitialEmail.md renamed to tests/Entra/Formatting/Test-ContosoUsersFormattingCapitalInitialEmail.md tests/Entra/Formatting/Test-ContosoUsersFormattingCapitolInitialEmail.md renamed to tests/Entra/Formatting/Test-ContosoUsersFormattingCapitalInitialEmail.md

@@ -1,4 +1,4 @@
-function Test-ContosoUsersFormattingCapitolInitialEmail {
+function Test-ContosoUsersFormattingCapitalInitialEmail {
     $result = $true
     try {
         $users = Invoke-MtGraphRequest -RelativeUri "users" -Filter "userType eq 'Member'" -Select "displayName","givenName","surname","mail"

…soUsersFormattingCapitolInitialEmail.ps1 …soUsersFormattingCapitalInitialEmail.ps1tests/Entra/Formatting/Test-ContosoUsersFormattingCapitolInitialEmail.ps1 renamed to tests/Entra/Formatting/Test-ContosoUsersFormattingCapitalInitialEmail.ps1 tests/Entra/Formatting/Test-ContosoUsersFormattingCapitolInitialEmail.ps1 renamed to tests/Entra/Formatting/Test-ContosoUsersFormattingCapitalInitialEmail.ps1

@@ -1,11 +1,11 @@
 
 BeforeAll {
-    . "$PSScriptRoot\Test-ContosoUsersFormattingCapitolInitialEmail.ps1"
+    . "$PSScriptRoot\Test-ContosoUsersFormattingCapitalInitialEmail.ps1"
 }
 
 Describe "Contoso" -Tag "ENTRA.UF.1003.T01.Email", "Entra", "CustomTests", "Formatting", "Users" {
     It "ENTRA.UF.1003.T01.Email: Must be Capital First Initial and Last Name with First Letter Capitalized" {
-        $result = Test-ContosoUsersFormattingCapitolInitialEmail
+        $result = Test-ContosoUsersFormattingCapitalInitialEmail
         $result | Should -Be $true -Because "All user emails must follow the capital-initial format."
     }
 }

tests/Entra/Formatting/Test-ContosoUsersFormattingCapitolInitialEmail.tests.ps1

@@ -0,0 +1,10 @@
+BeforeAll {
+    . "$PSScriptRoot/Test-ContosoUsersAllowedBusinessNumbers.ps1"
+}
+
+Describe "Contoso" -Tag "ENTRA.UV.1007", "Entra", "CustomTests", "Validation", "Users", "BusinessNumber" {
+    It "ENTRA.UV.1007: Business Number - All users should have an allowed business number" {
+        $result = Test-ContosoUsersAllowedBusinessNumbers
+        $result | Should -Be $true -Because "All users must have a business number from the valid list."
+    }
+}

tests/Entra/Validating/Test-ContosoUsersAllowedBusinessNumbers.Tests.ps1

@@ -0,0 +1,18 @@
+This test checks if there are any users missing or using an invalid business phone number from the valid list.
+
+Contoso's company policy requires that all users have a valid business phone number. This is crucial for operational needs.
+
+**To remediate this issue:**
+
+- Identify any user with a missing or invalid business phone number.
+- Submit a correction request through [Form: Invalid or Missing Business Number](https://contoso.service-now.com/busnumbermissing).
+  - 🔺 If no action occurs within three days, escalate to HR.
+
+**Learn more:**
+
+- [Invalid or Missing Business Number](https://contoso.service-now.com/busnumbermissing)
+- [HR Escalation Process](https://contoso.service-now.com/hrescalation)
+
+<!--- Results --->
+
+%TestResult%

tests/Entra/Validating/Test-ContosoUsersAllowedBusinessNumbers.md

@@ -0,0 +1,46 @@
+function Test-ContosoUsersAllowedBusinessNumbers {
+    param(
+        [string] $ValidatingPath = ("$PSScriptRoot/validation.json")
+    )
+    $result = $true
+    try {
+        # Log the ValidatingPath for debugging
+        Write-Output "Using ValidatingPath: $ValidatingPath"
+        
+        # Load valid business numbers from validation.json
+        $validation = Get-Content -Path $ValidatingPath -Raw | ConvertFrom-Json -Depth 10
+        $validNumbers = $validation.validLocations.businessPhones
+
+        # Retrieve all member users from Graph, selecting businessPhones
+        $users = Invoke-MtGraphRequest -RelativeUri "users" -Filter "userType eq 'Member'" -Select "displayName","businessPhones"
+        $invalidUsers = @()
+
+        foreach ($user in $users) {
+            # Skip certain accounts you do not want to evaluate
+            if ($user.displayName -eq "On-Premises Directory Synchronization Service Account") {
+                continue
+            }
+
+            # Check if the user’s business number is missing OR not in the list of valid business numbers
+            $phone = $user.businessPhones[0]
+            if ($null -eq $phone -or -not ($validNumbers -contains $phone)) {
+                $result = $false
+                $invalidUsers += $user
+            }
+        }
+
+        if ($result) {
+            $TestResults = "All users have a valid business number."
+        } else {
+            $TestResults = "These users have invalid or missing business numbers:`n%TestResult%"
+        }
+        
+        Add-MtTestResultDetail -Result $TestResults -GraphObjects $invalidUsers -GraphObjectType Users
+    }
+    catch {
+        $result = $false
+        Write-Error $_.Exception.Message
+    }
+
+    return $result
+}

tests/Entra/Validating/Test-ContosoUsersAllowedBusinessNumbers.ps1

@@ -0,0 +1,10 @@
+BeforeAll {
+    . "$PSScriptRoot/Test-ContosoUsersAllowedCities.ps1"
+}
+
+Describe "Contoso" -Tag "ENTRA.UV.1003", "Entra", "CustomTests", "Validation", "Users", "City" {
+    It "ENTRA.UV.1003: Cities - All users should have a valid city" {
+        $result = Test-ContosoUsersAllowedCities
+        $result | Should -Be $true -Because "All users must have a city from the valid list."
+    }
+}

tests/Entra/Validating/Test-ContosoUsersAllowedCities.Tests.ps1

@@ -0,0 +1,18 @@
+This test checks if there are any users missing or using an invalid city from the valid list.
+
+Contoso's company policy requires that all users have a valid city on record. This is crucial for ensuring correct contact information.
+
+**To remediate this issue:**
+
+- Identify any user with an invalid or missing city.
+- Submit a correction request through [Form: Invalid or Missing City - HR Ticket](https://contoso.service-now.com/invalidcity).
+  - 🔺 If no action occurs within three days, escalate to HR.
+
+**Learn more:**
+
+- [Invalid or Missing City - HR Ticket](https://contoso.service-now.com/invalidcity)
+- [HR Escalation Process](https://contoso.service-now.com/hrescalation)
+
+<!--- Results --->
+
+%TestResult%

tests/Entra/Validating/Test-ContosoUsersAllowedCities.md

@@ -0,0 +1,42 @@
+function Test-ContosoUsersAllowedCities {
+    param(
+        [string] $ValidatingPath = ("$PSScriptRoot/validation.json")
+    )
+    $result = $true
+    try {
+        # Log the ValidatingPath for debugging
+        Write-Output "Using ValidatingPath: $ValidatingPath"
+        
+        # Load valid cities from validation.json
+        $validation = Get-Content -Path $ValidatingPath -Raw | ConvertFrom-Json
+        $validCities = $validation.validLocations.city
+
+        # Retrieve all member users from Graph
+        $users = Invoke-MtGraphRequest -RelativeUri "users" -Filter "userType eq 'Member'" -Select "displayName","city"
+        $invalidUsers = @()
+
+        foreach ($user in $users) {
+            if ($user.displayName -eq "On-Premises Directory Synchronization Service Account") {
+                continue
+            }
+            # Check if city is missing or invalid (case-sensitive)
+            if ($null -eq $user.city -or -not ($validCities | Where-Object { $_ -ceq $user.city })) {
+                $result = $false
+                $invalidUsers += $user
+            }
+        }
+
+        if ($result) {
+            $TestResults = "All users have a valid city."
+        } else {
+            $TestResults = "These users have invalid or missing cities:`n%TestResult%"
+        }
+        
+        Add-MtTestResultDetail -Result $TestResults -GraphObjects $invalidUsers -GraphObjectType Users
+    }
+    catch {
+        $result = $false
+        Write-Error $_.Exception.Message
+    }
+    return $result
+}