Skip to main content
Skip table of contents

AWS CloudTrail

LAST UPDATED: 05/02/2024

Overview

AWS CloudTrail is a service that enables governance, compliance, operational auditing, and risk auditing of your AWS account.

D3 SOAR is providing REST operations to function with AWS CloudTrail.

For example, you can use CloudTrail to view, search, download, archive, analyze, and respond to account activity across your AWS infrastructure. You can identify who or what took which action, what resources were acted upon, when the event occurred, and other details to help you analyze and respond to activity in your AWS account.

AWS CloudTrail is available for use in:

D3 SOAR

V12.7.241+

Category

Cloud Services

Deployment Options

Option II, Option IV

Known Limitations

AWS account has default quotas, formerly referred to as limits, for each AWS service. The following table describes quotas, or limits, within CloudTrail. CloudTrail has no adjustable quotas.

Resource

Default Limit

Comments

Trails per region

5

This limit cannot be increased.

Get, describe, and list APIs

10 transactions per second (TPS)

The maximum number of operation requests you can make per second without being throttled. The LookupEvents API is not included in this category.

This limit cannot be increased.

LookupEvents API

2 transactions per second (TPS)

The maximum number of operation requests you can make per second without being throttled.

This limit cannot be increased.

All other APIs

1 transaction per second (TPS)

The maximum number of operation requests you can make per second without being throttled.

This limit cannot be increased.

Event data stores in CloudTrail Lake

5 per region

This limit cannot be increased.

Event selectors

5 per trail

This limit cannot be increased.

Advanced event selectors

500 conditions across all advanced event selectors

If a trail uses advanced event selectors, a maximum of 500 total values for all conditions in all advanced event selectors is allowed. Unless a trail logs data events on all resources, such as all S3 buckets or all Lambda functions, a trail is limited to 250 data resources. Data resources can be distributed across event selectors, but the overall total cannot exceed 250.

This limit cannot be increased.

Data resources in event selectors

250 across all event selectors in a trail

If you choose to limit data events by using event selectors or advanced event selectors, the total number of data resources cannot exceed 250 across all event selectors in a trail. The limit of a number of resources on an individual event selector is configurable up to 250. This upper limit is allowed only if the total number of data resources does not exceed 250 across all event selectors.

Examples:

A trail with 5 event selectors, each configured with 50 data resources, is allowed. (5*50=250)

A trail with 5 event selectors, 3 of which are configured with 50 data resources, 1 of which is configured with 99 data resources, and 1 of which is configured with 1 data resource, is also allowed. ((3*50)+1+99=250)

A trail configured with 5 event selectors, all of which are configured with 100 data resources, is not allowed. (5*100=500)

This limit cannot be increased.

The limit does not apply if you choose to log data events on all resources, such as all S3 buckets or all Lambda functions.

Event size

All event versions: events over 256 KB cannot be sent to CloudWatch Logs.

Event version 1.05 and newer: total event size limit of 256 KB.

Amazon CloudWatch Logs and Amazon CloudWatch Events each allow a maximum event size of 256 KB. CloudTrail does not send events over 256 KB to CloudWatch Logs or CloudWatch Events.

Starting with event version 1.05, events have a maximum size of 256 KB. This is to help prevent exploitation by malicious actors and allow events to be consumed by other AWS services, such as CloudWatch Logs and CloudWatch Events.

CloudTrail file size sent to Amazon S3

50 MB ZIP file, after compression

For both management and data events, CloudTrail sends events to S3 in a maximum of 50 MB (compressed) ZIP files.

If enabled on the trail, log delivery notifications are sent by Amazon SNS after CloudTrail sends ZIP files to S3.

Please refer to Quotas in AWS CloudTrail for detailed information.

Connection

To connect to AWS CloudTrail from D3 SOAR, please follow this part to collect the required information below:

Parameter

Description

Example

Server URL

The AWS domain level server URL.

https://cloudtrail.<region_name>.amazonaws.com

Access Key

Please check the Policy Permission for this access key in the AWS Management Console and ensure that this access key includes DescribeTrails, ListTrails, CreateTrail, DeleteTrail, UpdateTrail, StartLogging, StopLogging, LookupEvents, ListTags, RemoveTags, GetEventSelectors, GetInsightSelectors, PutEventSelectors, PutInsightSelectors and GetTrailStatus permissions. The following are required permissions for each command: Create Trail(CreateTrail), Delete Trails(DeleteTrail), Describe Trails(DescribeTrails), List Trails(ListTrails), Update Trails(UpdateTrail), Start Logging(StartLogging), Stop Logging(StopLogging), List Tags(ListTags), Remove Tags(RemoveTags), Get Event Selectors(GetEventSelectors), Get Insight Selectors(GetInsightSelectors), Put Event Selectors(PutEventSelectors), Put Insight Selectors(PutInsightSelectors), Get Trail Status(GetTrailStatus), LookupEvent(LookupEvents), getTrail(getTrail)

