Remediating local administrators with proactive remediations

Like last week, this week is all about proactive remediations, a feature of Endpoint Analytics. As mentioned last week, proactive remediations are script packages that can detect common issues and remediate those issues if needed. All of that before the user even realizes that there is an issue. Those remediations can help with reducing support calls. The strength is that the remediations can be anything to address potential issues, as long as it can be addressed by using PowerShell. Each script package contains a detection script and a remediation script and that script package is deployed through Microsoft Intune. For deploying script packages, Microsoft Intune relies on the Intune Management Extension (IME).

To show the real power of proactive remediations, I’ll further develop the local administrators example of last week. Even in this modern world, local administrators are still a hot item. Last week the focus was on the detection part of proactive remediations and in this post I’ll focus on the remediation part of proactive remediations. I’ll start this post by constructing the remediation script, followed by creating the script package. I’ll end this post by verifying the results. Last week the focus for the results was locally on the device and in this post I’ll focus on the results in Microsoft Intune. This week I’ll skip the important requirements, as I’ve already documented them last week.

Constructing the remediation script

The first step is constructing the remediation script. That script should remediate the faulty configuration that was detected by the detection script. In this example, which is shown below, the remediation script is focused on a scenario in which the user of the device is a local administrator and should remain a local administrator. To fulfill that scenario the remediation script will remove all accounts, with exception of the default Administrator and the currently logged-on user, from the Administrators group. After removal of the accounts from the Administrators group, the script will add the correct accounts to the Administrators group. That will make sure that only the verified and correct accounts are members of the Administrators group and are configured on the local device. When the adjustment to the members of the Administrators group was successful, the script will return an exit code of 0 and when the adjustment to the members of the Administrators was a failure, the script will return an exit code of 1. The last line of output, before the exit code, will be displayed in the logs and can be useful information when verifying and troubleshooting the remediation script. Before using the script, make sure to adjust the array with administrator accounts to the correct list of administrators. That required adjustments is mentioned in the script example below.

#Define variables
$currentUser = (Get-CimInstance Win32_ComputerSystem).Username -replace '.*\\'
$localAdministrators = @("[YourGlobalAdminRoleSid]","[YourDeviceAdminRoleSid]") #Adjust to your local administrators
try {
$administratorsGroup = ([ADSI]"WinNT://$env:COMPUTERNAME").psbase.children.find("Administrators")
$administratorsGroupMembers = $administratorsGroup.psbase.invoke("Members")
foreach ($administratorsGroupMember in $administratorsGroupMembers) {
$administrator = $administratorsGroupMember.GetType().InvokeMember('Name','GetProperty',$null,$administratorsGroupMember,$null)
if (($administrator -ne "Administrator") -and ($administrator -ne $currentUser)) {
$administratorsGroup.Remove("WinNT://$administrator")
Write-Host "Successfully removed $administrator from Administrators group"
}
}
foreach ($localAdministrator in $localAdministrators) {
$administratorsGroup.Add("WinNT://$localAdministrator")
Write-Host "Successfully added $localAdministrator to Administrators group"
}
Write-Host "Successfully remediated the local administrators"
}
catch {
$errorMessage = $_.Exception.Message
Write-Error $errorMessage
exit 1
}

Note: Just like last week I’m relying on ADSI for making the required adjustments.

Creating the script package

