This article discusses how to integrate the Amazon API gateway with the Cequence Unified API Protection (UAP) platform.

Integration architecture

The Amazon API gateway integration for the Cequence UAP platform is made of the following components.

Amazon API Gateway

Receives incoming requests from clients and routes the requests to the appropriate API backend services or applications.

Generates detailed log entries for each request and response, including headers, body, query parameters, and other metadata relevant to Cequence UAP platform analysis.

Amazon CloudWatch

Receives log events from API Gateway and stores them in log groups.

Note: Amazon CloudWatch limitations limit batch sizes to 1MB and 5000 transactions per second, per region. Use the Service Quotas service to change the transaction-per-second limit. The batch size limit cannot be increased.

Amazon CloudWatch Events

A serverless event management service that enables the triggering of an AWS service at a scheduled interval. Amazon CloudWatch Events triggers an AWS Lambda function that captures API Gateway log events every minute.

AWS Lambda function

Triggered every minute by AWS CloudWatch Events. Pulls the API Gateway log entries from AWS CloudWatch Events, transforms the entries into the payload format used by the Cequence UAP platform, aggregates the entries over the last minute of activity, and posts the batch to the Cequence UAP platform for analysis.

The procedures in this article automate the Lambda function configuration by discovering all API gateways and their deployed stages, then configuring the dependencies above. A Terraform script that provides this automation can be applied to an individual AWS account.

Prerequisites

• Working APIs deployed to various stages in API Gateway.
• Terraform release v1.9.8 or later.
• An AWS account with sufficient permissions to manage API Gateway, Lambda, IAM, CloudWatch, EventBridge Scheduler, and EC2.
• AWS CLI release 2.14.0 or later
• Access to an AWS CLI user account with specific privileges and roles, which are described in a following section.
• An AWS policy named according to the following format.
  

  iam_apigw_lambda_cloudwatch_eventbridge_cq_integration

AWS CLI user privileges

Setting up the Amazon API Gateway integration requires the use of an AWS CLI user account with an access key, secret, and below privileges. These restricted permissions gets applied to resources that are created by Terraform.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:GetRole",
                "iam:DeleteRole",
                "iam:PutRolePolicy",
                "iam:DeleteRolePolicy",
                "iam:GetRolePolicy",
                "iam:PassRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy"
            ],
            "Resource": [
                "arn:aws:iam::*:role/cequence_*",
                "arn:aws:iam::*:role/AmazonAPIGatewayPushToCloudWatchLogs2-*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "lambda:CreateFunction",
                "lambda:DeleteFunction",
                "lambda:GetFunction",
                "lambda:UpdateFunctionConfiguration",
                "lambda:UpdateFunctionCode",
                "lambda:ListVersionsByFunction",
                "lambda:GetFunctionCodeSigningConfig"
            ],
            "Resource": "arn:aws:lambda:*:*:function:cequence-api-gateway-cloudwatch-lambda1-*"
            },
        {
            "Effect": "Allow",
            "Action": [
                "scheduler:CreateSchedule",
                "scheduler:DeleteSchedule",
                "scheduler:GetSchedule"
            ],
            "Resource": "arn:aws:scheduler:*:*:schedule/default/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:DeleteLogGroup",
                "logs:PutRetentionPolicy"
            ],
            "Resource": [
                "arn:aws:logs:*:*:log-group:/aws/lambda/cequence-api-gateway-cloudwatch-lambda1-*",
                "arn:aws:logs:*:*:log-group:/aws/apigateway/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "ec2:DescribeRegions",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "apigateway:GET",
                "apigateway:POST",
                "apigateway:PUT",
                "apigateway:PATCH",
                "apigateway:DELETE"
            ],
            "Resource": [
                "arn:aws:apigateway:*::/restapis/*/stages/*",
                "arn:aws:apigateway:*::/restapis/*/stages",
                "arn:aws:apigateway:*::/restapis/*/deployments",
                "arn:aws:apigateway:*::/account"
            ]
        }
    ]
}

The Terraform script requires the following roles and permissions.

API Gateway Role (aws_iam_role.api_gateway_cloudwatch)

