Logging network activity events - Amazon CloudTrail
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Logging network activity events

Note

Network activity events is in preview release for CloudTrail and is subject to change.

CloudTrail network activity events enable VPC endpoint owners to record Amazon API calls made using their VPC endpoints from a private VPC to the Amazon Web Services service. Network activity events provide visibility into the resource operations performed within a VPC. For example, logging network activity events can help VPC endpoint owners detect when credentials from outside their organization attempt to access their VPC endpoints.

You can log network activity events for the following services:

  • Amazon CloudTrail

  • Amazon EC2

  • Amazon KMS

  • Amazon Secrets Manager

You can configure both trails and event data stores to log network activity events.

By default, trails and event data stores do not log network activity events. Additional charges apply for network activity events. For more information, see Amazon CloudTrail Pricing.

Advanced event selector fields for network activity events

You configure advanced event selectors to log network activity events by specifying the event source for which you want to log activity. You can configure advanced event selectors using the Amazon SDKs, Amazon CLI, or CloudTrail console.

The following advanced event selector fields are required to log network activity events:

  • eventCategory – To log network activity events, the value must be NetworkActivity. eventCategory can only use the Equals operator.

  • eventSource – The event source for which you want to log network activity events. eventSource can only use the Equals operator. If you want to log network activity events for multiple event sources, you must create a separate field selector for each event source.

    Valid values include:

    • cloudtrail.amazonaws.com

    • ec2.amazonaws.com

    • kms.amazonaws.com

    • secretsmanager.amazonaws.com

The following advanced event selector fields are optional:

  • eventName – The requested action that you want to filter on. For example, CreateKey or ListKeys. eventName can use any operator.

  • errorCode – The requested error code that you want to filter on. Currently, the only valid errorCode is VpceAccessDenied. You can use only the Equals operator with errorCode.

  • vpcEndpointId – Identifies the VPC endpoint that the operation passed through. You can use any operator with vpcEndpointId.

Network activity events are not logged by default when you create a trail or event data store. To record CloudTrail network activity events, you must explicitly configure each event source for which you want to collect activity.

Additional charges apply for logging network activity events. For CloudTrail pricing, see Amazon CloudTrail Pricing.

Logging network activity events with the Amazon Web Services Management Console

You can update an existing trail to log network activity events using the console.

Update an existing trail to log network activity events

Use the following procedure to update an existing trail to log network activity events.

Note

Additional charges apply for logging network activity events. For CloudTrail pricing, see Amazon CloudTrail Pricing.

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

  2. In the left navigation pane of the CloudTrail console, open the Trails page, and choose a trail name.

  3. In Network activity events, choose Edit.

    To log network activity events, take the following steps:

    1. From Network activity event source, choose the source for network activity events.

    2. In Log selector template, choose a template. You can choose to log all network activity events, log all network activity access denied events, or choose Custom to build a custom log selector to filter on multiple fields, such as eventName and vpcEndpointId.

    3. (Optional) Enter a name to identify the selector. The selector name is listed as Name in the advanced event selector and is viewable if you expand the JSON view.

    4. In Advanced event selectors build expressions by choosing values for Field, Operator, and Value. You can skip this step if you are using a predefined log template.

      1. For excluding or including network activity events, you can choose from the following fields in the console.

        • eventName – You can use any operator with eventName. You can use it to include or exclude any event, such as CreateKey.

        • errorCode – You can use it to filter on an error code. Currently, the only supported errorCode is VpceAccessDenied.

        • vpcEndpointId – Identifies the VPC endpoint that the operation passed through. You can use any operator with vpcEndpointId.

      2. For each field, choose + Condition to add as many conditions as you need, up to a maximum of 500 specified values for all conditions.

      3. Choose + Field to add additional fields as required. To avoid errors, do not set conflicting or duplicate values for fields.

    5. To add another event source for which you want to log network activity events, choose Add network activity event selector.

    6. Optionally, expand JSON view to see your advanced event selectors as a JSON block.

  4. Choose Save changes to save your changes.

Logging network activity events with the Amazon Command Line Interface

You can configure your trails or event data stores to log network activity events using the Amazon CLI.

Examples: Logging network activity events for trails

You can configure your trails to log network activity events using the Amazon CLI. Run the put-event-selectors command to configure the advanced event selectors for your trail.

To see whether your trail is logging network activity events, run the get-event-selectors command.

Example: Log network activity events for CloudTrail operations

