# Third-party integrations for Security Hub
You can enhance your security posture with third-party integrations for AWS Security Hub. With this feature you can enable integrations that consume findings from Security Hub, allowing you to incorporate your operational, investigation, and response tools with Security Hub. Currently Security Hub supports integration with Jira Cloud and ServiceNow.
**Topics**
+ [Integrations for AWS Security Hub Jira Cloud](jiracloud.md)
+ [Integrations for ServiceNow](servicenow.md)
+ [KMS key policies for Security Hub ticketing integrations](securityhub-v2-integrations-key-policy.md)
+ [Testing configured ticketing integrations](securityhub-v2-test-ticket-integration.md)
# Integrations for AWS Security Hub Jira Cloud
This topic describes how to integrate with Jira Cloud. Before completing any of the procedures in this topic, you must purchase a Jira Cloud subscription plan. For information about subscription plans, see [Pricing](https://www.atlassian.com/software/jira/pricing) on the Atlassian website.
This integration allows you to send Security Hub findings to Jira Cloud, manually or automatically, so you can manage them as part of your operational workflows. For example, you can assign ownership to issues that need investigation and remediation.
For accounts in an organization, only the delegated administrator can configure an integration. The delegated administrator can manually use the create ticket feature for any member account findings. Additionally, the delegated administrator can use [automation rules](https://docs.aws.amazon.com/securityhub/latest/userguide/security-hub-v2-automation-rules.html) to automatically create tickets for any findings associated with member accounts. When defining an automation rule, the delegated administrator can set criteria, which can include all member accounts or specific member accounts. For information about setting a delegated administrator, see [Setting a delegated administrator account in Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/security-hub-v2-set-da.html).
For accounts not in an organization, all aspects of this feature are available.
## Prerequisites
Prior to connecting Security Hub with your Jira Cloud environment you must ensure that the following configuration steps are done in your Jira environment.
+ Install the AWS Security Hub for Jira cloud app.
+ Have at least one software development project that is company managed.
+ Assign the AWS app to the software development projects you want to receive findings from Security Hub.
Steps for each of these prerequisites are listed below.
### 1. Install the AWS Security Hub for Jira Cloud app
Security Hub has an app to support its integration with Jira. This app installs custom fields and a custom issue type which allows Security Hub b to populate specific attributes about Security Hub findings.
1. Sign in to your Atlassian site as the administrator.
1. Choose **Settings**, and choose **Apps**.
1. If directed to the marketplace page, choose **Find new apps**. If directed to the apps page, choose **Explore apps**, and then search for *AWS Security Hub for Jira Cloud*. Then choose **Get it now**.
### 2. Create a project or verify existing projects
This step is required if you haven't created a project. For information about how to create a project, see [Create a new project](https://support.atlassian.com/jira-software-cloud/docs/create-a-new-project/) in the Jira Cloud Support documentation.
**Requirements for creating a project**
Make sure to do the following when creating a new project.
+ Choose **Software development** for the project template.
+ Choose **Company-managed** for the project type.
**Requirements for existing projects**
Any existing projects in your Jira environment, which will be integrated with Security Hub, must be a project type of **Company-managed**.
### 3. Add your projects to the AWS Security Hub for Jira Cloud app
In order for Security Hub to be able to successfully send findings to your Jira environment each project that you want to use with Security Hub must be associated with the AWS Security Hub for Jira Cloud app. Associating a Jira project with the app ensures that the necessary custom fields for are associated with the project and can be populated when Security Hub sends findings to the project.
1. Sign in to your Atlassian site as the administrator.
1. Choose **Settings**, and choose **Apps**.
1. From the list of apps, choose **AWS Security Hub for Jira Cloud**.
1. Choose the **Connector settings** tab.
1. Under **Projects enabled**, choose **Add Jira Project**.
1. From the dropdown, choose **Add all**, or select a project. Repeat this part of the step if you want to add more than one project, but not all projects.
1. Choose **Save**.
You can verify which projects have been successfully installed from the **Installation Manager** tab. You can also verify configurations for fields, screens, statuses, and workflows from the **Installation Manager** tab.
For additional information regarding Jira Cloud, see [Jira Cloud resources](https://support.atlassian.com/jira-software-cloud/resources/) on the Atlassian website.
## Recommendations
**Creating a dedicated system account for your Jira environment**
Security Hub’s integration with Jira Cloud uses an OAuth connection that is associated with a specific user within your Jira instance. Creating a dedicated system account to use for your Security Hub OAuth connection is recommended for your connection for the following reasons:
+ A dedicated system user ensures that the connection is not associated with an employee who’s permissions to the Jira environment could change over time, impacting the ability for Security Hub to integrate with your Jira environment.
+ Each issue that Security Hub creates in Jira will show a created by that is the username that was used to create the OAuth connection. Using a system account for the OAuth connection will result in this system account showing as the ticket creator, helping to provide visibility that the finding was created through the Security Hub integration and not manually by another Jira user.
## Configure an integration between Security Hub and Jira Cloud
The following procedure needs to be completed for each of your Jira Cloud projects that you want to send Security Hub findings to.
**Note**
When you create a Jira Cloud connector, you are redirected from the current AWS Region to `"https://3rdp.oauth.console.api.aws"`, so you can complete the connector registration. Afterwards, you are returned to the AWS Region where the connector is being created.
**To configure an integration for Jira Cloud**
1. Sign in to your AWS account with your credentials, and open the Security Hub console at [https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1](https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1).
1. From the navigation pane, choose **Management**, and then choose **Integrations**.
1. Choose **Add Jira Cloud**.
1. For **Details**, enter a unique and descriptive name for your integration, and determine whether to enter an optional description for your integration.
1. For **Encryptions** choose how you want to encrypt your integration credentials within Security Hub.
+ **Use AWS owned key** - With this option a Security Hub owned service key will be used to encrypt your integration credential data within Security Hub.
+ **Choose a different KMS key (advanced)** - With this option you choose an AWS KMS key that you have created which you want to be used for encrypting your integration credential data within Security Hub. For information about how to create an AWS KMS key, see [Create a AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the * AWS Key Management Service Developer Guide*. If you choose to use your own key you must add policy statements to the KMS key that allow Security Hub access to the key. See [AWS KMS key policies for Security Hub ticketing integrations](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-v2-integrations-key-policy.html) for details on the necessary policies.
**Note**
You cannot change these settings once you complete this configuration. However, If you choose **Customized key**, you can edit your customized key policy at any time.
1. (Optional) For **Tags**, create and add a tag to your integration. You can add up to 50 tags.
1. For **Authorizations**, choose **Create connector and authorize**. A pop-up appears where you choose **Allow** to complete the authorization. After you complete the authorization, a check box appears letting you know the authorization was successful.
1. For **Configurations**, enter the Jira Cloud project ID.
1. Choose **Complete configuration**. After you complete the configuration, you can view your configured integrations in the **Configured integrations** tab.
Once you have configured your integration with Jira you can test the connection to confirm that everything is configured properly in your Jira environment and in Security Hub. See the [ Testing configured ticketing integrations](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-v2-test-ticket-integration.html) for more details.
## Additional Jira integration details
**Rate limit considerations**
Jira enforces API rate limits to maintain service stability and ensure fair usage across their platform. When using the AWS Security Hub integration with Jira, these rate limits may impact the processing of Security Hub findings, particularly in environments generating high volumes of findings. This can result in delayed ticket creation, and in scenarios with extremely high finding volumes, some findings may not be processed into Jira tickets at all. To optimize your integration, consider implementing filters on Automation rules in Security Hub to prioritize ticketing on most important findings, monitoring your Jira API usage through their admin console, and planning your workflow based on your Jira license tier's specific rate limits. For business-critical implementations, contact your Jira administrator to review your rate limit allocations.
For detailed information about Jira API rate limits, refer to the [Rate limiting](http://developer.atlassian.com/cloud/jira/platform/rate-limiting/) documentation on the Atlassian Developers Guide website.
**Authentication and security**
Jira API authentication requires proper OAuth 2.0 configuration for secure access. Ensure your application follows Atlassian's security best practices for API integration.
Resources:
+ Jira Rest APi v3: [https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)
+ Implementing OAuth 2.0 (3LO): [https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/)
+ Administer Jira Cloud apps: [https://support.atlassian.com/jira-cloud-administration/resources/](https://support.atlassian.com/jira-cloud-administration/resources/)
+ Manage Jira permissions: [https://support.atlassian.com/jira-cloud-administration/docs/manage-project-permissions/](https://support.atlassian.com/jira-cloud-administration/docs/manage-project-permissions/)
# Creating a ticket for a Jira Cloud integration
After you create an integration with Jira Cloud, you can create a ticket for a finding.
**Note**
A finding will always be associated with a single ticket through its entire lifecycle. All subsequent updates to a finding after initial creation will be sent to the same ticket. If a connector associated with an automation rule is changed, the updated connector will only be used for new and incoming findings that match the rule criteria.
**To create a ticket for a finding**
1. Sign in to your AWS account with your credentials, and open the Security Hub console at [https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1](https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1).
1. From the navigation pane, under **Inventory**, choose **Findings**.
1. Choose a finding. In the finding, choose **Create ticket**.
1. For **Integration**, open the dropdown menu, and choose an integration. This integration is the integration you previously created when you configured the Jira Cloud project. Choose the integration where you want findings sent.
1. Choose **Create**.
# Viewing a ticket for a Jira Cloud integration
After you create a ticket for a finding, you can open the ticket on your Jira Cloud instance.
**To view a finding on your Jira Cloud instance**
1. Sign in to your AWS account with your credentials, and open the Security Hub console at [https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1](https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1).
1. From the navigation pane, under **Inventory**, choose **Findings**.
1. Choose the finding where you created the ticket.
1. In the finding, choose the ticket ID to view the ticket on your Jira Cloud instance or **View JSON**.
# Integrations for ServiceNow
This topic describes how to access the Security Hub console to configure an integration for ServiceNow ITSM. Before completing any of the procedures in this topic, you must have a subscription to ServiceNow ITSM before you can add this integration. For more information, see [the pricing page](https://www.servicenow.com/lpgp/pricing-itsm.html) on the ServiceNow website.
For accounts in an organization, only the delegated administrator can configure an integration. The delegated administrator can manually use the create ticket feature for any member account findings. Additionally, the delegated administrator can use [automation rules](https://docs.aws.amazon.com/securityhub/latest/userguide/security-hub-v2-automation-rules.html) to automatically create tickets for any findings associated with member accounts. When defining an automation rule, the delegated administrator can set criteria, which can include all member accounts or specific member accounts. For information about setting a delegated administrator, see [Setting a delegated administrator account in Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/security-hub-v2-set-da.html).
For accounts not in an organization, all aspects of this feature are available.
## Prerequisites - configure ServiceNow environment
You must complete the following prerequisites before configuring an integration for ServiceNow ITSM. Otherwise, your integration between ServiceNow ITSM and Security Hub will not work.
### 1. Install Security Hubfindings integration for IT Service Management (ITSM)
The following procedure describes how to install Security Hub plugin.
1. Sign into your ServiceNow ITSM instance, and then open the application navigator.
1. Navigate to the [ServiceNow Store](https://store.servicenow.com/store).
1. Search for *Security Hub findings integration for IT Service Management (ITSM)*, and then choose **Get** to install the application.
**Note**
In the settings for the Security Hub application, choose which action to take when new Security Hub findings are sent to your ServiceNow ITSM environment. You can choose **Do nothing**, **Create incident**, **Create problem**, or **Create both (incident/problem)**.
### 2. Configure the Client Credentials grant type for inbound OAuth requests
You must configure this grant type for inbound OAuth requests. For more information, see [Client Credentials grant type for Inbound OAuth is supported](https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB1645212) in the ServiceNow Support webpage.
### 3. Create an OAuth application
If you already created an OAuth application, you can skip this prerequisite. For information about creating an OAuth application, see [Setting up OAuth](https://www.servicenow.com/docs/csh?topicname=client-credentials.html&version=latest).
## Prerequisites - configure AWS Secrets Manager
To use Security Hub's integration with ServiceNow, the credentials for your ServiceNow OAuth application must be stored in Secrets Manager. Storing your credentials in Secrets Manager allows you to have control and visibility into the use of the credentials while also allowing Security Hub to use the credentials to integrate with your ServiceNow instance. To store your credentials in Secrets Manager, you must use a customer managed AWS KMS key to protect the secrets. This AWS KMS key allows you to protect the secrets while stored at rest and also allows a policy to be attached to the key which gives Security Hub permissions to access the key that is protecting the secret.
Use the following steps to configure Secrets Manager for your ServiceNow credentials.
### Step 1: Attach a policy to your AWS KMS key
To successfully configure your ServiceNow integration, you must first give Security Hub permissions to use the AWS KMS key that will be associated with your ServiceNow credentials in Secrets Manager.
**To modify the AWS KMS key policy for Security Hub to access your ServiceNow credentials**
1. Open the AWS KMS console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. Select an existing AWS KMS key or perform the steps to [Create a new key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS KMS Developer Guide*.
1. In the **Key policy** section, choose **Edit**.
1. If **Switch to policy view** is displayed, choose it to display the Key policy, and then choose **Edit**.
1. Copy the following policy block to your AWS KMS key policy, to grant Security Hub permission to use your key.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::your-account-id:root"
},
"Action": "kms:*",
"Resource": "*"
},
{
"Sid": "Allow Security Hub connector service to decrypt secrets",
"Effect": "Allow",
"Principal": {
"Service": "connector.securityhub.amazonaws.com"
},
"Action": "kms:Decrypt",
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": "secretsmanager.your-region.amazonaws.com"
},
"StringLike": {
"kms:EncryptionContext:SecretARN": "arn:aws:secretsmanager:your-region:your-account-id:secret:ServiceNow*"
}
}
}
]
}
```
1. Edit the policy by replacing the following values in the policy example:
+ Replace *your-account-id* with your AWS account ID.
+ Replace *your-region* with your AWS region (for example, `us-east-1`).
1. If you added the policy statement before the final statement, add a comma before adding this statement. Make sure that the JSON syntax of your AWS KMS key policy is valid.
1. Choose **Save**.
1. (Optional) Copy the key ARN to a notepad for use in the later steps.
### Step 2: Create the secret in Secrets Manager
Create a secret in Secrets Manager that will store your ServiceNow credentials. Security Hub will access this secret when interacting with your ServiceNow environment.
Follow the steps [To create a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) in the *AWS Secrets Manager User Guide*. After you create your secret, copy the Secret ARN as you will need this when creating your Security Hub connector.
When creating the secret, ensure you configure the following:
**Secret type**
Other type of secret
**Key/value pairs (Plaintext format)**
```
{
"ClientId": "your-servicenow-client-id",
"ClientSecret": "your-servicenow-client-secret"
}
```
The field names must be exactly `ClientId` and `ClientSecret` (case-sensitive). Security Hub requires these exact names to retrieve the credentials.
**Encryption key**
Use the AWS KMS key you configured in Step 1
**Resource policy**
Use the following resource policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "connector.securityhub.amazonaws.com"
},
"Action": "secretsmanager:GetSecretValue",
"Resource": "arn:aws:secretsmanager:your-region:your-account-id:secret:ServiceNow*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "your-account-id",
"aws:SourceArn": "arn:aws:securityhub:your-region:your-account-id:*"
}
}
}
]
}
```
Now that your secret is configured, you can create a Security Hub connector using the CreateConnectorV2 API or AWS Console. You'll need to provide:
+ **InstanceName**: Your ServiceNow instance URL (for example, `your-instance.service-now.com`)
+ **SecretArn**: The ARN of the secret you created in this procedure
## Configure an integration for ServiceNow ITSM
Security Hub can create incidents or problems automatically in ServiceNow ITSM.
**To configure an integration for ServiceNow ITSM**
1. Sign in to your AWS account with your credentials, and open the Security Hub console at [https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1](https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1).
1. From the navigation pane, choose **Management**, and then choose **Integrations**.
1. Under **ServiceNow ITSM**, choose **Add integration**.
1. For **Details**, enter a name for your integration, and determine whether to enter an optional description for your integration.
1. For **Encryptions** choose how you want to encrypt your integration credentials within Security Hub.
+ **Use AWS owned key** - With this option a Security Hub owned service key will be used to encrypt your integration credential data within Security Hub.
+ **Choose a different KMS key (advanced)** - With this option you choose an AWS KMS key that you have created which you want to be used for encrypting your integration credential data within Security Hub. For information about how to create an AWS KMS key, see [Create a AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the * AWS Key Management Service Developer Guide*. If you choose to use your own key you must add policy statements to the KMS key that allow Security Hub access to the key. See [AWS KMS key policies for Security Hub ticketing integrations](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-v2-integrations-key-policy.html) for details on the necessary policies.
**Note**
You cannot change these settings once you complete this configuration. However, If you choose **Customized key**, you can edit your customized key policy at any time.
1. For **Credentials**, enter your ServiceNow ITSM URL, and the ARN of your AWS Secrets Manager secret that was generated in the prerequisites section.
1. For **Tags**, determine whether to create and add an optional tag to your integration.
1. Choose **Add integration**. After you complete the configuration, you can view your configured integrations in the **Configured integrations** tab.
Once you have configured your integration with ServiceNow you can test the connection to confirm that everything is configured properly in your ServiceNow environment and in Security Hub. See the [ Testing configured ticketing integrations](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-v2-test-ticket-integration.html) for more details.
# Creating a ticket for a ServiceNow ITSM integration
After you create an integration with ServiceNow ITSM, you can create a ticket for a finding.
**Note**
A finding will always be associated with a single ticket through its entire lifecycle. All subsequent updates to a finding after initial creation will be sent to the same ticket. If a connector associated with an automation rule is changed, the updated connector will only be used for new and incoming findings that match the rule criteria.
**To create a ticket for a finding**
1. Sign in to your AWS account with your credentials, and open the Security Hub console at [https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1](https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1).
1. From the navigation pane, under **Inventory**, choose **Findings**.
1. Choose a finding. In the finding, choose **Create ticket**.
1. For **Integration**, open the dropdown menu, and choose an integration.
1. Choose **Create**.
# Viewing a ticket for a ServiceNow ITSM integration
After you create a ticket for a finding, you can open the ticket on your ServiceNow ITSM instance.
**To view a finding on your ServiceNow ITSM instance**
1. Sign in to your AWS account with your credentials, and open the Security Hub console at [https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1](https://console.aws.amazon.com/securityhub/v2/home?region=us-east-1).
1. From the navigation pane, under **Inventory**, choose **Findings**.
1. Choose the finding where you created the ticket.
1. In the finding, choose the ticket ID to view the ticket on your ServiceNow ITSM instance or **View JSON**.
# KMS key policies for Security Hub ticketing integrations
When using customer-managed KMS keys with Security Hub ticketing integrations, additional policies need to be added to the KMS key to allow Security Hub to interact with the key. Additionally, policies need to be added which allow the principal who is adding the key to the Security Hub connector permissions to access the key.
## Security Hub permissions policy
The following policy outlines the permissions that Security Hub needs to be able to access and use the KMS key that is associated with your Jira and ServiceNow connectors. This policy needs to be added to each KMS key that is associated with a Security Hub connector.
The policy contains the following permissions:
+ Permits Security Hub to protect, temporary access or refresh tokens used to communicate with your ticketing integrations, using the key. The permissions are restricted to operations related to specific Security Hub connectors through the condition block that checks the source ARN and encryption context.
+ Permits Security Hub to read metadata about the KMS key by allowing the `DescribeKey` operation. This permission is necessary for Security Hub to verify the key's status and configuration. The access is limited to specific Security Hub connectors through the source ARN condition.
```
{
"Sid": "Allow Security Hub access to the customer managed key",
"Effect": "Allow",
"Principal": {
"Service": "connector.securityhub.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt",
"kms:ReEncrypt*"
],
"Resource": "*",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:securityhub:Region:AccountId:connectorv2/*"
},
"StringLike": {
"kms:EncryptionContext:aws:securityhub:connectorV2Arn": "arn:aws:securityhub:Region:AccountId:connectorv2/*",
"kms:EncryptionContext:aws:securityhub:providerName": "CloudProviderName"
}
}
},
{
"Sid": "Allow Security Hub read access to the customer managed key",
"Effect": "Allow",
"Principal": {
"Service": "connector.securityhub.amazonaws.com"
},
"Action": [
"kms:DescribeKey"
],
"Resource": "*",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:securityhub:Region:AccountId:connectorv2/*"
}
}
}
```
Edit the policy by replacing the following values in the policy example:
+ Replace *CloudProviderName* with `JIRA_CLOUD` or `SERVICENOW`
+ Replace *AccountId* with the account ID where you are creating the Security Hub connector.
+ Replace *Region* with your AWS region (for example, `us-east-1`).
## IAM principal access for Security Hub operations
Any principal that will be assigning customer-managed KMS keys to a Security Hub connector needs to have permissions to perform key operations (describe, generate, decrypt, re-encrypt, and list aliases) for the key being added to the connector. This applies to the [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_CreateConnectorV2.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_CreateConnectorV2.html) and [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_CreateTicketV2.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_CreateTicketV2.html) APIs. The following policy statement should be included as part of the policy for any principal that will be interacting with these APIs.
```
{
"Sid": "Allow permissions to access key through Security Hub",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::AccountId:role/RoleName"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt",
"kms:ReEncrypt*"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"securityhub.Region.amazonaws.com"
]
},
"StringLike": {
"kms:EncryptionContext:aws:securityhub:providerName": "CloudProviderName"
}
}
},
{
"Sid": "Allow read permissions to access key through Security Hub",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::AccountId:role/RoleName"
},
"Action": [
"kms:DescribeKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"securityhub.Region.amazonaws.com"
]
}
}
}
```
Edit the policy by replacing the following values in the policy example:
+ Replace *RoleName* with the name of the IAM role that's making calls to Security Hub.
+ Replace *CloudProviderName* with `JIRA_CLOUD` or `SERVICENOW`.
+ Replace *AccountId* with the account ID where you are creating the Security Hub connector.
+ Replace *Region* with your AWS region (for example, `us-east-1`).
# Testing configured ticketing integrations
For configured Jira and ServiceNow integrations you can test the connection to ensure that all the configuration in Security Hub and in your Jira or ServiceNow environment is complete.
The test ticket feature will create a ticket with a title of `TESTING Test CreateTicketV2 Finding`. The test ticket is populated with sample data such as Account ID and region of the account where the test is performed, sample resource details, and sample AWS Finding JSON.
## Testing integrations using the console
Use the following steps to test your integration:
1. In the Security Hub navigation panel choose **Integrations**.
1. In the **Configured integrations** tab chose the integration that you want to test.
1. In the overview page for your integration choose **Create test ticket**.
1. If the test was successful a success message along with a link to the test ticket will be displayed. If the test was not successful an error for the test will be displayed. Based on the error message address the configuration issues in Security Hub or in your Jira or Service Now environment.
**Note**
The test ticket feature intended to help verify end to end functionality for the setup of a new connection or when you make changes to an existing connection. This feature will create a new ticket in your Jira or Service Now environment every time it is used and is not intended to be used for regular verification of your connection.
## Testing with the AWS CLI
To test your integration using the AWS CLI, use the `create-ticket-v2` command with the `--mode DRYRUN` parameter:
```
aws securityhub create-ticket-v2 \
--mode DRYRUN \
--region \
--connector-id \
--finding-metadata-uid "TEST_FINDING"
```
**Example**
The following example shows how to test an integration:
```
aws securityhub create-ticket-v2 \
--mode DRYRUN \
--region us-east-1 \
--connector-id "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" \
--finding-metadata-uid "TEST_FINDING"
```
**Successful Response**
A successful response returns the following:
```
{
"TicketId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"TicketSrcUrl": "https://your-instance.service-now.com/nav_to.do?uri=x_aws_se_0_finding.do?sys_id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
```
The `TicketSrcUrl` in the response provides a direct link to view the test ticket in your Jira or ServiceNow environment.
If the test fails, an error message will be displayed indicating the configuration issue that needs to be addressed.
## Troubleshooting Jira cloud integration errors
When testing your integration to Jira Cloud from Security Hub the following error messages may be returned. These error messages can provide insight on where the configuration issue with the connector could be and how to resolve.
**Jira Cloud integration error messages**
| Error | Error Message | Likely cause and resolution |
| --- | --- | --- |
| ConflictException | Cannot find jira project | **Likely cause:** Project on the connector is incorrect, or credentials/permissions issue preventing us from accessing the project. **Likely resolution:** Add the correct project to the connector or re-authenticate to Jira with the correct credentials. |
| ConflictException | Security Hub issue type not found | **Likely cause:** App installation issue or issue type is not associated with the project. **Likely resolution:** Perform the pre-requisite step to install the Jira app into your Jira environment and associate the app with the project. |