The second step is creating the script package. The script package can be created by using the proactive remediations functionality of Endpoint Analytics. That functionality can be used to schedule scripts to detect specific configurations and when that configuration is faulty, it can run scripts to remediate the configuration. The following six steps walk through the process of creating a script package, with a detection script and a remediation script. That will create a script package to detect the currently configured accounts from the Administrators and to remediate any faulty configuration that is detected. That script package can be scheduled to either perform the detection and remediation only once, or on a recurring schedule. The latter will make sure that it can actually be used for creating some baseline configurations, which might sound familiar when previously, or still, using Configuration Manager. The idea is the same, just a bit more simplistic and easier to use.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Reports Endpoint analytics (Preview) > Proactive remediations to open the Endpoint analytics (Preview) | Proactive remediations blade
  2. On the Endpoint analytics (Preview) | Proactive remediations blade, click Create script package to open the Create custom script wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the custom script package
  • Description: (Optional) Provide a valid description for the custom script package
  • Publisher: Provide a valid publisher for the custom script package
  • Version: [Greyed out]
  1. On the Settings page, provide the following information and click Next
  • Detection script file: Select the previously week created detection script
  • Detection script: [Greyed out]
  • Remediation script file: Select the created remediation script
  • Remediation script: [Greyed out]
  • Run this script using the logged-on credentials: No
  • Enforce script signature check: No
  • Run script in 64-bit PowerShell: No

Important: This configuration will run these scripts with bypassing the execution policy. Together with the information of my previous post, this could enable an administrative user to edit the script before running (and without the script being checked before running).

  1. On the Assignments page, provide the following information and click Next
  • Assign to: Select the assigned group and when selecting multiple groups, multiple lines will appear with all separate schedule configurations
  • Schedule: Click on the three dots to open the schedule configuration. This enables the administrator to configure a recurrence frequency for the script package. This can be Once, Daily, or Hourly.
    • When selecting Once, a specific date and time should be configured
    • When selecting Daily, a frequency and daily time should be configured
    • When selecting Hourly, a frequency should be configured
  1. On the Review + create page, verify the information and click Create

Verifying the results

When verifying the results, in Microsoft Intune, the first place to look is the proactive remediations overview. That provides an overview of all the different script packages that are deployed within the organization. That overview provides an easy first method to monitor the detection and remediation results of all the different deployed script packages. That overview is shown below and is available via Reports > Endpoint analytics > Proactive remediations.

When more details are required about a specific script package, the script package overview is the best place to look. That provides an overview that is specifically related to the status of a specific script package. That overview provides a clear bar chart for the status of the detection and remediation script of the script package. Besides that it also shows a nice daily remediation trend. That daily trend provides an overview of how often that specific situation is remediated. That overview is shown below and is available via Reports > Endpoint analytics > Proactive remediations > [Specific script package] > Overview.

When even more details are required about a specific script package on a specific device, the script package device status overview is the best place to look. That provides a clear overview about status details of a script package on the different devices. That overview includes standard information about the device and the last sync time, but also includes useful information that was part of the output of the detection script. That overview is shown below and is available via Reports > Endpoint analytics > Proactive remediations > [Specific script package] > Device status.

More information

For more information about Endpoint Analytics and Proactive Remediations, refer to the following docs

Detecting local administrators with proactive remediations

This week is all about proactive remediations, which is a feature of Endpoint Analytics. Proactive remediations are script packages that can detect common issues and remediate those issues if needed. All of that before the user even realizes that there is an issue. Those remediations can help with reducing support calls. The strength is that the remediations can be anything to address potential issues, as long as it can be addressed by using PowerShell. Each script package contains a detection script and a remediation script and that script package is deployed through Microsoft Intune. For deploying script packages, Microsoft Intune relies on the Intune Management Extension (IME).

To show the power of proactive remediations, I’ll use local administrators as an example. I’ve did something similar a long time ago for Configuration Manager and I still get many questions around that subject on my post about managing local administrators. Even in this modern world, local administrators are still a hot item. In this post I’ll focus on the detection part of proactive remediations and the remediation part itself might only be a week away. I’ll start this post by constructing the detection script, followed by creating the script package. I’ll end this post by verifying the results locally on the device.

Important prerequisites

