The Security and Compliance Center (SCC) and PowerShell
Beginning with Exchange Server 2007, Microsoft introduced PowerShell to enhance the Exchange Server product. PowerShell was a radical change at the time when Microsoft was known for its GUI interfaces. Yes, Microsoft had some command line access to its OS’s (think DOS), but by adding a command line interface, Microsoft had suddenly put the gauntlet down and announced to the world that it was serious about it products and providing an enhancement that would appeal to those who would look down on Microsoft because of the GUI-based approach.
While Exchange Server 2007 ran what was then known as PowerShell 1.0, and while it was a good addition to existing Exchange Server management it was not perfect. It was not as flexible as it is today and was sorely in need of enhancement. Over the years Microsoft has produced PowerShell versions 1.0 to the current 6.1. There are PowerShell modules for Active Directory, Exchange and SharePoint. Now with the age of cloud systems like Office 365 there are PowerShell modules for Exchange Online, Teams, Azure AD and also the focus of this book the Security and Compliance Center (SCC).
Over time Microsoft has increased the functionality of these various modules. With the Security and Compliance Center in particular, additional components have been added with their respective PowerShell cmdlets like Labels and Fingerprints. Expect these cmdlets to keep changing as Microsoft continues to add additional functionality.
Why PowerShell and Not the Security and Compliance Center
There are many reasons to use PowerShell to manage and manipulate the Security and Compliance Center. Some of the reasons are obvious while others may require some explanation. Below is a list of reasons of why you should learn about PowerShell in the SCC:
- PowerShell allows the use of standard Windows commands that you would run in the Command Prompt.
- PowerShell brings powerful commands to the table to enable you to work with a complex environment.
- PowerShell is integrated with almost all of Microsoft’s on-premises and cloud applications and third-party vendors are creating modules for PowerShell to manage their products.
- PowerShell allows for heavy automation. While this would seem to be geared to larger environments, smaller shops can utilize scheduling for common tasks – reporting, maintenance, bulk maintenance, etc. – to reduce the time needed and human errors in managing their Office 365 Tenants.
- Some things just cannot be done in the GUI. This is important. This is not advertised or spelled out by Microsoft. There are many options or configurations that can ONLY be performed with PowerShell. To make this clear, PowerShell is not limited in its management of Exchange as the GUI is. So it is important to learn it when learning about the Security and Compliance Center.
- PowerShell works with objects. These objects can enable you to do powerful tasks in the SCC.
- PowerShell can get a task done in fewer lines than say VBScript. Some will find this to be an advantage as it can take less time to accomplish a task by writing it in PowerShell.
- PowerShell works with many technologies – XML, WMI, CIM, .NET, COM and Active Directory. The last one is important as you will see later, we can tie scripts together between multiple modules if necessary.
- PowerShell provides a powerful help and search function. When working with new PowerShell command, Get-Help is extremely useful as it can provide working examples of code. Searching for commands is easy as well and if you know what you want to manipulate (e.g. policies), just searching for commands with a keyword of ‘policy’ can help direct your Get-Help query to find the relevant command.
Security and Compliance Center PowerShell
Simply put, the SCC Shell is the original Windows PowerShell with a module loaded specifically with SCC-oriented cmdlets.
Cmdlet (definition) - is a single PowerShell command like Get-Label. Pronunciation: ‘commandlet’.
Module (definition) - is a collection of additional PowerShell cmdlets that are grouped together for one purpose or function. Example modules are SCC, Exchange Online and Teams. There are many more, but these examples are relevant to this book.
PowerShell cmdlets come in two basic groupings - safe exploratory cmdlets (ones starting with ‘GET’ for example) and others that can configure or modify the SCC configuration (SET, REMOVE, etc.) which are not as safe and can be dangerous to a production SCC environment).
Anatomy of a PowerShell Cmdlet:
Verb - The action part of the cmdlet. Whether this is Get, Remove, List, Set or Add and more that are less common. These words are the first word of the cmdlet and to the left of the dash of the cmdlet name.
Noun - The word or words to the right of the dash of the PowerShell cmdlet name. These words help describe what is being affected in he Security and Compliance Center. Examples include - ComplianceTag, DLPComplianceRule, RoleGroup and more.
Parameter(s) - These are the options which are selected and upon which the PowerShell cmdlet will act. To get an idea of what parameters are present for each cmdlet you will need to do run a Get-Help <cmdlet> -full. We will review that later in this chapter.
Switch - Options that can be toggled for a cmdlet that don’t need additional information (-WhatIf for example).
Add-RoleGroupMember
Adds a user in Azure AD to one of the many role groups in the SCC.
Get-HoldComplianceRule
Lists all of the Hold Compliance Rules in the SCC.
When exploring PowerShell for the SCC for the first time, it is advisable to start with the Get cmdlets as these cmdlets will provide the beginner to PowerShell the following items:
- A view into Compliance Cases that exists
- List role holders in the SCC
- Non-destructive PowerShell practice
- A means to generating reports or the SCC
Get cmdlets are benign in the sense that the current environment is not being changed or re-configured. This provides for safe learning or exploration not only for PowerShell but your SCC configuration as well. It is highly recommended that you review some basic cmdlets like the following as a good starting point for your venture into SCC PowerShell:
Get-AuditConfig Get-DevicePolicy Get-DLPKeywordDictionary
Get-CaseGoldRule Get-RoleGroup Get-Group
Get-Label Get-ActivityAlert Get-ManagementRole
** Note ** We can list all Get cmdlets with one command ‘Get-Command Get-*’
Single cmdlets are the core part of PowerShell. However you can combine the results gathered by one cmdlet and feed this to another cmdlet in PowerShell which then processes results from the previous cmdlet. This process is known as piping. By combining two cmdlets together like this we now have a very powerful tool to construct one-liners. Caution should be used as not all cmdlets can be piped into another or vice versa.
One-liner (definition) – In PowerShell a one-liner literally is either a single command that performs a function or it is comprised of a set of cmdlets that are paired together with a pipe symbol ‘|’.
For an example of piping we are passing information from Get-Label to Remove-Label to remove all existing labels. If we did not use the pipelining feature, you would have to perform the Remove-Label for each label instead of using the pipeline method, which will run this for all labels in one cmdlet. The pipe allows us to do that in bulk, which saves time and produces a single table of results.
Get-Label | Remove-Label
** Note ** Some cmdlets may return too many results and are often restricted to a set limit. A way around this limit is to use ‘-ResultSize’ and specifying a larger number, like 2,000, or using ‘Unlimited’ which will provide as many results it can find without restrictions.
Sample output:
An alternative to piping would require quite a bit more effort, and some techniques we have not covered yet. The code would involve basically gathering all the labels and storing their identities in a variable and the reading through the variable and running Get-Label for each label stored in that variable:
$Labels = Get-Label
Foreach ($Label in $Labels) {
Remove-Label -Name $_.Name
}
The results are the same, while the complexity has gone up substantially. Some combined cmdlets can save server resources in terms of CPU and memory usage. As these cmdlets are run in the cloud on Microsoft’s own servers, if we were to run too many cmdlets or cmdlets that involve large amounts of users, throttling is introduced in an effort to control resources on Microsoft’s side:
Protecting Yourself and What If
PowerShell is powerful. PowerShell can thus cause some havoc in your Security and Compliance Center. How can you protect your infrastructure from your missteps?
- Run Get cmdlets first to get a general familiarity of PowerShell in the SCC
- Use the WhatIf switch when running cmdlets: this will show what would have occurred if a cmdlet was run.
An example of the WhatIf switch would be what would happen if you were to get Compliance Cases in the and remove the Compliance Cases:
Get-ComplianceCase | Remove-ComplianceCase -WhatIf
Whatif: Deleting the compliance case “Hold for some mailboxes” will also remove all searches and search actions associated with this case. Do you want to continue?
Whatif: Deleting the compliance case “Case # 4302-1” will also remove all searches and search actions associated with this case. Do you want to continue?
Notice the WhatIf statement in front of each result. If this command was run in production, all cases would be deleted. However, because we ran the same command with the WhatIf switch only a simulation was run, no Compliance Cases were removed.
A certain amount of discovery involves understanding the SCC. With this knowledge, finding commands that are necessary to perform actions becomes easier. For example querying role permissions to look for rogue administrators in the SCC. Circling back to labels. We need to manipulate some information or create a report on labels in our Security and Compliance Center. If you don’t know what commands that can be run, we rely on a specific cmdlet called ‘Get-Command’. With this we can find cmdlets we need:
Get-Command *label*
Running this will look for any PowerShell cmdlet that has the word ‘label’ in it. The wildcard ‘*’ that is located in front and behind the word ‘label’ just means that we are searching for any command that may or may not have additional letters before or after the word ‘‘label’. A small portion of the results are listed below:
Now, let’s say we actually need to look at Sensitive Information Types in the environment:
Get-Command *SensitiveInfo*
As you can see, the Get-Command is useful for finding cmdlets in PowerShell that you can use in the SCC. We can also start with a noun, like Get and use the wildcard to discover all Get cmdlets in a module:
Get-Command Get-*
Small sample:
PowerShell Modules
When working with the SCC and because of its dependency on Azure Active Directory we may need other cmdlets in order to perform certain actions. When working in the default SCC Shell, PowerShell cmdlets for Azure Active Directory are not preloaded. In order to load these cmdlets, we may need to install the module. With PowerShell 5.0 we can download modules of all sorts using the ‘Install-Module’ cmdlet like so:
Install-Module -Name AzureAD
** Note ** If this is the first time the Install-Module cmdlet has been run, you may receive a message about a ‘NuGet Provider’. This provider is what allows the interaction between PowerShell and the NuGet repository where the modules are stored. Make sure to answer yes as to whether to install it.
Once the NuGet module has installed, we can now install the AzureAD module via the NuGet provider:
** Note ** As we can see from the above screenshot, this repository is initially untrusted by default. This is to be expected. We can set this repository as a trusted repository with this one-liner:
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
Once the module is installed we can now connect to AzureAD to work with this part of an Office 365 tenant:
Connect-AzureAD
After the PowerShell module has loaded, additional cmdlets are available.
Along with Get-Command, Get-Help will assist you in exploring PowerShell for the SCC.
When faced with running a new cmdlet in PowerShell or just figuring out what other options are available for a PowerShell cmdlet, the Get-Help and Get-Command cmdlets are extremely helpful. If you’ve used Linux or Unix they are like the man pages of old where a description of what the command can do, where it can be run, various examples of how the command can be used and more. When using the Get-Help and Get-Command, just like other PowerShell commands, there are switches that you can use to help enhance the basic cmdlet. For example, take this cmdlet:
Get-Help New-RetentionCompliancePolicy
The above command returns some information on the New-RetentionCompliancePolicy cmdlet:
Notice the main sections: Name, Synopsis, Syntax, Description, Related Links and Remarks. The command we ran provided us with a nice summary of what this command can do and the Related Link section points you to the online documentation for this cmdlet. However, what is missing is the switches or options that are available for the cmdlet as well as some examples on how to use the cmdlet as well. To get these, run the following:
Get-Help Get-RetentionPolicy -Full
The same first section appear: Name, Synopsis, Syntax and Description. However, a few additional sections appear now - Parameters:
When you work with a command that you are unfamiliar with, it would be advisable to start with the -Full switch to get all information on the cmdlet as well as some examples on how to use the command. The major weakness of the help command as well as the Online help is that some commands are very complex and have so many options that they don’t feel as complete as they might. This means that even after finding the right parameters, it may take some time to get the right results. If you find yourself in this situation, you can turn to your favorite Internet search engine to find the right syntax OR possibly get a close enough example that a bit of tweaking will make the cmdlet run the way you expect.
Inputs, Outputs and Examples:
Cloud-Only vs Synced Environments
For anyone who manages Office 365, knowing what PowerShell cmdlets will work with their environment is a crucial piece of information. In that spirit we want to make sure that these differences are clearly delineated in the rest of the book and when we are working with PowerShell. The important thing to remember is that if your accounts and other objects are not synced to the cloud you will need to make your changes in Office 365 directly and not to anything on-premises like Active Directory. This is simply because Office 365 is in this scenario your source of truth and it is the master copy of these objects. If, however, you have Active Directory and you are syncing these objects to the cloud your on-premises Active Directory is the source of truth or Start of Authority. Those synced objects need to be changed in your on-premises Active Directory, to be more precise those synced attributes are actual only read-only in the cloud.
Non-Synced Accounts (Cloud-Only)
For those who do not want any infrastructure for their email services, this is a common setup. In this configuration, all your objects exist in Office 365 only. All management tools and scripts will run against these cloud-only objects. The Admin Console for your tenant should show all of these objects as ‘cloud-only’ and this only manageable from Office 365’s connections.
Synced Accounts
It is common, but not entirely true of all of these environments, that a synced environment will have AD on-premises as a source of authority for all user and group objects in Office 365.
What’s Next?
In this introduction we have just scratched the surface of what is available in PowerShell for the Security and Compliance Center. Let’s go ahead and get in deep with PowerShell in Chapter 1.