Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: CC-BY-SA-4.0
- Overview of the Easy Setup Deployment Process
- Enable Trusted Access with AWS Organizations for StackSets
- CloudFormation Implementation Instructions
- Customizations for Control Tower Implementation Instructions
- Easy Setup Architecture Details
The current method today to deploy the common solutions and prerequisites is a multi-step process that requires the user to clone the repo, manually set some settings in organizations/CloudFormation, deploy a CFN template, run a shell script, then deploy more CFN templates. Customers have provided feedback that while this process works, it can lead to deployment delays at times because of the manual steps that are involved. Users of the AWS SRA needed a simpler way to deploy it's code library which has led to the easy setup method here.
The easy setup solution performs all of the steps in this section automatically so that you do not have to perform them on your own. This section describes, at a high level, the automated process.
The first steps in the easy setup of the AWS SRA code library is focused on the operations required to build the staging s3 bucket where the code library will be stored and the process to clone the github AWS SRA code which is then uploaded to the staging bucket.
The next steps within the easy setup of the AWS SRA code library focuses on deploying the common prerequisites solution which is provides the base resources shared and used by each of the core solutions that are provided through the AWS SRA code library (e.g. the GuardDuty AWS SRA solution, the Security Hub AWS SRA solution, etc.) See for more information
The final steps within the easy setup of the AWS SRA code library is the deployment of the individual AWS SRA solutions. Each of the AWS SRA solutions has a set of parameters defined within the AWS SRA easy setup CloudFormation template. To deploy an AWS SRA solution, set it's associated deployment parameter to 'Yes'. Each AWS SRA Solution also has a set of parameters that can be used to further customize the solutions configuration options.
For the AWS SRA deployment to work, you must enabled trusted access with AWS Organizations.
- Please follow the instructions here to do this: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-enable-trusted-access.html
- The process to implement the easy setup begins with downloading the
sra-easy-setup.yamltemplate from the repository. Then, either follow the instructions for deployment via the AWS console or by using the AWS command line interface (CLI). - Trusted Access with AWS Organizations for StackSets must be manually enabled first.
Note: all AWS CLI commands in this section are run using credentials for the management account. See https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html for more information on configuring AWS CLI
Download the sra-easy-setup.yaml template by either navigating to it in the AWS SRA code library repository, or by using the example download commands in this section.
curl -LJO https://raw.githubusercontent.com/aws-samples/aws-security-reference-architecture-examples/main/aws_sra_examples/easy_setup/templates/sra-easy-setup.yamlDeployment using the AWS console requires the template to be downloaded first (see above).
In your AWS management account, navigate to the CloudFormation service console.
In the CloudFormation service console, navigate to the stacks area.
In the stacks area, create a stack, and then select the "Upload a template file" option. Click on "Next", then follow the process to deploy the stack. Be sure to specify the appropriate parameters for the template as needed.
- IMPORTANT: If
AWS Organizationsis being used without AWS Control Tower, you must also specify the following parameter values as you create the stack:pControlTowerasfalsepLogArchiveAccountIdas the AWS Account Id of the account designated to be theLog Archiveaccount.pSecurityAccountIdas the AWS Account Id of the account designated to be theSecurity Toolingaccount.pGovernedRegionsas a list of AWS regions separated by commas
Deployment using the AWS CLI requires the template to be downloaded first.
The easy setup template is greater than 51,200 bytes, therefore, in order to deploy it via the AWS command line interface, you are required to have an S3 bucket that it can be stored in. You can do this from the AWS console, or by using the example command below.
aws s3api create-bucket --bucket [bucket name] --create-bucket-configuration LocationConstraint=[region]Prepare and run the aws cloudformation deploy command to launch the template. Use the example command below to do this.
- Be sure to alter the folder/path for the
sra-easy-setup.yamltemplate-file appropriately (replace[path to template file]) - Be sure to put in the s3 bucket name (replace
[s3 bucket name from step 1]) - Be sure to specify the proper parameter overrides and specify the alarm email address (
[email address]) - If
AWS Organizationsis being used without AWS Control Tower, you must also specify the following parameter values as you create the stack:pControlTowerasfalsepLogArchiveAccountIdas the AWS Account Id of the account designated to be theLog Archiveaccount.pSecurityAccountIdas the AWS Account Id of the account designated to be theSecurity Toolingaccount.pGovernedRegionsas a list of AWS regions separated by commas
NOTE: The example command below deploys The Guard Duty, Security Hub, and Config Management solutions (you can remove those 3 parameters or replace them with other solutions deployment parameters)
aws cloudformation deploy --template-file [path to template file]/sra-easy-setup.yaml --stack-name sra-easy-setup --s3-bucket [s3 bucket name from step 1] --capabilities CAPABILITY_NAMED_IAM --parameter-overrides pDeployGuardDutySolution=Yes pDeployConfigManagementSolution=Yes pDeploySecurityHubSolution=Yes pSRAAlarmEmail=[email address]aws cloudformation deploy --template-file [path to template file]/sra-easy-setup.yaml --stack-name sra-easy-setup --s3-bucket [s3 bucket name from step 1] --capabilities CAPABILITY_NAMED_IAM --parameter-overrides pControlTower=false pLogArchiveAccountId=<LOG_ARCHIVE_ACCOUNT_ID> pSecurityAccountId=<SECURITY_ACCOUNT_ID> pGovernedRegions=<COMMA_SEPARATED_REGIONS>From within the management account:
- Delete the
sra-easy-setupCloudFormation stack - Delete any remaining
sra-*CloudWatch log groups - Delete any remaining
/sra/*SSM Parameters - Delete any remaining
sra-*IAM roles - Delete any remaining
sra-*Lambda functions - Delete any remaining
sra-*S3 buckets
To install the AWS SRA Easy Setup solution using Customizations for Control Tower (CfCT), you must have CfCT setup, the sra-common-prerequisites-control-tower-execution-role.yaml, sra-easy-setup.yaml, and manifest.yaml template files downloaded from the code library, the AWSControlTowerExecution role created in the management account, the sra-easy-setup.yaml file committed to the codecommit repo under the templates folder, and the manifest.yaml file updated appropriately. Follow the instructions in this section to accomplish this.
- These instructions are assuming you are using CfCT version 2. If you are using CfCT version 1, there will be other differences in implementation behavior. Please refer to Customizations for AWS Control Tower Deployment Instructions for more information on CfCT version 1 that may help you with this.
- Trusted Access with AWS Organizations for StackSets must be manually enabled.
Follow the instructions for deploying Customizations for Control Tower (CfCT) here: https://docs.aws.amazon.com/controltower/latest/userguide/step1.html
Use these options when deploying CfCT in your environment:
Stack name= custom-control-tower-initiationAWS CodePipeline Source= AWS CodeCommitFailure Tolerance Percentage= 0
A. On the local machine install git and git-remote-codecommit.
B. Clone the AWS CodeCommit repository via the following example command:
git clone codecommit::<HOME REGION>://custom-control-tower-configuration custom-control-tower-configurationDownload the sra-common-prerequisites-control-tower-execution-role.yaml AWS SRA template by either navigating to it in the AWS SRA code library repository, or by using the example download commands in this section.
curl -LJO https://raw.githubusercontent.com/aws-samples/aws-security-reference-architecture-examples/main/aws_sra_examples/solutions/common/common_prerequisites/templates/sra-common-prerequisites-control-tower-execution-role.yamlDownload the sra-easy-setup.yaml template by either navigating to it in the AWS SRA code library repository, or by using the example download commands in this section.
curl -LJO https://raw.githubusercontent.com/aws-samples/aws-security-reference-architecture-examples/main/aws_sra_examples/easy_setup/templates/sra-easy-setup.yamlDownload the manifest.yaml template by either navigating to it in the AWS SRA code library repository, or by using the example download commands in this section.
The AWS SRA Easy Setup Manifest file contains parameters to deploy AWS SRA solutions and you may update these parameters as you need.
For example, setting the pDeploySecurityHubSolution parameter to Yes will deploy the AWS SRA Security Hub solution.
There are other parameters that are related to each solution as well in the manifest file.
You can set these options during initial deployment or update them later.
You must leave the pCreateAWSControlTowerExecutionRole parameter set to false or the pipeline will fail because the AWSControlTowerExecution role will already be deployed.
curl -LJO https://raw.githubusercontent.com/aws-samples/aws-security-reference-architecture-examples/main/aws_sra_examples/easy_setup/customizations_for_aws_control_tower/manifest.yaml- Be sure to alter the folder/path for the
sra-common-prerequisites-control-tower-execution-role.yamltemplate-file you downloaded in step II.1 above appropriately (replace[path to template file])
aws CloudFormation deploy --template-file [path to template file]/sra-common-prerequisites-control-tower-execution-role.yaml --stack-name sra-common-prerequisites-control-tower-execution-role --capabilities CAPABILITY_NAMED_IAMSee Define a custom configuration in the Customizations for Control Tower (CfCT) documentation for more information about the steps within this section.
- Copy the
sra-easy-setup.yamltemplate file that was downloaded in Step II.2 above into thecustom-control-tower-configuration/templatesfolder within your locally cloned git repo (from step I.2.B above).
- Copy the
manifest.yamltemplate file that was downloaded in Step II.3 above into thecustom-control-tower-configurationfolder within your locally cloned git repo (from step I.2.B above). - Update the region so that it matches your AWS Control Tower home region.
- Update parameters to deploy and configure AWS SRA Solutions as needed.
Note: depending on your CfCT deployment, you may want to copy the contents into your manifest file instead if you have other custom configuration resources you may have already deployed.
- Perform the
git add,git commit, andgit pushoperations appropriately to commit and push these changes to the CodeCommit repo. This will start the CodePipeline process to deploy the AWS SRA Easy Setup solution.
From within the management account:
- Comment out (or remove) the
sra-easy-setupsolution resource from within themanifest.yamlfile. Then commit and push these changes to the CodeCommit repository. - Delete any remaining
sra-*CloudWatch log groups - Delete any remaining
/sra/*SSM Parameters - Delete any remaining
sra-*IAM roles - Delete any remaining
sra-*Lambda functions - Delete any remaining
sra-*S3 buckets
The entire process to deploy the common solution and pre-requisites is set in to motion by deploying a single CloudFormation template. Currently, this prototype is focused on deployment of what is needed for Module 1 (the staging of the AWS SRA code library to the staging s3 bucket in the management account). This is done by deploying the sra-common-prerequisites-staging-s3-bucket-codebuild.yaml (which in turn creates the sra-common-prerequisites-staging-s3-bucket-codebuild stack) into the management account.
The sra-codebuild AWS CodeBuild project is designed and created to perform the processes required to do a git clone operation on the AWS SRA public github repository and run the necessary operations to package and upload it to the AWS SRA code library staging S3 bucket.
The sra-clone-library AWS Lambda function is designed and created to perform the start operation for the sra-codebuild AWS CodeBuild project.
The sra-clone-library AWS Lambda function perform the start operation for the sra-codebuild AWS CodeBuild project via the boto3 AWS SDK.
The AWS SRA code library common prerequisite sra-common-prerequisites-staging-s3-bucket CloudFormation stack is launched. See for more information.
The AWS SRA code library staging sra-staging-[AccountId]-[Region] Amazon S3 bucket is created along with the appropriate bucket policy in preparation to have the AWS SRA code library uploaded to it later in the process. NOTE: [AccountId] and [Region] will be replaced with the appropriate account id and region being deployed to respectively in the S3 bucket name.
The sra-codebuild AWS CodeBuild project, once started by the sra-clone-library AWS Lambda function, will perform a git clone operation on the AWS SRA public github repository to clone the AWS SRA code library into the CodeBuild execution environment.
The sra-codebuild AWS CodeBuild project, after the AWS SRA code library has been cloned, packages the cloned AWS SRA code library appropriately and then uploads it into the sra-staging-[AccountId]-[Region] Amazon S3 bucket.
The AWS SRA code library common prerequisite sra-common-prerequisites-management-account-parameters CloudFormation stack is launched. See for more information.
The AWS SRA code library common prerequisite sra-common-prerequisites-main-ssm CloudFormation stack is launched. See for more information.
Each AWS SRA solution has a deployment parameter within the easy-setup yaml CloudFormation template (e.g. pDeployGuardDutySolution and pDeploySecurityHubSolution are 2 of these deployment parameters). If a solutions deployment parameter is set to "Yes" when the easy-sra template is deployed or updated, then the appropriate AWS SRA solution stack will be created and the solution will be deployed into the AWS environment. All deployment parameters for solutions are set to "No" by default. If the parameters for AWS SRA solutions are left as default, they may be updated later as a part of an update operation to the easy-setup template parameters in order to deploy an AWS SRA solution.