search close

PHP Module Install

access_time Updated Jun 20, 2021

Note: Our PHP module requires a minimum version of PHP 5.3.

Installing the PHP module with PEAR

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

Once you download the PEAR package, it will be installed in the default location configured by your system, commonly /usr/share/php. The following command will help you identify the PEAR directory:

pear config-show | grep "PEAR directory"

Next, we will check the PHP configuration for the PEAR directory’s existence within the include_path:

php -i | grep include_path

Note: If the PEAR directory is not within your PHP include_path, the next step would be to modify your PHP file.

3. Include the module within your application

Once your PHP configuration is verified to load PEAR packages, update your application.

To do so, you will need to include the PHP module in your applications source near the top of your application code:

require_once('SigSci/sigsci.php');

4. Use the module within your application

After installing the module you’ll need to call the SigSciModule class, and capture the response to make a decision on whether or not to block. Learn more about configuring and using the PHP module here.

Installing the PHP module from a tarball

1. Download the Signal Sciences PHP module tarball

curl -O https://dl.signalsciences.net/sigsci-module-php/sigsci-module-php_latest.tar.gz

2. Extract the PHP module

After downloading the package, extract it to the current directory:

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

3. Include the module within your application

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.

Once the module is within your application tree, you will need to require it at the beginning of your application.

require_once('sigsci.php');

4. Use the module within your application

After installing the module you’ll need to call the SigSciModule class, and capture the response to make a decision on whether or not to block. Learn more about configuring and using the PHP module here.

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

To get started, we will call the SigSciModule class:

$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();
?>

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.

Once $sigsci->preRequest() has completed, you will now have access to $sigsci->block().

Detected attack types such as SQLI and XSS, which are returned to the module from the agent, can be pulled 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().

Simplified Configuration

To simplify this process and to take advantage of the __construct() and __destruct() magic methods, instantiate the SigSciModuleSimple() class, which extends SigSciModule() and automatically calls preRequest and postRequest within __construct() and __destruct() respectfully.

This simplifies implementation into the following snippet:

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

// Your application code ....
?>

Advanced Configuration

We provide the ability to 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, we need to update the agent configuration to point to /var/tmp/sigsci-lua. To ensure the module can communicate with the agent, we 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: