Configuration Options

Configuration up to v2.14.0

const configKeyMapping = {
   'enableModule'
   'pxAppId'
   'cookieSecretKey'
   'authToken'
   'proxy'
   'apiTimeoutMS'
   'activitiesTimeout'
   'customRequestHandler'
   'getUserIp'
   'blockingScore'
   'ipHeaders'
   'sendPageActivities'
   'sensitiveHeaders'
   'debugMode'
   'maxBufferLength'
   'jsRef'
   'cssRef'
   'customLogo'
   'sensitiveRoutes'
   'whitelistRoutes'
   'enforcedRoutes'
   'monitoredRoutes'
   'dynamicConfigurations'
   'moduleMode'
   'firstPartyEnabled'
   'additionalActivityHandler'
   'enrichCustomParameters'
   'testingMode'
   'whitelistExt'
   'bypassMonitorHeader'
   'advancedBlockingResponse'
   'telemetryCommandHeader'
   'customTemplateRoot'
   'customTemplateData'
   'filterByIP'
   'filterByUserAgent'
   'filterByMethod'
   'externalActivities'
   'pxhdSecure'
   'backendUrl'
   'customCookieHeader'
   'enableLoginCredsExtraction'
   'loginCredsExtraction'
 }

Configuration From v3.0.0

First Party

A boolean flag to enable/disable first party mode.

🚧

Notice!

To enable first party mode, you will first need to follow these installation steps.

Default: true

const pxConfig = {
  ...
  px_first_party_enabled: false
  ...
};

Module Enabled

A boolean flag to enable/disable the PerimeterX Enforcer.

Default: true

const pxConfig = {
  ...
  px_module_enabled: false
  ...
};

Module Mode

Sets the working mode of the Enforcer.

Possible values:

  • "monitor" - Monitor Mode
  • "active_blocking" - Blocking Mode

Default: "monitor"

const pxConfig = {
  ...
  px_module_mode: "active_blocking"
  ...
};

Blocking Score

Sets the minimum blocking score of a request.

Possible values:

  • Any integer between 0 and 100.

Default: 100

const pxConfig = {
  ...
  px_blocking_score: 100
  ...
};

Logger Severity

👍

AWS CloudWatch

Like all [email protected] functions, PerimeterX's AWS Lambda enforcer outputs logs to AWS CloudWatch. See here for more information about how to retrieve logs from CloudWatch.

Sets the logging verbosity level. The available options are:

  • none - no logs will be generated
  • error - logs only when severe errors occur, best for production environments
  • debug - logs more descriptive messages, helpful for analyzing and debugging the enforcer flow

Default: error

const pxConfig = {
  ...
  px_logger_severity: 'debug'
  ...
};

Sensitive Routes

An array of route prefixes and/or regular expressions that trigger a server call to PerimeterX servers every time the page is viewed, regardless of viewing history.

Default: Empty

const pxConfig = {
  ...
  px_sensitive_routes: ['/login', /\/user\/.*\/checkout/]
  ...
};

Enforced Specific Routes

An array of route prefixes and/or regular expressions that are always validated by the PerimeterX Worker (as opposed to whitelisted routes).

A regular expression can be defined using new RegExp or directly as an expression, and will be treated as is.

A string value of a path will be treated as a prefix.

Default: Empty

const pxConfig = {
  ...
  px_enforced_routes: ['/home',/^\/$/]
  ...
};

Monitored Specific Routes

An array of route prefixes and/or regular expressions that are always set to be in monitor mode. This only takes effect when the module is enabled and in blocking mode.

A regular expression can be defined using new RegExp or directly as an expression, and will be treated as is.

A string value of a path will be treated as a prefix.

Default: Empty

const pxConfig = {
  ...
  px_monitored_routes: ['/home', new RegExp(/^\/$/)]
  ...
};

Filter Traffic By Route

An array of route prefixes and/or regular expressions that are always whitelisted and not validated by the PerimeterX Worker.

A regular expression can be defined using new RegExp or directly as an expression, and will be treated as is.

A string value of a path will be treated as a prefix.

Default: Empty

const pxConfig = {
  ...
  px_filter_by_route: ['/contact-us', /\/user\/.*\/show/]
  ...
};

Filter Traffic by User Agent

An array of user agents constants and/or regular expressions that are always filtered and not validated by the PerimeterX middleware.

Default: Empty

const pxConfig = {
  ...
  px_filter_by_user_agent: ['testUserAgent/v1.0', /test/]
  ...
};

Filter Traffic by IP

An array of IP ranges / IP addresses that are always filtered and not validated by the PerimeterX Lambda Function.

Default: Empty

const pxConfig = {
  ...
  px_filter_by_ip: ['192.168.10.0/24', '192.168.2.2']
  ...
};

Filter Traffic by HTTP Method

