Advanced Configuration

Customizing Default Block Pages

Custom Logo
It is possible to add a custom logo to the blocking page by adding the key custom_logo with a valid URL as the value to the $perimeterxConfig array. 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.

$perimeterxConfig = [
  ...
  'custom_logo' => 'https://s.perimeterx.net/logo.png',
  ...
];

 Custom JS/CSS 

The block page can be modified with custom CSS by adding to the $perimeterxConfig the key css_ref and providing a valid URL to the CSS file. There is also the option to add a custom JS file by adding js_ref key to the $perimeterxConfig and providing the JS file that will be loaded with the block page. Both these configurations expect valid URLs. If the URLs provided are not valid, an exception will be thrown.

$perimeterxConfig = [
  ...
  'css_ref' => 'https://s.perimeterx.net/custom_block.css',
  'js_ref' => 'https://s.perimeterx.net/custom_block.js',
  ...
];

No Blocking, Monitor Only

/**
 * @param \Perimeterx\PerimeterxContext $pxCtx
 */
$perimeterxConfig['custom_block_handler'] = function ($pxCtx) {
    $block_score = $pxCtx->getScore();
    $block_uuid = $pxCtx->getUuid();
    $full_url = $pxCtx->getFullUrl();

    // user defined logic goes here
};

$px = Perimeterx::Instance($perimeterxConfig);
$px->pxVerify();

Extracting Recommended Action

/**
 * @param \Perimeterx\PerimeterxContext $pxCtx
 */
$perimeterxConfig['custom_block_handler'] = function ($pxCtx) {
    $block_score = $pxCtx->getScore();
    $block_uuid = $pxCtx->getUuid();
    $action = $pxCtx->getBlockAction();

    /* user defined logic comes here */
    error_log('px score for user is ' . $block_score);
    error_log('px recommended action for user is ' . $action);
    error_log('px page uuid is ' . $block_uuid);

    switch ($action) {
        case "block":
            log("do block");
            break;
        case "captcha":
            log("do captcha");
            break;
        default:
            log("unknown action");
    }
};

Module Mode

Default mode: Perimeterx::$MONITOR_MODE

Possible Values:

• Perimeterx::$ACTIVE_MODE - Module blocks users crossing the predefined block threshold. Server-to-server requests are sent synchronously.
• Perimeterx::$MONITOR_MODE - Module does not block users crossing the predefined block threshold. The pxCustomBlockHandler function will be eval'd in case one is supplied, upon crossing the defined block threshold.

$perimeterxConfig = [
  ...
  'module_mode' => Perimeterx::$ACTIVE_MODE
  ...
];

Extracting the Real User IP Address

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

The user's IP can be passed to the HUMAN module using a custom user-defined function on the $HUMANConfig array, or by passing a list of headers to extract the real IP from, ordered by priority.

Default with no predefined header: $_SERVER['REMOTE_ADDR']

// IP extraction using request headers
$perimeterxConfig = [
  ...
  'ip_headers' => ['X-TRUE-IP', 'X-Forwarded-For']
  ...
];

/**
 * IP extraction using a custom user-defined function
 * @param \Perimeterx\PerimeterxContext $pxCtx
 */
$perimeterxConfig['custom_user_ip'] = function ($pxCtx) {
    $headers = getallheaders();

    /* using a socket ip */
    $ip = $_SERVER['REMOTE_ADDR'];

    /* using an ip from a x-forwarded-for header */
    $xff = explode(",", $headers['X-Forwarded-For']);
    $ip = $xff[count($xff)-1];

    /* using an ip from a custom header */
    $ip = $headers['X-REAL-CLIENT-IP'];

    return $ip;
};

$px = Perimeterx::Instance($perimeterxConfig);
$px->pxVerify();

Custom URI

The URI can be returned to the HUMAN module using a custom user function defined on the $HUMANConfig variable.

Default: $_SERVER['REQUEST_URI']

/**
 * @param \Perimeterx\PerimeterxContext $pxCtx
 */
$perimeterxConfig['custom_uri'] = function ($pxCtx) {
    return $_SERVER['HTTP_X_CUSTOM_URI'];
};

$px = Perimeterx::Instance($perimeterxConfig);
$px->pxVerify();

Filter Sensitive Headers

A list of sensitive headers can be configured to prevent specific headers from being sent to HUMAN servers (lower case header names). Filtering cookie headers for privacy is set by default, and can be overridden on the $HUMANConfig variable.

Default: cookie, cookies

$perimeterxConfig = [
  ...
  'sensitive_headers' => ['cookie', 'cookies', 'secret-header']
  ...
];