• Purpose: Allows API Gateway to push logs to CloudWatch
• Trust Policy: Allows only apigateway.amazonaws.com to assume this role
• Permissions: Uses AWS managed policy AmazonAPIGatewayPushToCloudWatchLogs
• Used by: API Gateway account settings for CloudWatch logging

Lambda Role (aws_iam_role.lambda_role)

• Purpose: Enables Lambda function to interact with CloudWatch Logs
• Trust Policy: Allows only lambda.amazonaws.com to assume this role
• Custom Policy Permissions:

• logs:CreateLogGroup
  logs:CreateLogStream
  logs:PutLogEvents
  logs:FilterLogEvents
  logs:Unmask

• Scope: Full access to CloudWatch logs resources (arn:aws:logs:*:*:*)

EventBridge Role (aws_iam_role.eventbridge_role)

• Purpose: Allows EventBridge to invoke the Lambda function
• Trust Policy: Allows only scheduler.amazonaws.com to assume this role
• Custom Policy Permissions:

  lambda:InvokeFunction

• Scope: Limited to only the specific Lambda function ARN

Terraform Installation

The main Terraform file main.tf is structured in two parts.

Note: This integration requires Terraform release v1.9.8 or later.

Global resources

The Global Resources section creates resources that are applicable to the entire account and are not region-specific. These resources are shared across all regions in the AWS account.

Regional resources:

The Regional Resources section creates region-specific resources in each target region. These include:

• Lambda functions
• EventBridge scheduler
• CloudWatch log groups
• API Gateway configurations
• Monitoring of APIs deployed across multiple AWS regions within the same account
• Independent set of monitoring resources for each region

This modular approach ensures comprehensive API scanning and monitoring capabilities across all regions where your APIs are deployed, while maintaining proper resource isolation and regional compliance.

1. Download the compressed AWS API gateway integration bundle.
2. Move the compressed file to a folder named cequence_aws_apigw_zendesk, then run the following command.
   

   tar -xvf cequence-aws-api-gateway-2.1.xxxxxxx.tar.gz 
   cd cequence/terraform

3. (Optional) Run the following command to a list of API Gateways.
   

   ../bin/scan-aws-api-gateways.sh > api-list.txt
   cat api-list.txt

4. From the terraform folder, run the terraform init command.
   Create the terraform.tfvars file with contents similar to the following sample.

   cequence_client_id = "xxxxx"
   cequence_client_secret = "xxxxxxx"
   cequence_auth_endpoint = "https://auth.xxxxx.xxxxx.cloud/auth/realms/cequence/protocol/openid-connect/token"
   cequence_edge_endpoint = "https://edge.xxxxx.xxxxx.cloud/api-transactions"

5. (Optional) Test deployment on one of the API Gateways chosen from Step #3.
   

   terraform apply -var='api_gateway_apis={"us-west-2"="tvja0oxvpf/test"}'

6. Run the following command to deploy on all API Gateways.

   terraform apply -var="$(../bin/scan-aws-api-gateways.sh)"

The final step in this procedure scans all APIs in the AWS account and enables the integrations for the deployed APIs in all stages. As a best practice, consider running the terraform apply command daily as part of a cron job or pipeline in order to discover and catalog new APIs.

Please make sure you save terraform.tfstate generated using terraform command. This is needed for future terraform apply and destroy commands.

Post-Installation

• The Lambda function runs every minute, aggregating logs from the specified API Gateway.
• Monitor the CloudWatch Log Group for Lambda function logs.
  

  /aws/lambda/cequence-api-gateway-cloudwatch-lambda-*

• The API Gateway logs will be in the following log group.

  /aws/apigateway/[API_ID]/[STAGE]

Note

1. AWS API Gateway limits log events to 1024 bytes. Log events larger than 1024 bytes, such as request and response bodies, are truncated by API Gateway before submission to CloudWatch logs.

2. The Current implementation of Terraform caters to REST APIs only

Cleanup

To remove all created resources, run the following command.

terraform destroy

Confirm the action by entering 'yes' when prompted.