버전: 1.1.4.1

설치 및 초기화

개요

BotManager-CloudFront-Agent는 Origin 서버를 수정하지 않고 AWS Lambda@Edge를 활용하여 BotManager의 탐지 기능을 간단하게 적용할 수 있도록 설계되었습니다.

BotManager는 다양한 분석 기법(헤더 분석, 행위 분석, 해외 IP 차단, 접속 통계 등)을 통해 봇 및 매크로 사용자를 탐지하는 솔루션입니다. 이를 통해 웹 서비스를 보호하고, 악성 사용자 및 자동화된 봇의 위협으로부터 데이터를 안전하게 관리할 수 있습니다.

AWS CloudFront란?

Amazon CloudFront는 AWS 글로벌 엣지 네트워크를 통한 CDN 서비스로, 정적·동적 콘텐츠를 최종 사용자에게 빠르게 전달합니다.

주요 특징:

500개 이상 엣지 로케이션, HTTP/2·gRPC·WebSocket 지원
Lambda@Edge로 요청/응답 중간에 커스텀 코드 실행
보안 통합: AWS WAF, AWS Shield, SSL/TLS
실시간 로깅: CloudWatch, S3, Kinesis 연동

설치 방법

1. Lambda 함수 생성

경고

Lambda 함수는 us-east-1(N. Virginia) 리전에서 만들어야 합니다. 이는 AWS의 요구 사항으로, 이 리전은 함수를 전 세계적으로 복제하기 위한 중앙 위치 역할을 하기 때문입니다.

us-east-1 지역의 AWS 콘솔 → IAM > 역할 → 역할 생성
trusted entity 선택 및 Custom trust policy를 입력하세요:

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

권한 추가를 위해 리스트에서 AWSLambdaBasicExecutionRole 선택합니다.
역할 이름은 BotManager-CloudFront-Role로 설정합니다.
AWS 콘솔 → Lambda > 함수 생성
함수 이름 및 환경 설정:
- 함수 이름: botmanager-cloudfront-agent
- 런타임: Node.js 18.x 이상
- 실행 역할: 앞서 생성한 BotManager-CloudFront-Role

2. 에이전트 업로드

아래 링크의 BotManager-CloudFront-Agent를 다운 받은 후 콘솔에서 .zip file을 선택해서 업로드 합니다.
- 다운로드 링크
업로드가 완료되면 아래 3개의 파일이 생성됩니다:
- botmanager-config.json
- index.mjs
- package.json

3. BotManager 초기 설정 적용

에이전트를 설치할 도메인을 선택하고 Code source에서 botmanager-config.json에 아래 내용 복사 후 붙여 넣습니다.

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

Key	Require	Value	Description
`BM_TENANTID`	Yes	`{tenantId}`	고객사 식별을 위한 고유 ID
`BM_DOMAINNAME`	Yes	`{domainName}`	요청이 들어오는 서버의 도메인
`BM_SERVERURL`	No	`https://botmanager.stclab.com`	탐지 서버 URL
`BM_PROTECTION_SERVERURL`	No	`https://cdn-botmanager.stclab.com`	차단 페이지(Captcha, Deny, Challenge) URL
`BM_SERVER_TIMEOUT`	No	`1000`	탐지 서버로의 HTTP 요청 타임 아웃(ms)
`BM_STATIC_BYPASS`	No	`false`	Lambda에서 Document가 아닌 정적 리소스 호출시 로직이 실행될 경우 Document 일때만 탐지하도록하는 설정값
`BM_COOKIE_HTTPONLY`	No	`false`	Browser-Agent없이 Lambda만 사용할 경우 식별자 보호를 위한 쿠키 설정값
`BM_COOKIE_PROTOCOL`	No	`https`	Browser-Agent에서 서비스 페이지의 프로토콜을 알 수 없는 경우 쿠키 생성시 해당 프로토콜 설정에 맞게 쿠키 생성
`BM_LOGLEVEL`	No	`ERROR`	로그 레벨(DEBUG, INFO, WARN, ERROR)
`BM_BYPASS`	No	`false`	Lambda에서 BotManager Agent가 로직을 실행하지 않도록하는 플래그

4. 새 버전 개시

코드 적용이 완료되었으면 Actions의 Publish new version을 클릭하여 새로운 버전으로 게시를 진행합니다.

5. CloudFront와 연결

CloudFront에 적용할 botmanager-cloudfront-agent Lambda ARN을 복사합니다.
AWS 콘솔 → CloudFront > 배포 → BotManager-CloudFront-Agent를 적용할 대상 배포를 선택합니다.
Behaviors 탭 → 수정할 Behavior 우측 Edit 클릭합니다.
Lambda Function Associations:
- Viewer Request → 복사한 botmanager-cloudfront-agent 버전 ARN을 붙여 넣습니다.
- Viewer Response → 동일 ARN을 붙여넣습니다.

경고

뒤에 버전명을 꼭 넣어주세요. (버전이 1일 경우 :1을 추가하면 됩니다.)

무효화를 위해 Invalidations 탭에서 Create invalidation을 클릭 합니다.
객체 경로에 /*을 입력하고 무효화 생성을 클릭합니다.
콘솔에서 CloudFront 무효화 상태를 확인 하세요. (배포 완료 대기 5–10분 소요)

설치 완료!

완료되면 CloudFront에 BotManager-CloudFront-Agent가 Lambda@Edge에 연결되어 봇 및 매크로를 탐지·차단 할 수 있게 됩니다.

개요​

AWS CloudFront란?​

설치 방법​

1. Lambda 함수 생성​

2. 에이전트 업로드​

3. BotManager 초기 설정 적용​

4. 새 버전 개시​

5. CloudFront와 연결​

개요