AWS - CloudTrail

AWS CloudTrail is a service that enables governance, compliance, operational auditing, and risk auditing of your AWS account. With CloudTrail, you can log, continuously monitor, and retain account activity related to actions across your AWS infrastructure. CloudTrail provides event history of your AWS account activity, including actions taken through the AWS Management Console, AWS SDKs, command line tools, and other AWS services. This event history simplifies security analysis, resource change tracking, and troubleshooting. For more information, see the AWS CloudTrail documentation .

Configure AWS CloudTrail on Demisto

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for AWS - CloudTrail.
  3. Click Add instance to create and configure a new integration instance.
    • Name : a textual name for the integration instance.
    • Default Region :
    • Role Arn
    • Role Session Name
    • Role Session Duration
  4. Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Demisto CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

  1. Create a trail: aws-cloudtrail-create-trail
  2. Delete a trail: aws-cloudtrail-delete-trail
  3. Get the settings of a trail: aws-cloudtrail-describe-trails
  4. Update a trail: aws-cloudtrail-update-trail
  5. Start recording logs: aws-cloudtrail-start-logging
  6. Stop recording logs: aws-cloudtrail-stop-logging
  7. Search API activity events: aws-cloudtrail-lookup-events

1. Create a trail


Creates a trail that specifies the settings for delivery of log data to an Amazon S3 bucket. A maximum of five trails can exist in a region, irrespective of the region in which they were created.

Base Command

aws-cloudtrail-create-trail

Input
Argument Name Description Required
name Specifies the name of the trail Required
s3BucketName Specifies the name of the Amazon S3 bucket designated for publishing log files Required
s3KeyPrefix Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery Optional
snsTopicName Specifies the name of the Amazon SNS topic defined for notification of log file delivery Optional
includeGlobalServiceEvents Specifies whether the trail is publishing events from global services, such as IAM, to the log files Optional
isMultiRegionTrail Specifies whether the trail is created in the current region or in all regions. The default is false. Optional
enableLogFileValidation Specifies whether log file integrity validation is enabled. The default is false. Optional
cloudWatchLogsLogGroupArn Specifies a log group name using an Amazon Resource Name (ARN), a unique identifier that represents the log group to which CloudTrail logs will be delivered. Not required unless you specify CloudWatchLogsRoleArn. Optional
cloudWatchLogsRoleArn Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group Optional
kmsKeyId Specifies the KMS key ID to use to encrypt the logs delivered by CloudTrail. 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. Optional
region The AWS Region, if not specified the default region will be used Optional
roleArn The Amazon Resource Name (ARN) of the role to assume Optional
roleSessionName An identifier for the assumed role session Optional
roleSessionDuration The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. Optional
Context Output
Path Type Description
AWS.CloudTrail.Trails.Name string Specifies the name of the trail
AWS.CloudTrail.Trails.S3BucketName string Specifies the name of the Amazon S3 bucket designated for publishing log files
AWS.CloudTrail.Trails.IncludeGlobalServiceEvents boolean Specifies whether the trail is publishing events from global services such as IAM to the log files
AWS.CloudTrail.Trails.IsMultiRegionTrail boolean Specifies whether the trail exists in one region or in all regions
AWS.CloudTrail.Trails.TrailARN string Specifies the ARN of the trail that was created
AWS.CloudTrail.Trails.LogFileValidationEnabled boolean Specifies whether log file integrity validation is enabled
AWS.CloudTrail.Trails.SnsTopicARN string Specifies the ARN of the Amazon SNS topic that CloudTrail uses to send notifications when log files are delivered
AWS.CloudTrail.Trails.S3KeyPrefix string Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery
AWS.CloudTrail.Trails.CloudWatchLogsLogGroupArn string Specifies the Amazon Resource Name (ARN) of the log group to which CloudTrail logs will be delivered
AWS.CloudTrail.Trails.CloudWatchLogsRoleArn string Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group
AWS.CloudTrail.Trails.KmsKeyId string Specifies the KMS key ID that encrypts the logs delivered by CloudTrail
AWS.CloudTrail.Trails.HomeRegion string The region in which the trail was created
Command Example

!aws-cloudtrail-create-trail name=test s3BucketName=test

Context Example

image

Human Readable Output

image

2. Delete a trail


Deletes a trail. This operation must be called from the region in which the trail was created. DeleteTrail cannot be called on the shadow trails (replicated trails in other regions) of a trail that is enabled in all regions.

Base Command

aws-cloudtrail-delete-trail

Input
Argument Name Description Required
name Specifies the name or the CloudTrail ARN of the trail to be deleted. The format of a trail ARN is: arn:aws:cloudtrail:us-east-1:123456789012:trail/MyTrail Required
Context Output

There is no context output for this command.