Before actually starting with Endpoint Analytics it’s important to have the different prerequisites in place. That means the correct licenses and the correct configuration.

  • The device must be running Windows 10 Enterprise, Professional, or Education
  • The devices must be enrolled into Endpoint Analytics
  • The devices must be Azure AD joined or hybrid Azure AD joined and meet one of the following conditions:
    • the device is managed by Intune.
    • the device is co-managed device and running Windows 10, version 1903 or later.
    • the device is co-managed device and running on pre-1903 versions of Windows 10 with the Client apps workload pointed to Intune
  • The user must be licensed for Endpoint Analytics, which is included in Enterprise Mobility + Security E3 or higher and Microsoft 365 Enterprise E3 or higher, and when not using the latter, additional licensing of the following:
    • Windows 10 Enterprise E3 or E5
    • Windows 10 Education A3 or A5
    • Windows Virtual Desktop Access E3 or E5

Constructing the detection script

The first step is constructing the detection script. That script should detect the correct situation. In this example, the detection script should detect the correct number of local administrators and also the correct local administrator users. For a successful detection of the correct (number of) local administrators, the script should return an exit code of 0 and for a failed detection of the (number of) local administrators, the script should return an exit code of 1. That failure will eventually trigger the remediation script. More about that, next week. Besides that, it’s good to know that the last line of output, before the exit code, will also be displayed in the logs. That can be helpful when verifying and troubleshooting the detection script. The following example detection script will verify the number of local administrators and once the number matches, it will actually verify the local administrator users with the configured list of local administrators. Make sure to adjust that list with the correct local administrators and make sure to adjust the number of local administrators. The required adjustments are mentioned in the script example below.

#Define variables
$localAdministrators = @()
$memberCount = 0
$numberLocalAdministrators = 4 #Adjust to your number of administrators
try {
$currentUser = (Get-CimInstance Win32_ComputerSystem).Username -replace '.*\\'
$administratorsGroup = ([ADSI]"WinNT://$env:COMPUTERNAME").psbase.children.find("Administrators")
$administratorsGroupMembers= $administratorsGroup.psbase.invoke("Members")
foreach ($administrator in $administratorsGroupMembers) {
$localAdministrators += $administrator.GetType().InvokeMember('Name','GetProperty',$null,$administrator,$null)
}
if ($localAdministrators.Count -eq $numberLocalAdministrators) {
foreach($localAdministrator in $localAdministrators) {
switch ($localAdministrator) {
#Adjust to your local administrators
"Administrator" { $memberCount = $memberCount + 1; break; }
"$currentUser" { $memberCount = $memberCount + 1; break; }
"[YourGlobalAdminRoleSid]" { $memberCount = $memberCount + 1; break; }
"[YourDeviceAdminRoleSid]" { $memberCount = $memberCount + 1; break; }
default {
Write-Host "The found local administrators are no match"
exit 1
}
}
}
if ($memberCount -eq $numberLocalAdministrators) {
Write-Host "The found local administrators are a match"
exit 0
}
}
else {
Write-Host "The number of local administrators doesn't match"
exit 1
}
}
catch {
$errorMessage = $_.Exception.Message
Write-Error $errorMessage
exit 1
}

Note: Compared to my previous post, I prefer to use ADSI above WMI and Get-LocalGroupMember. WMI was often too slow and the mentioned cmdlet doesn’t really like SIDs yet.

Creating the script package

The second step is creating the script package. The script package can be created by using the relatively new functionality of Endpoint Analytics, which is proactive remediations. That functionality can be used to basically schedule scripts to detect specific configurations and, if needed, remediate the configuration. The following six steps walk through the process of creating a script package, with a focus on the detection script. That will create a script package to detect the local administrators. That script package can be scheduled to either perform the detection (and remediation) only once, or on a recurring schedule. The latter will make sure that it can actually be used for creating some baseline configurations, which might sound familiar when previously, or still, using Configuration Manager. The idea is the same, just a bit more simplistic and easier to use.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Reports Endpoint analytics (Preview) > Proactive remediations to open the Endpoint analytics (Preview) | Proactive remediations blade
  2. On the Endpoint analytics (Preview) | Proactive remediations blade, click Create script package to open the Create custom script wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the custom script package
  • Description: (Optional) Provide a valid description for the custom script package
  • Publisher: Provide a valid publisher for the custom script package
  • Version: [Greyed out]
  1. On the Settings page, provide the following information and click Next
  • Detection script file: Select the created detection script
  • Detection script: [Greyed out]
  • Remediation script file: (Optional) More about the remediation script file next week
  • Remediation script: (Optional) More about the remediation script next week
  • Run this script using the logged-on credentials: No
  • Enforce script signature check: No
  • Run script in 64-bit PowerShell: No
  1. On the Assignments page, provide the following information and click Next
  • Assign to: Select the assigned group and when selecting multiple groups, multiple lines will appear with all separate schedule configurations
  • Schedule: Click on the three dots to open the schedule configuration. This enables the administrator to configure a recurrence frequency for the script package. This can be Once, Daily, or Hourly.
    • When selecting Once, a specific date and time should be configured
    • When selecting Daily, a frequency and daily time should be configured
    • When selecting Hourly, a frequency should be configured
  1. On the Review + create page, verify the information and click Create

