Bidirectionally integrate AWS Security Hub with Jira software - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resourcesAdditional information

Bidirectionally integrate AWS Security Hub with Jira software

Created by Joaquin Manuel Rinaudo (AWS)

Summary

This solution supports a bidirectional integration between AWS Security Hub and Jira. Using this solution, you can automatically and manually create and update JIRA tickets from Security Hub 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 controls automatically create or update tickets in Jira.

  • In the Security Hub console, use Security Hub 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 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.

  • Reopen Jira tickets when Security Hub 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 finding is synchronized across the workflows in both services. This workflow is a derivative of SecDevOps Risk Workflow by Dinis Cruz, licensed under CC BY 4.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.

For an example of a Jira ticket automatically generated by this solution, see the Additional information 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 is enabled on your AWS accounts.

    • In AWS Organizations, you have designated a Security Hub administrator account.

    • You have a cross-account 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 is enabled on your AWS account.

  • A Jira Server 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.

  • 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 (Atlassian support).

    • For Jira Cloud, a Jira API token. For more information, see Manage API tokens (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 generates a finding against a specified security control, such as those in the AWS Foundational Security Best Practices standard.

  2. An Amazon CloudWatch event associated with the finding and the CreateJIRA action initiates an AWS Lambda function.

  3. The Lambda function uses its configuration file and the finding's GeneratorId field to evaluate whether it should escalate the finding.

  4. 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.

  5. The Lambda function uses the credentials stored in AWS Secrets Manager to create a ticket in Jira. Jira notifies the developer.

  6. The developer addresses the underlying security finding and, in Jira, changes the status of the ticket to TEST FIX.

  7. Security Hub 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.

Scenario 2: Developer decides to accept the risk

  1. Security Hub generates a finding against a specified security control, such as those in the AWS Foundational Security Best Practices standard.

  2. A CloudWatch event associated with the finding and the CreateJIRA action initiates a Lambda function.

  3. The Lambda function uses its configuration file and the finding's GeneratorId field to evaluate whether it should escalate the finding.

  4. 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.

  5. The Lambda function uses the credentials stored in Secrets Manager to create a ticket in Jira. Jira notifies the developer.

  6. The developer decides to accept the risk and, in Jira, changes the status of the ticket to AWAITING RISK ACCEPTANCE.

  7. 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.

  8. A CloudWatch daily event initiates the refresh Lambda function, which identifies closed JIRA tickets and updates their related Security Hub findings as SUPPRESSED.

An architecture diagram showing Jira and Security Hub integration when a developer accepts the risk of a finding.

Tools

  • AWS CloudFormation 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 helps you monitor system events for your AWS resources by using rules to match events and route them to functions or streams.

  • AWS Lambda 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 is an account management service that helps you consolidate multiple AWS accounts into an organization that you create and centrally manage.

  • AWS Secrets Manager 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 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 repository. It includes the sample code and Jira workflow for this solution.

Epics

TaskDescriptionSkills required

Import the workflow.

As an administrator in Jira, import the issue-workflow.xml file to your Jira Server instance. This file can be found in the aws-securityhub-jira-software-integration repository in GitHub. For instructions, see Using XML to create a workflow (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.

  1. For your project, make sure you have identified an issue type scheme for the project. You can create a new issue type or select from an existing one, such as Bug.

  2. Assign the imported workflow to a workflow scheme according to the instructions in Activate a workflow (Jira documentation).

  3. Assign the workflow scheme to a project according to the instructions in Associate a workflow scheme with a project (Jira documentation).

Jira administrator
TaskDescriptionSkills required

Configure the solution parameters.

  1. In the conf folder, open params_prod.shfile.

  2. Provide values for the following parameters:

    • ORG_ACCOUNT_ID – The account ID for your AWS Organizations management account. The solution reads account tags and assigns tickets to the specific security contacts defined in those AWS account tags.

    • ORG_ROLE – The name of the IAM role used to access the AWS Organization management account. This role must have OrganizationsReadOnlyAccess permissions.

    • EXTERNAL_ID – An optional parameter if you are using an external ID to assume the IAM role defined in ORG_ROLE. For more information, see How to use an external ID (IAM documentation).

    • JIRA_DEFAULT_ASSIGNEE – This is the Jira ID for default assignee for all Security Issues. This default assigned is used in case account is not tagged properly or role cannot be assumed.

    • JIRA_INSTANCE – The HTTPS address for your Jira server in the following format: team-<team-id>.atlassian.net/

    • JIRA_PROJECT_KEY – The name of the Jira project key used to create tickets, such as SEC or TEST. This project must already exist in Jira. 

    • ISSUE_TYPE –  The name of the issue type scheme assigned to the project in Jira, such as Bug or Security Issue.

    • REGIONS – List of AWS Region codes where you want to deploy this solution, such as eu-west-1.

  3. Save and close the solution parameter file.

AWS systems administrator

Identify the findings you want to automate.

  1. Open the Security Hub console at https://console.aws.amazon.com/securityhub/

  2. In the Security Hub navigation pane, choose Findings.

  3. Choose the finding title.

  4. Choose the finding ID. This displays the complete JSON for the finding.

  5. In the JSON, copy the string in the GeneratorId field. This value is in AWS Security Finding Format (ASFF). For example, aws-foundational-security-best-practices/v/1.0.0/S3.1 corresponds to findings from the security control S3.1 S3 Block Public Access setting should be enabled.

  6. Repeat these steps until you have copied all of the GeneratorID values for any findings you want to automate.

Add the findings to the configuration file.

  1. In src/code, open the config.jsonconfig file.

  2. Paste the GeneratorID values you retrieved in the previous story into the default parameter, and use commas to separate each ID.

  3. Save and close the configuration file.

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
     ]
    } 
 }
