Modules/M365DSCAgent.psm1

<#
.Description
This function tests the configuration of the agent
 
.Example
Test-M365DSCAgent
 
.Functionality
Public
#>

function Test-M365DSCAgent
{
    [CmdletBinding()]
    param()

    #region Telemetry
    $data = [System.Collections.Generic.Dictionary[[System.String], [System.Object]]]::new()
    $data.Add('Event', 'TestAgent')
    Add-M365DSCTelemetryEvent -Data $data -Type 'TestAgent'
    #endregion

    [array]$Recommendations = @()
    [array]$Issues = @()
    $TotalSteps = 3

    #region PowerShell Version
    Write-Progress -Activity 'Scanning PowerShell Version...' -PercentComplete (1 / $TotalSteps * 100)
    $CurrentPSVersion = [version]$PSVersionTable.PSVersion

    if ($PSVersionTable.PSEdition -ne 'Core' -or $CurrentPSVersion -lt [version]'7.6')
    {
        $Issues += @{
            ID      = 'I1'
            Message = "Microsoft365DSC requires PowerShell 7.6 or higher. The current session is running PowerShell $CurrentPSVersion " + `
                "($($PSVersionTable.PSEdition) edition). Please install PowerShell 7 from: https://aka.ms/powershell-release"
        }
    }
    #endregion

    #region MaxEnvelopeSize
    # Reading the WinRM configuration needs the WinRM service to be running
    Write-Progress -Activity 'Scanning WinRM MaxEnvelopeSize...' -PercentComplete (2 / $TotalSteps * 100)
    $winRMService = Get-Service -Name 'WinRM' -ErrorAction SilentlyContinue
    if ($null -eq $winRMService -or $winRMService.Status -ne 'Running')
    {
        $Issues += @{
            ID      = 'I3'
            Message = "The WinRM service is not running. Start it, or run 'winrm quickconfig' from an elevated session, to allow DSC to operate."
        }
    }
    else
    {
        try
        {
            $currentMaxEnvelopeSize = [System.Int32](Get-Item -Path 'WSMan:\localhost\MaxEnvelopeSizekb' -ErrorAction Stop).Value
            if ($currentMaxEnvelopeSize -lt 10240)
            {
                $Recommendations += @{
                    ID      = 'R1'
                    Message = "We recommend increasing the MaxEnvelopeSize of the agent's WinRM to a minimum of 10 Mb." + `
                        ' To make the change, run: Set-Item -Path WSMan:\localhost\MaxEnvelopeSizekb -Value 10240'
                }
            }
        }
        catch
        {
            $Issues += @{
                ID      = 'I3'
                Message = "Unable to read the WinRM MaxEnvelopeSize: $($_.Exception.Message)"
            }
        }
    }
    #endregion

    #region Modules Dependencies
    Write-Progress -Activity 'Scanning Dependencies...' -PercentComplete (3 / $TotalSteps * 100)
    $dependencies = Update-M365DSCDependencies -ValidateOnly
    foreach ($dependency in $dependencies)
    {
        $Issues += @{
            ID      = 'I2'
            Message = "M365DSC has a dependency on module $($dependency.ModuleName) which was not found. You need to install " + `
                "this module by running: Install-Module $($dependency.ModuleName) -RequiredVersion $($dependency.RequiredVersion) -Force"
        }
    }
    #endregion

    Write-Progress -Completed -Activity 'Completed Analysis'
    if ($Issues.Count -gt 0)
    {
        $errorMessage = "The following issues were detected with the current agent's configuration. Please take " + `
            "proper action to remediate. `r`n"
        $i = 1
        foreach ($issue in $Issues)
        {
            $errorMessage += " [$i/$($Issues.Count)] $($issue.Message)`r`n"
            $i++
        }
        Write-Error -Message $errorMessage -ErrorAction Continue
    }

    if ($Recommendations.Count -gt 0)
    {
        $warningMessage = "The following recommendations were issued. We strongly recommend addressing those: `r`n"
        $i = 1
        foreach ($recommendation in $Recommendations)
        {
            $warningMessage += " [$i/$($Recommendations.Count)] $($recommendation.Message)`r`n"
            $i++
        }
        Write-Warning -Message $warningMessage
    }

    if ($Recommendations.Count -eq 0 -and $Issues.Count -eq 0)
    {
        Write-Host 'The agent is properly configured.'
    }
}

<#
.Description
This function configures the LCM with a self signed encryption certificate
 
.Parameter KeepCertificate
Specifies that the temporarily created CER file should not be deleted.
 
.Parameter ForceRenew
Specifies that a new certificate should be forcefully created.
 
.Parameter GeneratePFX
Specifies that a PFX export should be created for the generated certificate.
 
.Parameter Password
Specifies the password for the PFX file. We recommend using with -GeneratePFX.
 
.Example
Set-M365DSCAgentCertificateConfiguration -KeepCertificate
 
.Example
Set-M365DSCAgentCertificateConfiguration -GeneratePFX -Password 'P@ssword123!'
 
.Functionality
Public
#>

