Manually install the AWS Lambda@Edge Enforcer

If your organization uses AWS CloudFront services, you can use HUMAN’s 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.

Prerequisites

• An AWS account with appropriate permissions and access to the following (see AWS’ help article for more information):
  • AWS CloudFront with an existing CloudFront distribution. See AWS’ help article to learn how to create one.
  • AWS Lambda and permissions to deploy Lambda functions to CloudFront distributions
  • AWS CloudWatch
  • AWS IAM with permissions to create and modify IAM roles
• A command-line interface (CLI).
• A text editor.
• GitHub CLI. See GitHub’s repository to learn how to install it.
• Node Version Manager (nvm) installed on your device. See nvm’s GitHub repository to learn how to install it.
• The latest version of Node.js. After installing nvm, enter nvm install stable in your CLI to install it.
• Your unique HUMAN information:
  • Your Application ID. You can find this under Platform Settings > Applications > Overview in the HUMAN console. If you have multiple environments, you will also have multiple Application IDs, so be sure to choose the correct ID for the environment you want to install on.
  • Your Server Token. You can find this under Platform Settings > Applications > Status & Settings > Server Token.
  • Your Risk Cookie Key. You can find this under Bot Defender > Policies > Policy Settings > Policy Information. You may need to generate a new key if you do not already have one.

Define the Lambda functions

The Lambda@Edge Enforcer consists of three Lambda functions. Each function is integrated at a different event in an Amazon CloudFront distribution. They are:

• HumanEnforcer Lambda (required): Triggered by the viewer request event. You must create this Lambda function to properly install the Enforcer.
• HumanActivities Lambda (optional): Triggered by the origin response. You should only integrate this Lambda if you have enabled features or products that require response data.
• HumanFirstParty Lambda (optional): Triggered by the origin request. This Lambda will only be used for first-party requests from HUMAN, and it will not monitor typical website traffic.

The process for defining your Lambda functions is different depending on if you have an existing Lambda project or not.

• If you do not have an existing Lambda project, see Define with the HUMAN template.
• If you do have an existing Lambda project, see Define with an existing project.

Define with the HUMAN template

If you do not have an existing AWS project, then you can use HUMAN’s premade templates to quickly create and install the AWS Lambda@Edge Enforcer. This Enforcer is publicly available from our GitHub repository.

1. In your CLI, enter git clone https://github.com/PerimeterX/aws-lambda-edge-template.
2. Enter cd aws-lambda-edge-template.
3. Enter npm install. This installs the necessary dependencies to use the Enforcer template.
4. In your preferred text editor, open basic_example/src/custom/config.json and update the px_app_id, px_auth_token, and px_cookie_secret fields with your Application ID, Server Token, and Risk Cookie Key respectively.

5. Save config.json.
6. In your CLI, enter npm run zip to bundle your Lambda functions into ZIP files. This should create HumanActivities.zip, HumanEnforcer.zip, and HumanFirstParty.zip.

Next, see the steps in Deploy the Enforcer to complete your setup.

Define with an existing project

If you already have a Lambda project that you want to integrate the HUMAN Enforcer with, then you can follow the steps below.

The HumanEnforcer Lambda is required.

To get started:

1. Navigate to the directory of your Lambda project that contains the package.json file. Typically, this is the root directory of your project.
2. Enter npm i --save @humansecurity/aws-lambda-edge-enforcer. This will update your package.json dependencies with the latest HUMAN AWS Lambda@Edge Enforcer package.
3. Create a config.json file. We recommend doing this if you are creating multiple Lambda functions. If you plan to define custom functions as part of your configuration, you may want to modify this file to be a JavaScript (i.e., config.js) or TypeScript file (i.e., config.ts) rather than a JSON file.

Then, follow the appropriate section for each Lambda function:

• Define the HumanEnforcer Lambda (required)
• Define the HumanActivities Lambda
• Define the HumanFirstParty Lambda

Define the HumanEnforcer Lambda

The HumanEnforcer Lambda is the primary Lambda that determines the behavior of traffic activity in your CloudFront distribution. This Lambda is required so that the AWS Lambda@Edge Enforcer can function.

1. In your config.json file, insert the following code and update the APP_ID, AUTH_TOKEN, and COOKIE_SECRET fields with your Application ID, Server Token, and Risk Cookie Key respectively.

