Active Directory Stale Account Cleanup

1#Requires -Modules ActiveDirectory2<#3.SYNOPSIS4    Stages dormant AD accounts through disable -> quarantine -> report.5 6.DESCRIPTION7    Uses LastLogonTimestamp (replicated attribute) so a single DC query is8    accurate to within msDS-LogonTimeSyncInterval (default 14 days).9    Never deletes. Deletion is handled by Remove-QuarantinedAccounts.ps110    against objects whose quarantine period has elapsed.11 12.PARAMETER InactiveDays13    Days since last logon before an account is considered stale.14 15.PARAMETER QuarantineOU16    Distinguished name of the OU that staged accounts are moved into.17 18.PARAMETER WhatIf19    Dry run. Strongly recommended for the first execution.20 21.EXAMPLE22    .\Invoke-StaleAccountCleanup.ps1 -InactiveDays 120 -WhatIf23 24.NOTES25    Author : AIInfraEngine26    Version: 3.2.027#>28[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]29param(30    [ValidateRange(30, 3650)]31    [int]$InactiveDays = 120,32 33    [Parameter(Mandatory)]34    [string]$QuarantineOU,35 36    [string[]]$ExcludedOUs = @('OU=Service Accounts,DC=corp,DC=local'),37 38    [string[]]$ExcludedAccounts = @('svc-backup', 'brk-glass-01', 'krbtgt'),39 40    [ValidateSet('User', 'Computer', 'Both')]41    [string]$ObjectType = 'Both',42 43    [string]$ReportPath = ".\stale-accounts-$(Get-Date -Format 'yyyyMMdd-HHmmss').csv"44)45 46begin {47    $ErrorActionPreference = 'Stop'48    $cutoff  = (Get-Date).AddDays(-$InactiveDays)49    $results = [System.Collections.Generic.List[object]]::new()50 51    Write-Verbose "Cutoff date: $cutoff"52 53    if (-not (Get-ADOrganizationalUnit -Identity $QuarantineOU -ErrorAction SilentlyContinue)) {54        throw "Quarantine OU '$QuarantineOU' does not exist. Create it before running."55    }56}57 58process {59    $targets = @()60 61    if ($ObjectType -in 'User', 'Both') {62        $targets += Get-ADUser -Filter {63            Enabled -eq $true -and LastLogonTimestamp -lt $cutoff64        } -Properties LastLogonTimestamp, Description, DistinguishedName, whenCreated |65            Select-Object *, @{ n = 'ObjectClass'; e = { 'user' } }66    }67 68    if ($ObjectType -in 'Computer', 'Both') {69        $targets += Get-ADComputer -Filter {70            Enabled -eq $true -and LastLogonTimestamp -lt $cutoff71        } -Properties LastLogonTimestamp, Description, DistinguishedName, whenCreated, OperatingSystem |72            Select-Object *, @{ n = 'ObjectClass'; e = { 'computer' } }73    }74 75    Write-Verbose "Found $($targets.Count) candidate object(s) before exclusions."76 77    foreach ($obj in $targets) {78 79        # --- Exclusions -------------------------------------------------80        if ($ExcludedAccounts -contains $obj.SamAccountName.TrimEnd('$')) {81            Write-Verbose "Skipping $($obj.SamAccountName): on the account allow-list."82            continue83        }84        if ($ExcludedOUs | Where-Object { $obj.DistinguishedName -like "*$_" }) {85            Write-Verbose "Skipping $($obj.SamAccountName): protected OU."86            continue87        }88 89        # Guard against freshly-created objects that have never logged on90        if ($obj.whenCreated -gt $cutoff) {91            Write-Verbose "Skipping $($obj.SamAccountName): created after the cutoff."92            continue93        }94 95        $lastLogon = if ($obj.LastLogonTimestamp) {96            [DateTime]::FromFileTime($obj.LastLogonTimestamp)97        } else {98            $obj.whenCreated99        }100 101        $stamp = "Staged by AIInfraEngine $(Get-Date -Format 'yyyy-MM-dd'); last logon $($lastLogon.ToString('yyyy-MM-dd'))"102 103        if ($PSCmdlet.ShouldProcess($obj.DistinguishedName, 'Disable and move to quarantine')) {104            try {105                Set-ADObject -Identity $obj.DistinguishedName -Description $stamp106                Disable-ADAccount -Identity $obj.DistinguishedName107                Move-ADObject   -Identity $obj.DistinguishedName -TargetPath $QuarantineOU108                $status = 'Staged'109            }110            catch {111                Write-Warning "Failed on $($obj.SamAccountName): $($_.Exception.Message)"112                $status = "Error: $($_.Exception.Message)"113            }114        }115        else {116            $status = 'WhatIf'117        }118 119        $results.Add([pscustomobject]@{120            SamAccountName = $obj.SamAccountName121            ObjectClass    = $obj.ObjectClass122            LastLogon      = $lastLogon123            DaysInactive   = [math]::Round(((Get-Date) - $lastLogon).TotalDays)124            OriginalOU     = ($obj.DistinguishedName -split ',', 2)[1]125            Status         = $status126        })127    }128}129 130end {131    $results | Sort-Object DaysInactive -Descending | Export-Csv -Path $ReportPath -NoTypeInformation132 133    Write-Host ""134    Write-Host "  Candidates : $($results.Count)"      -ForegroundColor Cyan135    Write-Host "  Staged     : $(($results | Where-Object Status -eq 'Staged').Count)" -ForegroundColor Green136    Write-Host "  Errors     : $(($results | Where-Object Status -like 'Error*').Count)" -ForegroundColor Red137    Write-Host "  Report     : $ReportPath" -ForegroundColor Cyan138    Write-Host ""139}