Installing the Enforcer

Prerequisites

Installing & configuring PerimeterX AWS lambda edge enforcer requires basic knowledge in the following AWS services - CloudFront, Lambda, CloudWatch, IAM. Basic knowledge is also required in NodeJS for configuring the enforcer, adding custom functions, etc.

An AWS Account with necessary permissions for CloudFront, Lambda, CloudWatch, and IAM services is a prerequisite to install PerimeterX AWS lambda edge enforcer. This should include the necessary permissions to create and edit IAM roles. The application does not require the use of root privileges for deployment or operation.

Completing the enforcer deployment is estimated to take between 30-60 mins and will result with creating 1-3 new lambda functions, with a max size of 250kb (each), which are billable services according to your agreement with Amazon. There is no need to change current set service limits in relation to PerimeterX added Lambda functions. More information can be found here & here. The PXEnforcer Lambda function is the only mandatory function in order to enable PerimeterX Bot Defender solution on AWS.

IAM Specifications

The minimum required IAM specifications for using the PerimeterX AWS [email protected] Enforcer are the same as they would be for any [email protected] function as mentioned here. Required services include Lambda, CloudFront, IAM (to create the necessary [email protected] role and permissions), and CloudWatch (for [email protected] logging).

In order to use the PerimeterX CDN Deploy Tool to upload the PXEnforcer Lambda function and associate it with the distribution, an API Access Key is necessary. This may require permissions to create, update, and list access keys in IAM as well. The access key used for the enforcer installation must be associated with a user that has read and write access to Lambda Functions, CloudFront, and CloudWatch.

Secrets Manager

PerimeterX provides you with an application ID (px_app_id) along with two sensitive tokens: an authentication token (px_auth_token) used for validating requests sent to PerimeterX servers and a cookie secret (px_cookie_secret) used for encrypting and decrypting the PerimeterX cookie. Both of these secrets must be accessed in the PerimeterX enforcer as part of the AWS [email protected] Function.

While it is possible to hard-code these strings in the PerimeterX AWS Lambda Enforcer, it is best practice to store sensitive tokens in the AWS Secrets Manager. For more information on how to use the AWS Secrets Manager with [email protected] click here.

Enforcer Installation

Creating the Lambda Function on AWS

1. In the AWS console, click Services > Compute > Lambda.
2. Click Create function.
3. Set the Name field to PXEnforcer, set Runtime to Node.js 16.x, and select an existing role or create a new role.
4. Click Create function.

Uploading the PerimeterX Lambda Function and Required Configuration

1. Under Code entry type select Upload a .ZIP file.
2. Click Upload, navigate to the PXEnforcer.zip file provided to you by PerimeterX, and click Save.
3. If you haven't already, add the following mandatory parameters to the pxConfig object in the custom/config.js file:

const pxConfig = {
    px_app_id: '<your app ID>',
    px_cookie_secret: '<your cookie key>',
    px_auth_token: '<your auth token>',
    px_first_party_enabled: false,
}

Where:

4. Click Save.
5. Click Actions and select Publish New Version. Fill in a description for the version and click Publish.

📘

Where Can I Find the App ID, the Cookie Secret, and the Auth Token?

The PerimeterX Application ID / AppId and PerimeterX Token / Auth Token can be found in the Portal, under Platform Settings -> Applications.

PerimeterX Risk Cookie / Cookie Key can be found in the Portal, under Platform Settings -> Policies.

The Policy from where the Risk Cookie / Cookie Key is taken must correspond with the Application from where the Application ID / AppId and PerimeterX Token / Auth Token are taken.

Adding the PerimeterX Lambda Function Trigger

1. Select CloudFront from the menu on the left side of the screen.
2. Set CloudFront event to Viewer request.
3. Ensure the box under Enable trigger and replicate is checked.
4. Click Add and then Save.

First Party Installation

First party mode enables the module to send/receive data to/from the sensor, acting as a reverse-proxy for client requests and sensor activities. To setup First party mode for the PerimeterX AWS [email protected] Function, follow the steps below.

📘

Please Note

Installing First Party is highly recommended but not mandatory to get the enforcer deployed successfully. The following steps are required only for first party mode configurations where the PXEnforcer Lambda function is triggered on the viewer-request event. If the PXEnforcer Lambda is triggered on the origin-request event or if your setup is in third party mode, the following steps are not required.

Configuring the PerimeterX First Party Cache Policy

1. In the AWS console, navigate to the Cloudfront service.
2. Create a new cache policy called PXFirstPartyCachePolicy with the following field values:

Creating the First-Party Lambda Function on AWS

1. In the AWS console Click Services > Compute > Lambda.
2. Click Create function.
3. set the Name field to PXFirstParty, set Runtime to Node.js 16.x, and select an existing role or create a new role.
4. Click Create function.

Uploading and Configuring the First-Party Lambda Function

1. Under Code entry type select Upload a .ZIP file.
2. Click Upload, navigate to the PXFirstParty.zip file provided to you by PerimeterX, and click Save.
3. If you haven't already, add the px_app_id field to the pxConfig object in the custom/config.js file. (Only the px_app_id is used for this function, so it is not necessary to add your other configurations.)
4. Click Save.
5. Click Actions and select Publish new version. Fill in a description for the version and click Publish.

Creating the First Party Cloudfront Behavior

1. Select CloudFront from the menu on the left side of the screen.
2. Click into the Cloudfront distribution.
3. Create a new Cloudfront Behavior with the following field values:

4. Create the behavior.

PXActivities Installation

As part of Credentials Intelligence, the PerimeterX AWS Lambda module can send the additional_s2s activity to PerimeterX on the origin-response event, allowing PerimeterX to analyze data related to the origin response and not just the request. This includes information about the returned HTTP status code and whether an attempted login was successful.

📘

Please Note

The following steps are required only for configurations where credentials intelligence is enabled and the additional_s2s activity should be sent automatically to PerimeterX. If credentials intelligence is not enabled or if the additional_s2s activity will be sent manually, the following steps are not required.

Creating the PXActivities Lambda Function on AWS

1. In the AWS console Click Services > Compute > Lambda.
2. Click Create function.
3. Set the Name field to PXActivities, set Runtime to Node.js 16.x, and select an existing role or create a new role.
4. Click Create function.

Uploading and Configuring the PXActivities Lambda Function

1. Under Code entry type select Upload a .ZIP file.
2. Click Upload, navigate to the PXActivities.zip file provided to you by PerimeterX, and click Save.
3. If you haven't already, add the px_app_id field to the pxConfig object in the custom/config.js file. (Only the px_app_id is used for this function, so it is not necessary to add your other configurations.)
4. Click Save.
5. Click Actions and select Publish new version. Fill in a description for the version and click Publish.

Adding the PXActivities Lambda Function Trigger

1. Select CloudFront from the menu on the left side of the screen.
2. Set CloudFront event to Origin Response.
3. Check the Confirm deploy to [email protected] checkbox.
4. Click Add and then Save.