Jira Alert Channel
Configure Lacework to receive alert notifications in your Jira account. You can automate the process of generating Jira tickets with your existing security workflow. The Jira integration sends findings from the Alerts page to Jira. Jira issues are created based on the findings.
A Jira issue includes the following information:
- Alert ID
- Alert Type
- Alert Category
- Severity Level
- Start Time
- Link to the alert on Lacework Console
- Lacework Account Name
This integration supports both Jira Cloud and Jira Server versions and is qualified with the most recent GA versions of Jira.
Supported Integrations
Lacework supports two Jira integration types:
A unidirectional integration with Jira allows you to programmatically generate a corresponding Jira issue for an alert. When the alert status is updated, the Jira status is updated.
To complete the integration, see Alert Rules and Alert Channels.
A bidirectional integration with Jira allows you to programmatically generate a corresponding Jira issue for an alert. When the alert status is updated, the Jira status is updated, and vice-versa.
When you change the Jira status from Closed to Open, the alert remain as Closed.
When multiple bidirectional channels are associated with an alert, each channel generates a Jira issue. To enable the bidirectional functionality, select a primary channel among those by clicking Select as primary.
To complete the integration, see Alert Rules and Alert Channels
When the alert rule associated with an alert is disabled or deleted, you can still change the alert status by changing the corresponding Jira status.
Prerequisites
Verify the following prerequisites:
- A Jira user name and an API access token that is used to create new Jira issues. For management and security purposes, Lacework recommends creating a dedicated Lacework Jira user with appropriate permissions. For more information, refer to the Jira REST API Reference.
- A Jira user with sufficient privileges to create new Jira issues in the specified Jira project.
- A preexisting Jira issue type in the specified Jira project with a defined priority field. When Lacework creates new Jira issues, they are created based on the specified Jira issue type.
- Allowlist the Lacework outbound IPs to allow Lacework to communicate with the Jira server. See Lacework Outbound IPs.
Create the Jira Alert Channel
Do the following to create the Jira alert channel:
Log in to the Lacework Console as a Lacework user with administrative privileges.
Navigate to Settings > Notifications > Alert channels.
Select + Add new > Jira
Select Next.
Select a Jira Type:
- JIRA Cloud - Select this option if your Jira instance is hosted by Atlassian in their cloud.
- JIRA Server - Select this option if you host your Jira instance on your hardware or in a hosting service such as AWS.
Specify a name for the channel that is visible in the Lacework Console in the Name field.
From the Configuration drop-down, select the integration type.
noteIf you configure the Jira alert channel as bidirectional, you cannot modify it to unidirectional.
From the Group Issues by drop-down, select one of the options:
- Events - Select this option if you want to create a single Jira open issue when events of the same type but from different resources are detected by Lacework.
- Resources - Select this option if you want multiple Jira open issues when multiple resources are generating the same compliance event.
In the Jira URL field, specify the URL of your Jira implementation without the https prefix ("https://"). For example:
mycompany.atlassian.net
ormycompany.jira.com
.In the Jira Project Key field, specify the project key for the Jira project where the new Jira issues should be created. Note that the specified Jira Issue type must exist in the specified Jira project prior to creating the Lacework Jira channel.
In the Issue Type field, specify the Jira Issue type (for example: Bug) to create when a new Jira issue is created.
In the Username field, specify the Jira user name with a domain (for example:
user@mycompany.com
). Lacework recommends using a dedicated Jira user.Jira server - in the Password field ,specify the password to the Jira user specified in a previous step.
Jira Cloud - in the API token field, specify the Jira API token.
noteTo locate the Jira Cloud API token, navigate to the Atlassian management console, select the My User icon in the top right, select Manage Account and, select the Security tab at the top.
Optional—In the Custom field mapping field, select Upload a JSON file to upload a custom template file to populate values from a custom template JSON file.
Select Save.
Copy the URL displayed in the Webhook for Jira dialog to your clipboard.
Configure a Jira webhook using the copied URL, see Configure a Jira Webhook for Bi-Directional Integration.
Click Alert rules and configure your required alert routing details and options by using the alert channel you created.
- The integration will only work after you configure a webhook in Jira.
- After the a connection with Jira is successfully established, Lacework generates a test Jira ticket with the title Event: 0 {timestamp}> Test Event.
Configure a Jira Webhook for Bi-Directional Integration
After you successfully configure the Jira alert channel, you must configure the Jira webhook in Jira. Follow these steps:
- Log into the Jira Cloud console with an Org Admin account.
- Select System from the settings cog in the top right corner.
- In the System settings window, scroll to the bottom of the list on the left-hand side and, select WebHooks.
- Select Create a WebHook in the top right.
- Specify the required information:
- Enter a name for the Webhook.
- Enter the URL provided by the Integration in the Lacework settings page.
- Select ISSUE Updated and Deleted in the Events section.
- Verify that the Exclude body section is not selected.
- Select Create
You have successfully created the Webhook in Jira. Next you can test the integration.
Test the Integration
The integration test verifies the communication between Lacework and Jira works as expected. The integration test requires the following:
- A configured Jira alert channel.
- An alert rule that uses the above Jira alert channel. For additional details, see Alert Rules.
- An active alert that is triggered by the above alert rule.
Follow these steps to test the integration:
Log in to the Lacework Console as a Lacework user with administrative privileges.
Navigate to Settings > Notifications > Alert Channels and select the Jira alert channel.
Select the Test button.
A message indicating that the integration test successfully completed appears.
Change the alert status to either In progress or Closed.
Refresh your browser.
The integration status changes to Success.
After the integration is successfully configured and tested, Lacework will begin generating events that meet the specified severity levels, and issuing new Jira issues. Lacework priorities events with the highest severity, in case the Jira API reaches maximum capacity.
The status will display as Pending if the integration is inactive for 3 days or more. Inactivity indicates that the Jira webhook was not used within the aforementioned time.
Populate Values in New Jira Issues from a Custom Template
If you want the Jira alert channel to populate fields in the new Jira issues with values from a custom template JSON file, create a custom template JSON file with the populated values and select that file when creating the Lacework Jira alert channel.
In the following custom template example, use the name
field to specify the Jira status corresponding with the open alert (e.g., Backlog), and the Jira status corresponding with the closed alert (e.g., Done). Use the primary
field to confirm which status Lacework will use when opening or closing a Jira issue for that alert.
Expand to view example
{
"lacework": {
"status": {
"Open": [
{
"name": "Backlog",
"primary": true
},
{
"name": "Selected for Development"
}
],
"Closed": [
{
"name": "Done",
"primary": true
}
]
}
}
}
If you want the new Jira issues created by the Lacework Jira alert channel to have a specific label and have the priority id of 1, specify the following in your custom template JSON file.
Expand to view label and priority
{
"fields": {
"labels": [
"myLabel"
],
"priority":
{
"id": "1"
}
}
}
You can also include data from Lacework by using the following variables:
Expand to view variables
Field Name | Description |
---|---|
alert_source | The integration that serves as the origin of the data. For instance, the "Agent" source pertains to alerts that originate from data collected by Lacework agents. |
alert_category | The alert category this alert is classified as. See Alert Categories for more information. |
alert_subcategory | The alert subcategory this alert is classified as. See Alert Subcategories for more information. |
event_title | The title of the Lacework event. |
event_link | The link to the event in the Lacework Console. |
lacework_account | The Lacework application where the event occurred. The myLacework part of the Lacework application URL: myLacework.lacework.net. |
event_summary | A summary of the event including a description of why the event occurred. |
event_timestamp | The timestamp of when the event occurred. |
event_type | The type (or category) of the event. |
event_id | The Lacework ID for the event. |
event_severity | The severity of the event between numbers 1 and 5. The number 1 is the highest severity and 5 is the lowest severity. |
event_severity_str | A variable that represents the severity of the event: Critical, High, Medium, Low, or Info. |
Add the variables to the summary field as in the following example:
{
"fields": {
"summary": "$event_id: $event_title - $event_summary - from Lacework alerts"
}
}
Jira allows up to 255 characters for the summary. Any characters over 255 are truncated.
When creating the Jira alert channel, you must select the custom template file from the Custom Template File field.
For more examples of specifying Jira fields, see the Field input formats section in the Using the REST APIs in the Atlassian documentation. Use the 2.0 version of the Jira REST APIs.
Any fields specified in the custom template JSON file, must already exist in the specified Jira project.
Specifying a value for a Jira field in the custom template JSON file overrides the value populated by the Jira alert channel for the following fields:
- Summary
- Issue Type
- Project
- Priority
For the Description field, the value specified in the custom template JSON is prepended to the value provided by the Jira alert channel.
If you used a custom template for an alert channel, you can download it by clicking Download template_name template. The download link is available on the Configure Channel page when editing an alert channel and on the Alert Routing page when clicking the existing Jira alert channel's link.
Create a Custom Template with Dynamic Variables
You can use the $event_severity_str
variable to create a mapping to specific fields dynamically. This solution eliminates manual ticket triage by allowing the alert to flow directly to the responsible team's Jira queue.
The following custom template assigns the $event_severity_str
variable to the customfield_10242
custom field. If the custom field exists in the custom_field_mappings
object, then the value of the variable is used to find the mapping for the field.
Expand to view custom template
{
"fields": {
"customfield_10242": "$event_severity_str"
},
"lacework": {
"custom_field_mappings": {
"customfield_10242": {
"Critical": {
"id": "10478"
},
"High": {
"id": "10477"
},
"Medium": {
"id": "10476"
},
"Low": {
"id": "10475"
},
"Info": {
"id": "10475"
}
}
}
}
}
Assuming the $event_severity_str
variable evaluates to Critical, the result from this custom template will look like the following:
{
"fields": {
"customfield_10242": {
"id": "10478"
}
}
}
Map Lacework Severities to Jira Priorities
By default, the following Lacework alert severities are mapped to the following Jira priorities.
Lacework Severity | (Jira Priority ID) Jira Priority |
---|---|
Critical | (1) Highest |
High | (2) High |
Medium | (3) Medium |
Low | (4) Low |
Info | (5) Lowest |
You can override the default settings by specifying a mapping in a custom template as shown in the example JSON below. In this example, the following mapping occurs:
- Critical and high severity Lacework alerts maps to Jira issues with a priority of (2)
- Medium and low severity Lacework alerts maps to Jira issues with a priority of (3)
- Info Lacework alerts maps to Jira issues with a priority of (4)
Expand to view severity mapping example using priority ID
{
"lacework": {
"severity": {
"Critical": {
"id": "2"
},
"High": {
"id": "2"
},
"Medium": {
"id": "3"
},
"Low": {
"id": "3"
},
"Info": {
"id": "4"
}
}
}
}
Expand to view severity mapping example using priority name
{
"lacework": {
"severity": {
"Critical": {
"name": "Critical"
},
"High": {
"name": "High"
},
"Medium": {
"name": "Medium"
},
"Low": {
"name": "Low"
},
"Info": {
"name": "Minor"
}
}
}
}
Pulling Custom Priority IDs from Jira
When you add or delete priorities in Jira, the severity IDs will be different than the Jira defaults of 1 to 5. If your priorities are not the standard ones provided by Jira (Highest, High, Medium, Low, Lowest) you must use the IDs for those severities. You can find them by using the Jira API, or by using a web browser using the same Jira URL as above: https://JIRA_URL/rest/api/2/priority.
Create a Lacework Jira Cloud or Server Alert Channel Using Terraform
For organizations using Terraform to manage their environments, Lacework maintains the Terraform provider for Lacework, which enables configuration of Lacework alert channels using automation.
For a complete list of custom Terraform resources to manage alert channels in Lacework, see Managing Alert Channels with Terraform.
Expand to view terraform example
# Jira Cloud
resource "lacework_alert_channel_jira_cloud" "example" {
name = "My Jira Cloud Alert Channel Example"
jira_url = "mycompany.atlassian.net"
issue_type = "Bug"
project_key = "EXAMPLE"
username = "my@username.com"
api_token = "abcd1234"
}
# Jira Server
resource "lacework_alert_channel_jira_server" "example" {
name = "My Jira Server Alert Channel Example"
jira_url = "mycompany.atlassian.net"
issue_type = "Bug"
project_key = "EXAMPLE"
username = "my@username.com"
password = "abcd1234"
}
For additional information on lacework_alert_channel_jira_cloud
see Terraform Registry.
For additional information on lacework_alert_channel_jira_server
resource, see Terraform Registry.
Rotate the Webhook Secret
Lacework recommends rotating your webhook's secret regularly to avoid compromises. When you rotate the secret, the Console blocks the old secret and generates a new one.
Follow these steps:
- Log in to the Lacework Console as a Lacework user with administrative privileges.
- Go to Settings > Notifications > Alert channels.
- From the list of alert channels, click on the channel that needs a new webhook's secret.
- Select the ellipsis menu located next to the current webhook, then select Generate new webhook.
- Copy the new webhook URL to your clipboard.
- Create a Jira webhook using the copied URL, see Configure a Jira Webhook for Bi-Directional Integration.
- Select Delete to remove the old webhook URL from the alert channel.
Troubleshooting
If your Jira integration status is displaying as Pending within the Lacework Console, check Alert Channel Warnings for troubleshooting suggestions.
To check when the webhook was last used, go to Settings > Notifications > Alert channels in the Lacework Console, and click the row for your integration. The Bidrectional Webhook field displays when the webhook was Last used.
Using the integration in any way (as long as it triggers the Jira webhook) will put the integration status back into Success.