AKIAxxxxxxxxxxxx4CYL

Access Secret

The secret key for authentication.

Xdwchs****E8vjHyIx9x****6iPuWdX****DXSdH

Permission Requirements

Each endpoint in the AWS CloudTrail API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command

Policy

Service

Access level (Actions)

Create Trail

CloudTrail

CreateTrail

Delete Trail

CloudTrail

DeleteTrail

Describe Trail

CloudTrail

DescribeTrails

Get Event Selectors

CloudTrail

GetEventSelectors

Get Insight Selectors

CloudTrail

GetInsightSelectors

Get Trail

CloudTrail

GetTrail

Get Trail Status

CloudTrail

GetTrailStatus

List Tags

CloudTrail

ListTags

List Trails

CloudTrail

ListTrails

Lookup Events

CloudTrail

LookupEvents

Put Event Selectors

CloudTrail

PutEventSelectors

Put Insight Selectors

CloudTrail

PutInsightSelectors

Remove Tags

CloudTrail

RemoveTags

Start Logging

CloudTrail

StartLogging

Stop Logging

CloudTrail

StopLogging

Update Trail

CloudTrail

UpdateTrail

Configuring AWS CloudTrail to Work with D3 SOAR

If your login user is ready to use (no policy configuration is needed), please follow the steps below to get your access key and secret key.

If you want to configure an account with limited API access, please follow the Create Policy > Create User > Access Key and Secret Key to get keys.

  1. Sign in to the AWS console with your account credentials.

  2. Click the account icon at the top right corner, then click Security Credentials.

  3. On my security credentials page, under the AWS IAM credentials tab, click the button Create access key to create a new Access Key and Secret Key.

READER NOTE

If you do not have permission to read or create an access key, please ask your administrator for help.

  1. Copy the Access key ID and the Secret access key to use to connect with D3 SOAR.

READER NOTE

The secret access key can only be viewed or downloaded at this time. It is recommended that you promptly download the .csv file and securely store it for future reference. If you lose or forget your secret key, you will not be able to recover it. If you have lost your secret key, you will need to create a new access key and deactivate the old key. You can have a maximum of two access keys (active or inactive) at a time.

Creating Policy

  1. Click on Services, which will expand the navigation menu. Then select IAM.

  2. Select Access management, which will open a menu where you can select Policies. Then, click the Create Policy button.

  3. In the Select a service section, click on Service to Choose a service. Please refer to Permission Requirements for the service you have selected. Then click Next.

  4. Search and assign using the search box in the Actions allowed section. For example, search for ListTrails in the search box, and use the tick box underneath it to select this action. Please refer to Permission Requirements for the necessary Access level (Actions). It is possible to specify multiple permissions under the same policy. Then click Next.

  5. Type a name in the text box under Policy name. Click Create policy.

Creating User

  1. Locate the Users tab.

  2. Type a user name into the User details field, then click Next.

  3. Select your desired permissions under Permissions options. It is suggested to link directly to your created policy by selecting Attach policies directly. Please refer to Creating Policy for more detailed information. Then click Next.

  4. Review the details you have entered, and click Create user.

Access Key and Secret Key

  1. Find the user you have created, and click on your user to access the details.

  2. Under the Security credentials tab, click on Create access key.

  3. Create an access key and save the details. Click Done after saving these credentials.

READER NOTE

The secret access key can only be viewed or downloaded at this time. It is recommended that you promptly download the .csv file and securely store it for future reference. If you lose or forget your secret key, you will not be able to recover it. If you have lost your secret key, you will need to create a new access key and deactivate the old key. You can have a maximum of two access keys (active or inactive) at a time.

Configuring D3 SOAR to Work with AWS CloudTrail

  1. Log in to D3 SOAR.

  2. Find the AWS CloudTrail integration.

    1. Navigate to Configuration on the top header menu.

    2. Click on the Integration icon on the left sidebar.

    3. Type AWS CloudTrail in the search box to find the integration, then click it to select it.

    4. Click + Connection, on the right side of the Connections section. A new connection window will appear.

  3. Configure the following fields to create a connection to AWS CloudTrail.

    1. Connection Name: The desired name for the connection.

    2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.

    3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.

    4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.

    5. Description (Optional): Add your desired description for the connection.

    6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.

    7. Configure User Permissions: Defines which users have access to the connection.

    8. Active: Check the tick box to ensure the connection is available for use.

    9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.


      1. Input the Server URL. The default value is https://cloudtrail.<region_name>.amazonaws.com.
      2. Input the Access Key obtained from the AWS GuardDuty platform in step 3 of Access Key and Secret Key.
      3. Input the Secret Key obtained from the AWS GuardDuty platform in step 3 of Access Key and Secret Key.

    10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.

  4. Test the connection.

    1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.

    2. Click OK to close the alert window.

    3. Click + Add to create and add the configured connection.

