PowerShell module for the OMS Search API

In a previous blog post I described a scenario and use case for the Hybrid Runbook Worker for those without an easy way to upload to Azure Automation and leverage on-premises resources. Using the Hybrid Runbook Worker we leveraged the ARMclient to connect to the OMS Search API.

In this blog post we’ll leverage a PowerShell module you can upload to Azure Automation and use directly in your runbooks. The OMS module uses Azure Active Directory for authentication and authorization.

Note: The OMS Search API is not intended to copy over OMS analytics data into another system. It is intended to execute “short” queries with a scoped and limited time and date range

Download the PowerShell modules discussed in this blog post here.

We will do the following in this blog post:

• Import modules into Azure Automation
• Create an Azure Active Directory user
• Create the necessary assets in Azure Automation
• Create a runbook to get an OMS Search API result

Import PowerShell modules in Azure Automation

The following steps use the Azure preview portal.

• Download the two PowerShell modules from here to your computer.
• Navigate to your Azure Automation account and click Assets:

• Click Modules:

• Click Add a Module:

• Select Upload File and browse to the PowerShell modules you downloaded then select AzureActiveDirectory.zip first and click OK.
• This will import the PowerShell module and you will notice the extracting of activities will start after importing.

• Verify the extraction completed successfully.

• Import the second module OperationsManagementSuite.zip the same way you did the first and verify the extraction completed successfully.

Create an Azure Active Directory User

We need to create (or use an existing) Azure Active Delivery (AAD) account because our OMS Search API PowerShell module uses AAD for authentication. Joe Levy describes that process in full here.

Creating the necessary assets

For the two PowerShell modules we’ve imported in the previous steps, we need to make two connection objects. This will make our lives a lot easier in our runbooks. Navigate to Assets and click on Connections:

Click on Add a connection:

Create a new Connection of type AzureActiveDirectory . Since the fields for ClientID and Secret are mandatory (this will be fixed shortly) we need to fill in something here. Our runbook will not leverage these fields which are meant for applications. Fill in N/A for now:

Click on Save and create the second Connection of type OperationsManagementSuite :

Click on Save.

Create our OMS Search API Runbook

In my previous blog post I talked about monitoring a honeypot account. Let’s use the same scenario to create a runbook that checks for a failed honeypot account login on a specific server; this time leveraging our imported PowerShell modules.

• Create a new Runbook.

• For now, create a runbook using PowerShell Workflow.

Our Runbook:

workflow Get-OMSsearchQuery
{
	$Alert = $false
	#Get our Connection Objects
       $OMSConnection = Get-AutomationConnection -Name 'OMSConnection'
	$ADConnection = Get-AutomationConnection -Name 'ADConnection'

	#Create our Token	
	$UserName = $ADConnection.UserName + "@" + $ADConnection.AzureADDomain
	$ADConn = @{"Username"=$Username;"AzureADDomain"=$ADConnection.AzureADDomain;"Password"=$ADConnection.Password;"APPIdURI"=$ADConnection.AppIdURI;}
	$Token = Get-AzureADToken -Connection $ADConn
	
	#Use our OMSConnection object to retrieve our OMS information
	$WorkSpace = $OMSConnection.Workspace
	$SubID = $OMSConnection.SubscriptionID
	$Region = $OMSConnection.Region
	
	#Define our search query
	$Query = 'Type=SecurityEvent EventID=4625 Computer=WHDVM1'
	Write-Output "*** Executing query *** " $Query

	#Get our OMS Search query results for our Honeypot Account
	$Results = Search-OMSWorkspace -Token $Token -Query $Query -Connection $OMSConnection
	#Uncomment the next line if you want to see all results returned
	#$Results
	$Accounts = $Results.TargetUserName
	
	#Check our Honeypot Account
	foreach ($Account in $Accounts)
		{
			if($Account -eq "LocalAdmin")
          	{
			  $Alert = $true
			  $AccountName = $Account
		  	}
		} 
	#We have a match
	if($Alert -eq $true)
	{
		Write-Output "Raising Alert! Logon attempt found for account: $AccountName"
	}
	#We don't have a match
	else
		{
			Write-Output "These are not the droids you are looking for!"
		}
 }

Output when our Runbook is run:

Until next time. Happy automating!