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
Contents
- Advanced event selector fields for network activity events
- Logging network activity events with the Amazon Web Services Management Console
- Logging network activity events with the Amazon Command Line Interface
- Logging events with the Amazon SDKs
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 beNetworkActivity
.eventCategory
can only use theEquals
operator. -
eventSource
– The event source for which you want to log network activity events.eventSource
can only use theEquals
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
orListKeys
.eventName
can use any operator. -
errorCode
– The requested error code that you want to filter on. Currently, the only validerrorCode
isVpceAccessDenied
. You can use only theEquals
operator witherrorCode
. -
vpcEndpointId
– Identifies the VPC endpoint that the operation passed through. You can use any operator withvpcEndpointId
.
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
Sign in to the Amazon Web Services Management Console and open the CloudTrail console at https://console.amazonaws.cn/cloudtrail/
. -
In the left navigation pane of the CloudTrail console, open the Trails page, and choose a trail name.
-
In Network activity events, choose Edit.
To log network activity events, take the following steps:
-
From Network activity event source, choose the source for network activity events.
-
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
andvpcEndpointId
. -
(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.
-
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.
-
For excluding or including network activity events, you can choose from the following fields in the console.
-
eventName
– You can use any operator witheventName
. You can use it to include or exclude any event, such asCreateKey
. -
errorCode
– You can use it to filter on an error code. Currently, the only supportederrorCode
isVpceAccessDenied
. -
vpcEndpointId
– Identifies the VPC endpoint that the operation passed through. You can use any operator withvpcEndpointId
.
-
-
For each field, choose + Condition to add as many conditions as you need, up to a maximum of 500 specified values for all conditions.
-
Choose + Field to add additional fields as required. To avoid errors, do not set conflicting or duplicate values for fields.
-
-
To add another event source for which you want to log network activity events, choose Add network activity event selector.
-
Optionally, expand JSON view to see your advanced event selectors as a JSON block.
-
-
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.
Topics
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
To see whether your trail is logging network activity events, run the get-event-selectors
Topics
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
/ --regionregion
/ --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-nameTrailName
/ --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-nameTrailName
/ --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
update-event-data-store
To see whether your event data store includes network activity events, run the
get-event-data-store
aws cloudtrail get-event-data-store --event-data-store
EventDataStoreARN
Topics
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.