If you also want to add any custom configurations, we recommend doing so in this step before uploading any Lambda function to AWS CloudFront for the first time. You can review our available configurations with our help article.

1
{
2
    "px_app_id": "<APP_ID>",
3
    "px_auth_token": "<AUTH_TOKEN>",
4
    "px_cookie_secret": "<COOKIE_SECRET>"
5
}

2. In the file with your existing Lambda’s source code, add the appropriate code from below depending on if you have existing handler logic.

1
// index.ts
2
import { createHumanEnforceHandler } from '@humansecurity/aws-lambda-edge-enforcer';
3
import config from "./config.json"
4
5
// create and export the handler
6
export const handler = createHumanEnforceHandler(config);

3. If you want to deploy other Lambdas with the Enforcer, complete the setup for each by following the steps in either Define the HumanActivities Lambda or Define the HumanFirstParty Lambda.
4. Save config.json.
5. Bundle your Lambda function into a JavaScript file. For example, if you are bundling a function in a TypeScript file named index.ts into the dist directory, you would run: esbuild ./index.ts --bundle --minify --platform=node --target=es2022 --outfile=dist/index.js.
6. Zip your bundled function.

Once you’ve zipped your function, see the steps in Deploy the Enforcer to complete your setup.

Define the HumanActivities Lambda

You only need to configure the HumanActivities Lambda if you want to send the custom HUMAN configuration additional_s2s_activity to the origin. This lets HUMAN analyze data related to the response in addition to the request.

1. In your config.json file, insert the following code and update the APP_ID, AUTH_TOKEN, and COOKIE_SECRET fields with your Application ID, Server Token, and Risk Cookie Key respectively.

1
{
2
    "px_app_id": "<APP_ID>",
3
    "px_auth_token": "<AUTH_TOKEN>",
4
    "px_cookie_secret": "<COOKIE_SECRET>"
5
}

2. In the file with your existing Lambda’s source code, add the appropriate code from below depending on if you have existing handler logic.

1
// index.ts
2
import { createHumanActivitiesHandler } from '@humansecurity/aws-lambda-edge-enforcer';
3
import config from "./config.json"
4
5
// create and export the handler
6
export const handler = createHumanActivitiesHandler(config);

3. If you want to deploy other Lambdas with the Enforcer, complete the setup for each by following the steps in either Deploy the HumanEnforcer Lambda or Deploy the HumanFirstParty Lambda. Otherwise, continue to the next step.
4. Save config.json.
5. Bundle your Lambda function into a JavaScript file. For example, if you are bundling a function in a TypeScript file named index.ts into the dist directory, you would run: esbuild ./index.ts --bundle --minify --platform=node --target=es2022 --outfile=dist/index.js.
6. Zip your files.

Once you’ve zipped your function, see the steps in Deploy the Enforcer to complete your setup.

Define the HumanFirstParty Lambda

You only need to configure the HumanFirstParty Lambda if you want to support first-party requests. You can learn more about these requests with our help article.

1. In your config.json file, insert the following code and update the APP_ID field with your Application ID and add relevant first-party custom configurations you want to include to the definition.

1
{
2
    "px_app_id": "<APP_ID>",
3
    "px_auth_token": "<AUTH_TOKEN>",
4
    "px_cookie_secret": "<COOKIE_SECRET>"
5
}

2. In the file with your existing Lambda’s source code, add the following code:

1
// index.ts
2
import { createHumanFirstPartyHandler } from '@humansecurity/aws-lambda-edge-enforcer';
3
import config from "./config.json"
4
5
export const handler = createHumanFirstPartyHandler(config);

3. If you want to deploy other Lambdas with the Enforcer, complete the setup for each by following the steps in either Deploy the HumanEnforcer Lambda or Deploy the HumanActivities Lambda. Otherwise, continue to the next step.
4. Save config.json.
5. Bundle your Lambda function into a JavaScript file. For example, if you are bundling a function in a TypeScript file named index.ts into the dist directory, you would run: esbuild ./index.ts --bundle --minify --platform=node --target=es2022 --outfile=dist/index.js.
6. Zip your files.

Once you’ve zipped your function, see the steps in Deploy the Enforcer to complete your setup.

Deploy the Enforcer

Now that you have your Lambda functions ready, you must upload them to AWS CloudFront and deploy them. The steps to upload each type of Lambda are different, so be sure to follow the correct instructions for the Lambda you’re uploading.