An array of HTTP methods that are always filtered and not validated by the PerimeterX Lambda Function.

Default: Empty

const pxConfig = {
  ...
  px_filter_by_http_method: ['options']
  ...
};

Sensitive Headers

An array of headers that are not sent to PerimeterX servers on API calls.

Default: ['cookie', 'cookies']

const pxConfig = {
  ...
  px_sensitive_headers: ['cookie', 'cookies', 'x-sensitive-header']
  ...
};

IP Headers

An array of trusted headers that specify an IP to be extracted.

By default, the value from event.Records[0].cf.request.clientIp is used as the IP.

Default: Empty

const pxConfig = {
  ...
  px_ip_headers: ['x-user-real-ip']
  ...
};

👍

What if extracting the IP is a bit more complicated?

If configured headers are insufficient to extract the IP from the request, you may set this value to null and define a custom extraction function with the Extract User IP feature.

This section should be removed as it is outdated. Confirmed with Engineering and SA teams.

Custom Request Handler

A JavaScript function that adds a custom response handler to the request. This function must be set in the custom/custom.js file.

Default: null

const customInitCallback = () => {
  // ...
  PerimeterX.SetCustomRequestHandler((pxCtx, pxconfig, req) => {
    ...
    return {body: result, status: 200, statusDescription: "OK", header: {key: 'Content-Type', value:'application/json'}};
  });
  // ...
};

Additional Activity Handler

JavaScript function that allows interaction with the request data collected by PerimeterX before the data is returned to the PerimeterX servers. Does not alter the response. This function must be set in the custom/custom.js file.

The context passed into this function contains both the data enrichment object (accessible through the pxde property) as well as a boolean indicating whether the HMAC has been verified (accessible through the pxdeVerified property). See the example below.

Default: null

const customInitCallback = () => {
  // ...
  PerimeterX.SetAdditionalActivityHandler((pxCtx, config) => {
    const dataEnrichmentObject = pxCtx.pxde;
    const isDataEnrichmentVerified = pxCtx.pxdeVerified;
    // ...
  });
  // ...
};

Enrich Custom Parameters

With the enrich custom parameters function, you can add up to 10 custom parameters to be sent back to PerimeterX servers. When set, the function is called before setting the payload on every request to PerimeterX servers. The parameters should be passed according to the correct order (1-10). This function must be set in the custom/custom.js file.

Default: null

const customInitCallback = () => {
  // ...
  PerimeterX.SetEnrichCustomParamsFunction((customParams, originalRequest) => {
    customParams["custom_param1"] = "yay, test value";
    // ...
    return customParams;
  });
  // ...
};

Extract User IP

In case the px_ip_headers configuration isn't enough to extract the user IP from the incoming request, you can set a custom function to do this. If this function is set, this function is called in order to retrieve the IP from the request. This function must be set in the custom/custom.js file.

Note: The px_ip_headers configuration must be set to null for this function to be called.

Default: null

const customInitCallback = () => {
  // ...
  PerimeterX.SetExtractUserIpFunction((req) => {
    let ip; // string
    // ...
    return ip;
  });
  // ...
};

CSS Ref

Modifies a custom CSS by adding the CSSRef directive and providing a valid URL to the CSS.

Default: Empty

const pxConfig = {
  ...
  px_css_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css'
  ...
};

JS Ref

Adds a custom JS file by adding JSRef directive and providing the JS file that is loaded with the block page.

Default: Empty

const pxConfig = {
  ...
  px_js_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js'
  ...
};

Custom Logo

The logo is displayed at the top of the the block page.
Max-height = 150px, Width = auto.

Default: Empty

const pxConfig = {
  ...
  px_custom_logo: 'https://s.perimeterx.net/logo.png',
  ...
};

Custom Cookie Header

When set, instead of extracting the PerimeterX Cookie from the Cookie header, this property specifies a header name that will contain the PerimeterX Cookie.

Default: Empty

const pxConfig = {
  ...
  px_custom_cookie_header: "x-px-cookies"
  ...
};

Test Block Flow on Monitoring Mode

Allows you to test an enforcer’s blocking flow while you are still in Monitor Mode.

When the header name is set (e.g., x-px-block) and the value is set to 1, when there is a block response (for example from using a User-Agent header with the value of PhantomJS/1.0) the Monitor Mode is bypassed and full block mode is applied. If one of the conditions is missing the block will not apply. This is done per request.
To stay in Monitor Mode, set the header value to 0.

The header name is configurable using the px_bypass_monitor_header property.

Default: Empty

const pxConfig = {
  ...
  px_bypass_monitor_header: "x-px-block"
  ...
};

Login Credentials Extraction

🚧

Notice!

To enable this feature, your Cloudfront distribution must give the Lambda functions access to the request body. You can do this by editing the relevant Lambda Function Associations in the default behavior of your Cloudfront distribution.

