AWS prescriptive-guidance documentation change
Summary
Enhanced IAM role description for AWS Organizations access
Security assessment
Clarifies existing security configuration without changing requirements
Diff
diff --git a/prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.md b/prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.md index 3e00c1b4f..bb9e0458f 100644 --- a//prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.md +++ b//prescriptive-guidance/latest/patterns/bidirectionally-integrate-aws-security-hub-with-jira-software.md @@ -9 +9 @@ SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resourcesAddit - _Created by Joaquin Manuel Rinaudo (AWS)_ + _Created by Joaquin Rinaudo (AWS)_ @@ -13 +13 @@ SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resourcesAddit -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. +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. @@ -34 +34 @@ The solution allows you to: -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](https://creativecommons.org/licenses/by/4.0/deed.en_US). We recommend adding a Jira workflow condition so that only members of your security team can change the ticket status. +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 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. @@ -52 +52 @@ For an example of a Jira ticket automatically generated by this solution, see th - * You have a cross-account IAM role that has `AWSOrganizationsReadOnlyAccess` permissions to the AWS Organizations management account. + * You have a cross-account AWS Identity and Access Management (IAM) role that has `AWSOrganizationsReadOnlyAccess` permissions to the AWS Organizations management account. @@ -62 +62 @@ For an example of a Jira ticket automatically generated by this solution, see th - * A Jira Server instance + * A Jira Data Center instance @@ -66 +66 @@ For an example of a Jira ticket automatically generated by this solution, see th -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. +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. @@ -120 +120 @@ _Scenario 2: Developer decides to accept the risk_ - 8. A CloudWatch daily event initiates the refresh Lambda function, which identifies closed JIRA tickets and updates their related Security Hub findings as `SUPPRESSED`. + 8. A CloudWatch daily event initiates the refresh Lambda function, which identifies closed Jira tickets and updates their related Security Hub findings as `SUPPRESSED`. @@ -128,0 +129,2 @@ _Scenario 2: Developer decides to accept the risk_ +**AWS services** + @@ -152 +154 @@ Task| Description| Skills 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](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 +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 @@ -168 +170 @@ Configure the solution parameters.| - * `ORG_ROLE` – The name of the IAM role used to access the AWS Organization management account. This role must have `OrganizationsReadOnlyAccess` permissions. + * `ORG_ROLE` – The name of the IAM role used to access the AWS Organizations management account. This role must have `OrganizationsReadOnlyAccess` permissions. @@ -170,2 +172,2 @@ Configure the solution parameters.| - * `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_DEFAULT_ASSIGNEE` – This is the Jira default assignee for all security issues. This default assignee is used in case account is not tagged properly or role cannot be assumed. + * `JIRA_INSTANCE` – The HTTPS address for your Jira endpoint in the following format: `team-<team-id>.atlassian.net/` @@ -180 +182 @@ Identify the findings you want to automate.| - 1. Open the Security Hub console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/) + 1. Open the [Security Hub console](https://console.aws.amazon.com/securityhub/). @@ -184 +186 @@ Identify the findings you want to automate.| - 5. In the JSON, copy the string in the `GeneratorId` field. This value is in [AWS Security Finding Format](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.html) (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_. + 5. In the JSON, copy the string in the `GeneratorId` field. This value is in [AWS Security Finding Format (ASFF)](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.html). 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_. @@ -198,5 +200,5 @@ The following code example shows automating the `aws-foundational-security-best- - "Controls" : { - "eu-west-1": [ - "arn:aws:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0/rule/1.22" - ], - "default": [ + "Controls" : { + "eu-west-1": [ + "arn:aws:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0/rule/1.22" + ], + "default": [ @@ -205,3 +207,3 @@ The following code example shows automating the `aws-foundational-security-best- - ] - } - } + ] + } + } @@ -211 +213 @@ The following code example shows automating the `aws-foundational-security-best- -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 +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 @@ -221 +223 @@ Deploy the integration.| In a command line terminal, enter the following command -Upload Jira credentials to AWS Secrets Manager.| +Upload Jira credentials to Secrets Manager.| @@ -223,2 +225,2 @@ Upload Jira credentials to AWS Secrets Manager.| - 1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/). - 2. Under Secrets, choose **Store a new secret**. + 1. Open the [Secrets Manager console](https://console.aws.amazon.com/secretsmanager/). + 2. Under **Secrets** , choose **Store a new secret**. @@ -235,2 +237,2 @@ If you are using Jira Cloud, for **Key/value pairs** , do the following: - 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**. + 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**. @@ -248 +250 @@ Create the Security Hub custom action.| - 2. Open the Security Hub console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). + 2. Open the [Security Hub console](https://console.aws.amazon.com/securityhub/). @@ -285,3 +287,3 @@ The following is an example of an automatically generated Jira 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. + * 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.