Installation and Initialization

Overview

BotManager-CloudFront-Agent is designed to easily apply BotManager's detection capabilities using AWS Lambda@Edge without modifying the Origin server.

BotManager is a solution that detects bots and macro users through various analysis techniques (header analysis, behavior analysis, foreign IP blocking, access statistics, etc.). This protects web services and safely manages data from threats of malicious users and automated bots.

What is AWS CloudFront?

Amazon CloudFront is a CDN service through AWS global edge network that quickly delivers static and dynamic content to end users.

Key Features:

• Over 500 edge locations, supports HTTP/2, gRPC, WebSocket
• Lambda@Edge executes custom code during request/response
• Security Integration: AWS WAF, AWS Shield, SSL/TLS
• Real-time logging: Integration with CloudWatch, S3, Kinesis

Installation Methods

1. Create Lambda Function

warning

Lambda function must be created in the us-east-1 (N. Virginia) region. This is an AWS requirement, as this region serves as the central location for replicating functions globally.

1. AWS Console in us-east-1 region → IAM > Roles → Create role

2. Select trusted entity and enter Custom trust policy:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"Service": [
					"edgelambda.amazonaws.com",
					"lambda.amazonaws.com"
				]
			},
			"Action": "sts:AssumeRole"
		}
	]
}

3. Select AWSLambdaBasicExecutionRole from the list to add permissions.

4. Set role name to BotManager-CloudFront-Role.

5. AWS Console → Lambda > Create function

6. Function name and environment settings:

   • Function name: botmanager-cloudfront-agent
   • Runtime: Node.js 18.x or higher
   • Execution role: Previously created BotManager-CloudFront-Role

2. Upload Agent

1. Download BotManager-CloudFront-Agent from the link below, then upload by selecting .zip file in the console.

   • Download Link

2. After upload is complete, the following 3 files will be created:

   • botmanager-config.json
   • index.mjs
   • package.json

3. Apply BotManager Initial Configuration

1. Select the domain where the agent will be installed and copy and paste the following content into botmanager-config.json in Code source.

{
    "BM_TENANTID": "{TENANT ID}",
    "BM_DOMAINNAME": "{DOMAIN}"
}

Key	Require	Value	Description
BM_TENANTID	Yes	{tenantId}	Unique ID for customer identification
BM_DOMAINNAME	Yes	{domainName}	Domain of the server receiving requests
BM_SERVERURL	No	https://botmanager.stclab.com	Detection server URL
BM_PROTECTION_SERVERURL	No	https://cdn-botmanager.stclab.com	Block page (Captcha, Deny, Challenge) URL
BM_SERVER_TIMEOUT	No	1000	HTTP request timeout to detection server (ms)
BM_STATIC_BYPASS	No	false	Configuration value to detect only when Document if logic runs when calling static resources that are not Documents in Lambda
BM_COOKIE_HTTPONLY	No	false	Cookie configuration value for identifier protection when using only Lambda without Browser-Agent
BM_COOKIE_PROTOCOL	No	https	Cookie creation according to protocol settings when Browser-Agent cannot identify service page protocol during cookie creation
BM_LOGLEVEL	No	ERROR	Log level (DEBUG, INFO, WARN, ERROR)
BM_BYPASS	No	false	Flag to prevent BotManager Agent from executing logic in Lambda

4. Publish New Version

1. After code application is complete, click Publish new version in Actions to publish as a new version.

5. Connect to CloudFront

1. Copy the botmanager-cloudfront-agent Lambda ARN to apply to CloudFront.

2. AWS Console → CloudFront > Distributions → Select the target distribution to apply BotManager-CloudFront-Agent.

3. Behaviors tab → Click Edit on the right of the Behavior to modify.

4. Lambda Function Associations:

   • Viewer Request → Paste the copied botmanager-cloudfront-agent version ARN.
   • Viewer Response → Paste the same ARN.

warning

Be sure to include the version number at the end. (If version is 1, add :1.)

5. Click Create invalidation in Invalidations tab for invalidation.

6. Enter /* in object path and click Create invalidation.

7. Check CloudFront invalidation status in the console. (Wait 5–10 minutes for deployment to complete)

Installation Complete!

Once complete, BotManager-CloudFront-Agent will be connected to Lambda@Edge in CloudFront, enabling detection and blocking of bots and macros.