Description

Ensure that every stage of an Amazon API Gateway HTTP or WebSocket API (API Gateway V2) has access logging enabled. Access logs record who called the API and how, including the request ID, source IP address, route, status code and latency, and deliver them to a CloudWatch Logs log group.

Rationale

Without access logs, API calls cannot be traced, which makes it hard to detect credential misuse, abuse of routes or unusual traffic. Unauthorized data access or changes may go unnoticed, and incident response is slowed because there is no record to investigate. Enabling stage access logging with a structured format, appropriate retention, restricted log access and alerting provides the traceability needed for monitoring and investigations.

Impact

  • Provides a record of every API request for security monitoring and incident investigation

  • Supports troubleshooting of client and integration errors

  • CloudWatch Logs ingestion and storage costs apply, depending on request volume and the log format

Default Value

Access logging is disabled for new HTTP and WebSocket API stages.

Pre-Requisites

  • IAM permissions: apigateway:GET, apigateway:PATCH and apigateway:DELETE on the API stages, plus logs:CreateLogGroup and logs:DescribeLogGroups

  • A CloudWatch Logs log group to receive the logs, and its ARN

  • For WebSocket APIs: an IAM role for CloudWatch Logs set as the CloudWatch log role ARN in the API Gateway Settings of the region

Remediation

Test Plan

Console:

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

  2. Open the API Gateway console and select an HTTP or WebSocket API.

  3. Select Stages (for HTTP APIs, under Monitor select Logging) and select a stage.

  4. Check whether access logging is enabled and a log destination is set.

  5. Repeat for each stage of each API in each region in use.

  6. If access logging is disabled for any stage, follow the implementation steps.

CLI:

List the HTTP and WebSocket APIs:

aws apigatewayv2 get-apis --region <REGION> --query "Items[].[ApiId,Name,ProtocolType]" --output table

Show the access log destination of each stage of an API:

aws apigatewayv2 get-stages --region <REGION> --api-id <API_ID> --query "Items[].[StageName,AccessLogSettings.DestinationArn]" --output table

A stage fails if it has no access log settings (the destination shows as None).

Implementation Steps

Console:

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

  2. Open the API Gateway console and select the HTTP or WebSocket API.

  3. For an HTTP API, select Logging under Monitor, select the stage and choose Edit. For a WebSocket API, select Stages, select the stage and edit its logging settings.

  4. Turn on access logging.

  5. Enter the ARN of the CloudWatch Logs log group as the log destination.

  6. Choose a log format (for example JSON) that includes at least $context.requestId.

  7. Choose Save.

  8. Repeat for each affected stage in each region in use.

CLI:

The settings are passed in a file because a log format with several fields contains commas, which the inline syntax cannot parse. Save the following as access-log-settings.json:

{
"DestinationArn": "<LOG_GROUP_ARN>",
"Format": "{\"requestId\":\"$context.requestId\",\"ip\":\"$context.identity.sourceIp\",\"requestTime\":\"$context.requestTime\",\"routeKey\":\"$context.routeKey\",\"status\":\"$context.status\"}"
}

Enable access logging for a stage:

aws apigatewayv2 update-stage --region <REGION> --api-id <API_ID> --stage-name <STAGE_NAME> --access-log-settings file://access-log-settings.json

Backout Plan

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

  2. Open the API Gateway console, select the API and open the logging settings of the stage.

  3. Turn off access logging and save the change.

CLI:

aws apigatewayv2 delete-access-log-settings --region <REGION> --api-id <API_ID> --stage-name <STAGE_NAME>

Note: rolling back removes the record of API requests needed for monitoring and incident investigation.

Reference