Edit

Automate onboarding of Microsoft Defender for Cloud using PowerShell

  • Article

You can secure your Azure workloads programmatically, using the Microsoft Defender for Cloud PowerShell module. Using PowerShell enables you to automate tasks and avoid the human error inherent in manual tasks. This is especially useful in large-scale deployments that involve dozens of subscriptions with hundreds and thousands of resources, all of which must be secured from the beginning.

Onboarding Microsoft Defender for Cloud using PowerShell enables you to programmatically automate onboarding and management of your Azure resources and add the necessary security controls.

This article provides a sample PowerShell script that can be modified and used in your environment to roll out Defender for Cloud across your subscriptions.

In this example, we'll enable Defender for Cloud on a subscription with ID: d07c0080-170c-4c24-861d-9c817742786c and apply the recommended settings that provide a high level of protection, by enabling Microsoft Defender for Cloud's enhanced security features, which provides advanced threat protection and detection capabilities:

  1. Enable the enhanced security in Microsoft Defender for Cloud.

  2. Set the Log Analytics workspace to which the Log Analytics agent will send the data it collects on the VMs associated with the subscription – in this example, an existing user defined workspace (myWorkspace).

  3. Activate Defender for Cloud’s automatic agent provisioning, which deploys the Log Analytics agent.

  4. Set the organization’s CISO as the security contact for Defender for Cloud alerts and notable events.

  5. Assign Defender for Cloud’s default security policies.

Prerequisites

These steps should be performed before you run the Defender for Cloud cmdlets:

  1. Run PowerShell as admin.

  2. Run the following commands in PowerShell:

    Set-ExecutionPolicy -ExecutionPolicy AllSigned

    Install-Module -Name Az.Security -Force

Onboard Defender for Cloud using PowerShell

  1. Register your subscriptions to the Defender for Cloud Resource Provider:

    Set-AzContext -Subscription "d07c0080-170c-4c24-861d-9c817742786c"

    Register-AzResourceProvider -ProviderNamespace 'Microsoft.Security'

  2. Optional: Set the coverage level (Microsoft Defender for Cloud's enhanced security features on/off) of the subscriptions. If undefined, these features are off:

    Set-AzContext -Subscription "d07c0080-170c-4c24-861d-9c817742786c"

    Set-AzSecurityPricing -Name "VirtualMachines" -PricingTier "Standard"

  3. Configure a Log Analytics workspace to which the agents will report. You must have a Log Analytics workspace that you already created, that the subscription’s VMs will report to. You can define multiple subscriptions to report to the same workspace. If not defined, the default workspace will be used.

    Set-AzSecurityWorkspaceSetting -Name "default" -Scope "/subscriptions/d07c0080-170c-4c24-861d-9c817742786c" -WorkspaceId "/subscriptions/d07c0080-170c-4c24-861d-9c817742786c/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace"

  4. Auto-provision installation of the Log Analytics agent on your Azure VMs:

    Set-AzContext -Subscription "d07c0080-170c-4c24-861d-9c817742786c"

    Set-AzSecurityAutoProvisioningSetting -Name "default" -EnableAutoProvision

    Note

    We recommend that you enable auto provisioning to make sure that your Azure virtual machines are automatically protected by Microsoft Defender for Cloud.
    As part of the Defender for Cloud updated strategy, Azure Monitor Agent (AMA) will no longer be required for the Defender for Servers offering. However, it will still be required for Defender for SQL server on machines. As a result, deploying Azure Monitor Agent (AMA) with the Defender for Cloud portal is available for SQL servers on machines, with a new deployment policy. Learn more about how to migrate to SQL server-targeted Azure Monitoring Agent's (AMA) auto-provisioning process.

  5. Optional: It's highly recommended that you define the security contact details for the subscriptions you onboard, which will be used as the recipients of alerts and notifications generated by Defender for Cloud:

    Set-AzSecurityContact -Name "default1" -Email "CISO@my-org.com" -AlertAdmin -NotifyOnAlert

  6. Assign the default Defender for Cloud policy initiative:

    Register-AzResourceProvider -ProviderNamespace 'Microsoft.PolicyInsights'

    $Policy = Get-AzPolicySetDefinition | where {$_.Properties.displayName -EQ 'Microsoft cloud security benchmark'} 

New-AzPolicyAssignment -Name 'Microsoft cloud security benchmark' -PolicySetDefinition $Policy -Scope '/subscriptions/$($Subscription.Id)'

You've successfully onboarded Microsoft Defender for Cloud with PowerShell.

You can now use these PowerShell cmdlets with automation scripts to programmatically iterate across subscriptions and resources. This saves time and reduces the likelihood of human error. You can use this sample script as reference.

See also

To learn more about how you can use PowerShell to automate onboarding to Defender for Cloud, see the following article:

To learn more about Defender for Cloud, see the following articles: