Updated CloudTrail solution to enable Delegated Administrator (#159)

* updated cloudtrail solution to enable delegated administrator

* linting fixes

---------

Co-authored-by: ievgeniia ieromenko <ieviero@amazon.com>

Author: IevIe

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Table of Contents<!-- omit in toc -->
 
 - [Introduction](#introduction)
+- [2023-07-01](#2023-07-07)
 - [2023-07-01](#2023-07-01)
 - [2023-06-21](#2023-06-21)
 - [2023-06-20](#2023-06-20)
@@ -41,6 +42,12 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## 2023-07-07
+
+### Changed<!-- omit in toc -->
+
+- Updated [CloudTrail](https://github.com/aws-samples/aws-security-reference-architecture-examples/tree/main/aws_sra_examples/solutions/cloudtrail/cloudtrail_org) solution to enable delegated administrator. 
+
 ## 2023-07-01
 
 ### Changed<!-- omit in toc -->

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/README.md

@@ -12,8 +12,7 @@ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-
 
 ## Introduction
 
-The Organization CloudTrail solution will create an Organization CloudTrail within the Organization Management Account that is encrypted with a Customer Managed KMS Key managed in the Audit Account and logs delivered to the Log Archive Account. An
-Organization CloudTrail logs all events for all AWS accounts in the AWS Organization.
+The Organization CloudTrail solution will create an Organization CloudTrail within the Organization Management Account and delegate administration to a member account (e.g. Audit or Security Tooling). The Organization CloudTrail is encrypted with a Customer Managed KMS Key managed in the Audit Account and logs delivered to the Log Archive Account. An Organization CloudTrail logs all events for all AWS accounts in the AWS Organization.
 
 When you create an organization trail, a trail with the name that you give it will be created in every AWS account that belongs to your organization. Users with CloudTrail permissions in member accounts will be able to see this trail when they log
 into the AWS CloudTrail console from their AWS accounts, or when they run AWS CLI commands such as describe-trail. However, users in member accounts will not have sufficient permissions to delete the organization trail, turn logging on or off, change
@@ -39,27 +38,34 @@ The solution default configuration deploys an Organization CloudTrail enabling o
 
 - The Lambda Function contains logic for configuring the AWS Organization CloudTrail within the `management account`.
 
-#### 1.3 Lambda Execution IAM Role<!-- omit in toc -->
+#### 1.3 Lambda Layer<!-- omit in toc -->
+
+- The python boto3 SDK lambda layer to enable capability for lambda to enable delegated administrator for CloudTrail service.
+- This is downloaded during the deployment process and packaged into a layer that is used by the lambda function in this solution.
+- The CloudTrail API available in the current lambda environment (as of 06/6/2023) is boto3-1.20.32, however, enhanced functionality of the CloudTrail API used in this solution requires at least 1.26.4 (see references below).
+- Note: Future revisions to this solution will remove this layer when boto3 is updated within the lambda environment.
+
+#### 1.4 Lambda Execution IAM Role<!-- omit in toc -->
 
 - The AWS Lambda Function Role allows the AWS Lambda service to assume the role and perform actions defined in the attached IAM policies.
 
-#### 1.4 Lambda CloudWatch Log Group<!-- omit in toc -->
+#### 1.5 Lambda CloudWatch Log Group<!-- omit in toc -->
 
 - All the `AWS Lambda Function` logs are sent to a CloudWatch Log Group `</aws/lambda/<LambdaFunctionName>` to help with debugging and traceability of the actions performed.
 - By default the `AWS Lambda Function` will create the CloudWatch Log Group with a `Retention` (14 days) and are encrypted with a CloudWatch Logs service managed encryption key.
 
-#### 1.5 Organization CloudTrail<!-- omit in toc -->
+#### 1.6 Organization CloudTrail<!-- omit in toc -->
 
 - AWS CloudTrail for all AWS Organization accounts
 - Member accounts are automatically added and cannot modify
 - Data events can be disabled via the parameters
 - CloudWatch logs can be disabled via the parameters
 
-#### 1.6 Organization CloudTrail CloudWatch Log Group Role<!-- omit in toc -->
+#### 1.7 Organization CloudTrail CloudWatch Log Group Role<!-- omit in toc -->
 
 - IAM role used to send CloudTrail logs to the CloudWatch log group
 
-#### 1.7 Organization CloudTrail CloudWatch Log Group<!-- omit in toc -->
+#### 1.8 Organization CloudTrail CloudWatch Log Group<!-- omit in toc -->
 
 - Contains the CloudTrail logs with a `Retention` (400 days)
 
@@ -82,6 +88,10 @@ populated from the `SecurityAccountId` parameter within the `AWSControlTowerBP-B
 
 - AWS Secrets Manager secret containing the customer managed KMS key ARN
 
+#### 2.4 CloudTrail (Delegated admin)<!-- omit in toc -->
+
+- Delegated administrator account has administrative permissions on all trails and event data stores in the organization.
+
 ---
 
 ### 3.0 Security Log Archive Account<!-- omit in toc -->
@@ -185,3 +195,6 @@ In the `management account (home region)`, launch an AWS CloudFormation **Stack*
 
 - [Creating a CloudTrail for the Organization](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html)
 - [Allowing Cross-Account Access to a KMS Key](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html)
+- [Organization delegated administrator](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-delegated-administrator.html)
+- [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html)
+- [Python Boto3 SDK changelog](https://github.com/boto/boto3/blob/develop/CHANGELOG.rst)

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/documentation/sra-cloudtrail-org.png

@@ -23,6 +23,7 @@
     from aws_lambda_typing.events import CloudFormationCustomResourceEvent
     from mypy_boto3_cloudtrail.client import CloudTrailClient
     from mypy_boto3_cloudtrail.type_defs import DataResourceTypeDef, EventSelectorTypeDef
+    from mypy_boto3_organizations.client import OrganizationsClient
 
 # Setup Default Logger
 LOGGER = logging.getLogger(__name__)
@@ -39,11 +40,80 @@
 try:
     management_account_session = boto3.Session()
     CLOUDTRAIL_CLIENT: CloudTrailClient = management_account_session.client("cloudtrail", config=BOTO3_CONFIG)
+    ORG_CLIENT: OrganizationsClient = management_account_session.client("organizations")
 except Exception:
     LOGGER.exception(UNEXPECTED)
     raise ValueError("Unexpected error executing Lambda function. Review CloudWatch logs for details.") from None
 
 
+def list_delegated_administrator(delegated_admin_account_id: str, service_principal: str) -> None:
+    """Check if the delegated administrator account for the provided service principal exists.
+
+    Args:
+        delegated_admin_account_id: Delegated Administrator Account ID
+        service_principal: AWS Service Principal
+
+    Raises:
+        ValueError: Error registering the delegated administrator account
+    """
+    LOGGER.info(f"Checking if delegated administrator already registered for: {service_principal}")
+
+    try:
+        delegated_administrators = ORG_CLIENT.list_delegated_administrators(ServicePrincipal=service_principal)
+
+        if not delegated_administrators:
+            LOGGER.info(f"The delegated administrator {service_principal} was not registered")
+            raise ValueError("Error registering the delegated administrator account")
+    except ORG_CLIENT.exceptions.AccountAlreadyRegisteredException:
+        LOGGER.debug(f"Account: {delegated_admin_account_id} already registered for {service_principal}")
+
+
+def set_delegated_admin(delegated_admin_account_id: str) -> None:
+    """Set the delegated admin account.
+
+    Args:
+        delegated_admin_account_id: Admin account ID
+
+    Raises:
+        Exception: raises exception as e
+    """
+    try:
+        delegated_admin_response = CLOUDTRAIL_CLIENT.register_organization_delegated_admin(MemberAccountId=delegated_admin_account_id)
+        api_call_details = {"API_Call": "cloudtrail:RegisterOrganizationDelegatedAdmin", "API_Response": delegated_admin_response}
+        LOGGER.info(api_call_details)
+        LOGGER.info(f"Delegated admin ({delegated_admin_account_id}) enabled")
+    except CLOUDTRAIL_CLIENT.exceptions.AccountRegisteredException:
+        LOGGER.info("Delegated admin already registered")
+    except Exception as e:
+        LOGGER.error(f"Failed to enable delegated admin. {e}")
+        raise
+
+
+def deregister_delegated_administrator(delegated_admin_account_id: str, service_principal: str) -> None:
+    """Deregister the delegated administrator account for the provided service principal.
+
+    Args:
+        delegated_admin_account_id: Delegated Administrator Account ID
+        service_principal: AWS Service Principal format: service_name.amazonaws.com
+
+    """
+    LOGGER.info(f"Deregistering AWS Service Access for: {service_principal}")
+
+    try:
+        delegated_admin_response = CLOUDTRAIL_CLIENT.deregister_organization_delegated_admin(DelegatedAdminAccountId=delegated_admin_account_id)
+        api_call_details = {"API_Call": "cloudtrail:DeregisterOrganizationDelegatedAdmin", "API_Response": delegated_admin_response}
+        LOGGER.info(api_call_details)
+        LOGGER.info(f"Delegated admin ({delegated_admin_account_id}) deregistered")
+        delegated_administrators = ORG_CLIENT.list_delegated_administrators(ServicePrincipal=service_principal)
+
+        LOGGER.debug(str(delegated_administrators))
+
+        if not delegated_administrators:
+            LOGGER.info(f"The deregister was successful for the {service_principal} delegated administrator")
+    except ORG_CLIENT.exceptions.AccountNotRegisteredException:
+        LOGGER.info(f"Account: {delegated_admin_account_id} not registered for {service_principal}")
+
+
 def get_data_event_config(
     aws_partition: str, enable_data_events_only: bool, enable_s3_data_events: bool, enable_lambda_data_events: bool
 ) -> EventSelectorTypeDef:
@@ -72,19 +142,20 @@ def get_data_event_config(
             "IncludeManagementEvents": True,
             "DataResources": [],
         }
-
+    event_list: list = []
     if enable_s3_data_events:
         s3_data_resource: DataResourceTypeDef = {"Type": "AWS::S3::Object", "Values": [f"arn:{aws_partition}:s3:::"]}
-        event_selectors["DataResources"].append(s3_data_resource)
+        event_list.append(s3_data_resource)
         LOGGER.info("S3 Data Events Added to Event Selectors")
 
     if enable_lambda_data_events:
         lambda_data_resource: DataResourceTypeDef = {
             "Type": "AWS::Lambda::Function",
             "Values": [f"arn:{aws_partition}:lambda"],
         }
-        event_selectors["DataResources"].append(lambda_data_resource)
+        event_list.append(lambda_data_resource)
         LOGGER.info("Lambda Data Events Added to Event Selectors")
+    event_selectors["DataResources"] = event_list
 
     return event_selectors
 
@@ -173,9 +244,14 @@ def get_validated_parameters(event: CloudFormationCustomResourceEvent) -> dict:
     )
     parameter_pattern_validator("S3_BUCKET_NAME", params.get("S3_BUCKET_NAME"), pattern=r"^[0-9a-zA-Z]+([0-9a-zA-Z-]*[0-9a-zA-Z])*$")
     parameter_pattern_validator("SRA_SOLUTION_NAME", params.get("SRA_SOLUTION_NAME"), pattern=r"^.{1,256}$")
-    parameter_pattern_validator("ENABLE_S3_DATA_EVENTS", params.get("ENABLE_S3_DATA_EVENTS"), pattern=true_false_pattern)
-    parameter_pattern_validator("ENABLE_LAMBDA_DATA_EVENTS", params.get("ENABLE_LAMBDA_DATA_EVENTS"), pattern=true_false_pattern)
+    parameter_pattern_validator(
+        "DELEGATED_ADMIN_ACCOUNT_ID",
+        params.get("DELEGATED_ADMIN_ACCOUNT_ID"),
+        pattern=r"^\d{12}$",
+    )
     parameter_pattern_validator("ENABLE_DATA_EVENTS_ONLY", params.get("ENABLE_DATA_EVENTS_ONLY"), pattern=true_false_pattern)
+    parameter_pattern_validator("ENABLE_LAMBDA_DATA_EVENTS", params.get("ENABLE_LAMBDA_DATA_EVENTS"), pattern=true_false_pattern)
+    parameter_pattern_validator("ENABLE_S3_DATA_EVENTS", params.get("ENABLE_S3_DATA_EVENTS"), pattern=true_false_pattern)
 
     if params.get("CLOUDWATCH_LOG_GROUP_ARN", "") or params.get("CLOUDWATCH_LOG_GROUP_ROLE_ARN", ""):
         parameter_pattern_validator(
@@ -200,6 +276,8 @@ def process_create_update(params: dict) -> None:
         params: parameters
     """
     enable_aws_service_access(AWS_SERVICE_PRINCIPAL)
+    list_delegated_administrator(params["DELEGATED_ADMIN_ACCOUNT_ID"], AWS_SERVICE_PRINCIPAL)
+    set_delegated_admin(params["DELEGATED_ADMIN_ACCOUNT_ID"])
     cloudtrail_params = {
         "cloudtrail_name": params["CLOUDTRAIL_NAME"],
         "cloudwatch_log_group_arn": params["CLOUDWATCH_LOG_GROUP_ARN"],
@@ -210,19 +288,22 @@ def process_create_update(params: dict) -> None:
     }
 
     if params["action"] == "Add":
-        CLOUDTRAIL_CLIENT.create_trail(**get_cloudtrail_parameters(True, cloudtrail_params))
+        try:
+            CLOUDTRAIL_CLIENT.create_trail(**get_cloudtrail_parameters(True, cloudtrail_params))
+        except CLOUDTRAIL_CLIENT.exceptions.TrailAlreadyExistsException:
+            LOGGER.info(f"{params['CLOUDTRAIL_NAME']} already exists.")
     elif params["action"] == "Update":
         CLOUDTRAIL_CLIENT.update_trail(**get_cloudtrail_parameters(False, cloudtrail_params))
     LOGGER.info(f"Successful {params['action']} of the Organization CloudTrail")
 
     event_selectors = get_data_event_config(
         aws_partition=params.get("AWS_PARTITION", "aws"),
         enable_data_events_only=(params.get("ENABLE_DATA_EVENTS_ONLY", "false")).lower() in "true",
-        enable_s3_data_events=(params.get("ENABLE_S3_DATA_EVENTS", "false")).lower() in "true",
         enable_lambda_data_events=(params.get("ENABLE_LAMBDA_DATA_EVENTS", "false")).lower() in "true",
+        enable_s3_data_events=(params.get("ENABLE_S3_DATA_EVENTS", "false")).lower() in "true",
     )
 
-    if event_selectors and event_selectors["DataResources"]:
+    if event_selectors:
         CLOUDTRAIL_CLIENT.put_event_selectors(TrailName=params["CLOUDTRAIL_NAME"], EventSelectors=[event_selectors])
         LOGGER.info("Data Events Enabled")
 
@@ -252,6 +333,7 @@ def process_event(event: CloudFormationCustomResourceEvent, context: Context) ->
         process_create_update(params)
     elif params["action"] == "Remove":
         try:
+            deregister_delegated_administrator(params.get("DELEGATED_ADMIN_ACCOUNT_ID", ""), AWS_SERVICE_PRINCIPAL)
             CLOUDTRAIL_CLIENT.delete_trail(Name=params["CLOUDTRAIL_NAME"])
             LOGGER.info("Deleted the Organizations CloudTrail")
         except CLOUDTRAIL_CLIENT.exceptions.TrailNotFoundException:

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/documentation/sra-cloudtrail-org.pptx

@@ -0,0 +1 @@
+boto3

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/lambda/src/app.py

@@ -301,6 +301,7 @@ Resources:
         pCloudTrailS3BucketName: !Sub '{{resolve:secretsmanager:arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${pLogArchiveAccountId}:secret:sra/cloudtrail_org_s3_bucket:SecretString:OrganizationCloudTrailS3Bucket:AWSCURRENT}}'
         pCreateCloudTrailLogGroup: !Ref pCreateCloudTrailLogGroup
         pCreateLambdaLogGroup: !Ref pCreateLambdaLogGroup
+        pDelegatedAdminAccountId: !Ref pAuditAccountId
         pEnableDataEventsOnly: !Ref pEnableDataEventsOnly
         pEnableLambdaDataEvents: !Ref pEnableLambdaDataEvents
         pEnableS3DataEvents: !Ref pEnableS3DataEvents

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/layer/boto3/package.txt

@@ -282,6 +282,7 @@ Resources:
         pCloudTrailS3BucketName: !Sub '{{resolve:secretsmanager:arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${pLogArchiveAccountId}:secret:sra/cloudtrail_org_s3_bucket:SecretString:OrganizationCloudTrailS3Bucket:AWSCURRENT}}'
         pCreateCloudTrailLogGroup: !Ref pCreateCloudTrailLogGroup
         pCreateLambdaLogGroup: !Ref pCreateLambdaLogGroup
+        pDelegatedAdminAccountId: !Ref pAuditAccountId
         pEnableDataEventsOnly: !Ref pEnableDataEventsOnly
         pEnableLambdaDataEvents: !Ref pEnableLambdaDataEvents
         pEnableS3DataEvents: !Ref pEnableS3DataEvents

aws_sra_examples/solutions/cloudtrail/cloudtrail_org/templates/sra-cloudtrail-org-main-ssm.yaml

@@ -41,6 +41,7 @@ Metadata:
           - pEnableDataEventsOnly
           - pEnableLambdaDataEvents
           - pEnableS3DataEvents
+          - pDelegatedAdminAccountId
 
       - Label:
           default: General Lambda Function Properties
@@ -67,6 +68,8 @@ Metadata:
         default: Create CloudTrail Log Group
       pCreateLambdaLogGroup:
         default: Create Lambda Log Group
+      pDelegatedAdminAccountId:
+        default: Delegated Admin Account ID
       pEnableDataEventsOnly:
         default: Enable Data Events Only
       pEnableLambdaDataEvents:
@@ -139,6 +142,11 @@ Parameters:
       Indicates whether a CloudWatch Log Group should be explicitly created for the Lambda function, to allow for setting a Log Retention and/or KMS
       Key for encryption.
     Type: String
+  pDelegatedAdminAccountId:
+    AllowedPattern: '^\d{12}$'
+    ConstraintDescription: Must be 12 digits
+    Description: Delegated administrator account ID
+    Type: String
   pEnableDataEventsOnly:
     AllowedValues: ['true', 'false']
     Default: 'true'
@@ -324,6 +332,23 @@ Resources:
                   - cloudtrail:UpdateTrail
                 Resource: !Sub arn:${AWS::Partition}:cloudtrail:${AWS::Region}:${AWS::AccountId}:trail/*
 
+              - Sid: AllowCloudTrailDelegatedAdministrator
+                Effect: Allow
+                Action:
+                  - cloudtrail:RegisterOrganizationDelegatedAdmin
+                  - cloudtrail:DeregisterOrganizationDelegatedAdmin
+                Resource: "*"
+
+              - Sid: RegisterDeregisterDelegatedAdministrator
+                Effect: Allow
+                Action:
+                  - organizations:DeregisterDelegatedAdministrator
+                  - organizations:RegisterDelegatedAdministrator
+                Condition:
+                  StringLikeIfExists:
+                    organizations:ServicePrincipal: cloudtrail.amazonaws.com
+                Resource: !Sub arn:${AWS::Partition}:organizations::*:account/o-*/*
+
         - PolicyName: cloudtrail-org-policy-organization
           PolicyDocument:
             Version: 2012-10-17
@@ -332,10 +357,19 @@ Resources:
                 Effect: Allow
                 Action:
                   - organizations:DescribeOrganization
-                  - organizations:DisableAWSServiceAccess
-                  - organizations:EnableAWSServiceAccess
                   - organizations:ListAWSServiceAccessForOrganization
                   - organizations:ListAccounts
+                  - organizations:ListDelegatedAdministrators
+                Resource: '*'
+
+              - Sid: AWSServiceAccess
+                Effect: Allow
+                Action:
+                  - organizations:DisableAWSServiceAccess
+                  - organizations:EnableAWSServiceAccess
+                Condition:
+                  StringLikeIfExists:
+                    organizations:ServicePrincipal: cloudtrail.amazonaws.com
                 Resource: '*'
 
         - PolicyName: sra-cloudtrail-org-policy-iam
@@ -408,9 +442,21 @@ Resources:
       Environment:
         Variables:
           LOG_LEVEL: !Ref pLambdaLogLevel
+          DELEGATED_ADMIN_ACCOUNT_ID: !Ref pDelegatedAdminAccountId
       Code:
         S3Bucket: !Ref pSRAStagingS3BucketName
         S3Key: !Sub ${pSRASolutionName}/lambda_code/${pSRASolutionName}.zip
+      Layers:
+        - !Ref rCloudTrailOrgLambdaLayer
+
+  rCloudTrailOrgLambdaLayer:
+    Type: AWS::Lambda::LayerVersion
+    Properties:
+      Content:
+        S3Bucket: !Ref pSRAStagingS3BucketName
+        S3Key: !Sub ${pSRASolutionName}/layer_code/${pSRASolutionName}-layer.zip
+      Description: Boto3 version layerto enable CloudTrail delegated admin
+      LayerName: !Sub ${pCloudTrailLambdaFunctionName}-updated-boto3-layer
 
   rLambdaCustomResource:
     Type: Custom::LambdaCustomResource
@@ -427,3 +473,4 @@ Resources:
       KMS_KEY_ID: !Ref pOrganizationCloudTrailKMSKeyId
       S3_BUCKET_NAME: !Ref pCloudTrailS3BucketName
       SRA_SOLUTION_NAME: !Ref pSRASolutionName
+      DELEGATED_ADMIN_ACCOUNT_ID: !Ref pDelegatedAdminAccountId