The following example shows how to configure your trail to include all network activity events for CloudTrail API operations, such as CreateTrail and CreateEventDataStore calls. The value for the eventSource field is cloudtrail.amazonaws.com.

aws cloudtrail put-event-selectors / --trail-name TrailName / --region region / --advanced-event-selectors '[ { "Name": "Audit all CloudTrail API calls through VPC endpoints", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["NetworkActivity"] }, { "Field": "eventSource", "Equals": ["cloudtrail.amazonaws.com"] } ] } ]'

The command returns the following example output.

{ "TrailARN": "arn:aws:cloudtrail:us-east-1:111122223333:trail/TrailName", "AdvancedEventSelectors": [ { "Name": "Audit all CloudTrail API calls through VPC endpoints", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "NetworkActivity" ] }, { "Field": "eventSource", "Equals": [ "cloudtrail.amazonaws.com" ] } ] } ] }

Example: Log VpceAccessDenied events for Amazon KMS

The following example shows how to configure your trail to include VpceAccessDenied events for Amazon KMS. This example sets the errorCode field equal to VpceAccessDenied events and the eventSource field equal to kms.amazonaws.com.

aws cloudtrail put-event-selectors \ --region region / --trail-name TrailName / --advanced-event-selectors '[ { "Name": "Audit AccessDenied Amazon KMS events through VPC endpoints", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["NetworkActivity"] }, { "Field": "eventSource", "Equals": ["kms.amazonaws.com"] }, { "Field": "errorCode", "Equals": ["VpceAccessDenied"] } ] } ]'

The command returns the following example output.

{ "TrailARN": "arn:aws:cloudtrail:us-east-1:111122223333:trail/TrailName", "AdvancedEventSelectors": [ { "Name": "Audit AccessDenied Amazon KMS events through VPC endpoints", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "NetworkActivity" ] }, { "Field": "eventSource", "Equals": [ "kms.amazonaws.com" ] }, { "Field": "errorCode", "Equals": [ "VpceAccessDenied" ] } ] } ] }

Example: Log EC2 VpceAccessDenied events over a specific VPC endpoint

The following example shows how to configure your trail to include VpceAccessDenied events for Amazon EC2 for a specific VPC endpoint. This example sets the errorCode field equal to VpceAccessDenied events, the eventSource field equal to ec2.amazonaws.com, and the vpcEndpointId equal to the VPC endpoint of interest.

aws cloudtrail put-event-selectors \ --region region / --trail-name TrailName / --advanced-event-selectors '[ { "Name": "Audit AccessDenied EC2 events over a specific VPC endpoint", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["NetworkActivity"] }, { "Field": "eventSource", "Equals": ["ec2.amazonaws.com"] }, { "Field": "errorCode", "Equals": ["VpceAccessDenied"] }, { "Field": "vpcEndpointId", "Equals": ["vpce-example8c1b6b9b7"] } ] } ]'

The command returns the following example output.

{ "TrailARN": "arn:aws:cloudtrail:us-east-1:111122223333:trail/TrailName", "AdvancedEventSelectors": [ { "Name": "Audit AccessDenied EC2 events over a specific VPC endpoint", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "NetworkActivity" ] }, { "Field": "eventSource", "Equals": [ "ec2.amazonaws.com" ] }, { "Field": "errorCode", "Equals": [ "VpceAccessDenied" ] }, { "Field": "vpcEndpointId", "Equals": [ "vpce-example8c1b6b9b7" ] } ] } ] }

Examples: Logging network activity events for event data stores

You can configure your event data stores to include network activity events using the Amazon CLI. Use the create-event-data-store command to create a new event data store to log network activity events. Use the update-event-data-store command to update the advanced event selectors for an existing event data store.

To see whether your event data store includes network activity events, run the get-event-data-store command.

aws cloudtrail get-event-data-store --event-data-store EventDataStoreARN

Example: Log all network activity events for CloudTrail operations

The following example shows how to create an event data store that includes all network activity events related to CloudTrail operations, such as calls to CreateTrail and CreateEventDataStore. The value for the eventSource field is set to cloudtrail.amazonaws.com.

aws cloudtrail create-event-data-store \ --name "EventDataStoreName" \ --advanced-event-selectors '[ { "Name": "Audit all CloudTrail API calls over VPC endpoint", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["NetworkActivity"] }, { "Field": "eventSource", "Equals": ["cloudtrail.amazonaws.com"] } ] } ]'

The command returns the following example output.