• Upload the HumanEnforcer Lambda (required)
• Upload the HumanActivities Lambda
• Upload the HumanFirstParty Lambda
• Enable CloudWatch logs (recommended)

Upload the HumanEnforcer Lambda (required)

Complete the following steps to upload the HumanEnforcer Lambda.

1. Navigate to Lambda > Functions.
2. Select Create function to make a new Lambda function.
3. Select the option to Author from scratch.
4. Complete the fields to create a new function. You can leave most of the fields with their default values, but be sure to update the following:
   • Function name: Enter the name for your function.
   • Runtime: Select at least Node.js 18.x or higher.
   • Permissions > Change default execution role > Execution role: Choose the appropriate role defined by your Lambda permissions and fill in the fields that appear if necessary. The role is determined by your organization’s AWS policy.
     • If your organization already has a role with the appropriate permissions, select Use an existing role.
     • If your organization does not have an appropriate role, create a new one with one of the available options.
5. Select Create function to finish making your function.
6. From your Lambda > Functions table, select the function you just created.
7. In the Code source section, select Upload from and choose .zip file.
8. Select the Lambda function ZIP file.
9. Select Save.
10. Select Actions > Publish new version.
11. Copy the Function ARN.
12. Navigate to CloudFront > Distributions.
13. Select a Distribution ID > Behaviors.
14. If you already have a behavior that uses the Default (*) path pattern, select it. Otherwise, select Create behavior.
15. Complete the following fields:
    • Path Pattern: Default (*)
    • Cache policy and origin request policy (recommended): Select an origin request policy to ensure you do not remove important headers. If one does not exist, see AWS’ help article to create one. Our recommendations are:
      • AllViewerExceptHostHeader: We recommend using this policy, especially if you are also uploading the HumanFirstParty Lambda.
      • AllViewer
      • AllViewerAndCloudFrontHeaders-2022-06
    • Viewer request event:
      • Select Lambda@Edge for the function type.
      • Paste the Function ARN from Step 11 in the field that appears.
16. Select Save changes.

You have successfully integrated the HUMAN AWS Lambda@Edge Enforcer with your CloudFront distribution. Make sure to reach out to our support team to complete your tuning process.

Upload the HumanActivities Lambda

Complete the following steps to upload the HumanActivities Lambda.

1. Navigate to Lambda > Functions.
2. Select Create function to make a new Lambda function.
3. Select the option to Author from scratch.
4. Complete the fields to create a new function. You can leave most of the fields with their default values, but be sure to update the following:
   • Function name: Enter the name for your function.
   • Runtime: Select at least Node.js 18.x or higher.
   • Permissions > Change default execution role > Execution role: Choose the appropriate role defined by your Lambda permissions and fill in the fields that appear if necessary. The role is determined by your organization’s AWS policy.
     • If your organization already has a role with the appropriate permissions, select Use an existing role.
     • If your organization does not have an appropriate role, create a new one with one of the available options.
5. Select Create function to finish making your function.
6. From your Lambda > Functions table, select the function you just created.
7. In the Code source section, select Upload from and choose .zip file.
8. Select the Lambda function ZIP file.
9. Select Save.
10. Select Actions > Publish new version.
11. Copy the Function ARN.
12. Navigate to CloudFront > Distributions.
13. Select a Distribution ID > Behaviors.
14. If you already have a behavior that uses the Default (*) path pattern, select it. Otherwise, select Create behavior.
15. Complete the following fields:
    • Path Pattern: Default (*)
    • Origin response:
      • Select Lambda@Edge for the function type.
      • Paste the Function ARN from Step 11 in the field that appears.
16. Select Save changes.

Make sure you also upload the HumanEnforcer Lambda. Once you do, you have successfully integrated the HUMAN AWS Lambda@Edge Enforcer with your CloudFront distribution. Make sure to reach out to our support team to complete your tuning process.

Upload the HumanFirstParty Lambda

Complete the following steps to upload the HumanFirstParty Lambda.