Commands

AWS CloudTrail includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the AWS CloudTrail API, please refer to the AWS CloudTrail API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring AWS CloudTrail to Work with D3 SOAR for details.

Create Trail

Creates a trail that specifies the settings for delivery of log data to an Amazon S3 bucket.

READER NOTE

S3 Bucket Name is a required parameter to run this command.

  • Run the List Trails command to obtain the S3 Bucket Name. S3 Bucket Names can be found in the returned raw data at the path $.Trail.S3BucketName.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The name of the specified trail. Must be between 3 and 128 characters, containing only ASCII letters (a-z, A-Z), numbers (0-9), periods (.), underscores (_), or dashes (-), starting with a letter or number, and ending with a letter or number.

["d3*****-02"]

S3 Bucket Name

Required

The name of the Amazon S3 bucket designated for publishing log files. Please note, by default, Amazon S3 buckets and objects are private. To create or modify an Amazon S3 bucket to receive log files for an organization trail, you must change the bucket policy. Please refer to Amazon S3 bucket policy for CloudTrail for more details.

d3*****-02

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "IncludeGlobalServiceEvents": true,
        "IsMultiRegionTrail": false,
        "IsOrganizationTrail": false,
        "LogFileValidationEnabled": false,
        "Name": "d3*****-02",
        "S3BucketName": "d3*****-02",
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-02"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

SAMPLE DATA