{ "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLE492-301f-4053-ac5e-EXAMPLE441aa", "Name": "EventDataStoreName", "Status": "ENABLED", "AdvancedEventSelectors": [ { "Name": "Audit all CloudTrail API calls over VPC endpoint", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "NetworkActivity" ] }, { "Field": "eventSource", "Equals": [ "cloudtrail.amazonaws.com" ] } ] } ], "MultiRegionEnabled": true, "OrganizationEnabled": false, "RetentionPeriod": 366, "TerminationProtectionEnabled": true, "CreatedTimestamp": "2024-05-20T21:00:17.673000+00:00", "UpdatedTimestamp": "2024-05-20T21:00:17.820000+00:00" }

Example: Log VpceAccessDenied events for Amazon KMS

The following example shows how to create an event data store to include VpceAccessDenied events for Amazon KMS. This example sets the errorCode field equal to VpceAccessDenied events and the eventSource field equal to kms.amazonaws.com.

aws cloudtrail create-event-data-store \ --name EventDataStoreName \ --advanced-event-selectors '[ { "Name": "Audit AccessDenied Amazon KMS events over VPC endpoints", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["NetworkActivity"] }, { "Field": "eventSource", "Equals": ["kms.amazonaws.com"] }, { "Field": "errorCode", "Equals": ["VpceAccessDenied"] } ] } ]'

The command returns the following example output.

{ "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLEb4a8-99b1-4ec2-9258-EXAMPLEc890", "Name": "EventDataStoreName", "Status": "CREATED", "AdvancedEventSelectors": [ { "Name": "Audit AccessDenied Amazon KMS events over VPC endpoints", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "NetworkActivity" ] }, { "Field": "eventSource", "Equals": [ "kms.amazonaws.com" ] }, { "Field": "errorCode", "Equals": [ "VpceAccessDenied" ] } ] } ], "MultiRegionEnabled": true, "OrganizationEnabled": false, "RetentionPeriod": 366, "TerminationProtectionEnabled": true, "CreatedTimestamp": "2024-05-20T21:00:17.673000+00:00", "UpdatedTimestamp": "2024-05-20T21:00:17.820000+00:00" }

Example: Log EC2 VpceAccessDenied events over a specific VPC endpoint

The following example shows how to create an event data store to include VpceAccessDenied events for Amazon EC2 for a specific VPC endpoint. This example sets the errorCode field equal to VpceAccessDenied events, the eventSource field equal to ec2.amazonaws.com, and the vpcEndpointId equal to the VPC endpoint of interest.

aws cloudtrail create-event-data-store \ --name EventDataStoreName \ --advanced-event-selectors '[ { "Name": "Audit AccessDenied EC2 events over a specific VPC endpoint", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["NetworkActivity"] }, { "Field": "eventSource", "Equals": ["ec2.amazonaws.com"] }, { "Field": "errorCode", "Equals": ["VpceAccessDenied"] }, { "Field": "vpcEndpointId", "Equals": ["vpce-example8c1b6b9b7"] } ] } ]'

The command returns the following example output.

{ "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLEb4a8-99b1-4ec2-9258-EXAMPLEc890", "Name": "EventDataStoreName", "Status": "CREATED", "AdvancedEventSelectors": [ { "Name": "Audit AccessDenied EC2 events over a specific VPC endpoint", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "NetworkActivity" ] }, { "Field": "eventSource", "Equals": [ "ec2.amazonaws.com" ] }, { "Field": "errorCode", "Equals": [ "VpceAccessDenied" ] }, { "Field": "vpcEndpointId", "Equals": [ "vpce-example8c1b6b9b7" ] } ] } ], "MultiRegionEnabled": true, "OrganizationEnabled": false, "RetentionPeriod": 366, "TerminationProtectionEnabled": true, "CreatedTimestamp": "2024-05-20T21:00:17.673000+00:00", "UpdatedTimestamp": "2024-05-20T21:00:17.820000+00:00" }

Logging events with the Amazon SDKs

Run the GetEventSelectors operation to see whether your trail is logging network activity events. You can configure your trails to log network activity events by running the PutEventSelectors operation. For more information, see the Amazon CloudTrail API Reference.

Run the GetEventDataStore operation to see whether your event data store is logging network activity events. You can configure your event data stores to include network activity events by running the CreateEventDataStore or UpdateEventDataStore operations and specifying advanced event selectors. For more information, see Create, update, and manage event data stores with the Amazon CLI and the Amazon CloudTrail API Reference.