Install the AWS Lambda@Edge Enforcer

If your organization uses AWS CloudFront services, you can use HUMAN’s CloudFront Lambda@Edge Enforcer to protect against malicious behavior. This Enforcer uses AWS Lambda functions to deploy the Enforcer on your content delivery network (CDN) and determine how traffic to your organization’s server should be handled.

You can learn how to install the Enforcer with this article.

🚧

Warning

This process only works if you do not have an existing Enforcer integrated with your application. If you do, see our article on manual installation.

Prerequisites

• An AWS CloudFront account with the following permissions:
  • Create AWS IAM policies
  • Create or edit AWS IAM user permissions
  • Create AWS Access Keys
• Depending on your preferred deployment method, the following tools:
  • Docker method:
    • Docker. See how to install Docker with their documentation.
  • Script method:
    • Node.js 18.x or later and npm 10.x or later. See how to install both with npm’s documentation.
    • Git CLI. You can download it directly from Git.
    • GNU Wget. See how to install with their documentation.
• Your unique HUMAN information:
  • Your Application ID. You can find this under Platform Settings > Applications > Overview in the HUMAN console.
  • Your Server Token. You can find this under Platform Settings > Applications, then selecting an application and navigating to Application settings > Server token.
  • Your Risk Cookie Key. You can find this under Bot Defender > Policies > Policy Settings > Policy Information.
• Other HUMAN information provided by your Solutions Engineer:
  • Your logger authentication token.
  • Your remote configuration authentication token.
  • Your remote configuration ID.
  • An Enforcer configuration file, enforcerConfig.json. Be sure to save it in a directory you’ll remember (like /deploy).

AWS IAM Setup

The AWS Lambda@Edge installation consists of three parts. Be sure to complete each part in order.

1. Create an IAM Policy to use with an AWS IAM account
2. Assign an AWS IAM account with required permissions
3. Create an AWS Access Key

Create an AWS IAM Policy

You need to create a new IAM Policy with the necessary permissions to deploy the AWS Lambda@Edge Enforcer.

1. Navigate to the AWS Console > IAM Dashboard > Policies and click Create Policy.
2. In Step 1, Specify permissions > Policy editor, click JSON.
3. Replace the JSON that appears with the JSON below.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"lambda:CreateFunction",
				"lambda:UpdateFunctionCode",
				"lambda:UpdateFunctionConfiguration",
				"lambda:PublishVersion",
				"lambda:GetFunction",
				"lambda:ListFunctions",
				"lambda:InvokeFunction",
				"lambda:EnableReplication",
				"cloudfront:CreateDistribution",
				"cloudfront:UpdateDistribution",
				"cloudfront:GetDistribution",
				"cloudfront:ListDistributions",
				"cloudfront:ListCachePolicies",
				"cloudfront:CreateCachePolicy",
				"cloudfront:GetDistributionConfig",
				"iam:CreateRole",
				"iam:AttachRolePolicy",
				"iam:PutRolePolicy",
				"iam:PassRole",
				"iam:GetRole",
				"iam:ListRoles",
				"iam:GetUser"
			],
			"Resource": "*"
		}
	]
}

4. Click Next and provide a Policy name.
5. Click Create Policy.

Next, move on to Assign AWS IAM account permissions.

Assign AWS IAM account permissions

Your goal is to have at least one AWS IAM user with permission to send request to different AWS APIs. You can do this by either creating a new AWS IAM account or editing permissions for an existing account.

📘

Note

Unless specified, you can leave fields as their defaults or skip them.

Option 1: Create a new AWS IAM account

1. Navigate to the AWS Console > IAM Dashboard > Users and click Create user.
2. In Step 1, Specify User Details, provide a user name and click Next.
3. In Step 2, Set permissions:
4. In the Permissions options, choose Attack policies directly.
5. In the Permissions policies area that appears, click the checkbox next to the Policy you created in Create an AWS IAM Policy.
6. Click Next. Then, in Step 3, Review and create, click Create user.

Next, move on to Create an AWS Access Key.

Option 2: Edit an existing AWS IAM account

1. Navigate to the AWS Console > IAM Dashboard > Users.
2. Click the user you want to add permissions to.
3. Under Permissions > Permissions policies, click Add permissions > Add permissions.
4. From Step 1, Add permissions:
5. In Permissions options, choose Attack policies directly.
6. In the Permissions policies area that appears, click the checkbox next to the Policy you created in Create an AWS IAM Policy.
7. Click Next. Then, in Step 2, Review, click Add permissions.

Next, move on to Create an AWS Access Key.

Create an AWS Access key

