en-US/about_OrphanedSid.help.txt
|
TOPIC
about_OrphanedSid SHORT DESCRIPTION Finds, removes and restores orphaned SIDs in Active Directory access control lists. LONG DESCRIPTION An orphaned SID is an access control entry whose trustee no longer exists. When a user, group or computer is deleted, every ACL that named it keeps the entry, now showing only the raw security identifier. The entries grant nothing to anyone, but they clutter security reviews, hide real delegations, and are the first thing an auditor asks about. The module has three commands: Find-OrphanedSid Walks the objects under one or more search bases, reads each security descriptor, resolves every identity reference and writes one OrphanedSIDResult per entry that cannot be resolved. Nothing is changed. Remove-OrphanedSid Runs the same discovery, validates each SID against the protected and well-known lists, writes a Clixml backup of the object's ACL into a timestamped folder, and removes the orphaned entries. ConfirmImpact is High: it prompts once, -WhatIf previews, and an unattended run needs -Force. Restore-OrphanedSidBackup Applies the backed-up ACL of an object, or of every object under an OU or domain, from a backup folder, after validating the file's format, DN and SHA256 hash. Also ConfirmImpact High. HOW RESULTS ARE REPORTED Each command writes its results to the pipeline as objects. -OutputPath additionally writes a CSV: the discovered entries for Find-OrphanedSid and Remove-OrphanedSid, the restore results for Restore-OrphanedSidBackup. A summary goes to the console and to the log file. UNVERIFIED SIDS A SID is reported orphaned only when every directory lookup completed and none found it, or when it is found among deleted objects. When no lookup found the SID but at least one failed for another reason, such as a timeout, access denied or an unreachable domain controller, the SID may still belong to a live principal. Find-OrphanedSid lists it with VerificationStatus Unverified and a VerificationError naming each failed lookup, and any lookup skipped because the directory server could not be contacted. Remove-OrphanedSid never removes it, and logs a warning naming it. Unverified results are not cached, so the next lookup tries again. A SID from a trusted domain can only be checked by that domain. When it answers that the principal is gone, the SID is orphaned (LikelySource Foreign Domain/Trust). When its domain controllers cannot be reached or the trust is broken, the SID is unverified, and each such lookup waits for the trust to time out. Missing read permission does not make a SID unverified: Active Directory returns an empty search, not an error. Run the commands as an account that can read every object in scope. Logs go to -LogPath when it is given, otherwise to the LogFilePath of the -ConfigPath file, otherwise to .\Logs\<Command>_<yyyyMMdd_HHmmss>.log under the current directory. The whole run goes to that one file. An existing log file is appended to, and renamed aside first when it is larger than MaxLogFileSizeMB (default 10). Every line carries the run's correlation ID, so one run can be pulled out of a shared log with Select-String. Pass -CorrelationId to tie a run to a change record. -LogLevel sets the lowest level written to the file; security events are written at every level. Without -LogLevel the level is Verbose under -Verbose, Debug under -Debug, and otherwise the LogLevel of the -ConfigPath file, or Information. BACKUPS Remove-OrphanedSid writes one backup file per modified object into <BackupPath>\<yyyyMMdd_HHmmss>\, default .\Backup under the current directory. The file is Clixml holding the object DN, the SDDL, a SHA256 hash of the SDDL, the correlation ID and the user and computer that made the change. Restore-OrphanedSidBackup reads these files; nothing else does. PROTECTED SIDS SIDs in the ProtectedSIDs list (the BUILTIN Administrators, Users and Guests groups, SYSTEM, LOCAL SERVICE and NETWORK SERVICE) and SIDs matching WellKnownSIDPatterns are never reported as orphaned and never removed. Either list can be replaced through a JSON file passed as -ConfigPath. A list in the file replaces the default list in full; nothing is merged, so a file that adds a SID must repeat the defaults it keeps. The built-in well-known check cannot be changed by a file: BUILTIN groups (S-1-5-32-*), the universal and NT Authority SIDs, service SIDs, and the Domain, Schema and Enterprise Admins groups of any domain are never reported as orphaned whatever the file says. CONFIGURATION FILE -ConfigPath accepts a JSON file. Only these top-level keys are read; anything else is ignored: WellKnownSIDPatterns, ProtectedSIDs, BatchSize (results per streaming batch file, default 50), MemoryCheckInterval (default 50), LogLevel, LogFilePath, EnableLogFileRotation, MaxLogFileSizeMB. REQUIREMENTS Windows PowerShell 5.1 or PowerShell 7 on Windows, and the RSAT ActiveDirectory module. Discovery needs read access to the objects under -SearchBase; removal and restore need write access to their security descriptors. The commands run as the caller; there is no -Credential parameter. EXAMPLES Find-OrphanedSid -SearchBase 'OU=Users,DC=contoso,DC=com' Remove-OrphanedSid -SearchBase 'OU=Decommissioned,DC=contoso,DC=com' -WhatIf Remove-OrphanedSid -SearchBase 'OU=Decommissioned,DC=contoso,DC=com' -Force -BackupPath 'D:\ADBackups' Restore-OrphanedSidBackup -TargetObjectDN 'OU=Decommissioned,DC=contoso,DC=com' -BackupPath 'D:\ADBackups\20260703_104232' -Force SEE ALSO Find-OrphanedSid Remove-OrphanedSid Restore-OrphanedSidBackup https://github.com/fadwen/OrphanedSid |