You may also need to modify your Origin Request Policy for the Cloudfront distribution to allow the configured value for px_compromised_credentials_header on the origin request. If not, Cloudfront may remove this header before forwarding the request to the origin server.

This feature extracts credentials (hashed username and password) from requests and sends them to PerimeterX as additional info in the risk api call. The feature can be toggled on and off, and may be set for any number of unique paths. The settings are adjusted by modifying the pxConfig object in the index.js file.

If credentials are found to be compromised, the header px-compromised-credentials will be added to the origin request with the value 1. You may configure the name of this header with the px_compromised_credentials_header configuration.

Default Values

px_login_credentials_extraction_enabled: false

px_login_credentials_extraction: Empty

px_compromised_credentials_header: "px-compromised-credentials"

const pxConfig = {
  ...
  px_compromised_credentials_header: "px-comp-cred",
  px_login_credentials_extraction_enabled: true,
  px_login_credentials_extraction: [
    {
      path: "/login", // login path, automatically added to px_sensitive_routes
      method: "post", // supported methods: post
      sent_through: "body", // supported sent_throughs: body, header, query-param
      pass_field: "password", // name of the password field in the request
      user_field: "username" // name of the username field in the request
    },
    ...
  ],
  ...
};

It is also possible to define a custom callback to extract the username and password. The function should accept the request object as a parameter and return an object with the keys user and pass. If extraction is unsuccessful, the function should return null.

const pxConfig = {
    ...
    px_login_credentials_extraction_enabled: true,
    px_login_credentials_extraction: [{
        path: "/login", // login path
        method: "post", // supported values: post
        callback: (req) => {
            // custom implementation resulting in variables username and password
            if (username && password) {
                return { "user": username, "pass": password };
            } else {
                return null;
            }
        }
    }]
};

Additional S2S Activity

To enhance detection on login credentials extraction endpoints, the following additional information is sent to PerimeterX via an additional_s2s activity:

  • Response Code - The numerical HTTP status code of the response. This is sent automatically.
  • Login Success - A boolean indicating whether the login completed successfully. See the options listed below for how to provide this data.
  • Raw Username - The original username used for the login attempt. In order to report this information, make sure the configuration px_send_raw_username_on_additional_s2s_activity is set to true.

This additional_s2s activity can be sent either automatically via the PXActivities Lambda or manually from the origin server using the Additional Activity Header feature.

Manual Additional S2S Activity Via Header

Rather than using the PXActivities Lambda to send the additional_s2s activity, it is instead possible to generate the base additional_s2s activity along with the URL endpoint, and pass them to the origin server as headers on the original HTTP request. When enabled, the module will add two new headers to the original request and send them to the origin:

  • px-additional-activity, a stringified JSON activity that should be sent.
  • px-additional-activity-url, the complete URL endpoint to which the JSON object should be sent.

Note: If the PXEnforcer Lambda is associated with the viewer-request event, the two header names px-additional-activity and px-additional-activity-url must be added in the CloudFront Origin Request Policy.

Default Values

px_automatic_additional_s2s_activity_enabled: true

px_additional_s2s_activity_header_enabled: false

const pxConfig = {
  // ...
  px_automatic_additional_s2s_activity_enabled: false,
  px_additional_s2s_activity_header_enabled: true,
  //...
};

The px-additional-activity header value is a stringified JSON object that looks like this. Only the fields indicated with // MODIFY should be changed prior to sending. Other fields should not be altered in any way.

{
  "type": "additional_s2s",
  "timestamp": 1637000000,
  "socket_ip": "1.1.1.1",
  "px_app_id": "PX_APP_ID",
  "url": "https://www.example.com/the-target-url",
  "vid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "details": {
    "client_uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "request_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "ci_version": "v1",
    "http_status_code": null, // MODIFY, number (e.g., 200, 401, 404, etc.)
    "login_successful": null, // MODIFY, boolean (e.g., true, false)
    "raw_username": null // MODIFY, string (e.g., "[email protected]")
  }
}

After parsing the object and adding the appropriate http_status_code and login_successful fields in the origin server, send the JSON object as an HTTP POST request to the URL provided in the px-additional-activity-url header.

Note: The POST request should be sent with the Content-Type: application/json and Authorization: Bearer <PX_AUTH_TOKEN> headers.

Example Origin Server Behavior

app.post('/login', (req, res) => {
    // complete login flow, resulting in boolean variable isLoginSuccessful
    const responseStatusCode = isLoginSuccessful ? 200 : 401;
    res.sendStatus(responseStatusCode);
    if (req.headers['px-additional-activity'] && req.headers['px-additional-activity-url']) {
        handlePxAdditionalActivity(req, responseStatusCode, isLoginSuccessful);
    }
});

