Configuration Options

Configuring Required Parameters

Configuration options are set in pxModuleConfigurationSection

Required parameters:

• appId
• cookieKey
• apiToken

Customizing Default Block Pages

Custom Logo

Adding a custom logo to the blocking page is by providing the pxConfig a key customLogo , the logo will be displayed at the top div of the the block page The logo's max-height property would be 150px and width would be set to auto

The key customLogo expects a valid URL address such as https://s.perimeterx.net/logo.png

Example below:

...
  customLogo="https://s.perimeterx.net/logo.png"
...

Custom JS/CSS

The block page can be modified with a custom CSS by adding to the pxConfig the key cssRef and providing a valid URL to the css In addition there is also the option to add a custom JS file by adding jsRef key to the pxConfig and providing the JS file that will be loaded with the block page, this key also expects a valid URL

On both cases if the URL is not a valid format an exception will be thrown

Example below:

...
  jsRef="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"
  cssRef="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
...

Redirect to a Custom Block Page URL

Customizes the block page to meet branding and message requirements by specifying the URL of the block page HTML file. The page can also implement CAPTCHA.

Default: "" (empty string)

Example:

customBlockUrl = "http://sub.domain.com/block.html"

Note: This URI is allowed automatically to avoid infinite redirects.

Redirect on Custom URL

The redirectOnCustomUrl boolean flag to redirect users to a block page.

Default: false

Example:

  redirectOnCustomUrl = "false"

By default, when a user exceeds the blocking threshold and blocking is enabled, the user is redirected to the block page defined by the customBlockUrl variable. The defined block page displays a 307 (Temporary Redirect) HTTP Response Code.

When the flag is set to false, a 403 (Unauthorized) HTTP Response Code is displayed on the blocked page URL.

Setting the flag to true (enabling redirects) results in the following URL upon blocking:

http://www.example.com/block.html?url=L3NvbWVwYWdlP2ZvbyUzRGJhcg==&uuid=e8e6efb0-8a59-11e6-815c-3bdad80c1d39&vid=08320300-6516-11e6-9308-b9c827550d47

Setting the flag to false does not require the block page to include any of the examples below, as they are injected into the blocking page via the HUMAN ASP.NET Enforcer.

NOTE: The url parameter should be built with the URL Encoded query parameters (of the original request) with both the original path and variables Base64 Encoded (to avoid collisions with block page query params).

Custom Block Pages Requirements

As of version 2.8.0, Captcha logic is being handled through the JavaScript snippet and not through the Enforcer.

Users who have Custom Block Pages must include the new script tag and a new div in the .html block page.

Changing the Minimum Score for Blocking

default: 100

...
  blockingScore="100"
...

Custom Verification Handler

A custom verification handler can be called by the HUMANModule instead of the default behavior, to allow a user to customize the behavior based on the risk score returned by HUMAN.

The custom handler class should implement the IVerificationHandler interface, and its name should be added to the configuration section:

...
  customVerificationHandler="UniqueVerificationHandler"
...

The custom logic will reside in the Handle method, making use of the following arguments:

• HttpApplication application - The currently running ASP.NET application methods, properties and events. Calling application.CompleteRequest, for example, will directly execute the EndRequest event to return a response to the client.
• PxContext pxContext - The HUMAN context, containing valuable fields such as Score, UUID, BlockAction etc.
• PxModuleConfigurationSection pxConfig - The current configuration used by the HUMANModule, representing the PerimeterX.PxModuleConfigurationSection settings. Contains fields such as BlockingScore.

Common customization options are presenting of a captcha or a custom branded block page.

...

namespace myUniqueApp
{
    public class UniqueVerificationHandler : IVerificationHandler
    {
        public void Handle(HttpApplication application, PxContext pxContext, PxModuleConfigurationSection pxConfig)
        {
            // Custom verification logic goes here.
            // The following code is only an example of a possible implementation:

            if (pxContext.Score >= pxConfig.BlockingScore) // In the case of a high score, present the standard block/captcha page
            {
                PxModule.BlockRequest(pxContext, pxConfig);
                application.CompleteRequest();
            }
        }
    }
}

Enable/disable captcha in the block page

DEPRECATED

By enabling captcha support, a captcha will be served as part of the block page giving real users the ability to answer, get score clean up and passed to the requested page.