1. Navigate to Lambda > Functions.
2. Select Create function to make a new Lambda function.
3. Select the option to Author from scratch.
4. Complete the fields to create a new function. You can leave most of the fields with their default values, but be sure to update the following:
   • Function name: Enter the name for your function.
   • Runtime: Select at least Node.js 18.x or higher.
   • Permissions > Change default execution role > Execution role: Choose the appropriate role defined by your Lambda permissions and fill in the fields that appear if necessary. The role is determined by your organization’s AWS policy.
     • If your organization already has a role with the appropriate permissions, select Use an existing role.
     • If your organization does not have an appropriate role, create a new one with one of the available options.
5. Select Create function to finish making your function.
6. From your Lambda > Functions table, select the function you just created.
7. In the Code source section, select Upload from and choose .zip file.
8. Select the Lambda function ZIP file.
9. Select Save.
10. Select Actions > Publish new version.
11. Copy the Function ARN.
12. Navigate to CloudFront > Policies > Cache and select Create cache policy.
13. Create a cache policy with the following settings:
    • Minimum TTL: 0
    • Maximum TTL: 10
    • Default TTL: 5
    • Headers: Include the following headers
      • Host
      • User-agent
    • Query strings: All
    • Cookies: Including the following cookies
      • *_px*
      • px**
14. Select Create.

