Description

Ensure that every Amazon API Gateway REST API stage has CloudWatch execution logging enabled, with the log level set to errors only or errors and info. Execution logs record how API Gateway processes each request, including errors in authorizers, integrations and mapping.

Rationale

Without stage logging there is no record of API activity, which makes it hard to detect abuse and investigate incidents. Attackers could probe endpoints, extract data or misuse integrations without leaving traces. Enabling CloudWatch logging at the ERROR or INFO level, with appropriate log retention, restricted log access and alerting on anomalies, provides the visibility needed for monitoring and forensic analysis.

Impact

  • Provides a record of API errors and activity for troubleshooting and incident response

  • Supports monitoring and alerting on unusual API behaviour

  • CloudWatch Logs storage and ingestion costs apply, which grow with the log level and request volume

  • The INFO level and full request and response logging may record sensitive data; use them with care

Default Value

CloudWatch execution logging is turned off for new REST API stages. A CloudWatch Logs role must also be configured in the API Gateway account settings of each region before logging can be enabled.

Pre-Requisites

  • IAM permissions: apigateway:GET and apigateway:PATCH, plus iam:PassRole for the CloudWatch Logs role

  • An IAM role that API Gateway can assume to write to CloudWatch Logs (for example with the AWS managed policy AmazonAPIGatewayPushToCloudWatchLogs), set as the CloudWatch log role ARN in the API Gateway Settings of each 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 a REST API.

  3. Select Stages and select a stage.

  4. In the Logs and tracing section, check the CloudWatch logs setting.

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

  6. If CloudWatch logs are Off for the stage, follow the implementation steps.

CLI:

List the REST APIs:

aws apigateway get-rest-apis --region <REGION> --query "items[].[id,name]" --output table

Show the method settings of each stage of an API:

aws apigateway get-stages --region <REGION> --rest-api-id <REST_API_ID> --query "item[].{Stage:stageName,MethodSettings:methodSettings}" --output json

A stage fails if methodSettings is empty or no entry has loggingLevel set to ERROR or INFO. Access logging alone does not count as execution logging.

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 Settings in the left menu. If no CloudWatch log role ARN is set, choose Edit, enter the ARN of the logging role and choose Save changes.

  3. Select APIs, select the REST API and select Stages.

  4. Select the affected stage and choose Edit in the Logs and tracing section.

  5. Set CloudWatch logs to Errors only or Errors and info logs.

  6. Choose Save changes.

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

CLI:

Set the CloudWatch Logs role for API Gateway in the region (only needed once per region):

aws apigateway update-account --region <REGION> --patch-operations "op=replace,path=/cloudwatchRoleArn,value=<CLOUDWATCH_ROLE_ARN>"

Enable error logging for all methods of the stage:

aws apigateway update-stage --region <REGION> --rest-api-id <REST_API_ID> --stage-name <STAGE_NAME> --patch-operations "op=replace,path=/*/*/logging/loglevel,value=ERROR"

Backout Plan

Before making changes, save the current stage settings:

aws apigateway get-stage --region <REGION> --rest-api-id <REST_API_ID> --stage-name <STAGE_NAME> > <STAGE_NAME>-stage-backup.json

To roll back:

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

  2. Open the API Gateway console, select the REST API and select Stages.

  3. Select the stage and choose Edit in the Logs and tracing section.

  4. Set CloudWatch logs to Off and choose Save changes.

CLI:

aws apigateway update-stage --region <REGION> --rest-api-id <REST_API_ID> --stage-name <STAGE_NAME> --patch-operations "op=replace,path=/*/*/logging/loglevel,value=OFF"

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

Reference