function handlePxAdditionalActivity(req, statusCode, isLoginSuccessful) {
    try {
        // extract url and activity from the request headers
        const url = req.headers['px-additional-activity-url'];
        const activity = JSON.parse(req.headers['px-additional-activity']);

        // change the modifiable values
        activity.details['http_status_code'] = statusCode;
        activity.details['login_successful'] = isLoginSuccessful;
        if (activity.details['credentials_compromised'] && isLoginSuccessful) {
            // add raw username if credentials are compromised and login is successful
            activity.details['raw_username'] = req.body.username;
        } else {
            // remove raw username if login is not successful or credentials are not compromised
            delete activity.details['raw_username'];
        }

        // send the POST request
        axios.post(url, activity, {
            headers: {
                'Authorization': `Bearer ${env.PX_AUTH_TOKEN}`,
                'Content-Type': 'application/json'
            }
        });
    } catch (err) {
        console.error(`Error: ${err}`);
    }
}

Automatic Additional S2S Activities via PXActivities Lambda

🚧

Notice!

To enable additional_s2s activities as part of credentials intelligence, you will first need to follow these
installation steps.

To enable automatic sending of the additional_s2s activity on the PXActivities Lambda, ensure the following configurations are enabled on both the PXEnforcer and PXActivities Lambdas and the login successful reporting method is configured. If left empty, the login successful status will always be reported as false.

Note: The px_additional_s2s_activity_header_enabled configuration must be enabled even using the PXActivities Lambda to automatically send the additional_s2s activity.

Default Values

px_automatic_additional_s2s_activity_enabled: true

px_additional_s2s_activity_header_enabled: false

px_login_successful_reporting_method: Empty

const pxConfig = {
    ...
    px_automatic_additional_s2s_activity_enabled: true,
    px_additional_s2s_activity_header_enabled: true,
    px_login_successful_reporting_method: 'status' // supported values: status, header, custom
    ...
}

Status

Provide a status or array of statuses that represent a successful login. If a response's status code matches the provided value or one of the values in the provided array, the login successful status is set to true. Otherwise, it's set to false.

Note: To define a range of statuses, use the custom reporting method.

Default Values

px_login_successful_status: 200

const pxConfig = {
    ...
    px_login_successful_reporting_method: 'status',
    px_login_successful_status: [200, 202] // number or array of numbers
    ...
}

Header

Provide a header name and value. If the header exists on the response and matches the provided value, the login successful status is set to true. If the header is not found on the response, or if the header value does not match the value in the configuration, the login successful status is set to false.

Default Values

px_login_successful_header_name: x-px-login-successful

px_login_successful_header_value: 1

const pxConfig = {
    ...
    px_login_successful_reporting_method: 'header',
    px_login_successful_header_name: 'login-successful',
    px_login_successful_header_value: 'true'
    ...
}

Custom

Provide a custom callback that returns a boolean indicating if the login was successful. This callback should be set
in the custom.js file with the function PerimeterX.SetLoginSuccessfulCustomCallbackFunction().

// config.js

const pxConfig = {
    ...
    px_login_successful_reporting_method: 'custom',
    ...
}
// custom.js

const customInitCallback = () => {
    // other functions called on PX initialization
    PerimeterX.SetLoginSuccessfulCustomCallbackFunction((res) => {
        return res.statusCode < 400;
    });
};

Send Raw Username on Additional S2S Activity

When enabled, the raw username used for logins on login credentials extraction endpoints will be reported to PerimeterX if (1) the credentials were identified as compromised, and (2) the login was successful as reported via the property above.

Default: false

const pxConfig = {
    ...
    px_send_raw_username_on_additional_activity: true
    ...
}

Sensitive GraphQL Operations

🚧

Notice!

To enable this feature, your Cloudfront distribution must give the Lambda functions access to the request body. You can do this by editing the relevant Lambda Function Associations in the default behavior of your Cloudfront distribution.

For those using GraphQL endpoints, it is possible to trigger server-to-server risk calls on particular operation types or names. Like the sensitive routes feature, a request that contains an operation of the configured type or name will trigger a server call to PerimeterX servers every time that operation is performed.

If an operation type (e.g., query, mutation) is configured in px_sensitive_graphql_operation_types, all GraphQL operations of that type will be treated as sensitive. If an operation name is configured in px_sensitive_graphql_operation_names, all GraphQL operations with that name will be treated as sensitive.

Note: This feature only applies to requests that contain the string graphql somewhere in the path name.

Default Values:

px_sensitive_graphql_operation_types: Empty

px_sensitive_graphql_operation_names: Empty

const pxConfig = {
  ...
  px_sensitive_graphql_operation_types: ["mutation"],
  px_sensitive_graphql_operation_names: ["LoginOperation", "AccountInfoQuery"]
  ...
};

Did this page help you?