CODE 
[
    {
        "IncludeGlobalServiceEvents": true,
        "IsMultiRegionTrail": false,
        "IsOrganizationTrail": false,
        "LogFileValidationEnabled": false,
        "Name": "d3*****-02",
        "S3BucketName": "d3*****-02",
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-02"
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

IncludeGlobalServiceEvents

IsMultiRegionTrail

IsOrganizationTrail

LogFileValidationEnabled

Name

S3BucketName

TrailARN

True

False

False

False

d3*****-02

d3*****-02

arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-02

 Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Create Trail failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Incorrect S3 bucket policy is detected for bucket: xxx.

Error Sample Data

Create Trail failed.

Status Code: 400.

Message: Incorrect S3 bucket policy is detected for bucket: xxx.

Delete Trail

Deletes a specified trail. This operation must be called from the region in which the trails were created.

READER NOTE

Trail Name is a required parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The name or the CloudTrail ARN of the trail to be deleted. Trail Name can be obtained using the List Trails command. Please note, the trails can only be deleted from the region in which the trails were created, i.e, their Home Regions.

["d3*****-02"]

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "d3*****-02": {
        "status": "Successful"
    }
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "d3*****-02": {
        "status": "Successful"
    }
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

d3*****-02

{

"status": "Successful"

}

 Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Delete Trail failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Delete Trail failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Describe Trail

Retrieves settings for one or more trails associated with the current region for your account.

READER NOTE

Trail Name is an optional parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Optional

The list of the trails to describe, including trail names, trail ARNs, or both. If not specified, information for the trail(s) in the current region is returned. Please don’t input Shadow Trail names. A shadow trail replicates a region of a trail that was actually created in a different region. Trail Name can be obtained using the List Trails command.

["d3*****-01"]

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "trailList": [
        {
            "HasCustomEventSelectors": true,
            "HasInsightSelectors": false,
            "HomeRegion": "us-east-2",
            "IncludeGlobalServiceEvents": true,
            "IsMultiRegionTrail": true,
            "IsOrganizationTrail": false,
            "LogFileValidationEnabled": true,
            "Name": "d3*****-01",
            "S3BucketName": "d3*****-01",
            "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-01"
        }
    ]
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.trailList in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "trailList": [
        {
            "HasCustomEventSelectors": true,
            "HasInsightSelectors": false,
            "HomeRegion": "us-east-2",
            "IncludeGlobalServiceEvents": true,
            "IsMultiRegionTrail": true,
            "IsOrganizationTrail": false,
            "LogFileValidationEnabled": true,
            "Name": "d3*****-01",
            "S3BucketName": "d3*****-01",
            "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-01"
        }
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

trailList

{

"HasCustomEventSelectors": true,

"HasInsightSelectors": false,

"HomeRegion": "us-east-2",

"IncludeGlobalServiceEvents": true,

"IsMultiRegionTrail": true,

"IsOrganizationTrail": false,

"LogFileValidationEnabled": true,

"Name": "d3*****-01",

"S3BucketName": "d3*****-01",

"TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-01"

}

 Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Describe Trail failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Describe Trail failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Get Event Selectors

Describes the settings for the event selectors that you configured for your trail.

READER NOTE

Trail Name is a required parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The name of the trail or trail ARN to retrieve event selectors. Please note, you can only retrieve trail event selectors from the region in which the trails were created, i.e, their Home Regions. Trail Name can be obtained using the List Trails command.

["d3*****-04"]

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "EventSelectors": [
            {
                "DataResources": [
                    {
                        "Type": "AWS::S3::Object",
                        "Values": [
                            "arn:aws:s3"
                        ]
                    },
                    {
                        "Type": "AWS::Lambda::Function",
                        "Values": [
                            "arn:aws:lambda:us-east-2:391******688:function:AppMeshService1",
                            "arn:aws:lambda:us-east-2:391******688:function:AWSInstanceSchedulerStart"
                        ]
                    }
                ],
                "ExcludeManagementEventSources": [],
                "IncludeManagementEvents": true,
                "ReadWriteType": "All"
            }
        ],
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "EventSelectors": [
            {
                "DataResources": [
                    {
                        "Type": "AWS::S3::Object",
                        "Values": [
                            "arn:aws:s3"
                        ]
                    },
                    {
                        "Type": "AWS::Lambda::Function",
                        "Values": [
                            "arn:aws:lambda:us-east-2:391******688:function:AppMeshService1",
                            "arn:aws:lambda:us-east-2:391******688:function:AWSInstanceSchedulerStart"
                        ]
                    }
                ],
                "ExcludeManagementEventSources": [],
                "IncludeManagementEvents": true,
                "ReadWriteType": "All"
            }
        ],
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

EventSelectors

TrailARN

[
{
"DataResources": [
{
"Type": "AWS::S3::Object",
"Values": [
"arn:aws:s3"
]
},
{
"Type": "AWS::Lambda::Function",
"Values": [
"arn:aws:lambda:us-east-2:391******688:function:AppMeshService1",
"arn:aws:lambda:us-east-2:391******688:function:AWSInstanceSchedulerStart"
]
}
],
"ExcludeManagementEventSources": [],
"IncludeManagementEvents": true,
"ReadWriteType": "All"
}
]

arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04

 Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get Event Selectors failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Get Event Selectors failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Get Insight Selectors

Describes the settings for the insight event selectors that you configured for your trail.

READER NOTE

Trail Name is a required parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The name of the trail or trail ARN to retrieve insight selectors. Please note, you can only retrieve trail insight selectors from the region in which the trails were created, i.e., their Home Region. Trail Name can be obtained using the List Trails command.

["d3*****-04"]

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "InsightSelectors": [
            {
                "InsightType": "ApiCallRateInsight"
            }
        ],
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "InsightSelectors": [
            {
                "InsightType": "ApiCallRateInsight"
            }
        ],
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

InsightSelectors

TrailARN

CODE 
[{"InsightType": "ApiCallRateInsight"}]

arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04

 Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get Insight Selectors failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Get Insight Selectors failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Get Trail

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

READER NOTE

Trail Name is a required parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The list of the trails to retrieve details including trail names, trail ARNs, or both. Please do not input Shadow Trail names. A shadow trail replicates the region of a trail that was actually created in a different region. Trail Name can be obtained using the List Trails command.

["d3*****-01"]

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "Trail": {
            "HasCustomEventSelectors": true,
            "HasInsightSelectors": false,
            "HomeRegion": "us-east-2",
            "IncludeGlobalServiceEvents": true,
            "IsMultiRegionTrail": true,
            "IsOrganizationTrail": false,
            "LogFileValidationEnabled": true,
            "Name": "d3*****-01",
            "S3BucketName": "d3*****-01",
            "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-01"
        }
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "Trail": {
            "HasCustomEventSelectors": true,
            "HasInsightSelectors": false,
            "HomeRegion": "us-east-2",
            "IncludeGlobalServiceEvents": true,
            "IsMultiRegionTrail": true,
            "IsOrganizationTrail": false,
            "LogFileValidationEnabled": true,
            "Name": "d3*****-01",
            "S3BucketName": "d3*****-01",
            "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-01"
        }
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Trail

CODE 
{"HasCustomEventSelectors": true,"HasInsightSelectors": false,"HomeRegion": "us-east-2","IncludeGlobalServiceEvents": true,"IsMultiRegionTrail": true,"IsOrganizationTrail": false,"LogFileValidationEnabled": true,"Name": "d3*****-01","S3BucketName": "d3*****-01","TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-01"}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get Trail failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Get Trail failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Get Trail Status

Returns a JSON-formatted list of information about the specified trail. Fields include details on delivery errors, Amazon SNS and Amazon S3 errors, as well as start and stop logging times for each trail. This operation retrieves trail status from a single region. To retrieve trail status from all regions, you must call the operation for each region.

READER NOTE

Trail Name is a required parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The list of trails to get statuses, including trail names, trail ARNs, or both. Please do not input Shadow Trail names. A shadow trail replicates a region of a trail that was actually created in a different region. Trail Name can be obtained using the List Trails command.

["d3*****-01"]

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "IsLogging": true,
        "LatestDeliveryAttemptSucceeded": "2020-07-27T22:34:24Z",
        "LatestDeliveryAttemptTime": "2020-07-27T22:34:24Z",
        "LatestDeliveryTime": 1595889264.19,
        "LatestDigestDeliveryTime": 1595886922.732,
        "LatestNotificationAttemptSucceeded": "",
        "LatestNotificationAttemptTime": "",
        "StartLoggingTime": 1572307307.874,
        "TimeLoggingStarted": "2019-10-29T00:01:47Z",
        "TimeLoggingStopped": ""
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "IsLogging": true,
        "LatestDeliveryAttemptSucceeded": "2020-07-27T22:34:24Z",
        "LatestDeliveryAttemptTime": "2020-07-27T22:34:24Z",
        "LatestDeliveryTime": 1595889264.19,
        "LatestDigestDeliveryTime": 1595886922.732,
        "LatestNotificationAttemptSucceeded": "",
        "LatestNotificationAttemptTime": "",
        "StartLoggingTime": 1572307307.874,
        "TimeLoggingStarted": "2019-10-29T00:01:47Z",
        "TimeLoggingStopped": ""
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

IsLogging

LatestDeliveryAttemptSucceeded

LatestDeliveryAttemptTime

LatestDeliveryTime

LatestDigestDeliveryTime

LatestNotificationAttemptSucceeded

LatestNotificationAttemptTime

StartLoggingTime

TimeLoggingStarted

TimeLoggingStopped

True

7/27/2020 10:34:24 PM

7/27/2020 10:34:24 PM

1595889264.19

1595886922.732

1572307307.874

10/29/2019 12:01:47 AM

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get Trail Status failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Get Trail Status failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

List Tags

Lists the tags associated with the trail in the current region.

READER NOTE

Trail ARN is a required parameter to run this command.

  • Run the List Trails command to obtain Trail ARN. Trail ARNs can be found in the returned raw data at the path $.Trails[*].TrailARN.

Input

Input Parameter

Required/Optional

Description

Example

Trail ARN

Required

The list of trail ARNs whose tags will be listed. The list has a limit of 20 ARNs. Trail ARN can be obtained using the List Trails command. Please note, you can only get trail tags from the region in which the trails were created, i.e, their Home Regions.

["arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"]

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "ResourceTagList": [
        {
            "ResourceId": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04",
            "TagsList": [
                {
                    "Key": "t",
                    "Value": ""
                },
                {
                    "Key": "test",
                    "Value": ""
                }
            ]
        }
    ]
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.ResourceTagList in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "ResourceTagList": [
        {
            "ResourceId": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04",
            "TagsList": [
                {
                    "Key": "t",
                    "Value": ""
                },
                {
                    "Key": "test",
                    "Value": ""
                }
            ]
        }
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

ResourceTagList

JSON 
{
  "ResourceId": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04",
  "TagsList": [
    {
      "Key": "t",
      "Value": ""
    },
    {
      "Key": "test",
      "Value": ""
    }
  ]
}

 Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

List Tags failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The ARN lll is invalid.

Error Sample Data

List Tags failed.

Status Code: 400.

Message: The ARN lll is invalid.

List Trails

Returns the list for all trails in the current region and any associated shadow trails in other regions.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "Trails": [
        {
            "HomeRegion": "us-east-2",
            "Name": "d3*****-01",
            "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-01"
        },
        {
            "HomeRegion": "us-east-2",
            "Name": "d3*****-04",
            "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
        }
    ]
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.Trails in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
No Sample Data
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Trails

{

"HomeRegion": "us-east-2",

"Name": "d3*****-01",

"TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-01"

}

{

"HomeRegion": "us-east-2",

"Name": "d3*****-04",

"TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"

}

 Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

List Trails failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: N/A.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: N/A

Error Sample Data

List Trails failed.

Status Code: N/A.

Message: N/A

Lookup Events

Checks management events or CloudTrail Insights events that are captured by CloudTrail.

Input

Input Parameter

Required/Optional

Description

Example

Attribute Key

Optional

The key of the lookup attribute.

EventId

Attribute Value

Optional

The value of the lookup attribute.

f11***************d22

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "Events": [
        {
            "CloudTrailEvent": "{\"eventVersion\":\"1.05\",\"userIdentity\":{\"type\":\"IAMUser\",\"principalId\":\"AID*********VZO\",\"arn\":\"arn:aws:iam::391******688:user/j**u\",\"accountId\":\"391******688\",\"userName\":\"j**u\"},\"eventTime\":\"2020-06-23T17:44:03Z\",\"eventSource\":\"signin.amazonaws.com\",\"eventName\":\"ConsoleLogin\",\"awsRegion\":\"us-east-2\",\"sourceIPAddress\":\"216.251.***.***\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36\",\"requestParameters\":null,\"responseElements\":{\"ConsoleLogin\":\"Success\"},\"additionalEventData\":{\"LoginTo\":\"https://us-east-2.console.aws.amazon.com/************************\",\"MobileVersion\":\"No\",\"MFAUsed\":\"No\"},\"eventID\":\"f11***************d22\",\"eventType\":\"AwsConsoleSignIn\",\"recipientAccountId\":\"391******688\"}",
            "EventId": "f11***************d22",
            "EventName": "ConsoleLogin",
            "EventSource": "signin.amazonaws.com",
            "EventTime": 1592934243,
            "ReadOnly": "false",
            "Resources": [],
            "Username": "j**u"
        }
    ]
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "Events": [
        {
            "CloudTrailEvent": "{\"eventVersion\":\"1.05\",\"userIdentity\":{\"type\":\"IAMUser\",\"principalId\":\"AID*********VZO\",\"arn\":\"arn:aws:iam::391******688:user/j**u\",\"accountId\":\"391******688\",\"userName\":\"j**u\"},\"eventTime\":\"2020-06-23T17:44:03Z\",\"eventSource\":\"signin.amazonaws.com\",\"eventName\":\"ConsoleLogin\",\"awsRegion\":\"us-east-2\",\"sourceIPAddress\":\"216.251.***.***\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36\",\"requestParameters\":null,\"responseElements\":{\"ConsoleLogin\":\"Success\"},\"additionalEventData\":{\"LoginTo\":\"https://us-east-2.console.aws.amazon.com/********************\",\"MobileVersion\":\"No\",\"MFAUsed\":\"No\"},\"eventID\":\"f11***************d22\",\"eventType\":\"AwsConsoleSignIn\",\"recipientAccountId\":\"391******688\"}",
            "EventId": "f11***************d22",
            "EventName": "ConsoleLogin",
            "EventSource": "signin.amazonaws.com",
            "EventTime": 1592934243,
            "ReadOnly": "false",
            "Resources": [],
            "Username": "j**u"
        }
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Events

{

"CloudTrailEvent": "{\"eventVersion\":\"1.05\",\"userIdentity\":{\"type\":\"IAMUser\",\"principalId\":\"AID*********VZO\",\"arn\":\"arn:aws:iam::391******688:user/j**u\",\"accountId\":\"391******688\",\"userName\":\"j**u\"},\"eventTime\":\"2020-06-23T17:44:03Z\",\"eventSource\":\"signin.amazonaws.com\",\"eventName\":\"ConsoleLogin\",\"awsRegion\":\"us-east-2\",\"sourceIPAddress\":\"216.251.***.***\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36\",\"requestParameters\":null,\"responseElements\":{\"ConsoleLogin\":\"Success\"},\"additionalEventData\":{\"LoginTo\":\"https://us-east-2.console.aws.amazon.com/************************\",\"MobileVersion\":\"No\",\"MFAUsed\":\"No\"},\"eventID\":\"f11***************d22\",\"eventType\":\"AwsConsoleSignIn\",\"recipientAccountId\":\"391******688\"}",

"EventId": "f11***************d22",

"EventName": "ConsoleLogin",

"EventSource": "signin.amazonaws.com",

"EventTime": 1592934243.0,

"ReadOnly": "false",

"Resources": [],

"Username": "j**u"

}

 Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Lookup Events failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: EventId must be a valid UUID.

Error Sample Data

Lookup Events failed.

Status Code: 400.

Message: EventId must be a valid UUID.

Put Event Selectors

Configures an event selector for the specified trail(s). Use event selectors to further specify the management and data event settings for your trail(s). By default, trails created without specific event selectors will be configured to log all read and write management events, and no data events. You can specify up to 250 resources for an individual event selector, but the total number of data resources cannot exceed 250 across all event selectors in a trail.

READER NOTE

Trail ARN is an optional parameter to run this command.

  • Run the List Trails command to obtain Trail ARN. Trail ARNs can be found in the returned raw data at the path $.Trails[*].TrailARN.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Optional

The name or the CloudTrail ARN of the trail to configure the event selector. Trail Name can be obtained using the List Trails command. Please note, the trails can only configure the trail event selector from the region in which the trails were created, i.e, their Home Regions.

["d3*****-04"]

Read Write Type

Optional

Chooses whether the trail should log read-only events, write-only events, or both. The default value is All.

All

Include Management Events

Optional

Chooses whether the event selector should include management events for your trail(s). The default value is true.

True

Data Events S3

Optional

The S3 bucket ARNs or partial ARN strings to log data events.

["arn:aws:s3"]

Data Events Lambda

Optional

The Lambda Function ARNs to log data events. Lambda function ARNs are exact. Unlike S3, you cannot use matching.

["arn:aws:lambda:us-east-2:391******688:function:AppMeshService1","arn:aws:lambda:us-east-2:391******688:function:AWSInstanceSchedulerStart"]

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "EventSelectors": [
            {
                "DataResources": [
                    {
                        "Type": "AWS::S3::Object",
                        "Values": [
                            "arn:aws:s3"
                        ]
                    },
                    {
                        "Type": "AWS::Lambda::Function",
                        "Values": [
                            "arn:aws:lambda:us-east-2:391******688:function:AppMeshService1",
                            "arn:aws:lambda:us-east-2:391******688:function:AWSInstanceSchedulerStart"
                        ]
                    }
                ],
                "ExcludeManagementEventSources": [],
                "IncludeManagementEvents": true,
                "ReadWriteType": "All"
            }
        ],
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "EventSelectors": [
            {
                "DataResources": [
                    {
                        "Type": "AWS::S3::Object",
                        "Values": [
                            "arn:aws:s3"
                        ]
                    },
                    {
                        "Type": "AWS::Lambda::Function",
                        "Values": [
                            "arn:aws:lambda:us-east-2:391******688:function:AppMeshService1",
                            "arn:aws:lambda:us-east-2:391******688:function:AWSInstanceSchedulerStart"
                        ]
                    }
                ],
                "ExcludeManagementEventSources": [],
                "IncludeManagementEvents": true,
                "ReadWriteType": "All"
            }
        ],
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

EventSelectors

TrailARN

[
{
"DataResources": [
{
"Type": "AWS::S3::Object",
"Values": [
"arn:aws:s3"
]
},
{
"Type": "AWS::Lambda::Function",
"Values": [
"arn:aws:lambda:us-east-2:391******688:function:AppMeshService1",
"arn:aws:lambda:us-east-2:391******688:function:AWSInstanceSchedulerStart"
]
}
],
"ExcludeManagementEventSources": [],
"IncludeManagementEvents": true,
"ReadWriteType": "All"
}
]

arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Put Event Selectors failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Put Event Selectors failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Put Insight Selectors

Enables Insights event logging.

READER NOTE

Trail ARN is a required parameter to run this command.

  • Run the List Trails command to obtain Trail ARN. Trail ARNs can be found in the returned raw data at the path $.Trails[*].TrailARN.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The name(s) of the trail(s) or trail ARN(s) to configure the insight selector. Trail Name can be obtained using the List Trails command. Please note, you can only configure the trail insight selector from the region in which the trails were created, i.e., their Home Regions.

["d3*****-04"]

Insight Type

Optional

The type of the insight.

ApiCallRateInsight

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "InsightSelectors": [
            {
                "InsightType": "ApiCallRateInsight"
            }
        ],
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "InsightSelectors": [
            {
                "InsightType": "ApiCallRateInsight"
            }
        ],
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

failures

taskSets

{

"clusterArn": "arn:aws:ecs:us-east-2:391******688:cluster/ecscluster2",

"computedDesiredCount": 0,

"createdAt": 1594855802.167,

"id": "ecs-svc/293***********567",

"launchType": "EC2",

"loadBalancers": [],

"networkConfiguration": {

"awsvpcConfiguration": {

"assignPublicIp": "DISABLED",

"securityGroups": [

"sg-*********c809"

],

"subnets": [

"subnet-09e********235"

]

}

},

"pendingCount": 0,

"runningCount": 0,

"scale": {

"unit": "PERCENT",

"value": 0.0

},

"serviceArn": "arn:aws:ecs:us-east-2:391******688:service/ecsservice2",

"serviceRegistries": [],

"stabilityStatus": "STEADY_STATE",

"stabilityStatusAt": 1594855821.828,

"status": "ACTIVE",

"tags": [],

"taskDefinition": "arn:aws:ecs:us-east-2:391******688:task-definition/first-run-task-definition:1",

"taskSetArn": "arn:aws:ecs:us-east-2:391******688:task-set/ecscluster2/ecsservice2/ecs-svc/293***********567",

"updatedAt": 1594855821.828

}

 Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Put Insight Selectors failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Put Insight Selectors failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Remove Tags

Removes the specified tags from a trail.

READER NOTE

Trail ARN and Tag Key are required parameters to run this command.

  • Run the List Trails command to obtain Trail ARN. Trail ARNs can be found in the returned raw data at the path $.Trails[*].TrailARN.

  • Run the List Tags command to obtain Tag Key. Tag Keys can be found in the returned raw data at the path $.ResourceTagList[*].TagsList[*].Key.

Input

Input Parameter

Required/Optional

Description

Example

Trail ARN

Required

The ARN of the trail from which you want to remove tags. Trail ARN can be obtained using the List Trails command. Please note that you can only remove trail tags from the region in which the trails were created, i.e., their Home Regions.

arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04

Tag Key

Required

A list of tag keys to be removed. Tag Key can be obtained using the List Tags command. Please note that if the tag key you entered doesn’t exist in the trail, no error message will be returned.

["test"]

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "IncludeGlobalServiceEvents": true,
        "IsMultiRegionTrail": true,
        "IsOrganizationTrail": false,
        "LogFileValidationEnabled": false,
        "Name": "d3*****-04",
        "S3BucketName": "d3*****-02",
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.ResourceTagList in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "IncludeGlobalServiceEvents": true,
        "IsMultiRegionTrail": true,
        "IsOrganizationTrail": false,
        "LogFileValidationEnabled": false,
        "Name": "d3*****-04",
        "S3BucketName": "d3*****-02",
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

IncludeGlobalServiceEvents

IsMultiRegionTrail

IsOrganizationTrail

LogFileValidationEnabled

Name

S3BucketName

TrailARN

True

True

False

False

d3*****-04

d3*****-02

arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04

 Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Remove Tags failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: The ARN lll is invalid.

Error Sample Data

Remove Tags failed.

Status Code: 400.

Message: The ARN lll is invalid.

Start Logging

Starts the recording of AWS API calls and log file delivery for a trail.

READER NOTE

Trail Name is a required parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The name(s) or the CloudTrail ARN(s) of the trail(s) for which CloudTrail logs AWS API calls. Trail Name can be obtained using the List Trails command.

["d3*****-04"]

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "d3*****-04": {
        "status": "Successful"
    }
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "d3*****-04": {
        "status": "Successful"
    }
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

d3*****-04

{

"status": "Successful"

}

 Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Start Logging failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Start Logging failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Stop Logging

Suspends the recording of AWS API calls and log file delivery for the specified trail.

READER NOTE

Trail Name is a required parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The name(s) or the CloudTrail ARN(s) of the trail(s) for which CloudTrail will stop logging AWS API calls. Trail Name can be obtained using the List Trails command.

["d3*****-04"]

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "d3*****-04": {
        "status": "Successful"
    }
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "d3*****-04": {
        "status": "Successful"
    }
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

d3*****-04

{

"status": "Successful"

}

 Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Stop Logging failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Stop Logging failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

Update Trail

Updates the settings that specify delivery of log files.

READER NOTE

Trail Name is a required parameter to run this command.

  • Run the List Trails command to obtain the Trail Name. Trail Names can be found in the returned raw data at the path $.Trails[*].Name.

Input

Input Parameter

Required/Optional

Description

Example

Trail Name

Required

The name(s) or ARN(s) of the trail(s) to be updated. Trail Name can be obtained using the List Trails command.

["d3*****-04"]

S3 Bucket Name

Required

The name of the Amazon S3 bucket designated for publishing log files. You can get S3 Bucket Name from List Buckets command of AWS S3 integration. Please note, by default, Amazon S3 buckets and objects are private. To create or modify an Amazon S3 bucket to receive log files for an organization trail, you must change the bucket policy, please refer to https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html for details.

d3*****-02

Include Global Service Events

Optional

Chooses whether the trail is publishing events from global services such as IAM to the log files.

True

Apply Trail to All Regions

Optional

Chooses whether the trail exists in one region or in all regions.

True

Organization Trail

Optional

Chooses whether the trail is an organization trail.

False

Log File Validation

Optional

Chooses whether log file integrity validation is enabled.

True

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "IncludeGlobalServiceEvents": true,
        "IsMultiRegionTrail": true,
        "IsOrganizationTrail": false,
        "LogFileValidationEnabled": false,
        "Name": "d3*****-04",
        "S3BucketName": "d3*****-02",
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "IncludeGlobalServiceEvents": true,
        "IsMultiRegionTrail": true,
        "IsOrganizationTrail": false,
        "LogFileValidationEnabled": false,
        "Name": "d3*****-04",
        "S3BucketName": "d3*****-02",
        "TrailARN": "arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04"
    }
]
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

IncludeGlobalServiceEvents

IsMultiRegionTrail

IsOrganizationTrail

LogFileValidationEnabled

Name

S3BucketName

TrailARN

True

True

False

False

d3*****-04

d3*****-02

arn:aws:cloudtrail:us-east-2:391******688:trail/d3*****-04

 Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Update Trail failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS CloudTrail portal. Refer to the HTTP Status Code Registry for details.

Status Code: 400.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Unknown trail: *** for the user: ***.

Error Sample Data

Update Trail failed.

Status Code: 400.

Message: Unknown trail: *** for the user: ***.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close