{"id":33959435,"url":"https://github.com/bitsensor/php","last_synced_at":"2026-06-09T09:32:36.307Z","repository":{"id":62494641,"uuid":"155209065","full_name":"bitsensor/php","owner":"bitsensor","description":"BitSensor Web Application Security","archived":false,"fork":false,"pushed_at":"2019-04-19T10:20:30.000Z","size":2049,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-12-14T09:47:24.762Z","etag":null,"topics":["bitsensor","php","security"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitsensor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-29T12:34:22.000Z","updated_at":"2019-04-19T10:20:31.000Z","dependencies_parsed_at":"2022-11-02T11:30:48.058Z","dependency_job_id":null,"html_url":"https://github.com/bitsensor/php","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/bitsensor/php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsensor%2Fphp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsensor%2Fphp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsensor%2Fphp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsensor%2Fphp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitsensor","download_url":"https://codeload.github.com/bitsensor/php/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsensor%2Fphp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34101065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitsensor","php","security"],"created_at":"2025-12-12T21:10:59.290Z","updated_at":"2026-06-09T09:32:36.302Z","avatar_url":"https://github.com/bitsensor.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"![logo](https://dl2.pushbulletusercontent.com/3WwxLx0wKhfLB4sMWZ2QjLqFzwT5nwWD/Logo_BitSensorSmall_Light.png)\n\n# BitSensor PHP Plugin\n\nThe BitSensor PHP plugin.\n\n[BitSensor](https://bitsensor.io/)\n\n[Documentation](https://plugins.bitsensor.io/php)\n\n[Gitlab repo](https://git.bitsensor.io/plugins/php)\n\n\n## Setup BitSensor\n\n### Requirements\n* `php \u003e= 5.6.0`\n* `composer`\n* `uopz` [optional, for query tracing]\n  \n## Installation\n```bash\ncomposer require bitsensor/php\n```\n\n## Configuration\n\n### Code \n```php\n\u003c?php\nuse BitSensor\\Core\\BitSensor;\nuse BitSensor\\Core\\Config;\nuse BitSensor\\Connector\\ApiConnector;\nuse BitSensor\\Blocking\\Blocking;\nuse BitSensor\\Blocking\\Action\\BlockingpageAction;\nuse BitSensor\\Handler\\IpHandler;\nuse BitSensor\\Handler\\AfterRequestHandler;\n\n// Load Composer's autoloader\nrequire_once __DIR__ . '/vendor/autoload.php';\n\n// Create config using PHP.\nApiConnector::setUser('dev');\nApiConnector::setApiKey('secret-apikey');\n// ApiConnector::setHost('optional-host'); when not running on bitsensor.io\nBlockingpageAction::setUser('dev');\n// BlockingpageAction::setHost('optional-host'); //when not running on bitsensor.io\nBlocking::setAction(new BlockingpageAction());\nBitSensor::setConnector(new ApiConnector());\nIpHandler::setIpAddressSrc(IpHandler::IP_ADDRESS_REMOTE_ADDR);\nAfterRequestHandler::setExecuteFastcgiFinishRequest(true); // If you are using FastCGI\nBitSensor::setEnableUopzHook(true); // If you have enabled UOPZ\n\n// Start BitSensor \nBitSensor::run();\n```\n\n### JSON\n``index.php``\n```php\n\u003c?php\nuse BitSensor\\Core\\BitSensor;\n\nBitSensor::configure('/path/to/config.json');\n```\n\nSample configuration file:\n```json\n{ \n  \"connector\": {\n    \"type\": \"api\",\n    \"user\": \"dev\",\n    \"apikey\": \"php-plugin-test\"\n  },\n  \"blocking\": {\n    \"action\" :{ \n      \"type\": \"blockingpage\",\n      \"user\": \"dev\"\n    }\n  },\n  \"mode\": \"ids\",\n  \"ipAddressSrc\": \"remoteAddr\",\n  \"hostSrc\": \"serverName\",\n  \"logLevel\": \"none\",\n  \"uopzHook\": \"on\",\n  \"executeFastCgi\": \"off\"\n}\n```\n\n## Documentation\nYou have the following config options at your disposal:\n\n| PHP                           | JSON           | Value                                                                                                                                                      | Default                                                 | Description                                                                                                                |\n|-------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|\n| ```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                                                                    |\n| ```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.                                                                                      |\n| ```setIpAddress()```          | ipAddress      | ip override                                                                                                                                                | \u003cempty\u003e                                                 | IP address manual override value.                                                                                          |\n| ```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.                                                                                                    |\n| ```setHost()```               | host           | host address override                                                                                                                                      | \u003cempty\u003e                                                 | Hostname manual override value.                                                                                            |\n| ```setLogLevel()```           | logLevel       | ```Config::LOG_LEVEL_ALL``` (\"all\"), ```Config::LOG_LEVEL_NONE``` (\"none\")                                                                                 | ```Config::LOG_LEVEL_ALL``` (\"all\")                     | The logging level.                                                                                                         |\n| ```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. |\n| ```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.                                               |\n| ```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.                                 |\n\n### Connector Types\n\n#### Api\n| PHP                           | JSON           | Value                                                                                                                                                      | Default                                                 | Description                                                                                                                |\n|-------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|\n| ```setUser()```               | user           | username                                                                                                                                                   | \u003cempty\u003e                                                 | Your BitSensor username.                                                                                                   |\n| ```setApiKey()```             | apikey         | api key                                                                                                                                                    | \u003cempty\u003e                                                 | Your BitSensor API key.                                                                                                    |\n| ```setHost()```               | host           | hostname                                                                                                                                                   | {user}.bitsensor.io                                     | Hostname of the BitSensor endpoint.                                                                                        |\n| ```setPort()```               | port           | port                                                                                                                                                       | 8080                                                    | Port of the BitSensor endpoint.                                                                                            |\n\n#### File\n| PHP                 | JSON     | Value            | Default                               | Description  |\n|---------------------|----------|------------------|---------------------------------------|--------------|\n| ```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` |\n\n\n### Blocking Actions\n#### Blockingpage\n| PHP                           | JSON           | Value                                                                                                                                                      | Default                                                 | Description                                                                                                                |\n|-------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|\n| ```setUser()```               | user           | username                                                                                                                                                   | \u003cempty\u003e                                                 | Your BitSensor username.                                                                                                   |\n| ```setHost()```               | host           | hostname                                                                                                                                                   | {user}.bitsensor.io                                     | Hostname of the BitSensor endpoint.                                                                                        |\n| ```setPort()```               | port           | port                                                                                                                                                       | 2080                                                    | Port of the BitSensor endpoint.                                                                                            |\n\n## Query tracing\n    \nTo use PDO and MySQLi query tracing, the [uopz](https://github.com/krakjoe/uopz) pecl extension must be installed.\n\n```bash\n# You might have to install `pecl` and php-dev dependencies\nsudo apt-get install php-pear php-dev\n\npecl install uopz\n\n# You might have to add `extension=uopz.so` to your php.ini, if that does not happen automatically\necho 'extension=uopz.so' \u003e\u003e /etc/php/7.0/fpm/php.ini\n\n# In case of php-fpm, reload the service\nservice php7.0-fpm reload\n\n# Check successful installation, the output should be `1`\nphp -r 'echo extension_loaded(\"uopz\");'\n```\n\n## Logging\n\n### Monolog\n```php\n\u003c?php\nuse Monolog\\Logger;\n\nuse Monolog\\Handler\\PsrHandler;\nuse BitSensor\\Handler\\PsrLogHandler;\n\n// Your existing logger code\n$log = new Logger('name');\n\n// Add the BitSensor PsrLogHandler\n$log-\u003epushHandler(new PsrHandler(new PsrLogHandler()));\n```\n\n### Tags\nIf you are running many applications, it might be sensible to group them by a tag. You can create a tag using the following snippet:\n```php\n\u003c?php\nuse \\BitSensor\\Core\\BitSensor;\nBitSensor::putEndpoint(\"tag\", \"cool-applications\");\n```\n\n### WebSocket\nIf you are using websockets, BitSensor needs to know in order to properly detect attacks.\n```php\n\u003c?php\nuse \\BitSensor\\Core\\BitSensor;\nuse \\BitSensor\\Core\\EndpointConstants;\n\nBitSensor::putEndpoint(EndpointConstants::WEBSOCKET, 'true');\n```\n\n## Apache\nAfter sinking BitSensor hooks in your application, you can extend BitSensor's visibility to include Apache events that aren't processed by your application. \n\nTo log Apache errors add the following to your ``.htaccess``:\n```ApacheConf\n# Open .phar files as PHP files\nAddType application/x-httpd-php .phar\n\n# Add all errors you want BitSensor to handle\n# The path to BitSensor.phar is as seen in the URL in the browser\nErrorDocument 400 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=400\nErrorDocument 401 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=401\nErrorDocument 402 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=402\nErrorDocument 403 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=403\nErrorDocument 404 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=404\nErrorDocument 405 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=405\nErrorDocument 406 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=406\nErrorDocument 407 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=407\nErrorDocument 408 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=408\nErrorDocument 409 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=409\nErrorDocument 410 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=410\nErrorDocument 411 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=411\nErrorDocument 412 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=412\nErrorDocument 413 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=413\nErrorDocument 414 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=414\nErrorDocument 415 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=415\nErrorDocument 500 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=500\nErrorDocument 501 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=501\nErrorDocument 502 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=502\nErrorDocument 503 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=503\nErrorDocument 504 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=504\nErrorDocument 505 /path/to/BitSensor.phar/Handler/ErrorDocumentHandler.php?e=505\n\n# Add all errors you want to show a custom page for\n# The path is as seen in the URL in the browser\nSetEnv ERROR_DOCUMENT_400 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_401 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_402 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_403 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_404 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_405 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_406 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_407 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_408 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_409 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_410 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_411 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_412 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_413 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_414 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_415 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_500 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_501 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_502 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_503 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_504 /path/to/error/document.html\nSetEnv ERROR_DOCUMENT_505 /path/to/error/document.html\n```\n\n\n## Debugging\nFor more extensive debugging in your codebase, we provide the following hooks:\n\nDebug logging can be printed using ``BitSensor\\Util\\Log::d($msg)``,\nthis will only be printed when running in debug mode, activated by setting:\n\n```php\n\\BitSensor\\Util\\Log::setEnabled(true);\n```\n\nThis should be done in a test script and not in the actual source.\n\n## External dependencies\nLibraries not managed by Composer should go in the ``lib/`` folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsensor%2Fphp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitsensor%2Fphp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsensor%2Fphp/lists"}