Command Example

!aws-cloudtrail-delete-trail name=test

Human Readable Output
image

3. Get the settings of a trail


Retrieves settings for the trail associated with the current region for your account.

Base Command

aws-cloudtrail-describe-trails

Input
Argument Name Description Required
trailNameList Specifies a list of trail names, trail ARNs, or both, of the trails to describe. If an empty list is specified, information for the trail in the current region is returned. False
includeShadowTrails Specifies whether to include shadow trails in the response. A shadow trail is the replication in a region of a trail that was created in a different region. The default is "true". Optional
region The AWS Region, if not specified the default region will be used Optional
roleArn The Amazon Resource Name (ARN) of the role to assume Optional
roleSessionName An identifier for the assumed role session Optional
roleSessionDuration The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. Optional
Context Output
Path Type Description
AWS.CloudTrail.Trails.Name string Name of the trail set by calling CreateTrail
AWS.CloudTrail.Trails.S3BucketName string Name of the Amazon S3 bucket into which CloudTrail delivers your trail files
AWS.CloudTrail.Trails.S3KeyPrefix string Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery
AWS.CloudTrail.Trails.SnsTopicARN string Specifies the ARN of the Amazon SNS topic that CloudTrail uses to send notifications when log files are delivered
AWS.CloudTrail.Trails.IncludeGlobalServiceEvents boolean Set to "True" to include AWS API calls from AWS global services such as IAM. Otherwise, "False".
AWS.CloudTrail.Trails.IsMultiRegionTrail boolean Specifies whether the trail belongs only to one region or exists in all regions
AWS.CloudTrail.Trails.HomeRegion string The region in which the trail was created
AWS.CloudTrail.Trails.TrailARN string Specifies the ARN of the trail
AWS.CloudTrail.Trails.LogFileValidationEnabled boolean Specifies whether log file validation is enabled
AWS.CloudTrail.Trails.CloudWatchLogsLogGroupArn string Specifies an Amazon Resource Name (ARN), a unique identifier that represents the log group to which CloudTrail logs will be delivered
AWS.CloudTrail.Trails.CloudWatchLogsRoleArn string Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group
AWS.CloudTrail.KmsKeyId string Specifies the KMS key ID that encrypts the logs delivered by CloudTrail
AWS.CloudTrail.HasCustomEventSelectors boolean Specifies if the trail has custom event selectors
Command Example

!aws-cloudtrail-describe-trails

Context Example

image

Human Readable Output

image

4. Update a trail


Updates the settings that specify delivery of log files. Changes to a trail do not require stopping the CloudTrail service.

Base Command

aws-cloudtrail-update-trail

Input
Argument Name Description Required
name Specifies the name of the trail or trail ARN Required
s3BucketName Specifies the name of the Amazon S3 bucket designated for publishing log files Optional
s3KeyPrefix Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery Optional
snsTopicName Specifies the name of the Amazon SNS topic defined for notification of log file delivery Optional
includeGlobalServiceEvents Specifies whether the trail is publishing events from global services such as IAM to the log files Optional
isMultiRegionTrail Specifies whether the trail applies only to the current region or to all regions. The default is false. If the trail exists only in the current region and this value is set to true, shadow trails (replications of the trail) will be created in the other regions. If the trail exists in all regions and this value is set to false, the trail will remain in the region where it was created, and its shadow trails in other regions will be deleted. Optional
enableLogFileValidation Specifies whether log file validation is enabled. The default is false. Optional
cloudWatchLogsLogGroupArn Specifies a log group name using an Amazon Resource Name (ARN), a unique identifier that represents the log group to which CloudTrail logs will be delivered. Not required unless you specify CloudWatchLogsRoleArn. Optional
cloudWatchLogsRoleArn Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group Optional
kmsKeyId Specifies the KMS key ID to use to encrypt the logs delivered by CloudTrail Optional
region The AWS Region, if not specified the default region will be used Optional
roleArn The Amazon Resource Name (ARN) of the role to assume Optional
roleSessionName An identifier for the assumed role session Optional
roleSessionDuration The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. Optional
Context Output
Path Type Description
AWS.CloudTrail.Trails.Name string Specifies the name of the trail
AWS.CloudTrail.Trails.S3BucketName string Specifies the name of the Amazon S3 bucket designated for publishing log files
AWS.CloudTrail.Trails.IncludeGlobalServiceEvents boolean Specifies whether the trail is publishing events from global services such as IAM to the log files
AWS.CloudTrail.Trails.IsMultiRegionTrail boolean Specifies whether the trail exists in one region or in all regions
AWS.CloudTrail.Trails.TrailARN string Specifies the ARN of the trail that was created
AWS.CloudTrail.Trails.LogFileValidationEnabled boolean Specifies whether log file integrity validation is enabled
AWS.CloudTrail.Trails.SnsTopicARN string Specifies the ARN of the Amazon SNS topic that CloudTrail uses to send notifications when log files are delivered
AWS.CloudTrail.Trails.S3KeyPrefix string Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery
AWS.CloudTrail.Trails.CloudWatchLogsLogGroupArn string Specifies the Amazon Resource Name (ARN) of the log group to which CloudTrail logs will be delivered
AWS.CloudTrail.Trails.CloudWatchLogsRoleArn string Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group
AWS.CloudTrail.Trails.KmsKeyId string Specifies the KMS key ID that encrypts the logs delivered by CloudTrail
AWS.CloudTrail.Trails.HomeRegion string The region in which the trail was created
Command Example

