About the connector
AWS CloudTrail enables auditing, security monitoring, and operational monitoring by logging your AWS account activity.
This document provides information about the AWS CloudTrail Connector, which facilitates automated interactions with an AWS CloudTrail server using FortiSOAR™ playbooks. Add the AWS CloudTrail Connector as a step in FortiSOAR™ playbooks and perform automated operations such as creating a trail, updating a trail, deleting a trail, and others with AWS CloudTrail.
Version information
Connector Version: 1.1.0
FortiSOAR™ Version Tested on: 7.3.0-2034
Authored By: Fortinet
Certified: Yes
Release Notes for version 1.1.0
The following enhancements have been made to the AWS CloudTrail connector in version 1.1.0:
- Certified this version of the connector.
Installing the connector
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
cyops-connector-aws-cloudtrail
Prerequisites to configuring the connector
- The FortiSOAR™ server should have outbound connectivity to port 443 on the AWS CloudTrail server.
- You must know the configuration type, either IAM Role or Access Credentials, that you will use to connect to AWS. If you select Access Credentials as your configuration type, then you must know your account's AWS region that you will use to access AWS services and possess the AWS Access Key ID and the AWS Secret Access Key to access AWS services.
- To access the FortiSOAR™ UI, ensure that port 443 is open in the firewall.
Minimum Permissions Required
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the AWS CloudTrail connector card. On the connector popup, click the Configurations tab to enter the required configuration details:
| Parameter |
Description |
| Configuration Type |
Type of configuration using which you will provide credentials to access AWS CloudTrail and perform automated actions. You can select between IAM Role or Access Credentials.
If you select IAM Role, then enter details in the following field(s):
- AWS Instance IAM Role: IAM Role of your AWS instance to access AWS services.
If you select Access Credentials, then enter details in the following field(s):
- AWS Region: AWS region of your account to access the AWS CloudTrail.
- AWS Access Key ID: ID of the AWS Access Key to access AWS services.
- AWS Secret Access Key: Key of the AWS Secret Access to access AWS services.
|
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks. You can also use the annotations to access operations from FortiSOAR™:
| Function |
Description |
Annotation and Category |
| Create Trail |
Creates a trail that specifies the settings for delivery of log data to an Amazon S3 bucket. |
create_trail
Investigation |
| Get Trail Status |
Returns a JSON-formatted list of information about the specified trail. |
get_trail_status
Investigation |
| List Trails |
Lists trails that are in the current account. |
list_trails
Investigation |
| Update Trail |
Updates trail settings that control what events you are logging, and how to handle log files. |
update_trail
Investigation |
| Delete 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. |
delete_trail
Investigation |
| Lookup Events |
Looks up management events or CloudTrail Insights events that are captured by CloudTrail. You can look up events that occurred in a region within the last 90 days. |
lookup_events
Investigation |
| Start Logging |
Starts the recording of Amazon Web Services API calls and log file delivery for a trail. |
start_logging
Investigation |
| Stop Logging |
Suspends the recording of Amazon Web Services API calls and log file delivery for the specified trail. |
stop_logging
Investigation |
| Add Tags |
Adds one or more tags to a trail, up to a limit of 50. Overwrites an existing tag's value when a new value is specified for an existing tag key. Tag key names must be unique for a trail; you cannot have two keys with the same name but different values. |
add_tags
Investigation |
operation: Create Trail
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True', then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Name |
Specifies the name of the trail.
The name must meet the following requirements:
- Contain only ASCII letters (a-z, A-Z), numbers (0-9), periods (.), underscores (_), or dashes (-).
- Start with a letter or number, and end with a letter or number.
- Should be between 3 and 128 characters.
- Have no adjacent periods, underscores, or dashes.
- Names like my-_namespace and my--namespace are not valid.
- Not be in an IP address format (for example, 192.168.5.4)
|
| S3 BucketName |
Specifies the name of the Amazon S3 bucket designated for publishing log files |
| S3 Key Prefix |
Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery |
| SNS Topic Name |
Specifies the name of the Amazon SNS topic defined for notification of log file delivery. The maximum length supported is 256 characters. |
| Include Global Service Events |
Specifies whether the trail is publishing events from global services such as IAM to the log files. |
| Is MultiRegion Trail |
Specifies whether the trail is created in the current region or in all regions. The default is false. |
| Enable Log File Validation |
Specifies whether log file integrity validation is enabled. The default is false. |
| Cloud Watch Logs Log Group ARN |
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. |
| Cloud Watch Logs Role ARN |
Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group. |
| KMS Key ID |
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. |
| Is Organization Trail |
Specifies whether the trail is created for all accounts in an organization in Organizations, or only for the current Amazon Web Services account. The default is false and cannot be true unless the call is made on behalf of an Amazon Web Services account, which is the management account for an organization in Organizations. |
| Tags List |
A custom key-value pair that is associated with a resource such as a CloudTrail trail. e.g [{'key': 'keyname', 'value':'valuename'}]
Key (string) -- [REQUIRED] The key in a key-value pair. The key must not be longer than 128 Unicode characters. The key must be unique for the resource to which it applies.
Value (string) -The value in a key-value pair of a tag. The value must not be longer than 256 Unicode characters.
|
Output
The output contains the following populated JSON schema:
{
"Name": "",
"S3BucketName": "",
"IncludeGlobalServiceEvents": "",
"IsMultiRegionTrail": "",
"TrailARN": "",
"LogFileValidationEnabled": "",
"IsOrganizationTrail": "",
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
operation: Get Trail Status
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True', then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Name |
Specifies the name or the CloudTrail ARN of the trail for which you are requesting status. |
Output
The output contains the following populated JSON schema:
{
"IsLogging": "",
"StartLoggingTime": "",
"LatestDeliveryAttemptTime": "",
"LatestNotificationAttemptTime": "",
"LatestNotificationAttemptSucceeded": "",
"LatestDeliveryAttemptSucceeded": "",
"TimeLoggingStarted": "",
"TimeLoggingStopped": "",
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
operation: List Trails
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True' then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail.
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Next Token |
The token to use to get the next page of results after a previous API call. This token must be passed in with the same parameters that were specified in the original call. |
Output
The output contains the following populated JSON schema:
{
"Trails": [
{
"TrailARN": "",
"Name": "",
"HomeRegion": ""
}
],
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
operation: Update Trail
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True' then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Name |
Specifies the name of the trail or trail ARN. |
| S3 BucketName |
Specifies the name of the Amazon S3 bucket designated for publishing log files |
| S3 Key Prefix |
Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery. |
| SNS Topic Name |
Specifies the name of the Amazon SNS topic defined for notification of log file delivery. The maximum length supported is 256 characters. |
| Include Global Service Events |
Specifies whether the trail is publishing events from global services such as IAM to the log files. |
| Is MultiRegion Trail |
Specifies whether the trail is created in the current region or in all regions. The default is false. |
| Enable Log File Validation |
Specifies whether log file integrity validation is enabled. The default is false. |
| Cloud Watch Logs Log Group ARN |
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. |
| Cloud Watch Logs Role ARN |
Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group |
| KMS Key ID |
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. |
| Is Organization Trail |
Specifies whether the trail is created for all accounts in an organization in Organizations, or only for the current Amazon Web Services account. The default is false and cannot be true unless the call is made on behalf of an Amazon Web Services account, which is the management account for an organization in Organizations. |
Output
The output contains the following populated JSON schema:
{
"Name": "",
"S3BucketName": "",
"SnsTopicName": "",
"SnsTopicARN": "",
"IncludeGlobalServiceEvents": "",
"IsMultiRegionTrail": "",
"TrailARN": "",
"LogFileValidationEnabled": "",
"IsOrganizationTrail": "",
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
operation: Delete Trail
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True' then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Name |
Specifies the name or the CloudTrail ARN of the trail to be deleted. The following is the format of a trail ARN. arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail |
Output
The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
operation: Lookup Events
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True' then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail.
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Lookup Attributes |
Contains a list of lookup attributes. Currently, the list can contain only one item. e.g [{'AttributeKey': 'EventId'|'EventName'|'ReadOnly'|'Username'|'ResourceType'|'ResourceName'|'EventSource'|'AccessKeyId','AttributeValue': 'string'}].
AttributeKey - Specifies an attribute on which to filter the events returned.
AttributeValue - Specifies a value for the specified AttributeKey.
|
| Start Time |
Specifies that only events that occur after or at the specified time are returned. If the specified start time is after the specified end time, an error is returned. |
| End Time |
Specifies that only events that occur before or at the specified time are returned. If the specified end time is before the specified start time, an error is returned. |
| Event Category |
Specifies the event category. If you do not specify an event category, events of the category are not returned in the response.
Note: If you do not specify insight as the value of the EventCategory, then no Insights events are returned |
| Max Results |
Specify the maximum number of events this operation should return. Possible values are 1 through 50 (default). |
| Next Token |
The token to use to get the next page of results after a previous API call. This token must be passed in with the same parameters that were specified in the original call. For example, if the original call specified an AttributeKey of 'Username' with a value of 'root', the call with NextToken should include those same parameters. |
Output
The output contains the following populated JSON schema:
{
"Events": [
{
"EventId": "",
"EventName": "",
"ReadOnly": "",
"AccessKeyId": "",
"EventTime": "",
"EventSource": "",
"Username": "",
"Resources": [],
"CloudTrailEvent": ""
}
],
"NextToken": "",
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
operation: Start Logging
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True' then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Name |
Specifies the name or the CloudTrail ARN of the trail for which CloudTrail logs Amazon Web Services API calls |
Output
The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
operation: Stop Logging
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True' then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail.
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Name |
Specifies the name or the CloudTrail ARN of the trail for which CloudTrail will stop logging Amazon Web Services API calls. |
Output
The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
operation: Add Tags
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this option to assume a role. This parameter is required if you have specified 'IAM Role' as the 'Configuration Type'. If you have specified 'Access Credentials' as the 'Configuration Type', then this parameter is optional.
If you choose 'True', then you must specify the following parameters:
- AWS Region: AWS region of your account to access the AWS CloudTrail.
- Role ARN: ARN of the role that you want to assume for executing this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
|
| Resource ID |
Specifies the ARN of the trail to which one or more tags will be added. The format of a trail ARN is: e.g. arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail |
| Tags List |
Contains a list of tags, up to a limit of 50. A custom key-value pair that is associated with a resource such as a CloudTrail trail.
Key (string) - [REQUIRED] - The key must be must not be longer than 128 Unicode characters. The key must be unique for the resource to which it applies.
Value (string) - The value must not be longer than 256 Unicode characters. e.g {'Key': 'string', 'Value': 'string'}
|
Output
The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}
Included playbooks
The Sample - AWS CloudTrail - 1.1.0 playbook collection comes bundled with the AWS CloudTrail connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the AWS CloudTrail connector.
- Add Tags
- Create Trail
- Delete Trail
- Get Trail Status
- List Trails
- Lookup Events
- Start Logging
- Stop Logging
- Update Trail
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.
