# Bidirectionally integrate AWS Security Hub CSPM with Jira software *Joaquin Rinaudo, Amazon Web Services* ## Summary This solution supports a bidirectional integration between AWS Security Hub CSPM and Jira. Using this solution, you can automatically and manually create and update Jira tickets from Security Hub CSPM findings. Security teams can use this integration to notify developer teams of severe security findings that require action. The solution allows you to: + Select which Security Hub CSPM controls automatically create or update tickets in Jira. + In the Security Hub CSPM console, use Security Hub CSPM custom actions to manually escalate tickets in Jira. + Automatically assign tickets in Jira based on the AWS account tags defined in AWS Organizations. If this tag is not defined, a default assignee is used. + Automatically suppress Security Hub CSPM findings that are marked as false positive or accepted risk in Jira. + Automatically close a Jira ticket when its related finding is archived in Security Hub CSPM. + Reopen Jira tickets when Security Hub CSPM findings reoccur. **Jira workflow** The solution uses a custom Jira workflow that allows developers to manage and document risks. As the issue moves through the workflow, bidirectional integration ensures that the status of the Jira ticket and Security Hub CSPM finding is synchronized across the workflows in both services. This workflow is a derivative of *SecDevOps Risk Workflow* by Dinis Cruz, licensed licensed under [Apache License version 2.0](https://www.apache.org/licenses/LICENSE-2.0). We recommend adding a Jira workflow condition so that only members of your security team can change the ticket status. ![\[A workflow diagram of a Jira issue. You can fix the issue, accept the risk, or mark it as a false positive.\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/images/pattern-img/206b9907-c2a3-4142-90bf-d4eabee534c0/images/10b08232-437e-4b0a-b6a5-b5ef4d415ac5.png) For an example of a Jira ticket automatically generated by this solution, see the [Additional information](#bidirectionally-integrate-aws-security-hub-with-jira-software-additional) section of this pattern. ## Prerequisites and limitations **Prerequisites** + If you want to deploy this solution across a multi-account AWS environment: + Your multi-account environment is active and managed by AWS Organizations. + Security Hub CSPM is enabled on your AWS accounts. + In AWS Organizations, you have designated a Security Hub CSPM administrator account. + You have a cross-account AWS Identity and Access Management (IAM) role that has `AWSOrganizationsReadOnlyAccess` permissions to the AWS Organizations management account. + (Optional) You have tagged your AWS accounts with `SecurityContactID`. This tag is used to assign Jira tickets to the defined security contacts. + If you want to deploy this solution within a single AWS account: + You have an active AWS account. + Security Hub CSPM is enabled on your AWS account. + A Jira Data Center instance **Important** This solution supports use of Jira Cloud. However, Jira Cloud does not support importing XML workflows, so you need to manually re-create the workflow in Jira. You can find of the transitions and status in the GitHub repository. + Administrator permissions in Jira + One of the following Jira tokens: + For Jira Enterprise, a personal access token (PAT). For more information, see [Using Personal Access Tokens](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) (Atlassian support). + For Jira Cloud, a Jira API token. For more information, see [Manage API tokens](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) (Atlassian support). ## Architecture This section illustrates the architecture of the solution in various scenarios, such as when the developer and security engineer decide to accept the risk or decide to fix the issue. *Scenario 1: Developer addresses the issue* 1. Security Hub CSPM generates a finding against a specified security control, such as those in the [AWS Foundational Security Best Practices standard](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-standards-fsbp.html). 1. An Amazon CloudWatch event associated with the finding and the `CreateJIRA` action initiates an AWS Lambda function. 1. The Lambda function uses its configuration file and the finding's `GeneratorId` field to evaluate whether it should escalate the finding. 1. The Lambda function determines the finding should be escalated, it obtains the `SecurityContactID` account tag from AWS Organizations in the AWS management account. This ID is associated with the developer and is used as the assignee ID for the Jira ticket. 1. The Lambda function uses the credentials stored in AWS Secrets Manager to create a ticket in Jira. Jira notifies the developer. 1. The developer addresses the underlying security finding and, in Jira, changes the status of the ticket to `TEST FIX`. 1. Security Hub CSPM updates the finding as `ARCHIVED`, and a new event is generated. This event causes the Lambda function to automatically close the Jira ticket. ![\[An architecture diagram showing Jira and Security Hub integration when a developer fixes an issue.\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/images/pattern-img/206b9907-c2a3-4142-90bf-d4eabee534c0/images/18d9a6ce-dd38-4d36-a95d-270fce776c30.png) *Scenario 2: Developer decides to accept the risk* 1. Security Hub CSPM generates a finding against a specified security control, such as those in the [AWS Foundational Security Best Practices standard](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-standards-fsbp.html). 1. A CloudWatch event associated with the finding and the `CreateJIRA` action initiates a Lambda function. 1. The Lambda function uses its configuration file and the finding's `GeneratorId` field to evaluate whether it should escalate the finding. 1. The Lambda function determines the finding should be escalated, it obtains the `SecurityContactID` account tag from AWS Organizations in the AWS management account. This ID is associated with the developer and is used as the assignee ID for the Jira ticket. 1. The Lambda function uses the credentials stored in Secrets Manager to create a ticket in Jira. Jira notifies the developer. 1. The developer decides to accept the risk and, in Jira, changes the status of the ticket to `AWAITING RISK ACCEPTANCE`. 1. The security engineer reviews the request and finds the business justification appropriate. The security engineer changes the status of the Jira ticket to `ACCEPTED RISK`. This closes the Jira ticket. 1. A CloudWatch daily event initiates the refresh Lambda function, which identifies closed Jira tickets and updates their related Security Hub CSPM findings as `SUPPRESSED`. ![\[An architecture diagram showing Jira and Security Hub integration when a developer accepts the risk of a finding.\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/images/pattern-img/206b9907-c2a3-4142-90bf-d4eabee534c0/images/d5a2f946-9c79-4661-96c1-74c813cbf406.png) ## Tools **AWS services** + [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) helps you set up AWS resources, provision them quickly and consistently, and manage them throughout their lifecycle across AWS accounts and Regions. + [Amazon CloudWatch Events](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/WhatIsCloudWatchEvents.html) helps you monitor system events for your AWS resources by using rules to match events and route them to functions or streams. + [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) is a compute service that helps you run code without needing to provision or manage servers. It runs your code only when needed and scales automatically, so you pay only for the compute time that you use. + [AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html) is an account management service that helps you consolidate multiple AWS accounts into an organization that you create and centrally manage. + [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) helps you replace hardcoded credentials in your code, including passwords, with an API call to Secrets Manager to retrieve the secret programmatically. + [AWS Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) provides a comprehensive view of your security state in AWS. It also helps you check your AWS environment against security industry standards and best practices. **Code repository** The code for this pattern is available on GitHub, in the [aws-securityhub-jira-software-integration](https://github.com/aws-samples/aws-securityhub-jira-software-integration/) repository. It includes the sample code and Jira workflow for this solution. ## Epics ### Configure Jira | Task | Description | Skills required | | --- | --- | --- | | Import the workflow. | As an administrator in Jira, import the `issue-workflow.xml` file to your Jira Data Center instance. If you use Jira Cloud, you need to create the workflow according to the `assets/jira-cloud-transitions.png` and `assets/jira-cloud-status.png` files. Files can be found in the [aws-securityhub-jira-software-integration](https://github.com/aws-samples/aws-securityhub-jira-software-integration/) repository in GitHub. For instructions, see [Using XML to create a workflow](https://confluence.atlassian.com/adminjiraserver/using-xml-to-create-a-workflow-938847525.html) (Jira documentation). | Jira administrator | | Activate and assign the workflow. | Workflows are inactive until you assign them to a workflow scheme. You then assign the workflow scheme to a project.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.html) | Jira administrator | ### Set up the solution parameters | Task | Description | Skills required | | --- | --- | --- | | Configure the solution parameters. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.html) | AWS systems administrator | | Identify the findings you want to automate. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.html) | | | Add the findings to the configuration file. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.html)The following code example shows automating the `aws-foundational-security-best-practices/v/1.0.0/SNS.1` and `aws-foundational-security-best-practices/v/1.0.0/S3.1` findings.
{
    "Controls" : {
        "eu-west-1": [
         "arn:aws:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0/rule/1.22" 
     ],
        "default": [
aws-foundational-security-best-practices/v/1.0.0/SNS.1,
aws-foundational-security-best-practices/v/1.0.0/S3.1
     ]
    } 
 }
You can choose to automate different findings for each AWS Region. A good practice to help prevent duplicated findings is to select a single Region to automate creation of controls related to IAM. | AWS systems administrator | ### Deploy the integration | Task | Description | Skills required | | --- | --- | --- | | Deploy the integration. | In a command line terminal, enter the following command:
./deploy.sh prod
| AWS systems administrator | | Upload Jira credentials to Secrets Manager. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.html) | AWS systems administrator | | Create the Security Hub CSPM custom action. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.html) | AWS systems administrator | ## Related resources + [AWS Service Management Connector for Jira Service Management](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/integrations-jiraservicedesk.html) + [AWS Foundational Security Best Practices standard](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-standards-fsbp.html) ## Additional information **Example of a Jira ticket** When a specified Security Hub CSPM finding occurs, this solution automatically creates a Jira ticket. The ticket includes the following information: + **Title** – The title identifies the security issue in the following format: ``` AWS Security Issue :: :: ``` + **Description** – The description section of the ticket describes the security control associated with the finding, includes a link to the finding in the Security Hub CSPM console, and provides a short description of how to handle the security issue in the Jira workflow. The following is an example of an automatically generated Jira ticket. | | | --- | | Title | AWS Security Issue :: 012345678912 :: Lambda.1 Lambda function policies should prohibit public access. | | --- |--- | | **Description** | **What is the problem?** We detected a security finding within the AWS account 012345678912 you are responsible for.This control checks whether the AWS Lambda function policy attached to the Lambda resource prohibits public access. If the Lambda function policy allows public access, the control fails.**What do I need to do with the ticket?**Access the account and verify the configuration. Acknowledge working on ticket by moving it to "Allocated for Fix". Once fixed, moved to test fix so security validates the issue is addressed.If you think risk should be accepted, move it to "Awaiting Risk acceptance". This will require review by a security engineer.If you think is a false positive, transition it to "Mark as False Positive". This will get reviewed by a security engineer and reopened/closed accordingly. |