The BitSensor PHP plugin.
php >= 5.6.0composeruopz[optional, for query tracing]
composer require bitsensor/php<?phpuseBitSensor\Core\BitSensor;
useBitSensor\Core\Config;
useBitSensor\Connector\ApiConnector;
useBitSensor\Blocking\Blocking;
useBitSensor\Blocking\Action\BlockingpageAction;
useBitSensor\Handler\IpHandler;
useBitSensor\Handler\AfterRequestHandler;
// Load Composer's autoloaderrequire_once__DIR__ . '/vendor/autoload.php';
// Create config using PHP.
ApiConnector::setUser('dev');
ApiConnector::setApiKey('secret-apikey');
// ApiConnector::setHost('optional-host'); when not running on bitsensor.io
BlockingpageAction::setUser('dev');
// BlockingpageAction::setHost('optional-host'); //when not running on bitsensor.io
Blocking::setAction(newBlockingpageAction());
BitSensor::setConnector(newApiConnector());
IpHandler::setIpAddressSrc(IpHandler::IP_ADDRESS_REMOTE_ADDR);
AfterRequestHandler::setExecuteFastcgiFinishRequest(true); // If you are using FastCGI
BitSensor::setEnableUopzHook(true); // If you have enabled UOPZ// Start BitSensor
BitSensor::run();index.php
<?phpuseBitSensor\Core\BitSensor;
BitSensor::configure('/path/to/config.json');Sample configuration file:
{ "connector": {
"type": "api",
"user": "dev",
"apikey": "php-plugin-test"
},
"blocking": {
"action" :{ "type": "blockingpage",
"user": "dev"
}
},
"mode": "ids",
"ipAddressSrc": "remoteAddr",
"hostSrc": "serverName",
"logLevel": "none",
"uopzHook": "on",
"executeFastCgi": "off"
}You have the following config options at your disposal:
| PHP | JSON | Value | Default | Description |
|---|---|---|---|---|
setMode() | mode | BitSensor::MODE_IDS ("ids"), BitSensor::MODE_MONITORING ("monitoring"), BitSensor::MODE_OFF ("off") | BitSensor::MODE_IDS ("ids") | BitSensor pipeline running mode. Default "ids" mode includes process pipeline, false positive detection, auto-blocking. "monitoring" mode excludes auto-blocking while in "off" mode, only logging will be done |
setIpAddressSrc() | ipAddressSrc | Config::IP_ADDRESS_REMOTE_ADDR ("remoteAddr"), Config::IP_ADDRESS_X_FORWARDED_FOR ("forwardedFor"), Config::IP_ADDRESS_MANUAL ("manual") | Config::IP_ADDRESS_REMOTE_ADDR ("remoteAddr") | Source of the IP address of the user. |
setIpAddress() | ipAddress | ip override | IP address manual override value. | |
setHostSrc() | hostSrc | Config::HOST_SERVER_NAME ("serverName"), Config::HOST_HOST_HEADER ("hostHeader"), Config::HOST_MANUAL ("manual") | Config::HOST_SERVER_NAME ("serverName") | Source of the hostname. |
setHost() | host | host address override | Hostname manual override value. | |
setLogLevel() | logLevel | Config::LOG_LEVEL_ALL ("all"), Config::LOG_LEVEL_NONE ("none") | Config::LOG_LEVEL_ALL ("all") | The logging level. |
setOutputFlushing | outputFlushing | Config::OUTPUT_FLUSHING_ON ("on"), Config::OUTPUT_FLUSHING_OFF ("off") | Config::OUTPUT_FLUSHING_OFF ("off") | Output flushing. Turning this on allows the browser to render the page while BitSensor is still working in the background. |
setUopzHook | uopzHook | Config::UOPZ_HOOK_ON ("on"), Config::UOPZ_HOOK_OFF ("off") | Config::UOPZ_HOOK_ON ("on") | Uopz Hooking. Turning this on enables BitSensor to hook into function calls. |
setFastcgiFinishRequest | executeFastCgi | Config::EXECUTE_FASTCGI_FINISH_REQUEST_ON ("on"), Config::EXECUTE_FASTCGI_FINISH_REQUEST_OFF ("off") | Config::EXECUTE_FASTCGI_FINISH_REQUEST_OFF ("off") | Finish request to your FastCGI webserver, while processing BitSensor in a separate thread. |
| PHP | JSON | Value | Default | Description |
|---|---|---|---|---|
setUser() | user | username | Your BitSensor username. | |
setApiKey() | apikey | api key | Your BitSensor API key. | |
setHost() | host | hostname | {user}.bitsensor.io | Hostname of the BitSensor endpoint. |
setPort() | port | port | 8080 | Port of the BitSensor endpoint. |
| PHP | JSON | Value | Default | Description |
|---|---|---|---|---|
setFilename() | filename | File to write to | /var/log/bitsensor-datapoints-php.log | Logfile that is appended to. Make sure that the Apache or Nginx user can write to this file. Set this using touch /var/log/bitsensor-datapoints-php.log; chown www-data /var/log/bitsensor-datapoints-php.log; chmod 200 /var/log/bitsensor-datapoints-php.log |
| PHP | JSON | Value | Default | Description |
|---|---|---|---|---|
setUser() | user | username | Your BitSensor username. | |
setHost() | host | hostname | {user}.bitsensor.io | Hostname of the BitSensor endpoint. |
setPort() | port | port | 2080 | Port of the BitSensor endpoint. |
To use PDO and MySQLi query tracing, the uopz pecl extension must be installed.
# You might have to install `pecl` and php-dev dependencies
sudo apt-get install php-pear php-dev
pecl install uopz
# You might have to add `extension=uopz.so` to your php.ini, if that does not happen automaticallyecho'extension=uopz.so'>> /etc/php/7.0/fpm/php.ini
# In case of php-fpm, reload the service
service php7.0-fpm reload
# Check successful installation, the output should be `1`
php -r 'echo extension_loaded("uopz");'<?phpuseMonolog\Logger;
useMonolog\Handler\PsrHandler;
useBitSensor\Handler\PsrLogHandler;
// Your existing logger code$log = newLogger('name');
// Add the BitSensor PsrLogHandler$log->pushHandler(newPsrHandler(newPsrLogHandler()));If you are running many applications, it might be sensible to group them by a tag. You can create a tag using the following snippet:
<?phpuse \BitSensor\Core\BitSensor;
BitSensor::putEndpoint("tag", "cool-applications");If you are using websockets, BitSensor needs to know in order to properly detect attacks.
<?phpuse \BitSensor\Core\BitSensor;
use \BitSensor\Core\EndpointConstants;
BitSensor::putEndpoint(EndpointConstants::WEBSOCKET, 'true');After sinking BitSensor hooks in your application, you can extend BitSensor's visibility to include Apache events that aren't processed by your application.
To log Apache errors add the following to your .htaccess:
# Open .phar files as PHP filesAddTypeapplication/x-httpd-php .phar
# Add all errors you want BitSensor to handle# The path to BitSensor.phar is as seen in the URL in the browserErrorDocument400 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=400ErrorDocument401 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=401ErrorDocument402 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=402ErrorDocument403 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=403ErrorDocument404 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=404ErrorDocument405 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=405ErrorDocument406 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=406ErrorDocument407 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=407ErrorDocument408 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=408ErrorDocument409 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=409ErrorDocument410 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=410ErrorDocument411 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=411ErrorDocument412 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=412ErrorDocument413 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=413ErrorDocument414 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=414ErrorDocument415 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=415ErrorDocument500 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=500ErrorDocument501 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=501ErrorDocument502 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=502ErrorDocument503 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=503ErrorDocument504 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=504ErrorDocument505 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=505# Add all errors you want to show a custom page for# The path is as seen in the URL in the browserSetEnv ERROR_DOCUMENT_400 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_401 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_402 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_403 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_404 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_405 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_406 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_407 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_408 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_409 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_410 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_411 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_412 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_413 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_414 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_415 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_500 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_501 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_502 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_503 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_504 /path/to/error/document.html
SetEnv ERROR_DOCUMENT_505 /path/to/error/document.htmlFor more extensive debugging in your codebase, we provide the following hooks:
Debug logging can be printed using BitSensor\Util\Log::d($msg),
this will only be printed when running in debug mode, activated by setting:
\BitSensor\Util\Log::setEnabled(true);This should be done in a test script and not in the actual source.
Libraries not managed by Composer should go in the lib/ folder.