Logging network activity events - AWS CloudTrail
Advanced event selector fields for network activity eventsLogging network activity events with the AWS Management ConsoleLogging network activity events with the AWS Command Line InterfaceLogging events with the AWS SDKs

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 AWS API calls made using their VPC endpoints from a private VPC to the AWS 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:

  • AWS CloudTrail

  • Amazon EC2

  • AWS KMS

  • AWS 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 AWS 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 AWS SDKs, AWS 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 AWS CloudTrail Pricing.

Logging network activity events with the AWS Management Console

You can update an existing trail or event data store 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 AWS CloudTrail Pricing.

  1. Sign in to the AWS Management Console and open the CloudTrail console at https://console.aws.amazon.com/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.

Update an existing event data store to log network activity events

Use the following procedure to update an existing event data store to log network activity events.

Note

You can only log network activity events on event data stores of type CloudTrail events.

  1. Sign in to the AWS Management Console and open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/.

  2. In the left navigation pane of the CloudTrail console, under Lake, choose Event data stores.

  3. Choose the event data store name.

  4. 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.

  5. Choose Save changes to save your changes.

Logging network activity events with the AWS Command Line Interface

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

Examples: Logging network activity events for trails

You can configure your trails to log network activity events using the AWS 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 AWS KMS

The following example shows how to configure your trail to include VpceAccessDenied events for AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS

The following example shows how to create an event data store to include VpceAccessDenied events for AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS CLI and the AWS CloudTrail API Reference.