Create a custom integration with the console

Sign in to the Amazon Web Services Management Console and open the CloudTrail console at https://console.amazonaws.cn/cloudtrail/.

From the navigation pane, under Lake, choose Integrations.

On the Add integration page, enter a name for your channel. The name can be 3-128 characters. Only letters, numbers, periods, underscores, and dashes are allowed.

Choose My custom integration.

From Event delivery location, choose to log the same activity events to existing event data stores, or create a new event data store.

If you choose to create a new event data store, enter a name for the event data store and specify the retention period in days. You can keep the event data in an event data store for up to 3,653 days (about 10 years) if you choose the One-year extendable retention pricing option, or up to 2,557 days (about 7 years) if you choose the Seven-year retention pricing option.

If you choose to log activity events to one or more existing event data stores, choose the event data stores from the list. The event data stores can only include activity events. The event type in the console must be Events from integrations. In the API, the eventCategory value must be ActivityAuditLog.

In Resource policy, configure the resource policy for the integration's channel. Resource policies are JSON policy documents that specify what actions a specified principal can perform on the resource and under what conditions. The accounts defined as principals in the resource policy can call the PutAuditEvents API to deliver events to your channel.

1. (Optional) Enter a unique external ID to provide an extra layer of protection. The external ID is a unique string such as an account ID or a randomly generated string, to prevent against confused deputy.

   Note

   If the resource policy includes an external ID, all calls to the PutAuditEvents API must include the external ID. However, if the policy does not define an external ID, you can still call the PutAuditEvents API and specify an externalId parameter.

2. Choose Add Amazon account to specify each Amazon account ID to add as a principal in the resource policy for the channel.

(Optional) In the Tags area, you can add up to 50 tag key and value pairs to help you identify, sort, and control access to your event data store and channel. For more information about how to use IAM policies to authorize access to an event data store based on tags, see Examples: Denying access to create or delete event data stores based on tags. For more information about how you can use tags in Amazon, see Tagging your Amazon resources in the Amazon Web Services General Reference.

When you are ready to create the new integration, choose Add integration. There is no review page. CloudTrail creates the integration, but to integrate your custom events, you must specify the channel ARN in a PutAuditEvents request.

Call the PutAuditEvents API to ingest your activity events into CloudTrail. You can add up to 100 activity events (or up to 1 MB) per PutAuditEvents request. You'll need the channel ARN that you created in preceding steps, the payload of events that you want CloudTrail to add, and the external ID (if specified for your resource policy). Be sure that there is no sensitive or personally-identifying information in event payload before ingesting it into CloudTrail. Events that you ingest into CloudTrail must follow the CloudTrail Lake integrations event schema.

The following examples show how to use the put-audit-events CLI command. The --audit-events and --channel-arn parameters are required. You need the ARN of the channel that you created in the preceding steps, which you can copy from the integration details page. The value of --audit-events is a JSON array of event objects. --audit-events includes a required ID from the event, the required payload of the event as the value of EventData, and an optional checksum to help validate the integrity of the event after ingestion into CloudTrail.

aws cloudtrail-data put-audit-events \
--region region \
--channel-arn $ChannelArn \
--audit-events \
id="event_ID",eventData='"{event_payload}"' \
id="event_ID",eventData='"{event_payload}"',eventDataChecksum="optional_checksum"

The following is an example command with two event examples.

aws cloudtrail-data put-audit-events \
--region us-east-1 \
--channel-arn arn:aws:cloudtrail:us-east-1:01234567890:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \
--audit-events \
id="EXAMPLE3-0f1f-4a85-9664-d50a3EXAMPLE",eventData='"{\"eventVersion\":\0.01\",\"eventSource\":\"custom1.domain.com\", ...
\}"' \
id="EXAMPLE7-a999-486d-b241-b33a1EXAMPLE",eventData='"{\"eventVersion\":\0.02\",\"eventSource\":\"custom2.domain.com\", ...
\}"',eventDataChecksum="EXAMPLE6e7dd61f3ead...93a691d8EXAMPLE"

The following example command adds the --cli-input-json parameter to specify a JSON file (custom-events.json) of event payload.

aws cloudtrail-data put-audit-events \
--channel-arn $channelArn \
--cli-input-json file://custom-events.json \
--region us-east-1

The following are the sample contents of the example JSON file, custom-events.json.

{
    "auditEvents": [
      {
        "eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
        \"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
        \"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
        \"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
        \"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
        \"additionalEventData\":{\"key\":\"value\"},
        \"sourceIPAddress\":\"source_IP_address\",\"recipientAccountId\":\"recipient_account_ID\"}",
        "id": "1"
      }
   ]
}