1. Navigate to the AWS Console > IAM Dashboard > Users and select the user you just created or edited from Assign AWS IAM account permissions.
2. Click the Security credentials tab.
3. Navigate to the Access keys area and click Create access key.
4. In Step 1, Access key best practices & alternatives, select Other as the Use case. Then, click Next.
5. If you’d like, add a description. Otherwise, click Create access key.
6. Copy the Access key and Secret access key that appear.

🚧

Warning

This will be the only time you’ll see the access key and secret access key, so be sure to save it before closing the page!

Update the configuration file

1. Update the Enforcer configuration file, enforcerConfig.json, with your unique HUMAN information if it hasn’t been already.

{
  "px_app_id": "<APP_ID>",
  "px_auth_token": "<AUTH_TOKEN>",
  "px_cookie_secret": "<COOKIE_SECRET>",
  "px_logger_auth_token": "<LOGGER_AUTH_TOKEN>",
  "px_remote_config_auth_token": "<REMOTE_CONFIG_AUTH_TOKEN>",
  "px_remote_config_id": "<REMOTE_CONFIG_ID>"
}

2. Save your file and select your preferred method to run the Deploy Tool.
3. Docker method
4. Script method

Run the Deploy Tool

Docker method

📘

Note for Windows users

Windows users also need to complete additional setup for Docker:

1. In your Windows search bar, search for and open “Turn Windows features on or off”.
2. Find the Windows Hypervisor Platform feature and enable it.
3. Click OK to save your changes.
4. Open Windows PowerShell as an Administrator.
5. Copy and paste in C:\Windows\System32\wsl.exe --update --web-download, then hit Enter.

1. Pull the Docker Image by running:

docker pull us-docker.pkg.dev/hmn-registry/docker-public/cdn-enforcer-deploy-tool

2. Navigate to the directory where you created enforcerConfig.json. Based on our example from above, this would be the /deploy directory.
3. Run the deploy tool with the following:

docker run --rm -v $PWD:/app/local -it us-docker.pkg.dev/hmn-registry/docker-public/cdn-enforcer-deploy-tool

Script method

1. Navigate to the directory where you created enforcerConfig.json. Based on our example from above, this would be your /deploy directory.
2. Pull the HUMAN Deploy Tool zip from Google Artifact Registry using:

wget https://artifactregistry.googleapis.com/v1/projects/hmn-registry/locations/us/repositories/enforcers-public/files/cdn-enforcer-deploy-tool_win:1.0.1:cdn-enforcer-deploy-tool_win.zip:download?alt=media -O cdn-enforcer-deploy-tool.zip

wget https://artifactregistry.googleapis.com/v1/projects/hmn-registry/locations/us/repositories/enforcers-public/files/cdn-enforcer-deploy-tool_unix:1.0.1:cdn-enforcer-deploy-tool_unix.zip:download?alt=media -O cdn-enforcer-deploy-tool.zip

3. Unzip cdn-enforcer-deploy-tool.zip to the same directory you saved enforcerConfig.json in.
4. Run the tool by opening the appropriate script for your system:

• Windows: cdn-enforcer-deploy-tool.bat
• Mac or Linux: cdn-enforcer-deploy-tool.command

Deploy the Enforcer

1. When prompted, select AWS CloudFront Lambda@Edge and hit Enter.

🚀 HUMAN CDN Enforcer Deploy Tool 🚀
? Which platform do you want to deploy to? (Use arrow keys)
  ...
  Akamai EdgeWorker
❯ AWS CloudFront Lambda@Edge
  ...

2. Continue to follow the steps that appear to complete your deployment.
3. When you finish the setup, confirm that the displayed details are correct, then enter y to deploy the Enforcer.

Enable CloudWatch logs (recommended)

We recommend creating an IAM role for each Lambda you upload. This lets the function create log groups and log streams in CloudWatch. When you deploy a Lambda@Edge function, it distributes across all edge cache locations, and all logs from the Lambda related to those regions will appear in the CloudWatch logs of their respective edge cache areas. For example, if a user accesses the us-east-1 region, the corresponding logs will be found in us-east-1.

{  
"Version": "2012-10-17",  
"Statement": \[  
    {  
        "Effect": "Allow",  
        "Action": "logs:CreateLogGroup",  
        "Resource": "arn:aws:logs:_:_:_"  
    },  
    {  
        "Effect": "Allow",  
        "Action": [  
            "logs:CreateLogStream",  
            "logs:PutLogEvents"  
        ],  
        "Resource": \[  
            "arn:aws:logs:_:_:log-group:_:\*"  
        ]  
    }  
  ]  
}