Today, I am excited to introduce a new PowerShell module designed to help further simplify the deployment and configuration of Microsoft Defender for Identity. This tool will make it easier than ever to protect your organization from identity-based cyber-threats.
Getting started with Identity security can often seem like a daunting task, especially for modern organizations wrangling hybrid, multi-domain environments. Minor misconfigurations can lead to unnecessary stress on Identity infrastructure or worse, blind spots in protection.
Over the past few months our team has been working hard streamlining deployment and this new PowerShell module is the next step in that journey, helping automate the process of configuring the post-deployment requirements for Defender for Identity.
Getting started
Installing the module – the module is available for download from the PowerShell Gallery. It's best to check back regularly as the module will be updated whenever a new requirement is added because a new Health issue will be created in your workspace.
Install-Module DefenderForIdentity
Note: The DefenderForIdentity module requires the ActiveDirectory and the GroupPolicy modules to be installed on the server.
Importing the module – once installed use the following command to import the module:
Import-Module DefenderForIdentity
You can get a list of all the functions available within the module using the command:
Get-Command -Module DefenderForIdentity
And the output should look something like this:
You can also get more details on each function, what it does and how to run it by using the Get-Help command, similar to the following:
Get-Help -Name Test-MDIDSA -Full
Testing your configuration
The Test-MDIConfiguration function can be used to easily validate if the required configuration is applied. It has two modes: LocalMachine and Domain:
- The LocalMachine mode will validate that the specified configuration is applied correctly on the server which the function is being run on.
- The Domain mode will validate the existence of the Group Policy Objects (GPOs) created by the Set-MDIConfiguration function, and that they contain the correct configuration, are linked, and enabled.
It also has 9 configuration items that can be used separately or as a combination of more than one:
- AdfsAuditing – For the required SACL on the ADFS container in Active Directory
- AdvancedAuditPolicyCAs – For the Advanced Auditing Policy on Certificate Authority servers
- AdvancedAuditPolicyDCs – For the Advanced Auditing Policy on Domain Controllers
- CAAuditing – For the CertSrv service audit flags on Certificate Authority servers
- ConfigurationContainerAuditing – For the required SACL on the configuration container in Active Directory
- DomainObjectAuditing – For the required SACL on the domain in Active Directory
- NTLMAuditing – For the NTLM auditing policy on Domain Controllers
- ProcessorPerformance – For the high-performance power scheme on servers running the MDI sensor
- All - all configurations are validated.
For example, to validate the NTLM auditing on the local machine, run:
Test-MDIConfiguration -Mode LocalMachine -Configuration NTLMAuditing
If the result is true, it means that you already have the required NTLM auditing in place. If the result is false, you can use the Set-MDIConfiguration function to fix it.
As another example, to check if the Advanced Auditing Policy for the Domain Controllers is set to be applied with a GPO (by using the Domain mode), run:
Test-MDIConfiguration -Mode Domain -Configuration AdvancedAuditPolicyDCs
This will validate the existence of the ‘Microsoft Defender for Identity - Advanced Audit Policy for DCs’ GPO, that it contains the required Advanced Audit Configuration settings, that it is enabled only for the computer configuration (GPO Status == User Configuration Settings Disabled) and that it is linked at the Domain Controllers container in Active Directory.
Note: The AdfsAuditing, ConfigurationContainerAuditing and DomainObjectAuditing are available in both the LocalMachine and Domain modes, but they validate the required System Access Control List (SACL) on the relevant containers in Active Directory. See Configure audit policies for Windows event logs for more details.
To test all existing configurations at one, run:
Test-MDIConfiguration -Mode Domain -Configuration All
Getting details on the applied configuration
The Get-MDIConfiguration function can be used to get more details on the actual applied configuration, and determine which configuration is missing or misconfigured. It also has the LocalMachine and Domain modes:
- The LocalMachine mode will get the specified configuration from the server which the function is being run on.
- The Domain mode will get information on the Group Policy Objects (GPOs) created by the Set-MDIConfiguration function, or the SACLs on the Active Directory containers.
For example, to get details for the DomainObjectAuditing applied configuration, run:
Get-MDIConfiguration -Mode Domain -Configuration DomainObjectAuditing |
Select-Object -ExpandProperty Details
To get the status and details on all configurations on the local machine, run:
Get-MDIConfiguration -Mode LocalMachine -Configuration All
Setting configuration
The Set-MDIConfiguration function can be used to apply the required configuration. It also has the LocalMachine and Domain modes.
- The LocalMachine mode will set the configuration locally on the server which the function is being run on.
- The Domain mode will create the relevant Group Policy Object (GPO) with the correct configuration, enable only the computer configuration, and link it to the relevant container.
For example, to set the high-performance power scheme to be applied with a GPO (by using the Domain mode), run:
Set-MDIConfiguration -Mode Domain -Configuration ProcessorPerformance
Note: The same high-performance setting is required for all servers that have the MDI sensor installed, so you would need to link the same GPO to additional Organizational Units (OU) or at the domain level and use the security filtering to have the settings apply only on the relevant servers.
You can also use the -GpoNamePrefix parameter to have a different GPO name, to match the naming convention in your organization. For example:
Set-MDIConfiguration -Mode Domain -Configuration ProcessorPerformance -GpoNamePrefix "CONTOSO"
The Certificate Authority servers' configurations (AdvancedAuditPolicyDCs and CAAuditing) in the Domain mode are created as GPOs linked at the domain level but scoped using security filtering to the ‘Cert Publishers’ group, that by default contains only CA servers configured in the domain.
If you want the command to create the required GPO with all the settings, but have the GPO disabled and skip the creation of the link, you can add the -CreateGpoDisabled -SkipGpoLink switches:
Set-MDIConfiguration -Mode Domain -Configuration AdvancedAuditPolicyCAs, CAAuditing -CreateGpoDisabled -SkipGpoLink
As another example, for complete configuration, creating all relevant GPOs and setting all required SACLs on the relevant Active Directory containers, run:
Set-MDIConfiguration -Mode Domain -Configuration All
Reporting
The New-MDIConfigurationReport can be used to create an html report of the applied configuration, and get the command for each configuration item that needs to be fixed.
New-MDIConfigurationReport -Path C:\Temp -OpenHtmlReport
Other functionality
The module contains additional functions that can help validate the environment and settings readiness and manage the MDI sensors proxy configuration.
For example, to change the sensor’s proxy configuration, run:
Set-MDISensorProxyConfiguration -ProxyUrl 'http://proxy.contoso.com:8080' -ProxyCredential (Get-Credential)
Note: Setting the proxy configuration first stops the services, then makes the required changes to the configuration file, and starts the services back. Keep in mind that this process requires elevated privileges, so you'll need to run the PowerShell session as an administrator.
To test the connectivity to the Defender for Identity cloud services, run:
Test-MDISensorApiConnection
If you haven’t installed the sensor yet and/or want to validate the server’s connectivity using a different proxy or a different workspace than the one in the sensor’s configuration file, run:
$connectionParams = @{
BypassConfiguration = $true
SensorApiUrl = 'https://contososensorapi.atp.azure.com'
ProxyUrl = 'https://myproxy.contoso.com:8080'
ProxyCredential = $credential
}
Test-MDISensorApiConnection @connectionParams
In the future, MDI configuration requirements surfaced as health issues will include the relevant command needed to be run in order to fix the issue, and as new configuration requirements are added, this module will be updated to include those as well.
Conclusion:
We hope this blog post helps you understand the benefits of our new PowerShell module for Microsoft Defender for Identity. If you have any questions or feedback, please let us know.
PS:
I’d like to thank Will Sykes and Damon Neal for the idea to the module’s GPO approach, and to Raymond Roethof, Fabian Bader, and Elli Shlomo for providing valuable feedback during the early testing phases of the module.
Microsoft
