Jira
Integrate Lacework with Jira and receive alert notifications in your Jira account. With this integration, you can automate the process of generating Jira tickets with your existing security workflow.
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 Jira Cloud and Jira Server versions and is qualified with the most recent GA versions of Jira.
Unidirectional Integration
A unidirectional integration with Jira allows you to programatically 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.
Bidirectional Integration
A bidirectional integration with Jira allows you to programatically generate a corresponding Jira issue for an alert. When the alert status is updated, the Jira status is updated, and vice-versa.
note
When you change the Jira status from Closed to Open, the alert remains as Closed.
When multiple bidirectional channels are associated with an alert, each channel generates a separate 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
note
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.
Verify Prerequisites
Before creating the Jira alert channel in the Lacework Console, verify the following prerequisites:
- Provide 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.
- The Jira user must have sufficient privileges to create new Jira issues in the specified Jira project.
- This Jira issue type must exist in the specified Jira project prior to creating the Lacework Jira alert channel as described in the procedure below. When Lacework creates new Jira issues, it creates new issues 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 a Jira Alert Channel from the Lacework Console
Navigate to Jira
- Log in to the Lacework Console as a Lacework user with administrative privileges.
- Go to Settings > Notifications > Alert channels.
- Click + Add new.
- Select Jira.
- Click Next.
- Follow the steps in the next section.
Create a Jira Alert Channel
Ensure you have configured the Jira prerequisites as described in Verify Prerequisites. Then complete the following steps:
- 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 like AWS.
- In the Name field, enter a name for the channel that is visible in the Lacework Console.
- From the Configuration drop-down, select the integration type such as Unidirectional or Bidirectional. Note that once you have configured the alert channel to be bidirectional, it cannot be changed to unidirectional.
- From the Group Issues by drop-down, select one of the options:
- Events - Select this option if you want a single Jira open issue to be created when events of the same type but from different resources are detected by Lacework. For example, if three different S3 resources are generating the same compliance event, only one Jira open issue is created.
- Resources - Select this option if you want multiple Jira open issues to be created when multiple resources are generating the same compliance event. For example, if three different S3 resources are generating the same compliance event, three Jira open issues are created.
- In the Jira URL field, enter the URL of your Jira implementation without https protocol ("https://"), for example: mycompany.atlassian.net or mycompany.jira.com.
- In the Jira Project Key field, enter 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, enter the Jira Issue type (such as a Bug) to create when a new Jira issue is created.
- In the Username field, enter the Jira user name with a domain (e.g., user@mycompany.com). Lacework recommends a dedicated Jira user. See above for more information.
- If integrating to a Jira cloud, in the API Token field, enter the Jira API Token. For more information, see https://confluence.atlassian.com/cloud/api-tokens-938839638.html.
- If integrating to a Jira server, in the Password field enter the password to the Jira user specified in a previous step.
- Optional—In the Custom field mapping field, click Upload a JSON file to select a custom template file to populate values from a custom template JSON file. For more information, see the next section.
- Click Save.
- Copy the URL displayed in the Webhook for Jira dialog to your clipboard.
- Create a Jira webhook using the copied URL, see Webhooks for Jira Server and Webhooks for Jira Cloud.
note
- The integration will not work until a Jira webhook is correctly set up.
- After the Lacework-to-Jira connection is successfully established, Lacework generates a test Jira ticket with the title Event: 0 {timestamp}> Test Event.
- To complete the integration test, you need to create a Jira issue from an active alert, then update the status or add a comment to that Jira ticket.
- Click Alert rules and configure your required alert routing details/options by leveraging the alert channel you created.
When the integration is successfully set up and tested, Lacework will start generating events that meet the specified severity levels, and issuing new Jira issues. Suppose there is a large volume of events that exceed the ability of Jira REST API to create new Jira issues. In that case, priority is given to those events with the highest severity.
note
Lacework only supports converting a unidirectional alert channel to be bidirectional -- not converting a bidirectional channel to be unidirectional.
Populate Values in New Jira Issues from a Custom Template
If you want the Jira integration to populate fields in the new Jira issues with values from a custom template JSON file, you must create a custom template JSON file with the populated values and then specify that file when creating the Lacework Jira alert channel in the Lacework Console.
In the following custom template example, use the name field to specify the Jira status corresponding with the open alert (e.g., Backlog), and which 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.
{
"lacework": {
"status": {
"Open": [
{
"name": "Backlog",
"primary": true
},
{
"name": "Selected for Development"
}
],
"Closed": [
{
"name": "Done",
"primary": true
}
]
}
}
}
Additionally, 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.
{
"fields": {
"labels": [
"myLabel"
],
"priority":
{
"id": "1"
}
}
}
You can also include data from Lacework by using the following variables:
| Field Name | Description |
|---|---|
| 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_source | The source of the event or where the event occurred. |
| 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"
}
}
note
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.
note
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 a custom template was used 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 leverage 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.
{
"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 default 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 these 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)
{
"lacework": {
"severity": {
"Critical": {
"id": "2"
},
"High": {
"id": "2"
},
"Medium": {
"id": "3"
},
"Low": {
"id": "3"
},
"Info": {
"id": "4"
}
}
}
}
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 - 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 accessing the web browser using the same Jira URL as above: https://JIRA_URL/rest/api/2/priority.
Create a Lacework Jira Cloud/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.
If you are new to the Lacework Terraform Provider, or Lacework Terraform Modules, read the Terraform for Lacework Overview to learn the basics on how to configure the provider and more.
For a complete list of custom Terraform resources to manage alert channels in Lacework, see Managing Alert Channels with Terraform.
# 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"
}
Additional information on the lacework_alert_channel_jira_cloud resource can be found on the Terraform Registry.
Additional information on the lacework_alert_channel_jira_server resource can be found on the Terraform Registry.
Rotate a Webhook's Secret from the Lacework Console
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.
- 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.
- Click 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 Webhooks for Jira Server and Webhooks for Jira Cloud.
- Click Delete to remove the old webhook URL from the alert channel.