function Set-M365DSCAgentCertificateConfiguration
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param(
        [Parameter()]
        [Switch]
        $KeepCertificate,

        [Parameter()]
        [Switch]
        $ForceRenew,

        [Parameter()]
        [Switch]
        $GeneratePFX,

        [Parameter()]
        [System.String]
        $Password = 'Temp!P@ss123'
    )

    if ($GeneratePFX)
    {
        if ([System.String]::IsNullOrEmpty($Password))
        {
            throw 'GeneratePFX requires a password.'
        }

        # TODO: Enforce password parameter in a future release.
        if (-not $PSBoundParameters.ContainsKey('Password'))
        {
            Write-Warning -Message 'No -Password was specified and the PFX file is protected with a default password. Specify -Password to protect the private key. The default password will be removed in a future release.'
        }
    }

    $matchingCertificates = @(Get-ChildItem -Path Cert:\LocalMachine\My | `
        Where-Object { $_.Subject -match 'M365DSCEncryptionCert' })

    if ($GeneratePFX -and $matchingCertificates.Count -gt 0 -and -not $ForceRenew)
    {
        throw 'GeneratePFX requires either no certificate to exist or the -ForceRenew parameter.'
    }

    if ($ForceRenew)
    {
        foreach ($cert in $matchingCertificates)
        {
            Remove-Item -Path $cert.PSPath -DeleteKey | Out-Null
        }
        $matchingCertificates = @()
    }

    $certificateCreated = $false
    $certificateFilePath = "$env:TEMP\M365DSC.cer"
    if ($matchingCertificates.Count -eq 0)
    {
        Write-Verbose -Message 'No existing M365DSC certificate found. Creating one.'
        $cert = New-SelfSignedCertificate -Type DocumentEncryptionCertLegacyCsp `
            -DnsName 'Microsoft365DSC' `
            -Subject 'M365DSCEncryptionCert' `
            -HashAlgorithm SHA256 `
            -NotAfter (Get-Date).AddYears(10)
        $cert | Export-Certificate -FilePath $certificateFilePath -Force | Out-Null
        Import-Certificate -FilePath $certificateFilePath `
            -CertStoreLocation 'Cert:\LocalMachine\My' -Confirm:$false | Out-Null
        $certificateCreated = $true
        $matchingCertificates = @(Get-ChildItem -Path Cert:\LocalMachine\My | `
            Where-Object { $_.Subject -match 'M365DSCEncryptionCert' })
    }
    else
    {
        Write-Verbose -Message 'An existing M365DSC certificate was found. Re-using it.'
    }

    # Select the first matching certificate
    $existingCertificate = $matchingCertificates | Sort-Object -Property NotAfter -Descending | Select-Object -First 1
    $thumbprint = $existingCertificate.Thumbprint
    Write-Verbose -Message "Using M365DSCEncryptionCert with thumbprint {$thumbprint}"

    $configOutputFile = $env:TEMP + '\M365DSCAgentLCMConfig.ps1'
    $LCMConfigContent = @"
    [DSCLocalConfigurationManager()]
    Configuration M365AgentConfig
    {
        Node Localhost
        {
            Settings
            {
                CertificateID = '$thumbprint'
            }
        }
    }
    M365AgentConfig | Out-Null
    Set-DSCLocalConfigurationManager M365AgentConfig -Force
"@

    $LCMConfigContent | Out-File $configOutputFile
    & $configOutputFile

    if ($GeneratePFX)
    {
        $pfxFilePath = $certificateFilePath.Replace('.cer', '.pfx')
        $securePassword = ConvertTo-SecureString -String $Password -Force -AsPlainText
        Export-PfxCertificate -Cert $existingCertificate.PSPath `
            -FilePath $pfxFilePath `
            -Password $securePassword | Out-Null
        Write-Host "Private Key stored at {$pfxFilePath}"
    }

    if ($KeepCertificate)
    {
        $storedFiles = @()
        if ($certificateCreated)
        {
            $storedFiles += 'M365DSC.cer'
        }
        if ($GeneratePFX)
        {
            $storedFiles += 'M365DSC.pfx'
        }

        if ($storedFiles.Count -gt 0)
        {
            Write-Host "Certificate {$thumbprint} was stored under {$($env:TEMP)} with name $($storedFiles -join ' and ')"
        }
        else
        {
            Write-Verbose -Message "The existing certificate {$thumbprint} was re-used, no certificate file was written."
        }
    }
    else
    {
        try
        {
            Remove-Item -Path $configOutputFile -Confirm:$false -ErrorAction SilentlyContinue
            Remove-Item -Path './M365AgentConfig' -Recurse -Confirm:$false -ErrorAction SilentlyContinue
            if ($certificateCreated)
            {
                Remove-Item -Path $certificateFilePath -Confirm:$false -ErrorAction SilentlyContinue
            }
        }
        catch
        {
            Write-Error $_
        }
    }
    return $thumbprint
}

Export-ModuleMember -Function @(
    'Set-M365DSCAgentCertificateConfiguration',
    'Test-M365DSCAgent'
)