Merge branch 'main' into configRole

Author: cyphronix

aws_sra_examples/docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md

@@ -4,16 +4,28 @@ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-
 
 ---
 
+CfCT is a deployment mechanism for SRA solutions within Control Tower enabled AWS environments.
+The requisite [SRA solution configuration files](https://github.com/aws-samples/aws-security-reference-architecture-examples/tree/main/aws_sra_examples/solutions) are stored in either CodeCommit (deprecated service) or S3 and programmatically configured in AWS with a CodePipeline. Whether you're using the sra-easy-setup deployment method or deploying SRA controls ADHOC, the CfCT deployment mechanism makes managing and customizing SRA solutions easier.
+
+
 ## Table of Contents<!-- omit in toc -->
 
 - [Prerequisites](#prerequisites)
+  - [Deploy Control Tower](#deploy-control-tower)
   - [Create the AWSControlTowerExecution IAM Role](#create-the-awscontroltowerexecution-iam-role)
   - [Deploy Customizations for AWS Control Tower (CFCT) Solution](#deploy-customizations-for-aws-control-tower-cfct-solution)
   - [AWS CodeCommit Repo](#aws-codecommit-repo)
+  - [AWS S3 Repo](#aws-s3-repo)
+  - [Configure SRA Deployment Repo](#configue-your-sra-deployment-repo)
 - [References](#references)
 
+
 ## Prerequisites
 
+### Deploy Control Tower
+
+- These customizations act on existing Control Tower deployments. For more details on Control Tower and Landing Zone deployments, see the [userguide](https://docs.aws.amazon.com/controltower/latest/userguide/quick-start.html).
+
 ### Create the AWSControlTowerExecution IAM Role
 
 - The `AWSControlTowerExecution` Role provides the support needed to deploy solutions to the `management account` across regions as CloudFormation `StackSets` and it is required for the SRA CFCT solution deployments.
@@ -27,18 +39,31 @@ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-
     <!-- markdownlint-disable-next-line MD034 -->
     - `Amazon S3 URL` = https://s3.amazonaws.com/solutions-reference/customizations-for-aws-control-tower/latest/custom-control-tower-initiation.template
     - `Stack name` = custom-control-tower-initiation
-    - `AWS CodePipeline Source` = AWS CodeCommit
+    - `AWS CodePipeline Source` = AWS CodeCommit | S3
     - `Failure Tolerance Percentage` = 0
     - Acknowledge that AWS CloudFormation might create IAM resources with custom names
 
 Note: Version 2 or higher of CfCT is expected.
 
 ### AWS CodeCommit Repo
+*Note: AWS CodeCommit is being deprecated and cannot be deployed to new environments, unless that environment is a part of an AWS Organization with an account that already has CodeCommit deployed. Please see [AWS S3 Repo](#aws-s3-repo) for new AWS Accounts.*
+
+Create a CodeCommit repo for SRA customization [configuration files](#deployment-instructions).
 
 1. On the local machine install [git](https://git-scm.com/downloads) and [git-remote-codecommit](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-connect.html).
 2. Clone the AWS CodeCommit repository via `git clone codecommit::<HOME REGION>://custom-control-tower-configuration custom-control-tower-configuration`
 
+### AWS S3 Repo
+
+Create a CodeCommit repo for SRA cusotmization [configuration files](#deployment-instructions).
+
+- By default, the CodePipeline deployed from the custom-control-tower-initiation CloudFormation will use the `custom-control-tower-configuration-<< ACCOUNT NAME >>-<< REGION NAME >>` S3 bucket as a Source repo. Additionally, it will look for the `custom-control-tower-configuration.zip` file. The pipeline will fail without it. We have provided users with an example `_custom-control-tower-configuration.zip` file in S3 with an example repo for convenience.
+
+- If you would like to change the S3 bucket Source for the CodePipeline, you will need to navigate to the CodePipeline within the AWS console, edit the Source stage for the CodePipeline and update the Bucket name value. Users can also modify the S3 object key value if the ZIP filename differs from default.
+
+
 ## Deployment Instructions<!-- omit in toc -->
+*Note: these instructions assume version 2 or higher of the CfCT solution has been installed.*  
 
 1. Determine which version of the [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/) solution you have deployed:
    1. Within the `management account (home region)` find the **CloudFormation Stack** for the Customizations for Control Tower (e.g. `custom-control-tower-initiation`)
@@ -48,18 +73,59 @@ Note: Version 2 or higher of CfCT is expected.
       2. Version 2 = v2.x.x = manifest.yaml version 2021-03-15
 2. If version 2 is installed, continue to the deployment instructions below.  If not, you will need to update your version of CfCT.
 
-#### Deployment Instructions<!-- omit in toc -->
 
-Note: these instructions assume version 2 or higher of the CfCT solution has been installed.
+##### Configue Your SRA Deployment Repo
+
+SRA Customizations with CfCT are deployed via a CodePipeline from either a CodeCommit or S3 source. 
+Here's an example of an repo for sra-easy-deploy.yaml deployment with controls/parameters for GuardDuty.
+
+> ├── manifest.yaml  
+> |  
+> ├── templates  
+> │   └── sra-easy-setup.yaml  
+> |  
+> ├── parameters  
+> │   └── sra-guardduty-org-main-ssm.json  
+> |  
+> ├── policies  
+
+
+###### manifest.yaml file [**required**]
+
+The manifest file will contain all the high level SRA controls that will be deployed to your environment.
+An example manifest file for [sra-easy-setup.yaml](https://github.com/aws-samples/aws-security-reference-architecture-examples/blob/main/aws_sra_examples/easy_setup/customizations_for_aws_control_tower/manifest.yaml)
+
+   - Define all `parameters`, `organizational unit names`, `account names` and `SSM parameters` necessary for the SRA controls that you want to enable and configure here.
+
+   - If you are using a non-standard file structure in your Repo, as outlined above, the [*resource_file* key](https://github.com/aws-samples/aws-security-reference-architecture-examples/blob/main/aws_sra_examples/easy_setup/customizations_for_aws_control_tower/manifest.yaml#L13C5-L13C49) value in your manifest file must reflect the path to your template.
+
+   - Be sure to update the [*accounts* key](https://github.com/aws-samples/aws-security-reference-architecture-examples/blob/main/aws_sra_examples/easy_setup/customizations_for_aws_control_tower/manifest.yaml#L310) to reflect your Management Account name.
+   
+###### templates [**required**]
+
+The templates directory will contain the actual CloudFormation files that are defined within the manifest file.
+We use the sra-easy-setup deployment method as an example for the manifest above, [here's](https://github.com/aws-samples/aws-security-reference-architecture-examples/blob/main/aws_sra_examples/easy_setup/templates/sra-easy-setup.yaml) what the template file looks like.
+
+You can also deploy SRA solutions ADHOC, without the sra-easy-setup, by including their corresponding manifest CFN template entry under the resources list for your manifest.yaml file. Exmaples of manifest files for supported solutions can be found within the `aws_sra_examples` repo [aws_sra_examples/solutions/<< SOLUTION NAME >>/customizations_for_aws_control_tower/manifest.yaml](https://github.com/aws-samples/aws-security-reference-architecture-examples/tree/main/aws_sra_examples/solutions).
+
+   - You shouldn't need to modify much in this template file as all SRA controls and parameters are defined in the manifest and files under the parameters directory, respectively.
+
+###### policies [optional] 
+
+Service control policy JSON files go here. The files under the Policies directory will depend on what SRA controls that you're deploying to your environment. Not all SRA controls will require policies defined here.
+
+###### parameters [optional]
+
+Service control parameter JSON files go here. The files under the Parameters directory will depend on what SRA controls that you're deploying to your environment. Not all SRA controls will require parameters defined here.
+
+Above, we used the [sra-guardduty-org-main-ssm.json](https://github.com/aws-samples/aws-security-reference-architecture-examples/blob/main/aws_sra_examples/solutions/guardduty/guardduty_org/customizations_for_aws_control_tower/parameters/sra-guardduty-org-main-ssm.json) parameters file as an example for our sra-easy-setup deploying GuardDuty controls in AWS. 
+
+You can find examples of parameter files for each security solution that we support within the `aws_sra_examples` repo [aws_sra_examples/solutions/<< SOLUTION NAME >>/customizations_for_aws_control_tower/parameters/](https://github.com/aws-samples/aws-security-reference-architecture-examples/tree/main/aws_sra_examples/solutions).
+
+
+##### Push To CodeCommit or S3
+*Note: If you are using S3, the files above will need to be ZIPPED up and named `custom-control-tower-configuration`.*
 
-1. Copy the files to the Customizations for AWS Control Tower configuration `custom-control-tower-configuration`
-   - policies [optional]
-     - service control policies files (\*.json)
-   - templates [**required**]
-     - Copy the template files from the `templates` folder that are referenced in the `manifest.yaml`
-2. Update the manifest.yaml file with the `parameters`, `organizational unit names`, `account names` and `SSM parameters` for the target environment
-   - *Be sure to update `deployment_targets` `accounts` with your management account information*
-3. Deploy the Customizations for AWS Control Tower configuration by pushing the code to the `AWS CodeCommit` repository or uploading to the `AWS S3 Bucket`
 
 ### Delete Instructions<!-- omit in toc -->
 
@@ -72,6 +138,7 @@ Note: these instructions assume version 2 or higher of the CfCT solution has bee
    1. Delete the Stack Instances from the `CustomControlTower-<solution_name>*` CloudFormation StackSets
    2. After the Stack Instances are deleted, delete the `CustomControlTower-<solution_name>*` CloudFormation StackSets
 
+
 ## References
 
-- [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/)
+- [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/)

aws_sra_examples/modules/guardduty-org-module/templates/sra-guardduty-org-module-main.yaml

@@ -1203,9 +1203,9 @@ Outputs:
   oPublishingDestinationBucketArn:
     Description: Publishing Destination Bucket Name
     Value: !GetAtt [rGuardDutySolutionStack, Outputs.oPublishingDestinationBucketArn]
-  oGuardDutyDeliveryKeyArn:
-    Description: GuardDuty Delivery KMS Key ARN
-    Value: !GetAtt [rGuardDutySolutionStack, Outputs.oGuardDutyDeliveryKeyArn]
+  # oGuardDutyDeliveryKeyArn:
+  #   Description: GuardDuty Delivery KMS Key ARN
+  #   Value: !GetAtt [rGuardDutySolutionStack, Outputs.oGuardDutyDeliveryKeyArn]
   oAuditAccountId:
     Description: Audit Account ID
     Value: !GetAtt rGetCommonOutputsCustomResource.oAuditAccountId

aws_sra_examples/modules/guardduty-org-module/templates/sra-guardduty-org-solution.yaml

@@ -967,7 +967,7 @@ Outputs:
     Condition: cDeployGuardDutySolution
     Description: Publishing Destination Bucket Name
     Value: !GetAtt [rGuardDutySolutionStack, Outputs.oPublishingDestinationBucketArn]
-  oGuardDutyDeliveryKeyArn:
-    Condition: cDeployGuardDutySolution
-    Description: GuardDuty Delivery KMS Key ARN
-    Value: !GetAtt [rGuardDutySolutionStack, Outputs.oGuardDutyDeliveryKeyArn]
+  # oGuardDutyDeliveryKeyArn:
+  #   Condition: cDeployGuardDutySolution
+  #   Description: GuardDuty Delivery KMS Key ARN
+  #   Value: !GetAtt [rGuardDutySolutionStack, Outputs.oGuardDutyDeliveryKeyArn]

aws_sra_examples/solutions/ami_bakery/ami_bakery_org/lambda/src/codepipeline.py

@@ -90,7 +90,7 @@ def create_codepipeline(
         "roleArn": "arn:" + aws_partition + ":iam::" + account_id + ":role/" + codepipeline_role_name,
         "artifactStore": {"type": "S3", "location": bucket_name},
         "stages": [
-            {
+            {  # type: ignore
                 "name": pipeline_name + "-CodeCommitSource",
                 "actions": [
                     {
@@ -104,7 +104,7 @@ def create_codepipeline(
                     }
                 ],
             },
-            {
+            {  # type: ignore
                 "name": pipeline_name + "-DeployEC2ImageBuilder",
                 "actions": [
                     {

aws_sra_examples/solutions/config/config_org/lambda/src/config.py

@@ -92,7 +92,7 @@ def set_config_in_org(
     configuration_recorder: ConfigurationRecorderTypeDef = {
         "name": recorder_name,
         "roleARN": role_arn,
-        "recordingGroup": {
+        "recordingGroup": {  # type: ignore
             "allSupported": all_supported,
             "includeGlobalResourceTypes": include_global_resource_types,
             "resourceTypes": resource_types,

aws_sra_examples/solutions/guardduty/guardduty_org/templates/sra-guardduty-org-configuration.yaml

@@ -219,11 +219,19 @@ Parameters:
     Default: sra-guardduty-org-lambda
     Description: GuardDuty configuration Lambda role name
     Type: String
+# Turn this into a parameter as a default value instead.
   pKMSKeyArn:
     AllowedPattern: '^arn:(aws[a-zA-Z-]*)?:kms:[a-z0-9-]+:\d{12}:key\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$'
     ConstraintDescription: 'Key ARN example:  arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
     Description: Logging S3 bucket KMS Key ARN
     Type: String
+  # pKMSKeyArn:
+  #   AllowedPattern: ^([\w.-]{1,900})$|^(\/[\w.-]{1,900})*[\w.-]{1,900}$
+  #   ConstraintDescription:
+  #     Must be alphanumeric or special characters [., _, -]. In addition, the slash character ( / ) used to delineate hierarchies in parameter names.
+  #   Default: /sra/guardduty_org_delivery_key_arn
+  #   Description: SSM Parameter for Guard Duty delivery key ARN.
+  #   Type: AWS::SSM::Parameter::Value<String>
   pLambdaLogGroupKmsKey:
     AllowedPattern: '^$|^arn:(aws[a-zA-Z-]*){1}:kms:[a-z0-9-]+:\d{12}:key\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$'
     ConstraintDescription: 'Key ARN example:  arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
@@ -551,6 +559,7 @@ Resources:
       DISABLE_GUARD_DUTY: !Ref pDisableGuardDuty
       ENABLED_REGIONS: !Ref pEnabledRegions
       FINDING_PUBLISHING_FREQUENCY: !Ref pFindingPublishingFrequency
+      # KMS_KEY_ARN: !Sub '{{resolve:ssm:arn:${AWS::Partition}:ssm:${AWS::Region}:${pDelegatedAdminAccountId}:parameter/sra/guardduty_org_delivery_key_arn}}'
       KMS_KEY_ARN: !Ref pKMSKeyArn
       PUBLISHING_DESTINATION_BUCKET_ARN: !Sub arn:${AWS::Partition}:s3:::${pPublishingDestinationBucketName}
       SNS_TOPIC_ARN: !Ref rGuardDutyOrgTopic

aws_sra_examples/solutions/guardduty/guardduty_org/templates/sra-guardduty-org-delivery-kms-key.yaml

@@ -17,7 +17,6 @@ Metadata:
           default: General Properties
         Parameters:
           - pSRASolutionName
-          - pSRASecretsKeyAliasArn
 
       - Label:
           default: KMS Key Properties
@@ -33,8 +32,6 @@ Metadata:
         default: Organization Management Account ID
       pLogArchiveAccountId:
         default: Log Archive Account ID
-      pSRASecretsKeyAliasArn:
-        default: (Optional) SRA Secrets Manager KMS Key Alias ARN
       pSRASolutionName:
         default: SRA Solution Name
 
@@ -54,20 +51,12 @@ Parameters:
     ConstraintDescription: Must be 12 digits
     Description: Management Account ID
     Type: String
-  pSRASecretsKeyAliasArn:
-    AllowedPattern: '^$|^arn:(aws[a-zA-Z-]*)?:kms:[a-z0-9-]+:\d{12}:alias\/[a-zA-Z0-9/_-]+$'
-    ConstraintDescription: 'Key Alias ARN example:  arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias'
-    Description: (Optional) SRA Secrets Manager KMS Key Alias ARN
-    Type: String
   pSRASolutionName:
     AllowedValues: [sra-guardduty-org]
     Default: sra-guardduty-org
     Description: The SRA solution name. The default value is the folder name of the solution
     Type: String
 
-Conditions:
-  cCreateSecret: !Not [!Equals [!Ref pSRASecretsKeyAliasArn, '']]
-
 Resources:
   rGuardDutyDeliveryKey:
     Type: AWS::KMS::Key
@@ -138,50 +127,18 @@ Resources:
         - Key: sra-solution
           Value: !Ref pSRASolutionName
 
-  rGuardDutyDeliveryKeyAlias:
-    Type: AWS::KMS::Alias
-    Properties:
-      AliasName: !Sub alias/${pGuardDutyOrgDeliveryKeyAlias}
-      TargetKeyId: !Ref rGuardDutyDeliveryKey
-
-  rGuardDutyDeliveryKeySecret:
-    Type: AWS::SecretsManager::Secret
-    Condition: cCreateSecret
-    Metadata:
-      checkov:
-        skip:
-          - id: CKV_AWS_149
-            comment: A cross-account KMS Key is used
+  rGuardDutyDeliveryKeyParameter:
+    Type: AWS::SSM::Parameter
+    DeletionPolicy: Retain
     Properties:
-      Name: sra/guardduty_org_delivery_key_arn
+      Name: /sra/guardduty_org_delivery_key_arn
+      Type: String
+      Value: !Sub '{"GuardDutyDeliveryKeyArn":"${rGuardDutyDeliveryKey.Arn}"}'
       Description: GuardDuty Delivery KMS Key ARN
-      SecretString: !Sub '{"GuardDutyDeliveryKeyArn":"${rGuardDutyDeliveryKey.Arn}"}'  # checkov:skip=CKV_SECRET_6
-      KmsKeyId: !Ref pSRASecretsKeyAliasArn
       Tags:
-        - Key: sra-solution
-          Value: !Ref pSRASolutionName
+        sra-solution: !Ref pSRASolutionName
 
-  rGuardDutyDeliveryKeySecretPolicy:
-    Type: AWS::SecretsManager::ResourcePolicy
-    Condition: cCreateSecret
-    Properties:
-      BlockPublicPolicy: True
-      SecretId: !Ref rGuardDutyDeliveryKeySecret
-      ResourcePolicy:
-        Version: 2012-10-17
-        Statement:
-          - Action: secretsmanager:GetSecretValue # checkov:skip=CKV_SECRET_6
-            Effect: Allow
-            Principal:
-              AWS:
-                - !Sub arn:${AWS::Partition}:iam::${pManagementAccountId}:root
-            Resource: '*'
-            Condition:
-              ForAnyValue:StringEquals:
-                secretsmanager:VersionStage: AWSCURRENT
 Outputs:
   oGuardDutyDeliveryKeyArn:
     Description: GuardDuty Delivery KMS Key ARN
-    Value: !GetAtt rGuardDutyDeliveryKey.Arn
-    # Export:
-    #   Name: eGuardDutyDeliveryKeyArn
+    Value: !GetAtt rGuardDutyDeliveryKey.Arn