!aws-cloudtrail-update-trail name=test isMultiRegionTrail=true

Context Example

image

Human Readable Output

image

5. Start recording logs


Starts the recording of AWS API calls and log file delivery for a trail. For a trail that is enabled in all regions, this operation must be called from the region in which the trail was created. This operation cannot be called on the shadow trails (replicated trails in other regions) of a trail that is enabled in all regions.

Base Command

aws-cloudtrail-start-logging

Input
Argument Name Description Required
name Specifies the name or the CloudTrail ARN of the trail for which CloudTrail logs AWS API calls Required
region The AWS Region, if not specified the default region will be used Optional
roleArn The Amazon Resource Name (ARN) of the role to assume Optional
roleSessionName An identifier for the assumed role session Optional
roleSessionDuration The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. Optional
Context Output

There is no context output for this command.

Command Example

!aws-cloudtrail-start-logging name=test

Context Example

There is no context output for this command.

Human Readable Output

image

6. Stop recording logs


Suspends the recording of AWS API calls and log file delivery for the specified trail. Under most circumstances, there is no need to use this action. You can update a trail without stopping it first. This action is the only way to stop recording. For a trail enabled in all regions, this operation must be called from the region in which the trail was created, or an InvalidHomeRegionException will occur. This operation cannot be called on the shadow trails (replicated trails in other regions) of a trail enabled in all regions.

Base Command

aws-cloudtrail-stop-logging

Input
Argument Name Description Required
name Specifies the name or the CloudTrail ARN of the trail for which CloudTrail logs AWS API calls Required
region The AWS Region, if not specified the default region will be used Optional
roleArn The Amazon Resource Name (ARN) of the role to assume Optional
roleSessionName An identifier for the assumed role session Optional
roleSessionDuration The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role Optional
Context Output

There is no context output for this command.

Command Example

!aws-cloudtrail-stop-logging name=test

Context Example

There is no context output for this command.

Human Readable Output

image

7. Search API activity events


Looks up API activity events captured by CloudTrail that create, update, or delete resources in your account. Events for a region can be looked up for the times in which you had CloudTrail turned on in that region during the last seven days.

Base Command

aws-cloudtrail-lookup-events

Input
Argument Name Description Required
attributeKey Specifies an attribute on which to filter the returned events Required
attributeValue Specifies a value for the specified AttributeKey Required
startTime Specifies that only events that occur on or after the specified time are returned Optional
endTime Specifies that only events that occur on or before the specified time are returned Optional
region The AWS Region, if not specified the default region will be used Optional
roleArn The Amazon Resource Name (ARN) of the role to assume Optional
roleSessionName An identifier for the assumed role session Optional
roleSessionDuration The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. Optional
Context Output
Path Type Description
AWS.CloudTrail.Trails.Events.EventId string The CloudTrail ID of the returned event
AWS.CloudTrail.Trails.Events.EventName string The name of the returned event
AWS.CloudTrail.Trails.Events.EventTime date The date and time of the returned event
AWS.CloudTrail.Trails.Events.EventSource string The AWS service that the request was made to
AWS.CloudTrail.Trails.Events.Username string User name or role name of the requester that called the API in the event returned
AWS.CloudTrail.Trails.Events.ResourceName string The type of a resource referenced by the event returned. When the resource type cannot be determined, null is returned. Some examples of resource types are: Instance for EC2, Trail for CloudTrail, DBInstance for RDS, and AccessKey for IAM.
AWS.CloudTrail.Trails.Events.ResourceType string The name of the resource referenced by the event returned. These are user-created names whose values will depend on the environment. For example, the resource name might be "auto-scaling-test-group" for an Auto Scaling Group or "i-1234567" for an EC2 Instance.
AWS.CloudTrail.Trails.Events.CloudTrailEvent string A JSON string that contains a representation of the returned event
Command Example

!aws-cloudtrail-lookup-events attributeKey=EventName attributeValue=StartLogging

Context Example

image

Human Readable Output

image