PSGerickeUtil.psm1
|
<#
.SYNOPSIS Sets the log path for the script. .DESCRIPTION The Set-LogPath function sets the path where logs will be stored. If the specified folder path does not exist, it will be created. .PARAMETER Path The full path where logs will be stored. This parameter is mandatory. .PARAMETER WhatIf Shows what would happen if the cmdlet runs. The cmdlet is not run. .PARAMETER Confirm Prompts you for confirmation before running the cmdlet. .EXAMPLE Set-LogPath -Path "C:\Logs\MyLog.txt" This example sets the log path to "C:\Logs\MyLog.txt". If the "C:\Logs" folder does not exist, it will be created. .NOTES Author: Stefan Gericke Date: 2024-11-21 #> function Set-LogPath { [CmdletBinding(SupportsShouldProcess = $true)] param( [Parameter(Mandatory = $true)] [String] $Path ) trap { throw "Error setting log path: $($_.Exception.Message)" } $folderPath = Split-Path -Path $Path if (-not (Test-Path -Path $folderPath)) { New-Item -Path $folderPath -ItemType Directory -Force -ErrorAction Stop } if ($PSCmdlet.ShouldProcess("script variable", "Set path of the logfile")) { $script:logPath = $Path } } <# .SYNOPSIS Sets the Pushover api key for REST API calls. .DESCRIPTION The Set-RestApiKeyForPushoverApi function sets a secure Pushover api key for use in REST API calls. The user key is stored in a script-scoped variable for later use. .PARAMETER ApiKey The secure string representing the Pushover user key. This parameter is mandatory. .PARAMETER WhatIf Shows what would happen if the cmdlet runs. The cmdlet is not run. .PARAMETER Confirm Prompts you for confirmation before running the cmdlet. .EXAMPLE PS C:\> $secureUserKey = Read-Host "Enter Pushover User Key" -AsSecureString PS C:\> Set-RestApiKeyForPushoverApi -UserKey $secureUserKey This example prompts the user to enter a Pushover user key securely and then sets it using the Set-RestApiKeyForPushoverUser function. .NOTES Author: Stefan Gericke Date: 2024-11-21 #> function Set-RestApiKeyForPushoverApi { [CmdletBinding(SupportsShouldProcess = $true)] param( [Parameter(Mandatory = $true)] [securestring] $ApiKey ) if ($PSCmdlet.ShouldProcess("script variable", "Set api key")) { $script:pushoverApiKey = $ApiKey } } <# .SYNOPSIS Sets the Pushover user key for REST API calls. .DESCRIPTION The Set-RestApiKeyForPushoverUser function sets a secure Pushover user key for use in REST API calls. The user key is stored in a script-scoped variable for later use. .PARAMETER UserKey The secure string representing the Pushover user key. This parameter is mandatory. .PARAMETER WhatIf Shows what would happen if the cmdlet runs. The cmdlet is not run. .PARAMETER Confirm Prompts you for confirmation before running the cmdlet. .EXAMPLE PS C:\> $secureUserKey = Read-Host "Enter Pushover User Key" -AsSecureString PS C:\> Set-RestApiKeyForPushoverUser -UserKey $secureUserKey This example prompts the user to enter a Pushover user key securely and then sets it using the Set-RestApiKeyForPushoverUser function. .NOTES Author: Stefan Gericke Date: 2024-11-21 #> function Set-RestApiKeyForPushoverUser { [CmdletBinding(SupportsShouldProcess = $true)] param( [Parameter(Mandatory = $true)] [securestring] $UserKey ) if ($PSCmdlet.ShouldProcess("script variable", "Set user key")) { $script:pushoverUserKey = $UserKey } } <# .SYNOPSIS Sets a script-level variable to indicate whether UTC time should be used. .DESCRIPTION The Set-Utc function sets a script-level variable `$script:utc` to the value of the `$Utc` parameter. This function supports the ShouldProcess feature, allowing for confirmation before making changes. .PARAMETER Utc A mandatory boolean parameter that specifies whether to set the script-level variable to use UTC time. .PARAMETER WhatIf Shows what would happen if the cmdlet runs. The cmdlet is not run. .PARAMETER Confirm Prompts you for confirmation before running the cmdlet. .EXAMPLE Set-Utc -Utc $true This example sets the script-level variable to use UTC time. .EXAMPLE Set-Utc -Utc $false This example sets the script-level variable to not use UTC time. .INPUTS [bool] The function accepts a boolean value as input. .OUTPUTS None. The function does not produce any output. .NOTES Author: Stefan Gericke Date: 2025-01-07 #> function Set-Utc { [CmdletBinding(SupportsShouldProcess = $true)] param( [Parameter(Mandatory = $true)] [bool] $Utc ) if ($PSCmdlet.ShouldProcess("script variable", "Set utc time")) { $script:utc = $Utc } } <# .SYNOPSIS Sends a push notification using the Pushover service. .DESCRIPTION This function sends a push notification to a specified device using the Pushover service. It requires a user key and an API key for authentication. .PARAMETER UserKey The user key for the Pushover service. This is a secure string. .PARAMETER ApiKey The API key for the Pushover service. This is a secure string. .PARAMETER Message The message to be sent. This parameter is mandatory. .PARAMETER Device The device to which the message should be sent. Valid values are "iPadPro2020", "iPhone13Pro", and "iPhoneBI". .PARAMETER Title The title of the message. .PARAMETER Url A URL to be included with the message. .PARAMETER UrlTitle The title of the URL. .PARAMETER Priority The priority of the message. Valid values are "Lowest", "Low", "Normal", "High", and "Emergency". .PARAMETER Sound The sound to be played with the message. Valid values are "pushover", "bike", "bugle", "cashregister", "classical", "cosmic", "falling", "gamelan", "incoming", "intermission", "magic", "mechanical", "pianobar", "siren", "spacealarm", "tugboat", "alien", "climb", "persistent", "echo", "updown", and "none". .PARAMETER WhatIf Shows what would happen if the command runs. The command is not executed. .PARAMETER Confirm Prompts you for confirmation before running the command. .EXAMPLE Send-Pushover -UserKey $userKey -ApiKey $apiKey -Message "Test message" -Device "iPhone13Pro" -Priority "Normal" -Sound "pushover" This example sends a test message to the device "iPhone13Pro" with normal priority and the default "pushover" sound. .EXAMPLE Send-Pushover -UserKey $userKey -ApiKey $apiKey -Message "Urgent message" -Priority "Emergency" -Sound "siren" This example sends an urgent message with emergency priority and the "siren" sound. .NOTES Author: Stefan Gericke Date: 2024-11-06 #> function Send-Pushover { [CmdletBinding(SupportsShouldProcess = $true)] Param( [securestring] $UserKey, [securestring] $ApiKey, [Parameter(Mandatory = $true)] [string] $Message, [ValidateSet("iPadPro2020", "iPhone13Pro", "iPhoneBI")] [string] $Device, [string] $Title, [string] $Url, [string] $UrlTitle, [ValidateSet("Lowest", "Low", "Normal", "High", "Emergency")] [string] $Priority, [ValidateSet("pushover", "bike", "bugle", "cashregister", "classical", "cosmic", "falling", "gamelan", "incoming", "intermission", "magic", "mechanical", "pianobar", "siren", "spacealarm", "tugboat", "alien", "climb", "persistent", "echo", "updown", "none")] [string] $Sound ) # Check if user key and/or API key is available for doing web request if ([string]::IsNullOrEmpty($script:pushoverUserKey) -or $script:pushoverUserKey -ne $UserKey) { if ([string]::IsNullOrEmpty($UserKey) -and [string]::IsNullOrEmpty($script:pushoverUserKey)) { Write-Error "User key is mandatory to send a push notification!" } elseif (![string]::IsNullOrEmpty($UserKey)) { Set-RestApiKeyForPushoverUser -UserKey $UserKey } } if ([string]::IsNullOrEmpty($script:pushoverApiKey) -or $script:pushoverApiKey -ne $ApiKey) { if ([string]::IsNullOrEmpty($ApiKey) -and [string]::IsNullOrEmpty($script:pushoverApiKey)) { Write-Error "Api key is mandatory to send a push notification!" } elseif (![string]::IsNullOrEmpty($ApiKey)) { Set-RestApiKeyForPushoverApi -ApiKey $ApiKey } } # Map priority string to integer value switch ($Priority) { "Lowest" { $iPriority = -2 } "Low" { $iPriority = -1 } "Normal" { $iPriority = 0 } "High" { $iPriority = 1 } "Emergency" { $iPriority = 2 } Default { $iPriority = 0 } } # Prepare data for the request $data = @{ token = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($script:pushoverApiKey)) user = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($script:pushoverUserKey)) message = $Message } # Check if token and user are available if ([string]::IsNullOrEmpty($data["token"]) -or [string]::IsNullOrEmpty($data["user"])) { throw "App and User key are mandatory to send a push notification!" } if ($Device) { $data.Add("device", $Device) } if ($Title) { $data.Add("title", $Title) } if ($Url) { $data.Add("url", $Url) } if ($UrlTitle) { $data.Add("url_title", $UrlTitle) } if ($Sound) { $data.Add("sound", $Sound) } if ($Priority) { $data.Add("priority", $iPriority) if ($iPriority -eq 2) { $data.Add("retry", 30) $data.Add("expire", 1800) } } # Debug output if enabled if ($DebugPreference) { foreach ($key in $data.Keys) { if ($key -eq "token" -or $key -eq "user") { Write-Debug "Parameter: $key, Value: $(Get-MaskString -InputString $data[$key] -VisibleLength 3)" } else { Write-Debug "Parameter: $key, Value: $($data[$key])" } } } try { $uri = "https://api.pushover.net/1/messages.json" Write-Debug "Uri: $($uri)" if ($PSCmdlet.ShouldProcess("Message: $($Message)", "Send notification to API")) { $null = Invoke-RestMethod -Method Post -Uri $uri -Body $data } } catch { Write-Error "Web request not successful: $($_.ErrorDetails)" } } <# .SYNOPSIS Retrieves information about users with Enterprise Voice enabled in Microsoft Teams. .DESCRIPTION This function checks if a user or all users in the tenant have Enterprise Voice enabled in Microsoft Teams. It can either check a specific user by their UserPrincipalName or export the information for the whole tenant to a CSV file. .PARAMETER UserPrincipalName The UserPrincipalName of the user to check. This parameter is mandatory if you are checking a specific user. .PARAMETER ExportCSV A switch to indicate if the results for the whole tenant should be exported to a CSV file. .PARAMETER ExportPath The path where the CSV file should be saved. If not specified, a default path in the TEMP directory will be used. .EXAMPLE Get-TeamsPSTNEnterpriseVoiceEnabled -UserPrincipalName "user@example.com" Retrieves information about the specified user. .EXAMPLE Get-TeamsPSTNEnterpriseVoiceEnabled -ExportCSV Retrieves information about all users in the tenant and exports it to a CSV file in the TEMP directory. .EXAMPLE Get-TeamsPSTNEnterpriseVoiceEnabled -ExportCSV -ExportPath "C:\Exports\EV-enabled.csv" Retrieves information about all users in the tenant and exports it to the specified CSV file. .NOTES Author: Stefan Gericke Date: 2024-11-06 #> function Get-TeamsPSTNEnterpriseVoiceEnabled { [CmdletBinding(DefaultParameterSetName = 'WholeTenant')] Param( [Parameter(ParameterSetName = 'UserPrincipalName', Mandatory = $true, Position = 0)] [ValidateNotNullOrEmpty()] [string[]] $UserPrincipalName, [Parameter(ParameterSetName = 'WholeTenant', Position = 0)] [switch] $ExportCSV, [Parameter(ParameterSetName = 'WholeTenant', Position = 1)] [ValidateNotNullOrEmpty()] [string] $ExportPath = (Join-Path -Path $Env:TEMP -ChildPath "$(Get-Date -Format yyyyMMdd_HHmm)_EV-enabled.csv") ) # Check if you already have a connection to Microsoft Teams try { $null = Get-CsTenant Write-Debug "Connection to Microsoft Teams already established." } catch { Write-Warning "You are not connected to Microsoft Teams!" Write-Warning "Please log in with your credentials and the MFA token in your browser." try { Connect-MicrosoftTeams $null = Get-CsTenant Write-Debug "You are successfully logged in to Microsoft Teams." } catch { Write-Error "The log in to Microsoft Teams was not successful. The script will stop here!" return } } # Check the parameter set and collect the results switch ($PSCmdlet.ParameterSetName) { # Collect the information for the specified user 'UserPrincipalName' { $results = New-Object -TypeName "System.Collections.ArrayList" foreach ($upn in $UserPrincipalName) { try { Write-Debug "Request for $($upn) ..." $response = Get-CsOnlineUser -Identity $upn -ErrorAction SilentlyContinue if ($null -eq $response) { Write-Error "UPN $($upn) can't be found" continue } else { $results.Add([PSCustomObject]@{"UserPrincipalName" = $response.UserPrincipalName; "EnterpriseVoiceEnabled" = $response.EnterpriseVoiceEnabled }) } } catch { Write-Error $message.Exception.Message } } } 'WholeTenant' { # Collect all users with Enterprise Voice enabled in the tenant Write-Verbose "Get all users on the tenant with Enterprise Voice flag enabled. This will take some time. Please wait ..." try { if ($DebugPreference) { $debugNoOfUpns = 10 Write-Debug "Get only the first $($debugNoOfUpns) as result!" $results = Get-CsOnlineUser -Filter { EnterpriseVoiceEnabled -eq "true" } -ResultSize $debugNoOfUpns -ErrorAction Stop | Select-Object -Property UserPrincipalName, Alias, EnterpriseVoiceEnabled } else { $results = Get-CsOnlineUser -Filter { EnterpriseVoiceEnabled -eq "true" } -ErrorAction Stop | Select-Object -Property UserPrincipalName, Alias, EnterpriseVoiceEnabled } if ($ExportCSV -or !([string]::IsNullOrEmpty($ExportPath))) { $results | Export-Csv -Path $ExportPath -NoTypeInformation } } catch { $errorMessage = $_.Exception.Message if ($errorMessage -eq "Access Denied.") { Write-Error "No Permission to run this command!" } Disconnect-MicrosoftTeams return } } } return $results } <# .SYNOPSIS Creates a symbolic link, hard link, or junction. .DESCRIPTION This script creates a symbolic link, hard link, or junction at the specified path. Administrator permissions are required to create symbolic links and junctions. .PARAMETER LinkType The type of link to create. Valid values are 'SymbolicLink', 'HardLink', and 'Junction'. .PARAMETER TargetPath The target path for the link. .PARAMETER LinkPath The path where the link will be created. .EXAMPLE Add-LinkOfFileFolder -LinkType SymbolicLink -TargetPath "C:\Target" -LinkPath "C:\Link" Creates a symbolic link from "C:\Link" to "C:\Target". .EXAMPLE Add-LinkOfFileFolder -LinkType HardLink -TargetPath "C:\Target" -LinkPath "C:\Link" Creates a hard link from "C:\Link" to "C:\Target". .EXAMPLE Add-LinkOfFileFolder -LinkType Junction -TargetPath "C:\Target" -LinkPath "C:\Link" Creates a junction from "C:\Link" to "C:\Target". .NOTES Author: Stefan Gericke Date: 2024-11-07 #> function Add-LinkOfFileFolder { [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [ValidateSet('SymbolicLink', 'HardLink', 'Junction')] [string] $LinkType, [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [string] $TargetPath, [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [string] $LinkPath ) function Test-Administrator { $currentUser = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent()) return $currentUser.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator) } # Check if the target path exists if (!(Test-Path -Path $TargetPath)) { Write-Error "The target path $TargetPath does not exist." return } # CHeck if the link type is symbolic link or junction and if the user is an administrator if (($LinkType -eq 'SymbolicLink' -or $LinkType -eq 'Junction') -and !(Test-Administrator)) { Write-Error "Administrator permissions are required to create a symbolic link or junction." return } try { switch ($LinkType) { 'SymbolicLink' { $result = New-Item -ItemType SymbolicLink -Path $LinkPath -Value $TargetPath -ErrorAction Stop } 'HardLink' { $result = New-Item -ItemType HardLink -Path $LinkPath -Value $TargetPath -ErrorAction Stop } 'Junction' { $result = New-Item -ItemType Junction -Path $LinkPath -Value $TargetPath -ErrorAction Stop } } # Check if the link was created successfully if (!(Test-Path -Path $LinkPath)) { Write-Error "The $LinkType was not created successfully." return } Write-Verbose "$LinkType created successfully from $LinkPath to $TargetPath" return $result } catch { Write-Error $_.Exception.Message return } } <# .SYNOPSIS Retrieves credentials for an M365 tenant from either the clipboard, a file, or a secure string. .DESCRIPTION The Get-CredentialForM365Tenant function retrieves the client secret, client ID, tenant domain, and tenant ID for an M365 tenant. The credentials can be retrieved from the clipboard, a specified file, or a secure string. The function validates the retrieved values to ensure they are in the correct format. .PARAMETER FromClipboard Specifies that the credentials should be retrieved from the clipboard. .PARAMETER FilePath Specifies the path to the file from which the credentials should be retrieved. .PARAMETER SecureString Specifies the secure string from which the credentials should be retrieved. .EXAMPLE Get-CredentialForM365Tenant -FromClipboard Retrieves the credentials from the clipboard. .EXAMPLE Get-CredentialForM365Tenant -FilePath "C:\path\to\credentials.txt" Retrieves the credentials from the specified file. .EXAMPLE $secureString = ConvertTo-SecureString "client_secret client_id tenant_domain tenant_id" -AsPlainText -Force Get-CredentialForM365Tenant -SecureString $secureString Retrieves the credentials from the provided secure string. .NOTES The credentials should be stored in the clipboard, file, or secure string in the following format: <client_secret> <client_id> <tenant_domain> <tenant_id> The client ID and tenant ID must be valid GUIDs. The tenant domain must be a valid domain name. #> function Get-CredentialForM365Tenant { [CmdletBinding(DefaultParameterSetName = 'FromSecurestring')] [OutputType([System.Collections.Hashtable])] param ( [Parameter(ParameterSetName = 'FromClipboard', Mandatory = $true, Position = 0)] [switch] $FromClipboard, [Parameter(ParameterSetName = 'FromFile', Mandatory = $true, Position = 0)] [string] $FilePath, [Parameter(ParameterSetName = 'FromSecurestring', Mandatory = $true, Position = 0)] [securestring] $SecureString ) switch ($PSCmdlet.ParameterSetName) { 'FromClipboard' { # Retrieve the clipboard content if ($FromClipboard) { $secret = Get-Clipboard | ConvertTo-SecureString } return $null } 'FromFile' { # Check if the file exists if (-not (Test-Path -Path $FilePath)) { throw "The file does not exist." } # Retrieve the encrypted credential from the file $secret = Get-Content -Path $FilePath | ConvertTo-SecureString } 'FromSecurestring' { $secret = $SecureString } } # Check if the secure string contains the client secret, client ID, tenant domain, and tenant ID if ((([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($secret))) -split (" ")).Length -ne 4) { throw "The secure string must contain the client secret, client ID, tenant domain, and tenant ID. Make sure your encryoed string is in the format: <client_secret> <client_id> <tenant_domain> <tenant_id>" } $clientSecret = ConvertTo-SecureString -String ((([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($secret))) -split (" "))[0]) -AsPlainText -Force $clientID = (([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR((($Secret))))) -split (" "))[1] $tenantdomain = (([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR((($Secret))))) -split (" "))[2] $tenantId = (([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR((($Secret))))) -split (" "))[3] # Check if clientSecret is a valid secure string if ($clientSecret.Length -eq 0) { throw "The ClientSecret must be a secure string." } Write-Debug "ClientSecret is a valid secure string: $(Get-MaskString -InputString ((([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($secret))) -split (" "))[0]) -VisibleLength 3)" # Check if clientID is a valid GUID $regexGuid = "^[{]?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?$" if (-not ($ClientID -match $regexGuid)) { throw "The ClientID must be a valid GUID: $clientID" } Write-Debug "ClientID is a valid GUID: $clientID" # Check if TenantDomain is a valid domain $regexDomain = "^(?!:\/\/)([a-zA-Z0-9-_]+\.)*[a-zA-Z0-9][a-zA-Z0-9-_]+\.[a-zA-Z]{2,11}?$" if (-not ($tenantdomain -match $regexDomain)) { throw "The TenantDomain must be a valid domain: $tenantdomain" } Write-Debug "TenantDomain is a valid domain: $tenantdomain" # Check if TenantId is a valid GUID if (-not ($tenantId -match $regexGuid)) { throw "The TenantId must be a valid GUID." } Write-Debug "TenantId is a valid GUID: $tenantId" return @{ ClientSecret = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $clientID, $clientSecret TenantDomain = $tenantdomain TenantId = $tenantId } } <# .SYNOPSIS Formats a JSON file by reading its content, converting it to a PowerShell object, and then writing it back to a specified target file. .DESCRIPTION The Get-JsonFormatter function reads the content of a JSON file from a specified source file path, converts it to a PowerShell object, and then writes the formatted JSON content to a specified target file path. If the target file already exists, the function can overwrite it if the -Force switch is used. .PARAMETER SourceFilePath The path to the source JSON file that needs to be formatted. This parameter is mandatory. .PARAMETER TargetFilePath The path to the target file where the formatted JSON content will be written. This parameter is mandatory. .PARAMETER Depth Specifies how many levels of contained objects are included in the JSON representation. The default value is 99. .PARAMETER Compress A switch parameter that, if specified, compresses the JSON output by removing unnecessary white spaces. This parameter is optional. .PARAMETER Force A switch parameter that, if specified, forces the function to overwrite the target file if it already exists. This parameter is optional. .EXAMPLE Get-JsonFormatter -SourceFilePath "C:\path\to\source.json" -TargetFilePath "C:\path\to\target.json" This example reads the JSON content from "C:\path\to\source.json", formats it, and writes it to "C:\path\to\target.json". .EXAMPLE Get-JsonFormatter -SourceFilePath "C:\path\to\source.json" -TargetFilePath "C:\path\to\target.json" -Force This example reads the JSON content from "C:\path\to\source.json", formats it, and writes it to "C:\path\to\target.json", overwriting the target file if it already exists. .EXAMPLE Get-JsonFormatter -SourceFilePath "C:\path\to\source.json" -TargetFilePath "C:\path\to\target.json" -Depth 5 This example reads the JSON content from "C:\path\to\source.json", formats it with a depth of 5, and writes it to "C:\path\to\target.json". .EXAMPLE Get-JsonFormatter -SourceFilePath "C:\path\to\source.json" -TargetFilePath "C:\path\to\target.json" -Compress This example reads the JSON content from "C:\path\to\source.json", formats it, compresses the JSON output, and writes it to "C:\path\to\target.json". .NOTES - The SourceFilePath and TargetFilePath cannot be the same. - If the SourceFilePath does not exist, the function will throw an error. - If the TargetFilePath exists and the -Force switch is not used, the function will prompt the user to confirm overwriting the file. #> function Get-JsonFormatter { [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [string] $SourceFilePath, [Parameter(Mandatory = $true)] [string] $TargetFilePath, [Parameter(Mandatory = $false)] [int] $Depth = 99, [Parameter(Mandatory = $false)] [switch] $Compress, [Parameter(Mandatory = $false)] [switch] $Force ) # Check if SourceFilePath and TargetFilePath are not the same if ($SourceFilePath -eq $TargetFilePath) { throw "SourceFilePath and TargetFilePath cannot be the same." } # Check if the SourceFilePath not exists if (-not (Test-Path -Path $SourceFilePath)) { throw "The SourceFilePath '$SourceFilePath' does not exist." } # Check if the TargetFilePath exists if (Test-Path -Path $TargetFilePath) { if (-not $Force) { Write-Error "A file '$TargetFilePath' already exists. Use -Force to overwrite the file." # Ask the user if they want to overwrite the file and repeat the process until the user type 'Y' or 'N' do { $response = Read-Host "Do you want to overwrite the file '$TargetFilePath'? (Y/N)" if ($response -eq 'N') { Write-Error "The file '$TargetFilePath' already exists." exit } } while ($response -ne 'Y') } Write-Verbose "Overwriting the file '$TargetFilePath'." } # Get the content of the JSON file $json = Get-Content -Path $SourceFilePath -Raw try { # Convert the JSON content to a PowerShell object $jsonObject = $json | ConvertFrom-Json } catch { throw "Failed to convert the JSON content to a PowerShell object. $_" } # Convert the PowerShell object back to JSON and write it to the target file $jsonObject | ConvertTo-Json -Depth $Depth -Compress:$Compress | Set-Content -Path $TargetFilePath } <# .SYNOPSIS Masks a portion of a string, leaving a specified number of characters visible. .DESCRIPTION The Get-MaskString function takes an input string and a visible length as parameters. It returns the input string with all but the specified number of characters replaced by asterisks (*). If the input string is shorter than or equal to the visible length, the entire string is returned unmodified. .PARAMETER InputString The string to be masked. .PARAMETER VisibleLength The number of characters to leave visible at the beginning of the string. .EXAMPLE PS C:\> Get-MaskString -InputString "HelloWorld" -VisibleLength 5 Hello***** .EXAMPLE PS C:\> Get-MaskString -InputString "Short" -VisibleLength 10 Short .NOTES Author: Stefan Gericke Date: 2025-01-09 #> function Get-MaskString { param ( [Parameter(Mandatory = $true)] [string] $InputString, [Parameter(Mandatory = $true)] [int] $VisibleLength ) # Check if the input string is shorter than the visible length if ($InputString.Length -le $VisibleLength) { return $InputString } # Mask the input string $visiblePart = $InputString.Substring(0, $VisibleLength) $maskedPart = '*' * ($InputString.Length - $VisibleLength) $output = $visiblePart + $maskedPart return $output } <# .SYNOPSIS Creates a new credential for an M365 tenant. .DESCRIPTION This function generates a new credential for an M365 tenant by taking the ClientID, ClientSecret, TenantDomain, and TenantId as inputs. It validates these inputs and then converts them into a secure string which can be either copied to the clipboard, saved to a file, or returned as output. .PARAMETER ClientID The ClientID of the M365 tenant. It must be a valid GUID. .PARAMETER ClientSecret The ClientSecret of the M365 tenant. It must be a secure string. .PARAMETER TenantDomain The domain of the M365 tenant. It must be a valid domain from the format <domain>.onmicrosoft.com. .PARAMETER TenantId The TenantId of the M365 tenant. It must be a valid GUID. .PARAMETER ToClipboard Switch to indicate that the encrypted credential should be copied to the clipboard. .PARAMETER FilePath The file path where the encrypted credential should be saved. .PARAMETER NoOutput Indicates that the encrypted credential should be returned as output without any additional actions. .PARAMETER WhatIf Shows what would happen if the command runs. The command is not executed. .PARAMETER Confirm Prompts you for confirmation before running the command. .EXAMPLE PS> New-CredentialForM365Tenant -ClientID "your-client-id" -ClientSecret (ConvertTo-SecureString "your-client-secret" -AsPlainText -Force) -TenantDomain "your-tenant-domain" -TenantId "your-tenant-id" -ToClipboard This example creates a new credential for an M365 tenant and copies the encrypted credential to the clipboard. .EXAMPLE PS> New-CredentialForM365Tenant -ClientID "your-client-id" -ClientSecret (ConvertTo-SecureString "your-client-secret" -AsPlainText -Force) -TenantDomain "your-tenant-domain" -TenantId "your-tenant-id" -FilePath "C:\path\to\file.txt" This example creates a new credential for an M365 tenant and saves the encrypted credential to a specified file. .EXAMPLE PS> New-CredentialForM365Tenant -ClientID "your-client-id" -ClientSecret (ConvertTo-SecureString "your-client-secret" -AsPlainText -Force) -TenantDomain "your-tenant-domain" -TenantId "your-tenant-id" -NoOutput This example creates a new credential for an M365 tenant and returns the encrypted credential as output. .NOTES Ensure that the ClientID and TenantId are valid GUIDs, the ClientSecret is a secure string, and the TenantDomain is a valid domain. #> function New-CredentialForM365Tenant { [CmdletBinding(DefaultParameterSetName = 'NoOutput', SupportsShouldProcess = $true)] param ( [Parameter(ParameterSetName = 'NoOutput', Mandatory = $true)] [Parameter(ParameterSetName = 'ToClipboard', Mandatory = $true)] [Parameter(ParameterSetName = 'ToFile', Mandatory = $true)] [string] $ClientID, [Parameter(ParameterSetName = 'NoOutput', Mandatory = $true)] [Parameter(ParameterSetName = 'ToClipboard', Mandatory = $true)] [Parameter(ParameterSetName = 'ToFile', Mandatory = $true)] [securestring] $ClientSecret, [Parameter(ParameterSetName = 'NoOutput', Mandatory = $true)] [Parameter(ParameterSetName = 'ToClipboard', Mandatory = $true)] [Parameter(ParameterSetName = 'ToFile', Mandatory = $true)] [string] $TenantDomain, [Parameter(ParameterSetName = 'NoOutput', Mandatory = $true)] [Parameter(ParameterSetName = 'ToClipboard', Mandatory = $true)] [Parameter(ParameterSetName = 'ToFile', Mandatory = $true)] [string] $TenantId, [Parameter(ParameterSetName = 'ToClipboard', Mandatory = $true)] [switch] $ToClipboard, [Parameter(ParameterSetName = 'ToFile', Mandatory = $true)] [string] $FilePath ) # Check if ClientID is a valid GUID $regexGuid = "^[{]?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?$" if (-not ($ClientID -match $regexGuid)) { throw "The ClientID must be a valid GUID." } Write-Debug "ClientID is a valid GUID: $ClientID" # Check if ClientSecret is a valid secure string if ($ClientSecret.Length -eq 0) { throw "The ClientSecret must be a secure string." } Write-Debug "Secure string entered: $(Get-MaskString -InputString ([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($ClientSecret))) -VisibleLength 3)" # Check if TenantDomain is a valid domain $regexDomain = "^[a-zA-Z0-9-]+\.onmicrosoft\.com$" if (-not ($TenantDomain -match $regexDomain)) { throw "The TenantDomain must be a valid domain." } Write-Debug "TenantDomain is a valid domain: $TenantDomain" # Check if TenantId is a valid GUID if (-not ($TenantId -match $regexGuid)) { throw "The TenantId must be a valid GUID." } Write-Debug "TenantId is a valid GUID: $TenantId" # Convert the parameters to a single string and encrypt it $secureString = ConvertTo-SecureString (([System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($ClientSecret))) + " " + $ClientID + " " + $TenantDomain + " " + $TenantId) -AsPlainText -Force $encryptedText = ConvertFrom-SecureString $secureString switch ($PSCmdlet.ParameterSetName) { 'ToClipboard' { if ($ToClipboard) { if ($PSCmdlet.ShouldProcess("clipboard", "Set encrypted string")) { $encryptedText | Set-Clipboard } return $encryptedText } return $null } 'ToFile' { $directory = Split-Path -Path $FilePath -Parent if (Test-Path -Path $directory) { # Check if the directory exists if (Test-Path -Path $FilePath) { # Check if the file exists Write-Error "The file ($($FilePath)) already exists and won't be overwritten." } else { if ($PSCmdlet.ShouldProcess("File: $($FilePath)", "Create new file")) { $encryptedText | Out-File -FilePath $FilePath } } } else { Write-Error "The directory ($($directory)) does not exist and the file cannot be created." } return $encryptedText } 'NoOutput' { return $encryptedText } } } <# .SYNOPSIS Encrypts a secure string and sets it to the clipboard. .DESCRIPTION This function prompts the user to enter a secure string, encrypts it, and then sets the encrypted string to the clipboard. .PARAMETER None This function does not take any parameters. .PARAMETER WhatIf Shows what would happen if the command runs. The command is not executed. .PARAMETER Confirm Prompts you for confirmation before running the command. .EXAMPLE Set-ClipboardWithEncryptedString Prompts the user to enter a secure string, encrypts it, and sets the encrypted string to the clipboard. .NOTES Author: Stefan Gericke Date: 2024-11-06 #> function Set-ClipboardWithEncryptedString { [CmdletBinding(SupportsShouldProcess = $true)] Param() # Prompt the user to enter a secure string $secureString = Read-Host -AsSecureString -Prompt "Enter the secure string you need in the clipboard" Write-Debug "Secure string entered: $(Get-MaskString -InputString ([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureString))) -VisibleLength 3)" # Convert the secure string to an encrypted standard string $encryptedString = $secureString | ConvertFrom-SecureString # Set the encrypted string to the clipboard if ($PSCmdlet.ShouldProcess("clipboard", "Set encrypted string")) { $encryptedString | Set-Clipboard } } <# .SYNOPSIS Writes a log message to a specified log file with a given log level. .DESCRIPTION The Write-Log function writes a log message to a specified log file with a given log level. It supports logging messages with different levels such as Error, Warn, Info, Ok, Failed, and Success. The function can also log the date and time in UTC or local time based on the provided parameters. .PARAMETER LogMessage The message to be logged. This parameter is mandatory. .PARAMETER LogLevel The level of the log message. This parameter is mandatory and must be one of the following values: Error, Warn, Info, Ok, Failed, Success. .PARAMETER LogFile The path to the log file where the message will be written. If not specified, the function will use the script variable $script:logPath. .PARAMETER UTC A boolean parameter that indicates whether to log the date and time in UTC. If not specified, the function will use local time. .EXAMPLE Write-Log -LogMessage "This is an informational message" -LogLevel "Info" -LogFile "C:\Logs\logfile.txt" -UTC $true This example writes an informational message to the specified log file in UTC time. .EXAMPLE Write-Log -LogMessage "An error occurred" -LogLevel "Error" This example writes an error message to the default log file in local time. .NOTES The function requires the Set-LogPath and Set-Utc functions to be defined in the script or module. #> function Write-Log { [CmdletBinding()] param( [Parameter(Mandatory = $true)] [string] $LogMessage, [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [ValidateSet("Error", "Warn", "Info", "Ok", "Failed", "Success")] [string] $LogLevel, [string] $LogFile, [bool] $UTC ) # Check the LogFile variable is existing in script variable or parameter if ($script:logPath -ne $LogFile) { if (![string]::IsNullOrEmpty($LogFile)) { Set-LogPath -Path $LogFile } } Write-Debug "Log Path: $script:logPath" # Check the Utc variable is used as a parameter and set the Utc variable $utcUsed = $PSBoundParameters.ContainsKey('UTC') if ($utcUsed) { if ($UTC) { Set-Utc -Utc $true } else { Set-Utc -Utc $false } } Write-Debug "UTC: $script:utc" # Set Date/Time if ($script:utc) { # Get the current date and time in UTC $dateTime = Get-Date -Format "yyyy-MM-dd HH:mm:ss" -AsUTC } else { # Get the current date and time in local time $dateTime = Get-Date -Format "yyyy-MM-dd HH:mm:ss" } # Set log level $strLength = $MyInvocation.MyCommand.Parameters.LogLevel.Attributes.ValidValues | Sort-Object -Property Length -Descending | Select-Object -First 1 -ExpandProperty Length $countSpaces = $strLength + 3 - $LogLevel.Length $line = $dateTime + " " + $LogLevel.ToUpper() + (" " * $countSpaces ) + $LogMessage try { $line | Out-File -FilePath $script:logPath -Append # Write the line on the terminal Write-Verbose $line return $line } catch { $message = $_ Write-Error "Message ($line) not added to log file: $message" return } } # Utilities/Write-Log.ps1 $script:logPath = Join-Path -Path $Env:TEMP -ChildPath "$(Get-Date -Format yyyyMMdd_HHmm)_Script.log" $script:utc = $false # Rest API/Send-Pushover.ps1 $script:pushoverUserKey = New-Object -TypeName System.Security.SecureString $script:pushoverApiKey = New-Object -TypeName System.Security.SecureString |