"The Robots Are Coming" or "Litigation Hold Script for O365"

Many of us are in the joyful, big business, world of having an e-Discovery application that applies litigation hold automatically when a case is created, and custodians are entered. From the dark ages of my own past and for those of you that do not have access to that kind of tool for whatever reason, here is a script to apply litigation hold to the O365 client in PowerShell. The savings come in the ability to load a .csv with custodians, apply litigation hold to them, have reporting on all O365 litigation hold fields added to the original .csv.

This was created with the intent of all automation, to relieve us of the mundane, repetitive process work.  We then move on to work that has more value and is, in fact, more engaging. Follow along below, I will describe each section with the assumption that you are not adept at PowerShell. For those you that would like to skip ahead. The full script is available below with examples and basic descriptions of each section embedded.  If you need any assistance getting this working in your environment or have any questions, please DM and I would be happy to help!

The first section is what is going to open a secure channel to your company’s instance of O365 in the cloud. Where it says ‘YourCredentialsHere@domain.com’ enter the email address normally used to log into the O365 Security and Compliance portal. Keep in mind you need the same permissions to use this script as you would in the portal.

When you run the script for the first time you will load the function into PowerShell memory. This means that as long as that PowerShell window remains open, you will be able to use the functions. The functions are the short form of all the code below (I.e. Open-Exo). The function you see here is to open a remote session to the O365 portal. 

               Instead of entering all that gobbledygook below, you will only need to enter “Open-Exo”. This will open a remote session and apply your email address. A box will open, and you will be prompted for your password. For peace of mind, O365 forces the password to be encrypted.

Alright, now we’re connected to the matrix! It’s time for the good stuff. The other functions have already loaded so it’s as simple as entering in the two-word statement that you want to use. Don’t worry, there are more examples in the script itself.

Here we can see if someone is already on litigation hold in case we need a quick check. Enter “See-Lithold <SAMaccountname or UserPrincipalName>”.  The command will display if the field “Litigation Hold Enabled” is true or false. It will also let you know the date it was enabled and who enabled it.

A quick note: SAMaccountname is an Active Directory attribute that is often used as an employee ID and/or for employees to login to their computers. UserPrincipalName is an employee’s email address. They will be referred to affectionately as “SAM” and UPN” further on.

               Our next step is to look at adding litigation hold for a single custodian. Enter “Enable-Lithold <SAM or UPN>”.  This will also display on screen the litigation hold status of the employee.

At long last, we have what we all came here for, the good stuff!. This is where we take a .csv file of custodians a mile long and add litigation hold to all of them…in seconds. Best part, it will also print out the results to the same .csv for documentation and verification! The updated .csv will have the litigation hold enabled field as well as the time it was set and who (you!) set it. 

Enter “Enable-LitCSV”. As simple as that. 

Caveat: Make sure to place your list of custodians at “C:\Powershell\Custodians”. The custodians should be in column A and can either be SAM or UPN.

        If this saves you some time, that's all I ask. I’ve kept the script to the very basics, there is a great deal more functionality available. In fact, I based this on a small portion of the automation script I use for a large portion of my job. Be careful, the robots are coming!