Sensitive Routes

List of route prefixes. The HUMAN module will always match request URIs by this prefix lis. If match is found, the module will make a server-to-server call for the request, even if the cookie score is low and valid.

Default: None

$perimeterxConfig = [
  ...
  'sensitive_routes' => ['/login', '/user/profile']
  ...
];

API Timeouts

The timeout, in seconds (float), to wait for the HUMAN server API response. This controls the timeouts for HUMAN requests. The server-to-server API call is made when a risk cookie does not exist, or is expired or invalid. If the timeout is reached before the module receives a response, the client request will be passed.

Default: 1

$perimeterxConfig = [
  ...
  'api_timeout' => 2
  ...
];

API Connection Timeout

The API connection timeout, in seconds (float), is the amount of time to wait for the connection to the HUMAN server API.

Default: 1

$perimeterxConfig = [
  ...
  'api_connect_timeout' => 2
  ...
];

Activities Timeout

The activities timeout is the amount of time in seconds (float) to wait for the HUMAN server response.

Default: 1

$perimeterxConfig = [
  ...
  'activities_timeout' => 2
  ...
];

Activities Connection Timeout

The activities connection timeout is the amount of time in seconds (float) to wait for the connection to the HUMAN server when sending non-risk_api activities.

Default: 1

$perimeterxConfig = [
  ...
  'activities_connect_timeout' => 2
  ...
];

First Party

A boolean flag to enable/disable first party mode.

Default: true

$perimeterxConfig = [
    ..
    'px_first_party_enabled' => false
    ..
]

First Party for Code Defender

A boolean flag to enable/disable first party mode for Code Defender.

Default: false

$perimeterxConfig = [
    ..
    'px_cd_first_party_enabled' => true
    ..
]

Send Page Activities

A boolean flag to enable or disable sending of activities and metrics to HUMAN on each page request. Enabling this feature provides data that populates the HUMAN portal with valuable information, such as the amount of requests blocked and additional API usage statistics.

Default: false

$perimeterxConfig = [
  ...
  'send_page_activities' => true
  ...
];

Additional Page Activity Handler

Adding an additional activity handler is done by setting 'additional_activity_handler' with a user defined function on the '$HUMANConfig' variable. The 'additional_activity_handler' function will be executed before sending the data to the HUMAN portal.

Default: Only send activity to HUMAN as controlled by '$HUMANConfig'.

/**
 * @param string            $activityType
 * @param PerimeterxContext $pxCtx
 * @param array             $details
 */
$perimeterxConfig['additional_activity_handler'] = function ($activityType, $pxCtx, $details)
{
    // user defined logic here
};

$px = Perimeterx::Instance($perimeterxConfig);
$px->pxVerify();

Additional Activity Handler Usage Examples

Log Activity

/**
 * @param string            $activityType
 * @param PerimeterxContext $pxCtx
 * @param array             $details
 */
$perimeterxConfig['additional_activity_handler'] = function ($activityType, $pxCtx, $details) use ($logger)
{
    if ($activityType === 'block') {
        $logger->warning('PerimeterX {activityType} details', ['activityType' => $activityType, 'details' => $details]);
    } else {
        $logger->info('PerimeterX {activityType} details', ['activityType' => $activityType, 'details' => $details]);
    }
};

$px = Perimeterx::Instance($perimeterxConfig);
$px->pxVerify();

Send Activity to statsd

/**
 * @param string            $activityType
 * @param PerimeterxContext $pxCtx
 * @param array             $details
 */
$perimeterxConfig['additional_activity_handler'] = function ($activityType, $pxCtx, $details) use ($statsd)
{
    $statsd->increment('perimeterx_activity.' . $activityType);
};

$px = Perimeterx::Instance($perimeterxConfig);
$px->pxVerify();

Data-Enrichment

The additional activity handler can be used to retrieve information about the request using the data-enrichment object. First, validate the data enrichment object is verified, then you can access its properties.

Default: false

/**
 * @param string            $activityType
 * @param PerimeterxContext $pxCtx
 * @param array             $details
 */
$perimeterxConfig['additional_activity_handler'] = function ($activityType, $pxCtx, $details) use ($logger)
{
    if($pxCtx->getDataEnrichmentVerified()) {
        $pxde = $pxCtx->getDataEnrichment();
        if($pxde->f_type == 'blacklist') {
            $logger->info('Filtered request with id: {$pxde->f_id} at: {$pxde->timestamp}');
        }
    }
};

$px = Perimeterx::Instance($perimeterxConfig);
$px->pxVerify();

