PowerShell Module for Working With AD SID History

Merry ChristmasThis weekend I'll be celebrating Christmas in the US.  Today Santa brought me a 1500VA 865W UPS for my home lab server.  Now I don't have to worry about those winter power hiccups rebooting all of my HyperV guests.  Best of all the scripting elves will be able to write presents without interruption.

So in PowerShell style here's a little Christmas gift for you.

Introduction

This post is the fifth in the "SID Walker, Texas Ranger" series on SID history remediation with PowerShell.  Today we're wrapping up with a handy summary of each post in the series. We will also take the function library we've been using and upgrade it to a PowerShell module. Then we'll walk through the entire SID history remediation process using the provided cmdlets in this module.

The Story So Far

Those of you who follow my blog know that I have been stuck on this theme of SID history for several months now.  Why?  Because I see this quite frequently with customers, and I want to offer some practical guidance on dealing with it.  Here is a summary of the blog series that brought us to today's module:

  1. Using PowerShell to resolve Token Size issues caused by SID history
    Prior to starting the module development this post explained the background of token size issues as related to SID history.  I provided the basic SID history query that we use to produce the report and some great links for more information on token size.
  2. Do Over: SID History One-Liner
    As a follow up to the Token Size post I re-wrote the SID history report query as a one-liner.
  3. PowerShell: SID Walker, Texas Ranger (Part 1)
    This time we looked at Get-ACL and parsing SDDL strings, a warm up for the next post.
  4. PowerShell: SID Walker, Texas Ranger (Part 2)
    Next I wrote a function to swap SID history entries in ACLs/ACEs.  This compensates for a gap in the ADMT, because it cannot migrate SID history for file shares hosted on a NAS.
  5. PowerShell: SID Walker, Texas Ranger (Part 3): Exporting Domain SIDs and Trusts
    Looking at raw SIDs in a report is not very friendly, so I wrote a function that translates domain SIDs into domain names.  This makes the SID history report more meaningful when you can see the name of the domain from whence they came.  Enumerating all forest trusts and their domain SIDs required using some .NET ninja skills.
  6. How To Remove SID History With PowerShell
    To round out the functions I provided Get-SIDHistory and Remove-SIDHistory, emphasizing that this is the LAST step in the process.  I leveraged the previous domain SID function to even give us the ability to remove SID history selectively by old domain name.

I suggest that you go back and read all of the articles linked above. They will give you much more insight into the SID history cleanup process and the nuances of the provided functions. Then skim through the ADMT Guide to get familiar with the big picture.

All of these functions are now wrapped up in the module provided in today's blog post.

Installing the Module

If you've never installed a module there really isn't much to it.  Here's what you do:

  1. Create the module folder (adjust Documents path if necessary):
    New-Item -Type Directory -path "$home\Documents\WindowsPowerShell\Modules\SIDHistory"
  2. Download the attached ZIP file at the bottom of this article.
  3. Unzip the contents into this path:
    C:\Users\<username>\Documents\WindowsPowerShell\Modules\SIDHistory\
  4. Fire up the PowerShell console or ISE.
  5. Import-Module ActiveDirectory (This is a prerequisite.)
  6. Import-Module SIDHistory

Now you can use Get-Command and Get-Help to unwrap the present and see what's inside:

image

  • Get-Command -Module SIDHistory
  • Get-Help Get-SIDHistory -Full
  • Get-Help Get-SIDHistory -Online
  • Get-Command -Module SIDHistory | Get-Help -Full | More

You can use Get-Help -Full for each of the included functions to find syntax and descriptions.

Using the Module

The outline below will guide you through the process of using the functions to help remediate SID history.  Run them in this order.

  • Start up:
    • Import-Module ActiveDirectory
    • Import-Module SIDHistory
  • Get the SID history report:
    • Export-DomainSIDs
    • Export-SIDMapping
    • Update-SIDMapping
    • Open the SIDReportUpdated.csv file in Excel to see all of the SID history in your environment.
    • Keep an archive copy of these output files for documentation at the end of the project.
  • Use the ADMT for server migration:
    • Use the SIDMap.csv file with the ADMT to migrate servers with SID history.  This file recovers your OldSID/NewSID data from former migrations so that you can finish security translation on servers.
  • NAS permission migration:
    • If you have NAS-based file shares, migrate SID history of NTFS shares this way:
    • Run with -WhatIf the first time to see if there is any SID history to translate.
    • Convert-SIDHistoryNTFS \\server\share\path –WhatIf
    • Review the report files.  Run again without -WhatIf to actually update the ACLs.
    • Convert-SIDHistoryNTFS \\server\share\path
    • Review the report files.
    • Confirm share file access with affected users and groups.
  • Remove the SID history:
    • Confirm that you have good backups of Active Directory system state on two DCs in every domain.  You should always have a backout plan in case you missed some SID history remediation.
    • Once SID history remediation is verified on all servers you can begin removing SID history in phases.  First, use Get-SIDHistory to target the removal population with a specific query.  Second, pipe the output to Remove-SIDHistory.  Here are some examples:
    • Get-SIDHistory –MemberOf AccountingDept
    • Get-SIDHistory –MemberOf AccountingDept | Remove-SIDHistory
    • Get-SIDHistory –DomainName alpineskihouse.com
    • Get-SIDHistory –DomainName alpineskihouse.com | Remove-SIDHistory
    • See the help for extensive filtering capabilities of Get-SIDHistory.
  • Check your work:
    • Make an archive copy of your first SIDReportUpdated.csv and SIDMap.csv files.
    • Export-SIDMapping
    • Use the SIDReport.csv file as an audit to see where SID history remains.
    • Repeat the migration and removal processes until this report comes back empty.
  • Remediation (ie. Damage Control):
    • Assuming that your security translation was thorough then you should not see any issues.
    • If the help desk only gets a couple calls:
      • Manually clean up the permissions on a case-by-case basis.
    • If the help desk gets hammered with calls, then you have a couple options:
      • Identify the scope of impact and remediate those servers by doing more security translation.  You may have missed a few.
      • Do an AD authoritative restore to recover the SID history of impacted users.

The functions provided in this module will give you added visibility into the status of your SID history throughout the process and an easy way to target removal in the final phase.

Conclusion

This SID history project has been a lot of fun, and I'm sure there's more we could do with it.  I have a few ideas of my own, but I would like to hear your feedback.  What challenges have you encountered with SID history remediation?  Where do you think PowerShell could help?  Leave a comment below and let me know.

Additional Reading

SIDHistory.zip