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