Verifying the results

For the detection of the local administrators, I’ll focus mainly on the information locally on the device. Next week, when adding the remediation, the focus will be on Microsoft Intune when looking at the results. As it’s the IME that is addressing the execution of the script packages, the information related to the execution is also logged in the IME related logfiles. The most interesting information can be found in the IntuneManagementExtension.log. That logfile contains the execution information of the script packages and every related line in the log has a prefix of [HS]. That prefix is referring to HealthScripts, which is shown in the different logs and file locations. When looking at the [HS] prefix throughout the log, it’s divided into the following two categories:

  1. Scheduler – Looking at the log, the Scheduler is responsible for requesting and scheduling the script packages. Below, in Figure 3, is an example of the Scheduler that is scheduling the script package for detecting local administrators. The highlighted sections show information about the user, the policy and the schedule. All of that information is referenced below in more logs, file locations and the registry.
  1. Runner – Looking at the log, the Runner is responsible for executing and reporting about the script packages. Below, in Figure 4, is an example of the Runner that is actually executing the scheduled policy for detecting local administrators. The highlighted sections show information about the user, the policy, the schedule, the result and the output. All that information is referenced above in the script, and below in the file location and the registry.

The script package is store locally in the HealthScripts folder in the IMECache folder. That folder contains a folder, as shown below in Figure 5, that corresponds with the policy that was highlighted in the IntuneManagementExtension.log. That folder contains a script named detect and a script named remediate and both of those scripts correspond to the scripts of the script package. When the script package is only used for detection, the remediate script will be empty.

In the end all of the most important information is stored in the registry, in the Scrips key in HKLM\SOFTWARE\Microsoft\IntuneManagementExtension\SideCarPolicies. That key contains a key with information about the execution of the script package and that information is stored below a key of the user and the policy. That key contains the latest execution information and is shown below in Figure 6.

The Scripts key also contains a key with information about the result of the script package and that information is store below a key of the user and the policy. That key contains the result information that is reported and is shown in Figure 7.

The actual content of the Result value is shown below. That information contains the policy, the user, that status and the output. All the information that was referenced earlier in the script, log, file location and registry.

{ 
    "PolicyId":"176b61ca-59e6-4af1-b852-13a3102c5578",
    "UserId":"dedbba8f-f4f1-475c-a30b-895d87d77e9b",
    "PolicyHash":null,
    "Result":3,
    "ResultDetails":null,
    "InternalVersion":1,
    "ErrorCode":0,
    "ResultType":1,
    "PreRemediationDetectScriptOutput":"The found local administrators are a match",
    "PreRemediationDetectScriptError":null,
    "RemediationScriptErrorDetails":null,
    "PostRemediationDetectScriptOutput":null,
    "PostRemediationDetectScriptError":null,
    "RemediationStatus":4,
    "Info": {
        "RemediationExitCode":0,
        "FirstDetectExitCode":0,
        "LastDetectExitCode":0,
        "ErrorDetails":null
    }
}

More information

For more information about Endpoint Analytics and Proactive Remediations, refer to the following docs