Azure DevOps Alert Channel

Learn how to configure your Azure DevOps to receive Lacework alerts. This integration leverages the Azure DevOps REST API and an Azure Automation Account with a listening webhook to establish the connection between Lacework and Azure DevOps, as shown in the following diagram:

Create an Azure DevOps Personal Access Token (PAT)

From the Azure DevOps dashboard, complete the following steps:

1. Log in with an account that can create PATs to interface with DevOps boards within your organization/projects.
2. From the home page, select User settings > Personal access tokens.
3. Click + New Token.
4. On the Create a new personal access token page:
   • Name your token.
   • Select the organization where you want to use the token, or select All accessible organizations if you require access to multiple organizations.
   • Set your token to expire automatically after a set number of days.
   • Select Custom defined as your scope. Under Work Items, select Read, write & manage.
5. Click Create.
6. On the Success dialogue, you will see a PAT returned. Copy the token and store it in a secure location. For your security, it won't be shown again.

Create an Azure Automation Account

From the Azure portal, complete the following steps:

1. Log in with an account that's a member of the subscription Administrators role and a Co-Administrator of the subscription.
2. Select + Create a Resource.
3. Search for Automation. In the search results, select Automation.
4. Click + Create.
5. On the Create an Automation Account page:
   • Subscription: From the drop-down list, select the Azure subscription for the account.
   • Resource group: From the drop-down list, select your existing resource group, or select Create new.
   • Automation account name: Enter a name unique for it's location and resource group. Names for Automation Accounts that have been deleted might not be immediately available. You can't change the account name once it has been entered in the user interface.
   • Region: From the drop-down list, select a region for the Account. For an updated list of locations that you can deploy an Automation Account to, see Products available by region.
6. Click Review + Create.
7. Wait for Azure to run validation on the Automation Account settings that you have chosen. If validation passes, click Create to create the Automation Account.

Create an Automation Account Variable for the PAT

Do the following:

1. From your newly-created Automation Account, on the left-hand pane, select Variables under Shared Resources.
2. On the Variables page, select Add a variable.
3. On the New Variable drawer:
   • Name: Enter a name for the variable.
   • Type: From the drop-down list, select String.
   • Value: Enter the PAT you have created.
   • Encrypted: Toggle to Yes.
4. Click Create.

Create an Automation Account Runbook

Do the following:

1. From your newly-created Automation Account, select Runbooks under Process Automation to open the list of runbooks.

2. Click Create a runbook.

3. On the Create a runbook page:

   • Name: Name the runbook.
   • Runbook type: From the drop-down list, select PowerShell.
   • Runtime version: From the drop-down list, select 5.1.
   • Description: Enter an applicable description.

4. Click Create.

