search close

PHP Module Install

access_time Updated Jun 29, 2022

Requirements

  • PHP 5.3 or higher

Installation

  1. Download the Signal Sciences PHP PEAR module package.

    curl -O -L https://dl.signalsciences.net/sigsci-module-php/sigsci-module-php_latest.tgz
    pear install sigsci-module-php_latest.tgz
  2. Validate your PHP include_path. The PEAR package will be installed in the default location configured by your system (typically /usr/share/php). Run the following command to identify the PEAR directory:

    pear config-show | grep "PEAR directory"
  3. Check the PHP configuration to confirm the PEAR directory exists within the include_path.

    php -i | grep include_path

    If the PEAR directory is not within your PHP include_path, then you will need to modify your PHP file.

  4. At the top of your application code, add the following line to include the module within your application:

    require_once('SigSci/sigsci.php');
    

  1. Download the Signal Sciences PHP module archive.

    curl -O https://dl.signalsciences.net/sigsci-module-php/sigsci-module-php_latest.tar.gz
  2. Extract the PHP module archive to the current directory.

    tar -xvzf sigsci-module-php_latest.tar.gz

    After you extract the PHP package, you will need to include it within your application. Depending on your application structure, you may want to move the msgpack.php and sigsci.php files to a new directory to ensure the module is within your application tree.

  3. At the top of your application, add the following line:

    require_once('sigsci.php');
    

Using the PHP module

The Signal Sciences PHP module class is named SigSciModule. This module contains several methods used for communicating with the Signal Sciences agent in addition to the following methods which the customer can safely access:

__construct()
block()
agentResponseCode()
agentRequestID()
agentMeta()
agentTags()
preRequest()
postRequest()

Basic usage

  1. Call the SigSciModule class:

    $sigsci = new SigSciModule();
    
  2. After you instantiate the SigSciModule class, you will need to call $sigsci->preRequest(). This gathers request metadata which is sent to the agent to make a decision on the request.

    $sigsci->preRequest(); // Gathers request details for the agent
    
  3. Once $sigsci->preRequest() has completed, you will have access to $sigsci->block().

    if ($sigsci->block()){
    http_send_status(406);
    echo "Invalid Request Detected";
    ...
    
  4. Pull detected attack types such as SQLI and XSS, which are returned to the module from the agent, by calling the $sigsci->agentTags() method.

    You will also need to add $sigsci->postRequest() to the end of the application. If your application exits anywhere in your application code, you should make the $sigsci object available to that calling method to call $sigsci->postRequest().

    if ($sigsci->block()){
    http_send_status(406);
    echo "Invalid Request Detected";
    $sigsci->postRequest();
    exit();
    }
    
    // Your application code
    $sigsci->postRequest();
    ?>
    

Example

$sigsci = new SigSciModule();
$sigsci->preRequest(); // Gathers request details for the agent
if ($sigsci->block()){
http_send_status(406);
echo "Invalid Request Detected";
$sigsci->postRequest();
exit();
}

// Your application code
$sigsci->postRequest();
?>

Simplified configuration

You can use the __construct() and __destruct() magic methods to simplify the configuration process. Instantiate the SigSciModuleSimple() class, which extends SigSciModule() and automatically calls preRequest and postRequest within __construct() and __destruct() respectfully.

This simplifies implementation into the following example:

block()){
http_send_status(406);
echo "Invalid Request Detected";
exit();
}

// Your application code ....
?>

Advanced configuration

Alternatively, you can configure the module via an array(). The following attributes are set by default, but may need to be modified to provide support for different environments.

$config = array(
'max_post_size' => 100000, /* ignore posts bigger than this */
'timeout_microseconds' => 500000, /* fail open if agent calls take longer than this */
'socket_domain' => AF_UNIX, /* INET or UNIX */
'socket_address' => "/tmp/sigsci-lua",
'socket_port' => 0,
'allowed_methods' => array("GET", "POST", "PUT", "DELETE", "PATCH"),
'body_methods' => array("POST", "PUT", "PATCH"),
'filter_header' => array("cookie", "set-cookie", "authorization", "x-auth-token"), /* headers never sent to agent */
'anomaly_size' => 524288, /* if output is bigger size than this, send info to SigSci */
'anomaly_duration' => 1000, /* if request length is greater than this (millisecond), report back */
);

For example, on a SystemD-based system, the socket cannot run in /tmp/sigsci-lua. As a result, you will need to update the agent configuration to point to /var/tmp/sigsci-lua. To ensure the module can communicate with the agent, you must match the socket during module instantiation:

$sigsci_conf = array('socket_address' => '/var/tmp/sigsci-lua');
$sigsci = new SigSciModuleSimple($config);

Next Steps

Explore other installation options: