#!/usr/bin/python # Copyright: Ansible Project # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = ''' --- module: cloudtrail version_added: 5.0.0 short_description: manage CloudTrail create, delete, update description: - Creates, deletes, or updates CloudTrail configuration. Ensures logging is also enabled. - This module was originally added to C(community.aws) in release 1.0.0. author: - Ansible Core Team - Ted Timmons (@tedder) - Daniel Shepherd (@shepdelacreme) options: state: description: - Add or remove CloudTrail configuration. - 'The following states have been preserved for backwards compatibility: I(state=enabled) and I(state=disabled).' - I(state=enabled) is equivalet to I(state=present). - I(state=disabled) is equivalet to I(state=absent). type: str choices: ['present', 'absent', 'enabled', 'disabled'] default: present name: description: - Name for the CloudTrail. - Names are unique per-region unless the CloudTrail is a multi-region trail, in which case it is unique per-account. type: str default: default enable_logging: description: - Start or stop the CloudTrail logging. If stopped the trail will be paused and will not record events or deliver log files. default: true type: bool s3_bucket_name: description: - An existing S3 bucket where CloudTrail will deliver log files. - This bucket should exist and have the proper policy. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/aggregating_logs_regions_bucket_policy.html). - Required when I(state=present). type: str s3_key_prefix: description: - S3 Key prefix for delivered log files. A trailing slash is not necessary and will be removed. type: str is_multi_region_trail: description: - Specify whether the trail belongs only to one region or exists in all regions. default: false type: bool enable_log_file_validation: description: - Specifies whether log file integrity validation is enabled. - CloudTrail will create a hash for every log file delivered and produce a signed digest file that can be used to ensure log files have not been tampered. type: bool aliases: [ "log_file_validation_enabled" ] include_global_events: description: - Record API calls from global services such as IAM and STS. default: true type: bool aliases: [ "include_global_service_events" ] sns_topic_name: description: - SNS Topic name to send notifications to when a log file is delivered. type: str cloudwatch_logs_role_arn: description: - Specifies a full ARN for an IAM role that assigns the proper permissions for CloudTrail to create and write to the log group. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/send-cloudtrail-events-to-cloudwatch-logs.html). - Required when C(cloudwatch_logs_log_group_arn). type: str cloudwatch_logs_log_group_arn: description: - A full ARN specifying a valid CloudWatch log group to which CloudTrail logs will be delivered. The log group should already exist. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/send-cloudtrail-events-to-cloudwatch-logs.html). - Required when C(cloudwatch_logs_role_arn). type: str kms_key_id: description: - Specifies the KMS key ID to use to encrypt the logs delivered by CloudTrail. This also has the effect of enabling log file encryption. - The value can be an alias name prefixed by "alias/", a fully specified ARN to an alias, a fully specified ARN to a key, or a globally unique identifier. - Encryption can be disabled by setting I(kms_key_id=""). - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/encrypting-cloudtrail-log-files-with-aws-kms.html). type: str notes: - The I(purge_tags) option was added in release 4.0.0 extends_documentation_fragment: - amazon.aws.aws - amazon.aws.ec2 - amazon.aws.tags - amazon.aws.boto3 ''' EXAMPLES = ''' - name: create single region cloudtrail amazon.aws.cloudtrail: state: present name: default s3_bucket_name: mylogbucket s3_key_prefix: cloudtrail region: us-east-1 - name: create multi-region trail with validation and tags amazon.aws.cloudtrail: state: present name: default s3_bucket_name: mylogbucket region: us-east-1 is_multi_region_trail: true enable_log_file_validation: true cloudwatch_logs_role_arn: "arn:aws:iam::123456789012:role/CloudTrail_CloudWatchLogs_Role" cloudwatch_logs_log_group_arn: "arn:aws:logs:us-east-1:123456789012:log-group:CloudTrail/DefaultLogGroup:*" kms_key_id: "alias/MyAliasName" tags: environment: dev Name: default - name: show another valid kms_key_id amazon.aws.cloudtrail: state: present name: default s3_bucket_name: mylogbucket kms_key_id: "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012" # simply "12345678-1234-1234-1234-123456789012" would be valid too. - name: pause logging the trail we just created amazon.aws.cloudtrail: state: present name: default enable_logging: false s3_bucket_name: mylogbucket region: us-east-1 is_multi_region_trail: true enable_log_file_validation: true tags: environment: dev Name: default - name: delete a trail amazon.aws.cloudtrail: state: absent name: default ''' RETURN = ''' exists: description: whether the resource exists returned: always type: bool sample: true trail: description: CloudTrail resource details returned: always type: complex sample: hash/dictionary of values contains: trail_arn: description: Full ARN of the CloudTrail resource returned: success type: str sample: arn:aws:cloudtrail:us-east-1:123456789012:trail/default name: description: Name of the CloudTrail resource returned: success type: str sample: default is_logging: description: Whether logging is turned on or paused for the Trail returned: success type: bool sample: True s3_bucket_name: description: S3 bucket name where log files are delivered returned: success type: str sample: myBucket s3_key_prefix: description: Key prefix in bucket where log files are delivered (if any) returned: success when present type: str sample: myKeyPrefix log_file_validation_enabled: description: Whether log file validation is enabled on the trail returned: success type: bool sample: true include_global_service_events: description: Whether global services (IAM, STS) are logged with this trail returned: success type: bool sample: true is_multi_region_trail: description: Whether the trail applies to all regions or just one returned: success type: bool sample: true has_custom_event_selectors: description: Whether any custom event selectors are used for this trail. returned: success type: bool sample: False home_region: description: The home region where the trail was originally created and must be edited. returned: success type: str sample: us-east-1 sns_topic_name: description: The SNS topic name where log delivery notifications are sent. returned: success when present type: str sample: myTopic sns_topic_arn: description: Full ARN of the SNS topic where log delivery notifications are sent. returned: success when present type: str sample: arn:aws:sns:us-east-1:123456789012:topic/myTopic cloud_watch_logs_log_group_arn: description: Full ARN of the CloudWatch Logs log group where events are delivered. returned: success when present type: str sample: arn:aws:logs:us-east-1:123456789012:log-group:CloudTrail/DefaultLogGroup:* cloud_watch_logs_role_arn: description: Full ARN of the IAM role that CloudTrail assumes to deliver events. returned: success when present type: str sample: arn:aws:iam::123456789012:role/CloudTrail_CloudWatchLogs_Role kms_key_id: description: Full ARN of the KMS Key used to encrypt log files. returned: success when present type: str sample: arn:aws:kms::123456789012:key/12345678-1234-1234-1234-123456789012 tags: description: hash/dictionary of tags applied to this resource returned: success type: dict sample: {'environment': 'dev', 'Name': 'default'} ''' try: from botocore.exceptions import ClientError, BotoCoreError except ImportError: pass # Handled by AnsibleAWSModule from ansible.module_utils.common.dict_transformations import camel_dict_to_snake_dict from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule from ansible_collections.amazon.aws.plugins.module_utils.tagging import ansible_dict_to_boto3_tag_list from ansible_collections.amazon.aws.plugins.module_utils.tagging import boto3_tag_list_to_ansible_dict from ansible_collections.amazon.aws.plugins.module_utils.tagging import compare_aws_tags def get_kms_key_aliases(module, client, keyId): """ get list of key aliases module : AnsibleAWSModule object client : boto3 client connection object for kms keyId : keyId to get aliases for """ try: key_resp = client.list_aliases(KeyId=keyId) except (BotoCoreError, ClientError): # Don't fail here, just return [] to maintain backwards compat # in case user doesn't have kms:ListAliases permissions return [] return key_resp['Aliases'] def create_trail(module, client, ct_params): """ Creates a CloudTrail module : AnsibleAWSModule object client : boto3 client connection object ct_params : The parameters for the Trail to create """ resp = {} try: resp = client.create_trail(**ct_params) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to create Trail") return resp def tag_trail(module, client, tags, trail_arn, curr_tags=None, purge_tags=True): """ Creates, updates, removes tags on a CloudTrail resource module : AnsibleAWSModule object client : boto3 client connection object tags : Dict of tags converted from ansible_dict to boto3 list of dicts trail_arn : The ARN of the CloudTrail to operate on curr_tags : Dict of the current tags on resource, if any dry_run : true/false to determine if changes will be made if needed """ if tags is None: return False curr_tags = curr_tags or {} tags_to_add, tags_to_remove = compare_aws_tags(curr_tags, tags, purge_tags=purge_tags) if not tags_to_add and not tags_to_remove: return False if module.check_mode: return True if tags_to_remove: remove = {k: curr_tags[k] for k in tags_to_remove} tags_to_remove = ansible_dict_to_boto3_tag_list(remove) try: client.remove_tags(ResourceId=trail_arn, TagsList=tags_to_remove) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to remove tags from Trail") if tags_to_add: tags_to_add = ansible_dict_to_boto3_tag_list(tags_to_add) try: client.add_tags(ResourceId=trail_arn, TagsList=tags_to_add) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to add tags to Trail") return True def get_tag_list(keys, tags): """ Returns a list of dicts with tags to act on keys : set of keys to get the values for tags : the dict of tags to turn into a list """ tag_list = [] for k in keys: tag_list.append({'Key': k, 'Value': tags[k]}) return tag_list def set_logging(module, client, name, action): """ Starts or stops logging based on given state module : AnsibleAWSModule object client : boto3 client connection object name : The name or ARN of the CloudTrail to operate on action : start or stop """ if action == 'start': try: client.start_logging(Name=name) return client.get_trail_status(Name=name) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to start logging") elif action == 'stop': try: client.stop_logging(Name=name) return client.get_trail_status(Name=name) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to stop logging") else: module.fail_json(msg="Unsupported logging action") def get_trail_facts(module, client, name): """ Describes existing trail in an account module : AnsibleAWSModule object client : boto3 client connection object name : Name of the trail """ # get Trail info try: trail_resp = client.describe_trails(trailNameList=[name]) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to describe Trail") # Now check to see if our trail exists and get status and tags if len(trail_resp['trailList']): trail = trail_resp['trailList'][0] try: status_resp = client.get_trail_status(Name=trail['Name']) tags_list = client.list_tags(ResourceIdList=[trail['TrailARN']]) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to describe Trail") trail['IsLogging'] = status_resp['IsLogging'] trail['tags'] = boto3_tag_list_to_ansible_dict(tags_list['ResourceTagList'][0]['TagsList']) # Check for non-existent values and populate with None optional_vals = set(['S3KeyPrefix', 'SnsTopicName', 'SnsTopicARN', 'CloudWatchLogsLogGroupArn', 'CloudWatchLogsRoleArn', 'KmsKeyId']) for v in optional_vals - set(trail.keys()): trail[v] = None return trail else: # trail doesn't exist return None return None def delete_trail(module, client, trail_arn): """ Delete a CloudTrail module : AnsibleAWSModule object client : boto3 client connection object trail_arn : Full CloudTrail ARN """ try: client.delete_trail(Name=trail_arn) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to delete Trail") def update_trail(module, client, ct_params): """ Delete a CloudTrail module : AnsibleAWSModule object client : boto3 client connection object ct_params : The parameters for the Trail to update """ try: client.update_trail(**ct_params) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to update Trail") def main(): argument_spec = dict( state=dict(default='present', choices=['present', 'absent', 'enabled', 'disabled']), name=dict(default='default'), enable_logging=dict(default=True, type='bool'), s3_bucket_name=dict(), s3_key_prefix=dict(no_log=False), sns_topic_name=dict(), is_multi_region_trail=dict(default=False, type='bool'), enable_log_file_validation=dict(type='bool', aliases=['log_file_validation_enabled']), include_global_events=dict(default=True, type='bool', aliases=['include_global_service_events']), cloudwatch_logs_role_arn=dict(), cloudwatch_logs_log_group_arn=dict(), kms_key_id=dict(), tags=dict(type='dict', aliases=['resource_tags']), purge_tags=dict(default=True, type='bool') ) required_if = [('state', 'present', ['s3_bucket_name']), ('state', 'enabled', ['s3_bucket_name'])] required_together = [('cloudwatch_logs_role_arn', 'cloudwatch_logs_log_group_arn')] module = AnsibleAWSModule(argument_spec=argument_spec, supports_check_mode=True, required_together=required_together, required_if=required_if) # collect parameters if module.params['state'] in ('present', 'enabled'): state = 'present' elif module.params['state'] in ('absent', 'disabled'): state = 'absent' tags = module.params['tags'] purge_tags = module.params['purge_tags'] enable_logging = module.params['enable_logging'] ct_params = dict( Name=module.params['name'], S3BucketName=module.params['s3_bucket_name'], IncludeGlobalServiceEvents=module.params['include_global_events'], IsMultiRegionTrail=module.params['is_multi_region_trail'], ) if module.params['s3_key_prefix']: ct_params['S3KeyPrefix'] = module.params['s3_key_prefix'].rstrip('/') if module.params['sns_topic_name']: ct_params['SnsTopicName'] = module.params['sns_topic_name'] if module.params['cloudwatch_logs_role_arn']: ct_params['CloudWatchLogsRoleArn'] = module.params['cloudwatch_logs_role_arn'] if module.params['cloudwatch_logs_log_group_arn']: ct_params['CloudWatchLogsLogGroupArn'] = module.params['cloudwatch_logs_log_group_arn'] if module.params['enable_log_file_validation'] is not None: ct_params['EnableLogFileValidation'] = module.params['enable_log_file_validation'] if module.params["kms_key_id"] is not None: ct_params["KmsKeyId"] = module.params["kms_key_id"] client = module.client('cloudtrail') region = module.region results = dict( changed=False, exists=False ) # Get existing trail facts trail = get_trail_facts(module, client, ct_params['Name']) # If the trail exists set the result exists variable if trail is not None: results['exists'] = True initial_kms_key_id = trail.get('KmsKeyId') if state == 'absent' and results['exists']: # If Trail exists go ahead and delete results['changed'] = True results['exists'] = False results['trail'] = dict() if not module.check_mode: delete_trail(module, client, trail['TrailARN']) elif state == 'present' and results['exists']: # If Trail exists see if we need to update it do_update = False for key in ct_params: tkey = str(key) # boto3 has inconsistent parameter naming so we handle it here if key == 'EnableLogFileValidation': tkey = 'LogFileValidationEnabled' # We need to make an empty string equal None if ct_params.get(key) == '': val = None else: val = ct_params.get(key) if val != trail.get(tkey): do_update = True if tkey != 'KmsKeyId': # We'll check if the KmsKeyId casues changes later since # user could've provided a key alias, alias arn, or key id # and trail['KmsKeyId'] is always a key arn results['changed'] = True # If we are in check mode copy the changed values to the trail facts in result output to show what would change. if module.check_mode: trail.update({tkey: ct_params.get(key)}) if not module.check_mode and do_update: update_trail(module, client, ct_params) trail = get_trail_facts(module, client, ct_params['Name']) # Determine if KmsKeyId changed if not module.check_mode: if initial_kms_key_id != trail.get('KmsKeyId'): results['changed'] = True else: new_key = ct_params.get('KmsKeyId') if initial_kms_key_id != new_key: # Assume changed for a moment results['changed'] = True # However, new_key could be a key id, alias arn, or alias name # that maps back to the key arn in initial_kms_key_id. So check # all aliases for a match. initial_aliases = get_kms_key_aliases(module, module.client('kms'), initial_kms_key_id) for a in initial_aliases: if a['AliasName'] == new_key or a['AliasArn'] == new_key or a['TargetKeyId'] == new_key: results['changed'] = False # Check if we need to start/stop logging if enable_logging and not trail['IsLogging']: results['changed'] = True trail['IsLogging'] = True if not module.check_mode: set_logging(module, client, name=ct_params['Name'], action='start') if not enable_logging and trail['IsLogging']: results['changed'] = True trail['IsLogging'] = False if not module.check_mode: set_logging(module, client, name=ct_params['Name'], action='stop') # Check if we need to update tags on resource tags_changed = tag_trail(module, client, tags=tags, trail_arn=trail['TrailARN'], curr_tags=trail['tags'], purge_tags=purge_tags) if tags_changed: updated_tags = dict() if not purge_tags: updated_tags = trail['tags'] updated_tags.update(tags) results['changed'] = True trail['tags'] = updated_tags # Populate trail facts in output results['trail'] = camel_dict_to_snake_dict(trail, ignore_list=['tags']) elif state == 'present' and not results['exists']: # Trail doesn't exist just go create it results['changed'] = True results['exists'] = True if not module.check_mode: if tags: ct_params["TagsList"] = ansible_dict_to_boto3_tag_list(tags) # If we aren't in check_mode then actually create it created_trail = create_trail(module, client, ct_params) # Get the trail status try: status_resp = client.get_trail_status(Name=created_trail['Name']) except (BotoCoreError, ClientError) as err: module.fail_json_aws(err, msg="Failed to fetch Trail statuc") # Set the logging state for the trail to desired value if enable_logging and not status_resp['IsLogging']: set_logging(module, client, name=ct_params['Name'], action='start') if not enable_logging and status_resp['IsLogging']: set_logging(module, client, name=ct_params['Name'], action='stop') # Get facts for newly created Trail trail = get_trail_facts(module, client, ct_params['Name']) # If we are in check mode create a fake return structure for the newly minted trail if module.check_mode: acct_id = '123456789012' try: sts_client = module.client('sts') acct_id = sts_client.get_caller_identity()['Account'] except (BotoCoreError, ClientError): pass trail = dict() trail.update(ct_params) if 'EnableLogFileValidation' not in ct_params: ct_params['EnableLogFileValidation'] = False trail['EnableLogFileValidation'] = ct_params['EnableLogFileValidation'] trail.pop('EnableLogFileValidation') fake_arn = 'arn:aws:cloudtrail:' + region + ':' + acct_id + ':trail/' + ct_params['Name'] trail['HasCustomEventSelectors'] = False trail['HomeRegion'] = region trail['TrailARN'] = fake_arn trail['IsLogging'] = enable_logging trail['tags'] = tags # Populate trail facts in output results['trail'] = camel_dict_to_snake_dict(trail, ignore_list=['tags']) module.exit_json(**results) if __name__ == '__main__': main()