PerimeterX PHP SDK

Table of Contents

• Usage

• Dependencies
• Installation
• Basic Usage Example

• Configuration

• Blocking Score
• Custom Block Action * Extracting Recomended Action
• Enable/Disable Captcha
• Extracting Real IP Address
• Custom URI
• Filter Sensitive Headers
• API Timeouts
• Send Page Activities
• Additional Page Activity Handler
• Logging
• Debug Mode

• Contributing

• Tests

Dependencies

• PHP >= v5.5
• mcrypt

Installation

Installation can be done using Composer.

$ composer require perimeterx/php-sdk

It can also be done by downloading the sources for this repository, and running composer install.

Basic Usage Example

use Perimeterx\Perimeterx;

$perimeterxConfig = [
    'app_id' => 'APP_ID',
    'cookie_key' => 'COOKIE_SECRET',
    'auth_token' => 'AUTH_
    TOKEN',
    'blocking_score' => 60
];

/* Obtain PerimeterX SDK instance */
$px = Perimeterx::Instance($perimeterxConfig);

/* run verify at the beginning of a page request */
$px->pxVerify();

Configuration Options

Configuring Required Parameters

Configuration options are set on the $perimeterxConfig variable.

Required parameters:

• app_id
• cookie_key
• auth_token

All parameters are obtainable via the PerimeterX Portal. (Applications and Policies pages)

Changing the Minimum Score for Blocking

Default blocking value: 70

$perimeterxConfig = [
	..
    'blocking_score' => 75
    ..
]

Custom Blocking Actions

In order to customize the action performed on a valid block value, use the 'custom_block_handler' option, and provide a user-defined function.

The custom handler should contain the action to be taken, when a visitor receives a score higher than the 'blocking_score' value. Common customization options are presenting of a reCAPTCHA, or supplying a custom branded block page.

Default block behaviour: return an HTTP status code of 403 and serve the PerimeterX block page.

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

    // user defined logic goes here
};

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

Examples

Serving a Custom HTML Page

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

    $html = '<div>Access to ' . $full_url . ' has been blocked.</div> ' +
                  '<div>Block reference - ' . $block_uuid . ' </div> ' +
                  '<div>Block score - ' . $block_score . '</div>';

    //echo $html;
    header("Status: 403");
    die();
};

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

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 Recomended 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::$ACTIVE_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::$MONITOR_MODE
    ..
]

Enable/Disable CAPTCHA on the block page

By enabling CAPTCHA support, a CAPTCHA will be served as part of the block page, giving real users the ability to identify as a human. By solving the CAPTCHA, the user's score is then cleaned up and the user is allowed to continue normal use.

Default value: true

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

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 PerimeterX 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, PerimeterX module needs the real user's IP.

The user's IP can be passed to the PerimeterX module using a custom user defined function on the $perimeterxConfig variable.

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

/**
 * @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 PerimeterX module, using a custom user function, defined on the $perimeterxConfig 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 PerimeterX servers (lower case header names). Filtering cookie headers for privacy is set by default, and can be overridden on the $perimeterxConfig variable.

Default: cookie, cookies

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

API Timeouts

Note: Controls the timeouts for PerimeterX requests. The API is called when a Risk Cookie does not exist, or is expired or invalid.

The API Timeout, in seconds (float), to wait for the PerimeterX server API response.

Default: 1

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

The API Connection Timeout, in seconds (float), to wait for the connection to the PerimeterX server API.

Default: 1

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

Send Page Activities

A boolean flag to enable or disable sending of activities and metrics to PerimeterX on each page request. Enabling this feature will provide data that populates the PerimeterX 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 '$perimeterxConfig' variable. The 'additional_activity_handler' function will be executed before sending the data to the PerimeterX portal.

Default: Only send activity to PerimeterX as controlled by '$perimeterxConfig'.

/**
 * @param string            $activityType
 * @param PerimeterxContext $pxCtx
 * @param array             $details
 */
$perimeterxConfig['additional_activity_handler'] = function ($activityType, $pxCtx, $details)
{
    // user defined logic comes 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();

Logging

Log 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.

Default: \Perimeterx\PerimeterxLogger instance

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

Debug Mode

Enables debug logging mode.

Default: false

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

Contributing

The following steps are welcome when contributing to our project. ###Fork/Clone First and foremost, Create a fork of the repository, and clone it locally. Create a branch on your fork, preferably using a self descriptive branch name.

###Code/Run Help improve our project by implementing missing features, adding capabilites or fixing bugs.

To run the code, simply follow the steps in the installation guide. Grab the keys from the PerimeterX Portal, and try refreshing your page several times continously. If no default behaviours have been overriden, you should see the PerimeterX block page. Solve the CAPTCHA to clean yourself and start fresh again.

Feel free to check out the Example App, to have a feel of the project.

###Test

Tests for this project are written using PHPUnit.

Dont forget to test. The project relies heavily on tests, thus ensuring each user has the same experience, and no new features break the code. Before you create any pull request, make sure your project has passed all tests, and if any new features require it, write your own.

To run any of the tests in the available suite, first open the bootstrap.php.dist file, and change the values according to the in-file insturctions. Then, rename the bootstrap.php.dist to bootstrap.php. Finally, run the phpunit command, or phpunit <testName> to execute a specific test (e.g. phpunit PerimeterxCookieTest)

###Pull Request After you have completed the process, create a pull request to the Upstream repository. Please provide a complete and thorough description, explaining the changes. Remember this code has to be read by our maintainers, so keep it simple, smart and accurate.