15. Navigate to CloudFront > Distributions.
16. Select a Distribution ID > Behaviors.
17. Select Create behavior.
18. Complete the following fields:
    • Path Pattern: /<APP_ID_without_PX>/*. For example, for an ID that is PX123456, the path pattern should be /123456/*.
    • Viewer protocol policy: HTTP and HTTPS
    • Allowed HTTP methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
    • Cache policy: Select the cache policy you created in Step 14.
    • Origin request policy: AllViewerExceptHostHeader. You should have created this origin request policy while completing the steps in Upload the HumanEnforcer Lambda (required).
    • Origin request:
      • Select Lambda@Edge for the function type.
      • Paste the Function ARN from Step 11 in the field that appears.
19. Select Save changes.

Make sure you also upload the HumanEnforcer Lambda. Once you do, you have successfully integrated the HUMAN AWS Lambda@Edge Enforcer with your CloudFront distribution. Make sure to reach out to our support team to complete your tuning process.

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.

1
{  
2
"Version": "2012-10-17",  
3
"Statement": \[  
4
    {  
5
        "Effect": "Allow",  
6
        "Action": "logs:CreateLogGroup",  
7
        "Resource": "arn:aws:logs:_:_:_"  
8
    },  
9
    {  
10
        "Effect": "Allow",  
11
        "Action": [  
12
            "logs:CreateLogStream",  
13
            "logs:PutLogEvents"  
14
        ],  
15
        "Resource": \[  
16
            "arn:aws:logs:_:_:log-group:_:\*"  
17
        ]  
18
    }  
19
  ]  
20
}

Deploy the Enforcer using AWS CloudFromation

AWS CloudFormation is a service that enables users to model and manage infrastructure resources in an automated and secure manner.
Using CloudFormation, developers can define and provision AWS infrastructure resources using a JSON- or YAML-formatted infrastructure as code template.

Who can’t use this feature?

• If your AWS resources are managed by other IaC platforms like Pulumi, Terraform, etc.
• If you already have a CloudFront distribution in your AWS account and you want to integrate the Enforcer with it.

If one of these applies to you, you can follow the instructions in Deploy the Enforcer.

Prerequisites:

• Complete the instructions in the install the enforcer section and make sure you have the lambda zip files.
• AWS CLI installed and configured.
• AWS S3 bucket to store the lambda zip files.

1. Store the lambda zip files in the S3 bucket using the following command:

   $
   aws s3 cp HumanEnforcer.zip s3://<bucket-name>/HumanEnforcer.zip
   $
   aws s3 cp HumanActivities.zip s3://<bucket-name>/HumanActivities.zip
   $
   aws s3 cp HumanFirstParty.zip s3://<bucket-name>/HumanFirstParty.zip
2. Navigate to the deploy directory.

   $
   cd deploy
3. Edit the cfm_deploy.yaml file and replace the placeholders with the relevant values:

• DomainName: "<ORIGIN_DOMAIN_URL>"
• Example: - DomainName: "example.com"

1
    CloudFrontDistribution:
2
    Type: "AWS::CloudFront::Distribution"
3
    Properties:
4
      DistributionConfig:
5
        Enabled: true
6
        Origins:
7
          - DomainName: "<ORIGIN_DOMAIN_URL>"
8
            Id: "ExampleOrigin"
9
            CustomOriginConfig:
10
              HTTPPort: 80
11
              HTTPSPort: 443
12
              OriginProtocolPolicy: "https-only"

• PathPattern: "<PX_APP_ID_SUFFIX>/*"
• Example: for PX_APP_ID: pxapp12345 the PX_APP_ID_SUFFIX is app12345 (Remove the PX prefix from the app_id)

1
        CacheBehaviors:
2
          - PathPattern: "<PX_APP_ID_SUFFIX>/*"
3
            AllowedMethods:
4
                - "GET"
5
                - "HEAD"
6
                - "OPTIONS"
7
                - "PUT"
8
                - "POST"
9
                - "PATCH"
10
                - "DELETE"

Example:

1
        CacheBehaviors:
2
          - PathPattern: "pxapp12345/*"
3
            AllowedMethods:
4
                - "GET"
5
                - "HEAD"
6
                - "OPTIONS"
7
                - "PUT"
8
                - "POST"
9
                - "PATCH"
10
                - "DELETE"

4. Deploy the CloudFormation stack using the following command (NOTE: replace the placeholders with the relevant values - <stack-name> and <bucket-name> ):

   $
   aws cloudformation deploy \                                    
   >
   --stack-name <stack-name> \
   >
   --template-file cfm_deploy.yaml \
   >
   --capabilities CAPABILITY_IAM \
   >
   --parameter-overrides \
   >
   HumanLambdaCodeBucket=<bucket-name> \
   >
   EnforcerLambdaCodePath=HumanEnforcer.zip \
   >
   FirstPartyLambdaCodePath=HumanFirstParty.zip
5. After the stack is created, you can find the CloudFront distribution URL in the CloudFormation stack outputs (or in the AWS UI).

Add HumanActivitiesLambda

HumanActivitiesLambda is an optional additional lambda that runs on the origin response and can be used to send additional activities that require response information to the HUMAN Security API. This Lambda is in charge of generating the HUMAN Security PXHD cookie and needs to be deployed in case you’re using advanced features such as Credential Intelligence or GraphQL protection.

To add the HumanActivitiesLambda to the CloudFormation stack, you must adjust your cfm_deploy.yaml file to include the HumanActivitiesLambda before deployment.

1. Create the Activities Lambda by adding the following resource to your deployment yaml (after EnforcerExecutionRole, at line 65):

1
  HumanActivitiesLambda:
2
    Type: "AWS::Lambda::Function"
3
    Properties:
4
      FunctionName: "human-security-activities-lambda"
5
      Handler: "index.handler"
6
      Role: !GetAtt EnforcerExecutionRole.Arn
7
      Runtime: "nodejs20.x"
8
      Code:
9
        S3Bucket: !Ref HumanLambdaCodeBucket
10
        S3Key: !Ref ActivitiesLambdaCodePath
11
12
  HumanActivitiesLambdaFunctionVersion:
13
    Type: "AWS::Lambda::Version"
14
    Properties:
15
      FunctionName: !Ref HumanActivitiesLambda

2. Add to LambdaFunctionAssociations an origin-response EventType, with the following association: LambdaFunctionARN: !Ref HumanActivitiesLambdaFunctionVersion. For example:

1
            LambdaFunctionAssociations:
2
              - EventType: "viewer-request"
3
                LambdaFunctionARN: !Ref HumanEnforcerLambdaFunctionVersion
4
              - EventType: "origin-response"
5
                LambdaFunctionARN: !Ref HumanActivitiesLambdaFunctionVersion

3. Add the ActivitiesLambdaCodePath variable at the end of the yaml file. For example:

1
    ActivitiesLambdaCodePath:
2
    Type: String
3
    Description: "S3 path for the Activities Lambda code zip file."

4. Run the deployment command using the 3 lambdas:

$
aws cloudformation deploy \                                    
>
--stack-name <stack-name> \
>
--template-file cfm_deploy.yaml \
>
--capabilities CAPABILITY_IAM \
>
--parameter-overrides \
>
HumanLambdaCodeBucket=<bucket-name> \
>
EnforcerLambdaCodePath=HumanEnforcer.zip \
>
ActivitiesLambdaCodePath=HumanActivities.zip \
>
FirstPartyLambdaCodePath=HumanFirstParty.zip