default: true

...
  captchaEnabled="true"
...

First Party Mode

Enables the module to receive/send data from/to the sensor, acting as a "reverse-proxy" for client requests and sensor activities.

Customers are advised to use the first party sensor (where the web sensor is served locally, from your domain) for two main reasons:

• Improved performance - serving the sensor as part of the standard site content removes the need to open a new connection to HUMAN servers when a page is loaded.
• Improved detection - third party content may sometimes be blocked by certain browser plugins and privacy addons.
• First party sensor directly leads to improved detection, as observed on customers who previously moved away from third party sensor.

The following routes will be used in order to serve the sensor and send activities:

• /<PREFIX>/xhr/*
• /<PREFIX>/init.js

First Party may also require additional changes on the sensor snippet (client side). Refer to the portal for more information.

default: true

...
  firstPartyEnabled="true"
  firstPartyXhrEnabled="true"
...

Extracting the Real User IP Address

Note: IP extraction according to your network setup is important. It is common to have a load balancer/proxy on top of your applications, in this case the HUMAN module will send an internal IP as the user's. In order to perform processing and detection for server-to-server calls, HUMAN module need the real user ip.

The user ip can be returned to the HUMAN module using a name of a header including the IP address.

default: IP is taken from UserHostAddress of the incoming request

...
  socketIpHeader="X-PX-TRUE-IP"
...

Filter sensitive headers

A user can define a list of sensitive header he want to prevent from being send to HUMAN servers (lowered case header name), filtering cookie header for privacy is set by default and will be overridden if a user set the configuration

default: cookie, cookies

...
  sensitiveHeaders="cookie,cookies"
...

Sensitive Routes

List of routes prefix. The HUMAN module will always match request uri by this prefix list and if match was found will create a server-to-server call for, even if the cookie score is low and valid.

default: None

...
  sensitiveRoutes="/login,/user/profile"
...

Allowlist Routes

List of routes prefix. The HUMAN module will skip detection if the prefix match request uri .

default: None

...
  routesWhitelist="/login,/user/profile"
...

Enforcer Specific Routes

List of routes prefix. If the list is not empty, The HUMAN module will enforcer only on the url that match the prefix, any other route will be skipped

default: None

...
  enforceSpecificRoutes="/protect/route,/login,/checkout"
...

API Timeouts

Control the timeouts for HUMAN requests. The API is called when the risk cookie does not exist, or is expired or invalid.

API Timeout in milliseconds to wait for the HUMAN server API response.

default: 2000

...
  apiTimeout="2000"
...

Send Page Activities

Boolean flag to enable or disable page activities
Sending page activities is asynchronous and not blocking the request

default: True

...
  sendPageActivities="false"
...

Monitor Mode

Boolean flag to enable or disable monitor mode
While monitor mode is on, all requests will be inspected but not blocked
Set this flag to false to disable monitor mode

...
  monitorMode="true"
...

default: true

Base URI

A user can define a different API endpoint as a target URI to send the requests and will override the default address. Use this parameter after discussing the change with HUMAN support team.

default: https://sapi.perimeterx.net

...
  baseUri="https://sapi.perimeterx.net"
...

Custom User Agent Header

The user's user agent can be returned to the HUMAN module using a name of a header that includes the user agent

default: The User Agent is taken from header name "user-agent" from the incoming request

...
  useragentOverride="px-user-agent"
...

Data Enrichment

Users can use the additional activity handler to retrieve information for the request using the data-enrichment object. First, check that the data enrichment object is verified, then you can access it's properties.

Mitigation Urls

Users can define custom paths that allow blocking. All other paths will be set to monitoring mode.

mitigiation-urls="path1, path2"
...

namespace MyApp
{
    public class MyVerificationHandler : IVerificationHandler
    {
        public void Handle(HttpApplication application, PxContext pxContext, PxModuleConfigurationSection pxConfig)
        {
          ...
          if (pxContext.IsPxdeVerified) {
            dynamic pxde = pxContext.Pxde;
            // do something with the data enrichment
          }
          ...
        }
    }
}

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 (eg. 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 you will stay in Monitor Mode. This is done per request.
To stay in Monitor Mode, set the header value to 0.

The Header name is configurable using the bypassMonitorHeader property.

Default: not set

...
  bypassMonitorHeader="x-px-block"
...