Enrich Custom Params

With the enrich_custom_params function, you can add up to 10 custom parameters to be sent back to HUMAN servers. When set, the function is called before setting the payload on every request to HUMAN servers. The parameters should be passed according to the correct order (1-10).

Default: not set

/**
 * @param array             $customParamsArray
 */
$perimeterxConfig['enrich_custom_params'] = function ($customParamsArray)
{
    // user defined logic comes here
};

$px = Perimeterx::Instance($perimeterxConfig);
$px->pxVerify();

Enrich Custom Params Usage Examples

/**
 * @param array             $customParamsArray
 */
$perimeterxConfig['enrich_custom_params'] = function ($customParamsArray)
{
    $customParamsArray['custom_param1'] = "UserId";
    $customParamsArray['custom_param2'] = "SessionId";
    return $customParamsArray;
};

Logging

The HUMAN module logs messages via an implementation of \Psr\Log\LoggerInterface (see PSR-3 for full interface specification). By default, an instance of \Perimeterx\PerimeterxLogger is used which will log all message via PHP's error_log function. However, any custom logger that implements this interface may be used instead.

Default: \Perimeterx\PerimeterxLogger instance

$perimeterxConfig = [
  ...
  'logger' => new \My\Psr\Log\ConcreteLogger()
  ...
];

Debug Mode

Enables debug logging mode.

Default: false

$perimeterxConfig = [
  ...
  'debug_mode' => true
  ...
];

Once enabled, debug messages coming out from HUMAN should be in the following template:

[PerimeterX - DEBUG][APP_ID] - MESSAGE - for debug messages

[PerimeterX - ERROR][APP_ID] - MESSAGE - for error messages

An example log for an high score cookie:

[Mon Dec  4 14:03:50 20XX] [PerimeterX - DEBUG][APP_ID] -Starting request verification
[Mon Dec  4 14:03:50 20XX] [PerimeterX - DEBUG][APP_ID] -Request context created successfully
[Mon Dec  4 14:03:50 20XX] [PerimeterX - DEBUG][APP_ID] -No Captcha cookie present on the request
[Mon Dec  4 14:03:50 20XX] [PerimeterX - DEBUG][APP_ID] -Cookie V3 found, Evaluating
[Mon Dec  4 14:03:50 20XX] [PerimeterX - DEBUG][APP_ID] -Cookie evaluation ended successfully, risk score: 100
[Mon Dec  4 14:03:51 20XX] [PerimeterX - DEBUG][APP_ID] -Enforcing action: Captcha page is served

Guzzle Client Handler

Allows setting a handler to the Guzzle client object.

Default: false

$container = [];
$history = Middleware::history($container);
$handler = HandlerStack::create();
$handler->push($history);


$perimeterxConfig = [
  ...
  'guzzle_handler' => $handler
  ...
];

Custom Block URL

You can customize the block page to meet branding and message requirements by specifying the URL of the block page HTML file. The module will redirect to the block page defined in the custom_block_url variable. The defined block page will display a 307 (Temporary Redirect) HTTP Response Code.

Default: not set

$perimeterxConfig = [
  ...
  'custom_block_url' => '/block.html'
  ...
];

Defer Activities Sending

Specifies if sending page activities should be deferred until shutdown or not.

Default: true

$perimeterxConfig = [
  ...
  'defer_activities' => false
  ...
];

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 module's monitor mode is bypassed and active blocking 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 bypass_monitor_header property.

Default: not set

$perimeterxConfig = [
  ...
  'bypass_monitor_header' => 'x-px-block'
  ...
];

Return Response

Enables/disables the ability to return the response back (useful for frameworks like Symfony) instead of running die().

Default: false

$perimeterxConfig = [
  ...
  'return_response' => true
  ...
];

Advanced Blocking Response

Enables/disables the Advanced Blocking Response functionality, which returns the block response as a JSON object instead of HTML.

Default: false

$perimeterxConfig = [
  ...
  'enable_json_response' => true
  ...
];

Login Credentials Extraction

This feature extracts credentials (hashed username and password) from requests and sends them to HUMAN 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 px_login_credentials_extraction_enabled and px_login_credentials_extraction properties on the $perimeterxConfig array.

If credentials are found to be compromised, the field px-compromised-credentials will be added to the $_REQUEST object with the value "1". You may configure the name of this field with the px_compromised_credentials_header configuration.

Default Values

px_login_credentials_extraction_enabled: false

px_login_credentials_extraction: []

px_compromised_credentials_header: "px-compromised-credentials"