Note

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 IAM-related controls.

AWS systems administrator
TaskDescriptionSkills required

Deploy the integration.

In a command line terminal, enter the following command:

./deploy.sh prod
AWS systems administrator

Upload Jira credentials to AWS Secrets Manager.

  1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

  2. Under Secrets, choose Store a new secret.

  3. For Secret type, choose Other type of secret.

  4. If you are using Jira Enterprise, for Key/value pairs, do the following:

    • In the first row, enter auth in the key box, and then enter token_auth in the value box.

    • Add a second row, enter token in the key box, and then enter your personal access token in the value box.

    If you are using Jira Cloud, for Key/value pairs, do the following:

    • In the first row, enter auth in the key box, and then enter basic_auth in the value box.

    • Add a second row, enter token in the key box, and then enter your API token in the value box.

    • Add a third row, enter email in the key box, and then enter your email address in the value box.

  5. Choose Next.

  6. For Secret name, enter Jira-Token, and then at the bottom of the page, choose Next.

  7. On the Secret rotation page, keep Disable automatic rotation, and then at the bottom of the page, choose Next.

  8. On the Review page, review the secret details, and then choose Store.

AWS systems administrator

Create the Security Hub custom action.

  1. For each AWS Region, in the AWS Command Line Interface (AWS CLI), use the create-action-target command to create a Security Hub custom action named CreateJiraIssue.

    aws securityhub create-action-target --name "CreateJiraIssue" \
 --description "Create ticket in JIRA" \
 --id "CreateJiraIssue"
--region $<aws-region>

  2. Open the Security Hub console at https://console.aws.amazon.com/securityhub/.

  3. In the Security Hub navigation pane, choose Findings.

  4. In the list of findings, select the findings you want to escalate.

  5. In the Actions menu, choose CreateJiraIssue.

AWS systems administrator

Related resources

Additional information

Example of a Jira ticket

When a specified Security Hub 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 :: <AWS account ID> :: <Security Hub finding title>

  • 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 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.

<Link to Security Hub finding>

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.