• 3 min read

PowerShell module for the OMS Search API

Learn how to 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.

Update April 5th, 2016: This blog post is now superseded by this blog post

Update October 15th 2015: The OMS PowerShell module on Github are updated here to now support Azure resource groups, start/end date & time and will support using a service principal name (SPN).

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 bulk export OMS analytics data. 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:

Adding Module 1

  • Click Modules:

Adding Module 2

  • Click Add a Module:

Adding Module 3

  • 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.

Adding Module 4

  • Verify the extraction completed successfully.

Adding Module 5

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

Adding Module 6  

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:

Connections 1

Click on Add a connection:

Connections 2

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:

Connections 5

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

Connections 4

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.

Create runbook

  • For now, create a runbook using PowerShell Workflow.

Create runbook 2  

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
 $APIVersion = $OMSConnection.APIVersion
 
 #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 -Subscription $SubID -Workspace $Workspace -Region $Region -APIVersion "2015-03-20" -Query $Query
 #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:

runbook output

  Until next time. Happy automating!