Have you ever looked at your Active Directory and wondered, “Why do I still have computers listed that haven't been turned on since World Cup 2016?” Yeah, we've all been there. Keeping AD clean and up-to-date is like trying to organize your garage—it’s easy to put off until it becomes a total mess.
That’s where my PowerShell module, CleanupMonster, comes to the rescue. This little powerhouse is designed to help you effortlessly track down and deal with those old, stale computers cluttering your directory. Whether you want to move, disable, or even give them the boot, CleanupMonster has your back. And it doesn’t stop there—if you need to gather some intel from Entra ID (Azure AD), Intune, or Jamf to make an informed decision, CleanupMonster can handle that, too.
In this post, I'll explain how CleanupMonster can help you clean up your Active Directory without breaking a sweat. Let’s dive in and give your AD the spring cleaning it deserves!
Cleanup your Active Directory
The CleanupMonster PowerShell module was created as an easy way to remove stale computer objects from the Active Directory. However, each company and enterprise has rules regarding what happens to computers and how they should be handled. Then, there is a question of how to tell the computer that it is a stale object. While there are many solutions on the internet, if you look hard enough, CleanupMonster does this in a way that nothing comes close!
There are several ways to determine when a computer in Active Directory becomes inactive. However, the most common methods are LastLogonDate and PasswordLastSet, which should ideally not exceed 30 days. Some people might advise you to use simple PowerShell commands to locate and delete these inactive computers – it can be done in just five lines of code!
Get-ADComputer -filter * -Proper Name, DisplayName, SamAccountName, lastlogondate, PasswordLastSet | ft Name, DisplayName, SamAccountName, lastlogondate, PasswordLastSet
It's true that if you are lucky enough to have a small organization with only a few attributes to consider, you can make informed decisions and maintain a clean Active Directory without using CleanupMonster. However, things get more complicated for larger companies or enterprises. In these cases, there are VPN solutions, employees who haven't connected to the network for months, and those who work on Mac devices that may not get updated regularly. What if a computer object was just prepared for onboarding, but the cleanup script mistakenly identified it as inactive and deleted it? There are many potential issues, which can lead to employees opening tickets and reporting that they can't work anymore.
This is where CleanupMonster comes in. It's a PowerShell module with a single command called Invoke-ADComputersCleanup. Its multiple parameters allow it to be configured in many ways, meeting the most advanced scenarios you can imagine.
Features & Options
CleanupMonster has the following features:
- Ability to disable, disable and move, move and disable, move or delete computers
- All five actions from above can have different rules when a given task happens
- It's able to check when the object was created and prevent the deletion of objects younger than X days
- It's able to check LastLogonDate and LastPasswordSet and requires it to be certain days old to consider for disabling, moving, or delete
- If LastLogonDate or LastPasswordSet is empty, it is treated as never used; therefore, it applies the maximum number of days to it.
- It can check Intune data for LastLogonDate for a given computer, providing the ability to improve data with cloud data for those non-connected machines.
- It can check Entra ID data (Azure AD) for LastLogonDate for a given computer to improve the assessment of deletion.
- It's able to check Jamf PRO for LastLogonDate for macOS devices.
- You can target whole forest, or include/exclude specific domains from this process
This means you can configure it to only disable, move, or delete an object if LastLogonDate is over 90 days, LastPasswordDate is over 90 days, LastLogonDate in Azure AD is over 90 days, LastLogonDate in Intune is over 90 days, and LastLogonDate is over 90 days in Jamf PRO, and additional that the object was created over 90 days ago. This can be further enhanced to action an object based on OperatingSystem (include, exclude) and exclude certain Organizational Units or specific objects wholly based on their Name or DistinguishedName. All of this is configurable with just an option on the cmdlet. Finally, there's one more option called the Pending Deletion list. The pending deletion list keeps track of disabled/moved objects to know how long ago they were disabled/moved so that computer objects can be deleted. This means you can configure CleanupMonster to turn off an object but tell it to wait 90 days before deleting it. If the object gets reenabled during that time, it's automatically removed from the pending list, and the time timer starts again.
If that wasn't enough the module has:
- Built-in HTML reporting keeping track of what was actioned, what will be actioned, what is on pending deletion list, including logs from each action
- It's able to write to Event Log when the computer is actioned so it can be tracked in SIEM
- It has builtin DisableLimit, DeleteLimit that allow only X number of objects actioned per run, preventing abuse or accidental deletions.
- It provides Safety limits such as SafetyADLimit,SafetyAzureADLimit, SafetyIntuneLimit, SafetyJamfLimit that the script requires certain number of objects to be gathred before continuing. This is to prevent decision making process based on incomplete data because something went wrong during gathering data phase (lack of internet, certain server being down etc).
- Provides WhatIf functionality to Disabling, Move or Deleting together or separately
- Full logging of all actions to file
Additionally, with just a few lines of code, you can send daily results to email using PSWriteHTML functionality.
Example configuration #1
I don't want to bore you too much with text, so let's jump into how some of the configurations look like:
# Run the script
$Configuration = @{
Disable = $true
DisableNoServicePrincipalName = $null
DisableIsEnabled = $true
DisableLastLogonDateMoreThan = 90
DisablePasswordLastSetMoreThan = 90
DisableExcludeSystems = @(
# 'Windows Server*'
)
DisableIncludeSystems = @()
DisableLimit = 2 # 0 means unlimited, ignored for reports
DisableModifyDescription = $false
DisableModifyAdminDescription = $true
Delete = $true
DeleteIsEnabled = $false
DeleteNoServicePrincipalName = $null
DeleteLastLogonDateMoreThan = 180
DeletePasswordLastSetMoreThan = 180
DeleteListProcessedMoreThan = 90 # 90 days since computer was added to list
DeleteExcludeSystems = @(
# 'Windows Server*'
)
DeleteIncludeSystems = @(
)
DeleteLimit = 2 # 0 means unlimited, ignored for reports
Exclusions = @(
'*OU=Domain Controllers*'
'*OU=Servers,OU=Production*'
'EVOMONSTER$'
'EVOMONSTER.AD.EVOTEC.XYZ'
)
Filter = '*'
WhatIfDisable = $true
WhatIfDelete = $true
LogPath = "$PSScriptRoot\Logs\DeleteComputers_$((Get-Date).ToString('yyyy-MM-dd_HH_mm_ss')).log"
DataStorePath = "$PSScriptRoot\DeleteComputers_ListProcessed.xml"
ReportPath = "$PSScriptRoot\Reports\DeleteComputers_$((Get-Date).ToString('yyyy-MM-dd_HH_mm_ss')).html"
ShowHTML = $true
}
# Run one time as admin: Write-Event -ID 10 -LogName 'Application' -EntryType Information -Category 0 -Message 'Initialize' -Source 'CleanupComputers'
$Output = Invoke-ADComputersCleanup @Configuration
$Output
When run the script will disable object only if it matches last logon date over 90 days and last password date over 90 days and the object will be enabled. It will also disable maximum of 2 objects and modify admin description of the object with information about details of this action. However, to delete an object, it will require 180 days for the last logon and last password date and be on the processing list for at least 90 days. It will also delete only two objects per run. It won't touch objects in Domain Controllers OU, in Servers OU and it will ignore EVOMonster device. Since both WhatIfDelete and WhatIfDisable are enabled it will not do any real action and it will instead just display what it would do, doing no harm to AD. Finally it will generate HTML report to given path and display it in your favourite browser.
Example configuration #2
Of course, we can make a more complicated example which, as part of disabling, also moves the computer. You can choose the order DisableAndMove or MoveAndDisable depending on which permissions you have granted for your GMSA account. You can also define the path per domain where the computers are moved when required. There's also the ability to treat moving as a separate process: Disable/Move/Delete, rather than doing Disable & Move / Delete. As you can see in the example below, some commented-out settings show you unused but available options.
# connect to graph for Email sending
Connect-MgGraph -Scopes Mail.Send -NoWelcome
$invokeADComputersCleanupSplat = @{
#ExcludeDomains = 'ad.evotec.xyz'
# safety limits (minimum amount of computers that has to be returned from each source)
SafetyADLimit = 30
#SafetyAzureADLimit = 5
#SafetyIntuneLimit = 3
#SafetyJamfLimit = 50
# disable settings
Disable = $true
DisableAndMove = $true
DisableAndMoveOrder = 'DisableAndMove' # DisableAndMove, MoveAndDisable
#DisableIsEnabled = $true
DisableLimit = 1
DisableLastLogonDateMoreThan = 90
DisablePasswordLastSetMoreThan = 90
#DisableLastSeenAzureMoreThan = 90
DisableRequireWhenCreatedMoreThan = 90
DisablePasswordLastSetOlderThan = Get-Date -Year 2023 -Month 1 -Day 1
#DisableLastSyncAzureMoreThan = 90
#DisableLastContactJamfMoreThan = 90
#DisableLastSeenIntuneMoreThan = 90
DisableMoveTargetOrganizationalUnit = @{
'ad.evotec.xyz' = 'OU=Disabled,OU=Computers,OU=Devices,OU=Production,DC=ad,DC=evotec,DC=xyz'
'ad.evotec.pl' = 'OU=Disabled,OU=Computers,OU=Devices,OU=Production,DC=ad,DC=evotec,DC=pl'
}
# move settings
Move = $false
MoveLimit = 1
MoveLastLogonDateMoreThan = 90
MovePasswordLastSetMoreThan = 90
#MoveLastSeenAzureMoreThan = 180
#MoveLastSyncAzureMoreThan = 180
#MoveLastContactJamfMoreThan = 180
#MoveLastSeenIntuneMoreThan = 180
#MoveListProcessedMoreThan = 90 # disabled computer has to spend 90 days in list before it can be deleted
MoveIsEnabled = $false # Computer has to be disabled to be moved
MoveTargetOrganizationalUnit = @{
'ad.evotec.xyz' = 'OU=Disabled,OU=Computers,OU=Devices,OU=Production,DC=ad,DC=evotec,DC=xyz'
'ad.evotec.pl' = 'OU=Disabled,OU=Computers,OU=Devices,OU=Production,DC=ad,DC=evotec,DC=pl'
}
# delete settings
Delete = $false
DeleteLimit = 2
DeleteLastLogonDateMoreThan = 180
DeletePasswordLastSetMoreThan = 180
#DeleteLastSeenAzureMoreThan = 180
#DeleteLastSyncAzureMoreThan = 180
#DeleteLastContactJamfMoreThan = 180
#DeleteLastSeenIntuneMoreThan = 180
#DeleteListProcessedMoreThan = 90 # disabled computer has to spend 90 days in list before it can be deleted
DeleteIsEnabled = $false # Computer has to be disabled to be deleted
# global exclusions
Exclusions = @(
'*OU=Domain Controllers*' # exclude Domain Controllers
)
# filter for AD search
Filter = '*'
# logs, reports and datastores
LogPath = "$PSScriptRoot\Logs\CleanupComputers_$((Get-Date).ToString('yyyy-MM-dd_HH_mm_ss')).log"
DataStorePath = "$PSScriptRoot\CleanupComputers_ListProcessed.xml"
ReportPath = "$PSScriptRoot\Reports\CleanupComputers_$((Get-Date).ToString('yyyy-MM-dd_HH_mm_ss')).html"
# WhatIf settings
ReportOnly = $false
WhatIfDisable = $true
WhatIfMove = $true
WhatIfDelete = $true
ShowHTML = $true
DontWriteToEventLog = $true
}
$Output = Invoke-ADComputersCleanup @invokeADComputersCleanupSplat
# Now lets send email using Graph
[Array] $DisabledObjects = $Output.CurrentRun | Where-Object { $_.Action -eq 'Disable' }
[Array] $DeletedObjects = $Output.CurrentRun | Where-Object { $_.Action -eq 'Delete' }
$EmailBody = EmailBody -EmailBody {
EmailText -Text "Hello,"
EmailText -LineBreak
EmailText -Text "This is an automated email from Automations run on ", $Env:COMPUTERNAME, " on ", (Get-Date -Format 'yyyy-MM-dd HH:mm:ss'), " by ", $Env:UserName -Color None, Green, None, Green, None, Green -FontWeight normal, bold, normal, bold, normal, bold
EmailText -LineBreak
EmailText -Text "Following is a summary for the computer object cleanup:" -FontWeight bold
EmailList {
EmailListItem -Text "Objects actioned: ", $Output.CurrentRun.Count -Color None, Green -FontWeight normal, bold
EmailListItem -Text "Objects deleted: ", $DeletedObjects.Count -Color None, Salmon -FontWeight normal, bold
EmailListItem -Text "Objects disabled: ", $DisabledObjects.Count -Color None, Orange -FontWeight normal, bold
}
EmailText -Text "Following objects were actioned:" -LineBreak -FontWeight bold -Color Salmon
EmailTable -DataTable $Output.CurrentRun -HideFooter {
New-HTMLTableCondition -Name 'Action' -ComparisonType string -Value 'Delete' -BackGroundColor PinkLace -Inline
New-HTMLTableCondition -Name 'Action' -ComparisonType string -Value 'Disable' -BackGroundColor EnergyYellow -Inline
New-HTMLTableCondition -Name 'ActionStatus' -ComparisonType string -Value 'True' -BackGroundColor LightGreen -Inline
New-HTMLTableCondition -Name 'ActionStatus' -ComparisonType string -Value 'False' -BackGroundColor Salmon -Inline
New-HTMLTableCondition -Name 'ActionStatus' -ComparisonType string -Value 'Whatif' -BackGroundColor LightBlue -Inline
}
EmailText -LineBreak
EmailText -Text "Regards,"
EmailText -Text "Automations Team" -FontWeight bold
}
# send email using Mailozaurr
Send-EmailMessage -To 'przemyslaw.klys@test.pl' -From 'przemyslaw.klys@test.pl' -MgGraphRequest -Subject "Automated Computer Cleanup Report" -Body $EmailBody -Priority Low -Verbose -WhatIf
At the bottom of it, you can see how I'm using PSWriteHTML along with the Mailozaurr module, which, based on the module's output, sends me nicely formatted emails.
Fancy reporting & logging
One of the essential parts of any good solution is knowing what happens when it happens and having some option to go back in time and assess the situation. CleanupMonster provides an advanced reporting engine that allows you to view the following:
- What happened during the run time? Which objects were touched, and what parameters they had
- Devices history showing the history of script actions over time to look back 1-2-10 months back
- Devices are on the pending list for deletion, so you can see how many objects are waiting to be purged according to the rules you've used.
- All devices have a full assessment based on the provided rules, allowing you to assess how many devices require deletion and are still suitable.
All reports are visually attractive, so IT Directors/Managers can have a single view of all computer objects.
Every action the script takes or has taken in the past is accessible and can be used as evidence.
Installing or updating PowerShell module
CleanupMonster is available in PowerShellGallery as an easy-to-use download.
Install-Module CleanupMonster -Force -Verbose
If you need Jamf Pro functionality, you also need to install
Install-Module PowerJamf -Force -Verbose
If you need Azure AD (Entra ID) and Intune functionality, you also need to install
Install-Module GraphEssentials -Force -Verbose
Once the module is installed, you can adjust it to your needs. Please remember to use WhatIfDisable, WhatIfMove, WhatIfDelete, or WhatIf (which is pretendable for everyone). Also, make sure that DeleteLimit, DisableLimit, and MoveLimit start small 1-2-10 objects for the first time so you can quickly recover from the wrong configuration and go from there. Finally, Safety* properties help you ensure any timeouts when getting data won't ruin your AD. Make sure to use them carefully!
