Private/Start-UserAccountDisruption.ps1

<#
.SYNOPSIS
Disables AD users, resets their passwords, or performs both operations.
 
.DESCRIPTION
Selects enabled users for Disable and all users in the search base for other actions.
Runs LDAP DirectoryEntry operations in parallel to disable accounts, reset passwords, or perform both.
Excludes the current backdoor user in $global:BDUser and the configured break-glass account from all actions.
Refuses to proceed when the configured break-glass account cannot be resolved.
Each successful change writes TickValue to adminDescription. A missing NewPassword is replaced with a random password.
Displays progress, DC CPU and LDAP timing when available, and per-user success or error messages.
Q can stop processing. An unset break-glass account setting does not add a break-glass exclusion.
 
.PARAMETER SearchBase
Distinguished name of the OU or domain subtree containing the target users.
 
.PARAMETER Server
AD server used for user enumeration and LDAP changes; also queried for progress metrics.
 
.PARAMETER NewPassword
Plain-text replacement password for PwReset or Both. A random password is generated when omitted or blank.
 
.PARAMETER Action
Operation to perform: Disable, PwReset, or Both, matched without case sensitivity. Other values do not change accounts.
 
.PARAMETER TickValue
Value written to adminDescription after a successful change. Defaults to the current time as yyyy-MM-dd HH:mm:ss.
 
.PARAMETER ThrottleLimit
Maximum concurrent account-processing operations, from 1 through 100. Defaults to 5.
 
.EXAMPLE
Start-UserAccountDisruption -SearchBase "OU=Demo Accounts,OU=AS2Go,DC=example,DC=com" -Server "DC01.example.com" -Action Disable
Disables enabled users in the selected demo-account OU and marks successful changes.
 
.INPUTS
None. This function does not declare pipeline input.
 
.OUTPUTS
Console messages and output from invoked commands; no dedicated result object is defined.
 
.NOTES
Private AS2Go function. Run from an initialized AS2Go module session.
Requires permission to change the target users. The configured break-glass account is resolved from its distinguished name and excluded.
 
.COMPONENT
Category: Sub Function
 
.FUNCTIONALITY
Disables users, resets passwords, or both in the specified AD search base, excluding the current backdoor and configured break-glass accounts.
Marks changed accounts in adminDescription and reports results, progress, and available DC metrics.
#>