5. On the Edit PowerShell Runbook page, paste the following code into the PowerShell code editor:

   Automation Account Runbook

    param
   (
       [Parameter(Mandatory=$false)]
       [object] $WebhookData
   )
   if ($WebHookData){
   
       # The WebHook data comes in from the $WebHookData input param
       # This deserialized the JSON in the request body into an object and puts it in the $eventData variable
       $eventData = $webHookData.RequestBody | ConvertFrom-Json
   
       #= Automation Variables ============================================
       # This pulls the 'adoPat' variable (storing the PAT) in from the shared resources of the Automation Account
       $adoPat = Get-AutomationVariable -Name 'adoPat'
   
       # = ADO ============================================
       # CHANGE THESE VARIABLES TO MATCH YOUR AZURE DEVOPS ORG AND PROJECT
       $adoOrganization = 'MY_AZURE_DEVOPS_ORGANIZATION_PLACEHOLDER'             
       $adoProject = 'MY_AZURE_DEVOPS_PROJECT_PLACEHOLDER'            
       $adoItemType = 'task'                  
       $adoUri = 'https://dev.azure.com/{0}/{1}/_apis/wit/workitems/${2}?api-version=6.0' -f $adoOrganization, $adoProject, $adoItemType
   
       # These lines build the title for the work item and the description
       # The body supports HTML so the tags clean it up for better display
       $workItemTitle = "Alert: $($eventData.event_id) - $($eventData.event_title)"
       $workItemDesc = @"
   <h3>Event Details:</h3>
   <b>Title</b>            : $($eventData.event_title) <br>
   <b>Link</b>             : $($eventData.event_link) <br>
   <b>Lacework Account</b> : $($eventData.lacework_account) <br>
   <b>Event Source</b>     : $($eventData.event_source) <br>
   <b>Event Description</b>: $($eventData.event_description) <br>
   <b>Event TimeStamp</b>  : $($eventData.event_timestamp) <br>
   <b>Event Type</b>       : $($eventData.event_type) <br>
   <b>Event Id</b>         : $($eventData.event_id) <br>
   <b>Event Severity</b>   : $($eventData.event_severity) <br>
   "@
   
       # These will output the variables as a preview of what will go into the work item
       # This can be used to view the job in the Automation Account Runbook for troubleshooting as well
       $workItemTitle
       $workItemDesc
   
       # Configure the ADO Header required for authorizing with the Azure DevOps REST API
       $adoAuthHeader = @{Authorization = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$($adoPat)")) }
       # Configure the body for the REST API Patch Call
       # This passes in our title and description for work item creation.
       # If we need to add other things during work item creation like area or iteration, we can do that here by adding more sections.
       $adoBody = @(
           @{                                                                                                                                 
               'op' = 'add'
               'value' = $workItemTitle
               'from' = 'null'
               'path' = '/fields/System.Title'
           },
           @{                                                                                                                                 
               'op' = 'add'
               'value' = $workItemDesc
               'from' = 'null'
               'path' = '/fields/System.Description'
           }
       ) | ConvertTo-Json
   
       # This calls the Azure DevOps REST API Endpoint for work items with the following:
       # Authorization header using the PAT we created for work items
       # Body containing the PATCH JSON document needed to create the work item
       Invoke-RestMethod -Uri $adoUri -Method Patch -Headers $adoAuthHeader -ContentType 'application/json-patch+json' -Body $adoBody
   
   } else {
       Write-Error "NO DATA RETURNED"
   }

6. Change the value of the following variables in the runbook code to match your Azure DevOps environment:

   • $adoOrganization - Specifies your Azure DevOps organization name.
   • $adoProject - Specifies your Azure DevOps project name.

7. You can add work item fields in the runbook code. For more information, see Field descriptions for default and work item fields used in process templates.

8. Click Save, then click Publish.

9. From your Automation Account, select Webhooks under Resources.

10. Click + Add Webhook, then select Create a new webhook.

11. On the Create a new webhook page:

    • Name: Enter a name for your webhook.
    • Enabled: Toggle to Yes.
    • Expires: Set your webhook to expire automatically after a set number of days.
    • URL: Copy the URL of the webhook and save it to a secure location.

12. Click OK to return to the Add Webhook page.

13. From the Add Webhook page, select Configure parameters and run settings to open the Parameters page.

14. The wizard requires you to walk through the parameters, although no changes are needed. Click OK to return to the Add Webhook page.

15. Click Create.

Create the Lacework Alert Channel

Do the following:

1. Log in to the Lacework Console as a Lacework user with administrative privileges.
2. Go to Settings > Notifications > Alert channels.
3. Click + Add New.
4. Select Webhook.
5. Click Next.
6. On the Add alert channel page:
   • Name: Name the channel.
   • Webhook URL: Enter the URL you received from step 9 of Create an Automation Account Runbook.
7. Click Save.
8. From the Alert channels list, go to your newly-created webhook, then click Test. You should see the Integration test was successful message.
9. Check your Azure DevOps board for a work item sent by Lacework.

The next time an alert is created on the Lacework Console, a work item will appear on your Azure DevOps board.