{"id":13540138,"url":"https://github.com/terrylinooo/shieldon","last_synced_at":"2025-05-15T09:09:03.245Z","repository":{"id":42480204,"uuid":"186539280","full_name":"terrylinooo/shieldon","owner":"terrylinooo","description":"Web Application Firewall (WAF) for PHP.","archived":false,"fork":false,"pushed_at":"2023-06-17T09:05:07.000Z","size":3268,"stargazers_count":865,"open_issues_count":2,"forks_count":102,"subscribers_count":27,"default_branch":"2.x","last_synced_at":"2025-05-13T02:34:19.375Z","etag":null,"topics":["antiscraping","application-firewall","ddos-protection","laravel-firewall","php-firewall"],"latest_commit_sha":null,"homepage":"https://shieldon.io","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/terrylinooo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-05-14T03:38:37.000Z","updated_at":"2025-05-13T00:52:12.000Z","dependencies_parsed_at":"2024-01-16T20:30:06.425Z","dependency_job_id":"723e8f6d-8195-4129-b599-71a763519465","html_url":"https://github.com/terrylinooo/shieldon","commit_stats":{"total_commits":689,"total_committers":9,"mean_commits":76.55555555555556,"dds":0.07256894049346885,"last_synced_commit":"25acc4ed5e128485c2cbdd04935e04449a91d7f0"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrylinooo%2Fshieldon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrylinooo%2Fshieldon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrylinooo%2Fshieldon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrylinooo%2Fshieldon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terrylinooo","download_url":"https://codeload.github.com/terrylinooo/shieldon/tar.gz/refs/heads/2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310520,"owners_count":22049470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["antiscraping","application-firewall","ddos-protection","laravel-firewall","php-firewall"],"created_at":"2024-08-01T09:01:41.206Z","updated_at":"2025-05-15T09:08:58.235Z","avatar_url":"https://github.com/terrylinooo.png","language":"PHP","funding_links":[],"categories":["PHP","\u003ca id=\"0abd611fc3e9a4d9744865ca6e47a6b2\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"784ea32a3f4edde1cd424b58b17e7269\"\u003e\u003c/a\u003eWAF"],"readme":"#  Web Application Firewall :zap: `PHP`\n\nShieldon is a Web Application Firewall (WAF) for PHP, with a beautiful and useful control panel that helps you easily manage the firewall rules and security settings.\n\n![Shieldon - Web Application Firewall for PHP](https://i.imgur.com/G4xpugB.png)\n\n![build](https://github.com/terrylinooo/shieldon/workflows/build/badge.svg) [![codecov](https://codecov.io/gh/terrylinooo/shieldon/branch/2.x/graph/badge.svg?v=202008201)](https://codecov.io/gh/terrylinooo/shieldon) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/terrylinooo/shieldon/badges/quality-score.png?b=2.x)](https://scrutinizer-ci.com/g/terrylinooo/shieldon/?branch=2.x) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n\n\n- Website: [https://shieldon.io](https://shieldon.io/)\n- Wiki: [https://github.com/terrylinooo/shieldon/wiki](https://github.com/terrylinooo/shieldon/wiki)\n- GitHub repository:  [https://github.com/terrylinooo/shieldon](https://github.com/terrylinooo/shieldon)\n- WordPress plugin: [https://wordpress.org/plugins/wp-shieldon/](https://wordpress.org/plugins/wp-shieldon/)\n\n## Demo\n\n- Before you installing Shieldon, you can try the online [DEMO](https://shieldon.io/demo/) of the firewall control panel, the user and password both are `demo`.\n- Try temporarily blocked by Shieldon, refreshing serveral times on [shieldon.io](https://shieldon.io/), then you will see a dialog asking you for solving Google ReCaptcha to get unblocked.\n\n## Installation\n\nInstall via PHP Composer.\n```php\ncomposer require shieldon/shieldon ^2\n```\n\nThis will also install dependencies built for Shieldon:\n\n| package | description |\n| --- | --- |\n| [shieldon/psr-http](https://github.com/terrylinooo/psr-http) | PSR-7, 15, 17 Implementation with full documented and well tested. |\n| [shieldon/event-dispatcher](https://github.com/terrylinooo/event-dispatcher) | Simple event dispatcher. |\n| [shieldon/web-security](https://github.com/terrylinooo/web-security) | Collection of functions about web security. |\n| [shieldon/messenger](https://github.com/terrylinooo/messenger) |  Collection of modules of sending message to third-party API or service, such as Telegram, Line, RocketChat, Slack, SendGrid, MailGun and more... |\n\n## Concepts\n\nThis is basic concepts about how Shieldon works.\n\n![](https://i.imgur.com/pRbI7gg.png)\n\n- The network-layer firewall such as CloudFlare.\n- The system-layer firewall such as iptables module.\n- To use firewall software in the Web application layer, you can implement Shieldon in a very early stage of your APP, mostly just after Composer autoloader, or at the first place of middleware-pipeline.\n- Shieldon analyzes all your HTTP and HTTPS requests.\n- Once Shieldon has detected strange behaviors of a request, blocking and prompting them CAPTCHA to unblock.\n![Firewall Dialog 1](https://i.imgur.com/rlsEwSG.png)\n- If a request fails in a row many times (depends on your setting), they will be permanently banned in current data circle.\n![Firewall Dialog 2](https://i.imgur.com/Qy1sADw.png)\n- If a request has been permanently banned, but they still access your page, drop them in System-layer firewall - iptables. (You have to set up iptables bridge correctly)\n\n## How to Use\n\n### Integration with Frameworks\n\nThere are some step-by-step installation guides that lead you implementing Shieldon firewall on your PHP application. Choose a framework you are using.\n\n|   |   |   |   |\n| --- | --- | --- | --- |\n| ![Firewall in Laravel](https://shieldon.io/images/home/laravel-framework-firewall.png) | ![Firewall in CakePHP](https://shieldon.io/images/home/cakephp-framework-firewall.png) | ![Firewall in Symfony](https://shieldon.io/images/home/symfony-framework-firewall.png) | ![Firewall in PHPixie](https://shieldon.io/images/home/phpixie-framework-firewall.png) |\n| [Laravel](https://github.com/terrylinooo/shieldon/wiki/Laravel-Framework) | [CakePHP 3](https://github.com/terrylinooo/shieldon/wiki/CakePHP-Framework) | [Symfony](https://github.com/terrylinooo/shieldon/wiki/Symfony-Framework)  | [PHPixie](https://github.com/terrylinooo/shieldon/wiki/PHPixie-Framework) |\n| ![Firewall in FatFree](https://shieldon.io/images/home/fatfree-framework-firewall.png) | ![Firewall in CodeIgniterr](https://shieldon.io/images/home/codeigniter-framework-firewall.png) | ![Firewall in Yii Framework](https://shieldon.io/images/home/yii-framework-firewall.png) | ![Firewall in Zend](https://shieldon.io/images/home/zend-framework-firewall.png) |\n| [FatFree](https://github.com/terrylinooo/shieldon/wiki/FatFree-Framework) | [CodeIgniter 3](https://github.com/terrylinooo/shieldon/wiki/CodeIgniter-3-Framework)\u003cbr /\u003e[CodeIgniter 4](https://github.com/terrylinooo/shieldon/wiki/CodeIgniter-4-Framework) | [Yii 2](https://github.com/terrylinooo/shieldon/wiki/Yii-2-Framework) | [Zend MVC](https://github.com/terrylinooo/shieldon/wiki/Zend-Framework-MVC)\u003cbr /\u003e[Zend Expressive](https://github.com/terrylinooo/shieldon/wiki/Zend-Framework-Expressive) |\n| ![Firewall in Slim](https://shieldon.io/images/home/slim-framework-firewall.png) | ![Firewall in Fuel](https://shieldon.io/images/home/fuel-framework-firewall.png) | - |\n| [Slim 3](https://github.com/terrylinooo/shieldon/wiki/Slim-3-Framework)\u003cbr /\u003e[Slim 4](https://github.com/terrylinooo/shieldon/wiki/Slim-3-Framework) | [Fuel](https://github.com/terrylinooo/shieldon/wiki/Fuel-Framework) |  [Pure PHP project](https://github.com/terrylinooo/shieldon/wiki/Pure-PHP-Project) |\n\nListed frameworks: [Laravel](https://shieldon.io/en/guide/laravel.html), [Symfony](https://shieldon.io/en/guide/symfony.html), [CodeIgniter](https://shieldon.io/en/guide/codeigniter.html), [CakePHP](https://shieldon.io/en/guide/cakephp.html), [Yii](https://shieldon.io/en/guide/yii.html), [Zend](https://shieldon.io/en/guide/zend.html), [Slim](https://shieldon.io/en/guide/slim.html), [Fat-Free](https://shieldon.io/en/guide/fatfree.html), [Fuel](https://shieldon.io/en/guide/fuel.html), [PHPixie](https://shieldon.io/en/guide/phpixie.html). Can't find the documentation of the framework you are using?\n\nThere are three ways you can choose to use Shieldon on your application.\n\n- Implement Shieldon as a *`PSR-15 middleware`*.\n- Implement Shieldon in the *`bootstrap stage`* of your application.\n- Implement Shieldon in the *`parent controller`* extended by the other controllers.\n\nShieldon `2.x` implements PSR-7 so that it could be compatible with modern frameworks such as Laravel, Symfony, Slim, Yii and so on.\n\n### PSR-15 Middleware\n\n#### `Example: Slim 4 framework`\n\nIn this example, I will give you some tips on how to implement Shieldon as a PSR-15 middleware.\n\nI use Slim 4 framwork for demonstration. This way can be used on any framework supporting PSR-15 too, just with a bit modification.\n\n#### (1) Create a firewall middleware.\n\n```php\nclass FirewallMiddleware\n{\n    /**\n     * Example middleware invokable class\n     *\n     * @param ServerRequest  $request PSR-7 request\n     * @param RequestHandler $handler PSR-15 request handler\n     *\n     * @return Response\n     */\n    public function __invoke(Request $request, RequestHandler $handler): Response\n    {\n        $response = $handler-\u003ehandle($request);\n\n        $firewall = new \\Shieldon\\Firewall\\Firewall($request, $response);\n\n        // The directory in where Shieldon Firewall will place its files.\n        $firewall-\u003econfigure(__DIR__ . '/../cache/shieldon_firewall');\n\n        // The base url for the control panel.\n        $firewall-\u003econtrolPanel('/firewall/panel/');\n\n        $response = $firewall-\u003erun();\n\n        if ($response-\u003egetStatusCode() !== 200) {\n            $httpResolver = new \\Shieldon\\Firewall\\HttpResolver();\n            $httpResolver($response);\n        }\n\n        return $response;\n    }\n}\n```\n\n#### (2) Add the firewall middleware in your application.\n\nFor example, if you are using Slim 4 framework, the code should look like this.\n\n```php\n$app-\u003eadd(new FirewallMiddleware());\n```\n\n#### (3) Create a route for control panel.\n\nFor example, if you are using Slim 4 framework, the code should look like this. Then you can access the URL `https://yourwebsite.com/firewall/panel` to login to control panel.\n\n```php\n$app-\u003eany('/firewall/panel[/{params:.*}]', function (Request $request, Response $response, $args) {\n    $firewall = new \\Shieldon\\Firewall\\Firewall($request, $response);\n\n    // The directory in where Shieldon Firewall will place its files.\n    // Must be the same as firewallMiddleware.\n    $firewall-\u003econfigure(__DIR__ . '/../cache/shieldon_firewall');\n\n    $panel = new \\Shieldon\\Firewall\\Panel();\n    $panel-\u003eentry();\n});\n```\n\nNote:\n- The HTTP method `POST` and `GET` both should be applied to your website.\n- `POST` method is needed for solving CAPTCHA by users who were temporarily blocked.\n\n### Bootstrap Stage\n\n#### `Example: Laravel 6 framework`\n\nInitialize Shieldon in the bootstrap stage of your application, mostly in just right after composer autoloader has been included.\n\nIn this example, I use Laravel 6 for demonstration.\n\n#### (1) Before Initializing the $app\n\nIn your `bootstrap/app.php`, after `\u003c?php`, add the following code.\n\n```php\n/*\n|--------------------------------------------------------------------------\n| Run The Shieldon Firewall\n|--------------------------------------------------------------------------\n|\n| Shieldon Firewall will watch all HTTP requests coming to your website.\n| Running Shieldon Firewall before initializing Laravel will avoid possible\n| conflicts with Laravel's built-in functions.\n*/\nif (isset($_SERVER['REQUEST_URI'])) {\n\n    // This directory must be writable.\n    // We put it in the `storage/shieldon_firewall` directory.\n    $storage =  __DIR__ . '/../storage/shieldon_firewall';\n\n    $firewall = new \\Shieldon\\Firewall\\Firewall();\n    $firewall-\u003econfigure($storage);\n\n    // The base url for the control panel.\n    $firewall-\u003econtrolPanel('/firewall/panel/');\n    $response = $firewall-\u003erun();\n\n    if ($response-\u003egetStatusCode() !== 200) {\n        $httpResolver = new \\Shieldon\\Firewall\\HttpResolver();\n        $httpResolver($response);\n    }\n}\n```\n\n#### (2) Define a route for firewall panel.\n\n```php\nRoute::any('/firewall/panel/{path?}', function() {\n\n    $panel = new \\Shieldon\\Firewall\\Panel();\n    $panel-\u003ecsrf(['_token' =\u003e csrf_token()]);\n    $panel-\u003eentry();\n\n})-\u003ewhere('path', '(.*)');\n```\n\n### Parent Controller\n\n#### `Example: CodeIgniter 3 framework`\n\nIf you are using a MVC framework, implementing Shieldon in a parent controller is also a good idea. In this example, I use CodeIgniter 3 for demonstration.\n\n#### 1. Create a parent controller.\n\nLet's create a `MY_Controller.php` in the `core` folder.\n\n```php\nclass MY_Controller extends CI_Controller\n{\n    public function __construct()\n    {\n        parent::__construct();\n    }\n}\n```\n\n#### 2.  Initialize Firewall instance\n\nPut the initial code in the constructor so that any controller extends `MY_Controller` will have Shieldon Firewall initialized and `$this-\u003efirewall()` method ready.\n\n```php\nclass MY_Controller extends CI_Controller\n{\n    public function __construct()\n    {\n        parent::__construct();\n\n        // Composer autoloader\n        require_once APPPATH . '../vendor/autoload.php';\n\n        // This directory must be writable.\n        $storage = APPPATH . 'cache/shieldon_firewall';\n\n        $firewall = new \\Shieldon\\Firewall\\Firewall();\n        $firewall-\u003econfigure($storage);\n\n        // The base url for the control panel.\n        $firewall-\u003econtrolPanel('/firewall/panel/');\n        $response = $firewall-\u003erun();\n\n        if ($response-\u003egetStatusCode() !== 200) {\n            $httpResolver = new \\Shieldon\\Firewall\\HttpResolver();\n            $httpResolver($response);\n        }\n    }\n\n    /**\n     * Shieldon Firewall protection.\n     */\n    public function firewall()\n    {\n        $firewall = \\Shieldon\\Container::get('firewall');\n        $firewall-\u003erun();\n    }\n}\n```\n\n#### 3.  Defind a controller for controll panel.\n\nWe need a controller to get into Shieldon firewall controll panel, in this example, we defind a controller named `Firewall`.\n\n```php\nclass Firewall extends MY_Controller\n{\n    public function __construct()\n    {\n        parent::__construct();\n    }\n\n    /**\n     * This is the entry of our Firewall Panel.\n     */\n    public function panel()\n    {\n        $panel = new \\Shieldon\\Firewall\\Panel();\n        $panel-\u003eentry();\n    }\n}\n```\n\nFinally, no matter which way you choose, entering `https://yoursite.com/firewall/panel/`, the login page is suppose to be shown on your screen.\n\n![](https://i.imgur.com/GFKzNYh.png)\n\nThe default user and password is `shieldon_user` and `shieldon_pass`. The first thing to do is to change the login and password after you login to control panel.\n\n![Firewall Panel](https://i.imgur.com/MELx6Vl.png)\n\n\n##  Contributing\n\nThank you for your interest in contributing to our project! We welcome contributions from everyone. Before getting started, please take a moment to review the guidelines below:\n\n### Guidelines\n\n- Fork the repository and create your branch from master.\n- Make sure your code follows our coding style and conventions.\n- Keep your code concise, well-documented, and modular.\n- Write clear commit messages that describe the purpose of your changes.\n- Test your changes thoroughly to ensure they don't introduce any new issues.\n- Make sure your code builds successfully without any errors or warnings.\n- Update relevant documentation, including README files if necessary.\n- Submit a pull request (PR) to the master branch of the original repository.\n\n### Code Testing\n\nWe utilize a Docker image that includes various dependencies for our code testing. The image is based on `/tests/Fixture/docker/Dockerfile`.\n\nFollow the steps below to run the tests:\n\n- Make sure you have Docker installed on your machine. If not, you can download and install it from the official Docker website.\n- Navigate to the project directory and build the Docker image by running the following command:\n    ```\n    composer test:docker:build\n    ```\n- Once the Docker image is built, you can run the tests by executing the following command:\n    ```\n    composer test:docker:run\n    ```\n- Observe the test results and make note of any failures or errors. The output will be displayed in the terminal.\n\nThe coverage report will be generated in the `/tests/report` directory. You can view the report by opening the `index.html` file in your browser.\n\n---\n\n## Author\n\nShieldon library is brought to you by [Terry L.](https://terryl.in) from Taiwan.\n\n## License\n\nShieldon Firewall is an open-sourced software licensed under the **MIT** license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrylinooo%2Fshieldon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterrylinooo%2Fshieldon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrylinooo%2Fshieldon/lists"}