function Start-UserAccountDisruption {

    ################################################################################
    ###### #####
    ###### Bulk-manipulate AD users in parallel: #####
    ###### 1. Reset password #####
    ###### 2. Disable account #####
    ###### 3. Write tick value to adminDescription #####
    ###### #####
    ################################################################################

    param(
        [Parameter(Mandatory)]
        [string]$SearchBase,
        [Parameter(Mandatory)]
        [string]$Server,
        [string]$NewPassword,           # auto-generated if omitted
        [string]$Action,
        [string]$TickValue = (Get-Date -Format "yyyy-MM-dd HH:mm:ss"),
        [ValidateRange(1, 100)]
        [int]$ThrottleLimit = 5
    )

    $Info = Measure-FunctionRuntime -Begin

    $protectedBackdoorUser = [string]$global:BDUser
    if ([string]::IsNullOrWhiteSpace($protectedBackdoorUser)) {
        Write-AS2GoOutput -Type Warning -Message "Backdoor user is not configured; refusing to manipulate users."
        #Measure-FunctionRuntime -End -Details $Info
        #return
    }

    $protectedUserNames = @($protectedBackdoorUser | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
    $breakGlassDN = [string](Get-ASConfig -Setting "BreakGlassAccount")
    
    if (-not [string]::IsNullOrWhiteSpace($breakGlassDN)) {
        $breakGlassAccount = Get-ADUserDetails -SearchByDN -Identifier $breakGlassDN
        if ([string]::IsNullOrWhiteSpace($breakGlassAccount.SamAccountName) -or $breakGlassAccount.SamAccountName -eq "Account Not Found") {
            Write-AS2GoOutput -Type Warning -Message "Configured break-glass account could not be resolved; refusing to manipulate users."
            Measure-FunctionRuntime -End -Details $Info
            return
        }
        $protectedUserNames += $breakGlassAccount.SamAccountName
    }

    # Write-AS2GoOutput -Type Header -Message "Start-UserAccountDisruption"
    # Write-AS2GoOutput -Type H1 -Message $((Get-Help (Get-FunctionName)).Functionality)
    # Show-CurrentPhase -Phase "https://cymulate.com/cybersecurity-glossary"

    # Auto-generate password if none given
    if ([string]::IsNullOrWhiteSpace($NewPassword)) {
        $NewPassword = Get-RandomPassword
    }

    if ($Action -match "^Disable$") {
        $users = Get-ADUser `
            -Filter "Enabled -eq 'True'" `
            -SearchBase $SearchBase `
            -Server $Server `
            -Properties SamAccountName, SID

    }
    else {
        $users = Get-ADUser `
            -Filter "*" `
            -SearchBase $SearchBase `
            -Server $Server `
            -Properties SamAccountName, SID

    }

    $users = @($users | Where-Object { $_.SamAccountName -notin $protectedUserNames })

    $total = @($users).Count
    if ($total -eq 0) {
        Write-AS2GoOutput -Type Warning -Message "No eligible users found under $SearchBase"
        return
    }

    $cname = Convert-FromDNToCN -DistinguishedName $SearchBase
    Write-AS2GoOutput -Type Quit -Message "Press 'Q' at any time to abort User Manipulation`n for '$total' users under '$cname'!`n Password: '$NewPassword' | Tick: '$TickValue'"

    $startTime = Get-Date

    # ---- PARALLEL WORKER ----
    # Uses DirectoryServices.DirectoryEntry (raw LDAP on port 389) instead of the AD module.
    # This completely avoids ADWS and its connection pool limit — the root cause of
    # the "transient condition" error under parallel load.
    $manipulateWorker = {

        $dn = $_.DistinguishedName
        $sid = $_.SID.Value
        $sam = $_.SamAccountName
        $srv = $using:Server
        $pw = $using:NewPassword
        $tick = $using:TickValue
        $Manipulation = $using:Action

        $errors = [System.Collections.Generic.List[string]]::new()

        try {
            $entry = New-Object System.DirectoryServices.DirectoryEntry "LDAP://$srv/$dn"

            # 1. Reset password via LDAP SetPassword
            If ($Manipulation -match "^PwReset$|^Both$") {
            
                try {
                    $entry.Invoke("SetPassword", $pw)
                    $entry.Properties["adminDescription"].Value = $tick
                    $entry.CommitChanges()
                }
                catch { 
                    $errors.Add("PwReset: $($_.Exception.InnerException.Message ?? $_.Exception.Message)") 
                }
            }

            # 2+3. Disable account + write tick in a single LDAP roundtrip
            If ($Manipulation -match "^Disable$|^Both$") {
                try {
                    $uac = [int]$entry.Properties["userAccountControl"].Value
                    $entry.Properties["userAccountControl"].Value = $uac -bor 2
                    $entry.Properties["adminDescription"].Value = $tick
                    $entry.CommitChanges()
                }
                catch { 
                    $errors.Add("Disable+AdminDesc: $($_.Exception.InnerException.Message ?? $_.Exception.Message)") 
                }
            }
            $entry.Dispose()
        }
        catch {
            $errors.Add("LDAPConnect: $($_.Exception.Message)")
        }

        [PSCustomObject]@{
            User    = "$sam ($sid)"
            Success = ($errors.Count -eq 0)
            Errors  = ($errors -join " | ")
        }
    }

    # ---- PARALLEL JOB ----
    $job = $users | ForEach-Object -Parallel $manipulateWorker -ThrottleLimit $ThrottleLimit -AsJob

    $allResults = [System.Collections.Generic.List[object]]::new()
    $processed = 0
    $metricsRefreshEverySeconds = 3
    $lastMetricsTime = [DateTime]::MinValue   # force immediate first poll
    $lastValidCpu = $null
    $metricsJob = $null
    $progressTick = 0
    $pulseChars = @('|', '/', '-', '\\')
    $metrics = [PSCustomObject]@{ CPU = 'n/a'; LDAP = 'n/a' }

    # Metrics worker runs as background job — never blocks the monitor loop
    $metricsWorker = {
        param($srv)
        $cpu = 'n/a'
        try {
            $c = (Get-Counter -ComputerName $srv '\Processor(_Total)\% Processor Time' -MaxSamples 1 -ErrorAction Stop).CounterSamples[0].CookedValue
            $cpu = [math]::Round($c, 1)
        }
        catch {
            try {
                $s = Get-CimInstance -ClassName Win32_Processor -ComputerName $srv -OperationTimeoutSec 3 -ErrorAction Stop |
                Select-Object -ExpandProperty LoadPercentage
                if ($s) { $cpu = [math]::Round(($s | Measure-Object -Average).Average, 1) }
            }
            catch {}
        }
        $lat = 'n/a'
        try {
            $sw = [System.Diagnostics.Stopwatch]::StartNew()
            $d = New-Object System.DirectoryServices.DirectoryEntry("LDAP://$srv/RootDSE")
            $null = $d.Properties["defaultNamingContext"].Value
            $sw.Stop()
            $lat = $sw.ElapsedMilliseconds
        }
        catch {}
        [pscustomobject]@{ CPU = $cpu; LDAP = $lat }
    }

    # ---- MONITOR LOOP ----
    while ($job.State -eq "Running") {

        if ([Console]::KeyAvailable) {
            if ([Console]::ReadKey($true).Key -eq 'Q') {
                Stop-Job $job
                break
            }
        }

        $newResults = Receive-Job $job
        if ($null -ne $newResults) {
            foreach ($r in @($newResults)) { $allResults.Add($r) }
        }
        $processed = $allResults.Count

        $elapsed = (Get-Date) - $startTime
        $rate = if ($elapsed.TotalSeconds -gt 0) {
            [math]::Round($processed / $elapsed.TotalSeconds, 2)
        }
        else { 0 }

        $eta = if ($rate -gt 0) {
            [math]::Round(($total - $processed) / $rate, 1)
        }
        else { 0 }

        # Non-blocking async metrics
        if ($null -ne $metricsJob) {
            if ($metricsJob.State -ne 'Running') {
                $fresh = Receive-Job $metricsJob
                Remove-Job $metricsJob -Force
                $metricsJob = $null
                if ($null -ne $fresh) {
                    if ($fresh.CPU -is [ValueType]) { $lastValidCpu = $fresh.CPU }
                    $metrics = [PSCustomObject]@{
                        CPU  = if ($null -ne $lastValidCpu) { $lastValidCpu } else { $fresh.CPU }
                        LDAP = $fresh.LDAP
                    }
                }
            }
            elseif (((Get-Date) - $lastMetricsTime).TotalSeconds -gt 5) {
                Stop-Job $metricsJob
                Remove-Job $metricsJob -Force
                $metricsJob = $null
            }
        }
        if (($null -eq $metricsJob) -and (((Get-Date) - $lastMetricsTime).TotalSeconds -ge $metricsRefreshEverySeconds)) {
            $metricsJob = Start-Job -ScriptBlock $metricsWorker -ArgumentList $Server
            $lastMetricsTime = Get-Date
        }

        $pulse = $pulseChars[$progressTick % $pulseChars.Count]
        $progressTick++
        $cpuStatus = if ($metrics.CPU -is [ValueType]) { "$($metrics.CPU)%" } else { $metrics.CPU }
        $ldapStatus = if ($metrics.LDAP -is [ValueType]) { "$($metrics.LDAP)ms" } else { $metrics.LDAP }
        $percent = [math]::Round(($processed / $total) * 100, 2)

        Write-Progress `
            -Activity "Performing User Manipulation (PwReset + Disable + AdminDesc)" `
            -Status "$pulse Done: $processed/$total | $rate ops/s | ETA: $eta s | Throttle: $ThrottleLimit | DC CPU: $cpuStatus | LDAP: $ldapStatus" `
            -PercentComplete $percent

        Start-Sleep -Milliseconds 250
    }

    # Cleanup metrics job
    if ($null -ne $metricsJob) {
        Stop-Job $metricsJob -ErrorAction SilentlyContinue
        Remove-Job $metricsJob -Force -ErrorAction SilentlyContinue
    }

    # Collect remaining results
    $remainingResults = Receive-Job $job
    if ($null -ne $remainingResults) {
        foreach ($r in @($remainingResults)) { $allResults.Add($r) }
    }
    Remove-Job $job -Force
    Write-Progress -Activity "Performing User Manipulation (PwReset + Disable + AdminDesc)" -Completed

    # ---- RESULTS ----
    $succeeded = $allResults | Where-Object { $_.Success -eq $true }
    $failed = $allResults | Where-Object { $_.Success -eq $false }

    if ($succeeded) {
        Write-AS2GoOutput -Type TextMaker -Message "Successfully manipulated user accounts in the selected scope: $cname | " -TM "Total: $($succeeded.Count)"
    }

    #Undo-UserManipulation -TickValue $TickValue -Server $server -SearchBase $SearchBase

    if ($failed) {
        Write-AS2GoOutput -Type Warning -Message "$($failed.Count) user(s) had errors:"
        $failed | ForEach-Object {
            Write-AS2GoOutput -Type Bullet -Message "$($_.User): $($_.Errors)"
        }
    }

    Write-AS2GoOutput -Type Success -Message "Completed user account manipulation for the current scope (see examples above)."
    Write-Log -Message " >> Password used: $NewPassword"
    Write-Log -Message " >> TickValue: $TickValue"
    Measure-FunctionRuntime -End -Details $Info
}