Modules/M365DSCAgent.psm1
|
<#
.Description This function tests the configuration of the agent .Example Test-M365DSCAgent .Functionality Public #> function Test-M365DSCAgent { [CmdletBinding()] param( ) #Ensure the proper dependencies are installed in the current environment. Confirm-M365DSCDependencies #region Telemetry $data = [System.Collections.Generic.Dictionary[[String], [String]]]::new() $data.Add('Event', 'TestAgent') Add-M365DSCTelemetryEvent -Data $data #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 ($CurrentPSVersion -lt [version]5.1) { $Recommendations += @{ ID = 'R1' Message = 'We recommend installing PowerShell 5.1. You can download and install it from: ' + ` 'https://www.microsoft.com/en-us/download/details.aspx?id=54616' } } elseif ($CurrentPSVersion -ge [version]'6.0') { $Issues += @{ ID = 'I1' Message = "Microsoft365DSC is not supported with PowerShell Version $CurrentPSVersion. Please install version 5.1 from: " + ` 'https://www.microsoft.com/en-us/download/details.aspx?id=54616' } } #endregion # We need to do a quick configuration of WinRM in order to be able to obtain configuration information; Write-Progress -Activity 'Scanning WinRM MaxEnvelopeSize...' -PercentComplete (2 / $TotalSteps * 100) WinRM QuickConfig -Force | Out-Null #region MaxEnvelopeSize $CurrentMaxEnvelopeSize = (Get-Item -Path WSMan:\localhost\MaxEnvelopeSizekb).Value if ($CurrentMaxEnvelopeSize -le 1024) { $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' } } #endregion #region Modules Dependencies Write-Progress -Activity 'Scanning Dependencies...' -PercentComplete (3 / $TotalSteps * 100) $M365DSC = Get-Module Microsoft365DSC $ManifestPath = Join-Path -Path $M365DSC.ModuleBase -ChildPath 'Microsoft365DSC.psd1' $manifest = Import-PowerShellDataFile $ManifestPath $dependencies = $manifest.RequiredModules foreach ($dependency in $dependencies) { $module = Get-Module $dependency.ModuleName -ListAvailable | ` Where-Object -FilterScript { $_.Version -eq $dependency.RequiredVersion } if ($null -eq $module) { $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) { Write-Host "The following issues were detected with the current agent's configuration. Please take " + ` 'proper action to remediate.' $i = 1 foreach ($issue in $Issues) { Write-Error -Message " [$i/$($Issues.Count)] $($issue.Message)" } } if ($Recommendations.Count -gt 0) { Write-Host 'The following recommendations were issued. We strongly recommend adressing those: ' $i = 1 foreach ($recommendation in $Recommendations) { Write-Warning " [$i/$($Recommendations.Count)] $($recommendation.Message)" } } 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. .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' ) $existingCertificate = Get-ChildItem -Path Cert:\LocalMachine\My | ` Where-Object { $_.Subject -match 'M365DSCEncryptionCert' } if ($ForceRenew) { foreach ($cert in $existingCertificate) { Remove-Item $cert.PSPath | Out-Null } $existingCertificate = $null } if ($null -eq $existingCertificate) { Write-Verbose -Message 'No existing M365DSC certificate found. Creating one.' $certificateFilePath = "$env:Temp\M365DSC.cer" $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 $existingCertificate = Get-ChildItem -Path Cert:\LocalMachine\My | ` Where-Object { $_.Subject -match 'M365DSCEncryptionCert' } } else { Write-Verbose -Message 'An existing M365DSc certificate was found. Re-using it.' } $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 ($KeepCertificate) { Write-Host "Certificate {$thumbprint} was stored under {$($env:Temp)} with name M365DSC.cer and M365DSC.pfx" } else { try { Remove-Item -Path $configOutputFile -Confirm:$false -ErrorAction SilentlyContinue Remove-Item -Path './M365AgentConfig' -Recurse -Confirm:$false -ErrorAction SilentlyContinue } catch { Write-Error $_ } } if ($GeneratePFX) { if ($Password -eq $null) { Throw 'When the GeneratePFX switch is used, you also need to provide a password.' } $securePassword = ConvertTo-SecureString -String $password -Force -AsPlainText Export-PfxCertificate -Cert $existingCertificate.PSPath ` -FilePath $certificateFilePath.Replace('.cer', '.pfx') ` -Password $securePassword | Out-Null Write-Host "Private Key stored at {$($certificateFilePath.Replace('.cer','.pfx'))}" } return $thumbprint } Export-ModuleMember -Function @( 'Set-M365DSCAgentCertificateConfiguration', 'Test-M365DSCAgent' ) |