$perimeterxConfig['px_compromised_credentials_header'] = 'px-comp-creds';
$perimeterxConfig['px_login_credentials_extraction_enabled'] = true;
$perimeterxConfig['px_login_credentials_extraction'] = [
    [
        "path" => "/login",           // login path, automatically added to 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 return an associative array with the keys user and pass. If extraction is unsuccessful, the function should return null.

$perimeterxConfig['px_login_credentials_extraction_enabled'] = true;
$perimeterxConfig['px_login_credentials_extraction'] = [
    [
        "path" => "/login",                 // login path
        "method" => "POST",                 // supported methods: POST
        "callback_name" => "extractCreds"   // name of custom extraction callback
    ], ...
];

function extractCreds() {
    // custom implementation resulting in $username and $password
    if (empty($username) || empty($password)) {
        return null;
    }
    return [
        "user" => $username,
        "pass" => $password
    ];
}

Additional S2S Activity

To enhance detection on login credentials extraction endpoints, the following additional information is sent to HUMAN 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.

Login Success Reporting

There are a number of different possible ways to report the success or failure of the login attempt. If left empty, the login successful status will always be reported as false.

Default: Empty

$perimeterxConfig = [
  ...
  'px_login_successful_reporting_method' => 'status'
  ...
];

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

$perimeterxConfig['px_login_successful_reporting_method'] = 'status';
$perimeterxConfig['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 (accessed via the headers_list() function) 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

$perimeterxConfig['px_login_successful_reporting_method'] = 'header';
$perimeterxConfig['px_login_successful_header_name'] = 'login-successful';
$perimeterxConfig['px_login_successful_header_value'] = 'true';

Custom

Provide a custom callback that returns a boolean indicating if the login was successful. The value of the configuration field can be either an anonymous function or the name of the defined function as a string.

Default Values

px_login_successful_custom_callback: null

$perimeterxConfig['px_login_successful_reporting_method'] = 'custom';

// anonymous callback function
$perimeterxConfig['px_login_successful_custom_callback'] = function() {
    // ...
    return $isLoginSuccessful;
};

// name of defined function as string
$perimeterxConfig['px_login_successful_custom_callback'] = 'isLoginSuccessfulCallback';

function isLoginSuccessfulCallback() {
    // ...
    return $isLoginSuccessful;
}

Raw Username

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

Default: false

$perimeterxConfig['px_send_raw_username_on_additional_s2s_activity'] = true;

Manually Sending Additional S2S Activity

By default, this additional_s2s activity is sent automatically. If it is preferable to send this activity manually,
it's possible to disable automatic sending by configuring the value of px_automatic_additional_s2s_activity_enabled to false.

Default Value: true

$perimeterxConfig['px_automatic_additional_s2s_activity_enabled'] = false;

The activity can then be sent manually by invoking the function $px->pxSendAdditionalS2SActivity(), which accepts the following parameters:

Example Usage

// $px is an instance of the Perimeterx class

function handleLogin() {
    // login flow resulting in boolean $isLoginSuccessful
    $px->pxSendAdditionalS2SActivity($isLoginSuccessful ? 200 : 401, $isLoginSuccessful);
}

If further flexibility is needed, a JSON representation of the additional_s2s activity can be added to the $_REQUEST array. This activity can then be sent to another server if needed, parsed, modified, and sent via XHR POST as a JSON to HUMAN. To do this, disable automatic sending and enable the additional activity header configuration.

Default Value

px_additional_s2s_activity_header_enabled: false

$perimeterxConfig['px_automatic_additional_s2s_activity_enabled'] = false;
$perimeterxConfig['px_additional_s2s_activity_header_enabled'] = true;

The activity payload and URL destination will then be available by accessing $_REQUEST['px-additional-activity'] and $_REQUEST['px-additional-activity-url'], respectively.

function handleLogin() {
    // custom flow resulting in boolean $isLoginSuccessful
    $activity = json_decode($_REQUEST['px-additional-activity'], true);
    $activity['additional']['http_status_code'] = http_status_code();
    $activity['additional']['login_successful'] = $isLoginSuccessful;

    if ($isLoginSuccessful && $activity['additional']['credentials_compromised']) {
        $activity['additional']['raw_username'] = $_REQUEST['username'];
    }

    $url = $_REQUEST['px-additional-activity-url'];
    $headers = [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $_ENV['PX_AUTH_TOKEN']
    ];
    $body = json_encode($activity);

    sendPostRequest($url, $headers, $body);
}

function sendPostRequest($url, $headers, $body) {
    $curl = curl_init($url);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
    curl_exec($curl);
}