README

• LYRASOFT Firewall Package
  • Installation
    • Language Files
  • Register Admin Menu
  • Redirect
    • The Source Path Rules
    • The Dest Path
    • Other Params
    • Use Different Type from DB
    • Use Custom List
    • Instant Redirect
    • Disable
    • Hook
    • RedirectMiddleware params
  • IP Allow/Block (Firewall)
    • Admin IP Rules Management
    • Paths and Domains
    • Select DB Type
    • Custom List
    • Disable
    • Hook
    • FirewallMiddleware params
  • Cache
    • Cache Lifetime
    • Cache Clear
    • Cache Disable
  • Honeypot
    • Allow Good Bot
    • Built-in Block Words
    • HoneypotMiddleware params

Installation

Install from composer

composer require lyrasoft/firewall

Then copy files to project

php windwalker pkg:install lyrasoft/firewall -t routes -t migrations

Language Files

Add this line to admin & front middleware if you don't want to override languages:

$this->lang->loadAllFromVendor('lyrasoft/firewall', 'ini');

// OR
$this->lang->loadAllFromVendor(\Lyrasoft\Firewall\FirewallPackage::class, 'ini');

Or run this command to copy languages files:

php windwalker pkg:install lyrasoft/firewall -t lang

Register Admin Menu

Edit resources/menu/admin/sidemenu.menu.php

$menu->link($this->trans('unicorn.title.grid', title: $this->trans('firewall.redirect.title')))
    ->to($nav->to('redirect_list')->var('type', 'main'))
    ->icon('fal fa-angles-right');

$menu->link($this->trans('unicorn.title.grid', title: $this->trans('firewall.ip.rule.title')))
    ->to($nav->to('ip_rule_list')->var('type', 'main'))
    ->icon('fal fa-network-wired');

Redirect

Add RedirectMiddleware to etc/app/main.php

use Lyrasoft\Firewall\Middleware\RedirectMiddleware;

    // ...

    'middlewares' => [
        \Windwalker\DI\create(
            RedirectMiddleware::class,
            excludes: [
                'admin/*'
            ]
        ),
        
        // ...
    ],

Now you can add redirect records at admin:

The Source Path Rules

• Add / at start, the path will compare from site base root (not domain root).
• If you enable the Regex:
  • Add * will compare a path segment with any string.
  • Add ** will compare cross-segments.
  • You can add custom regex rules, like: /foo/(\d+)

The Dest Path

Thr dest path can be relative path: foo/bar or full URL: https://simular.co/foo/bar.

If you enabne the Regex, you may use variables start with $ to insert matched string. For example, a foo/*/edit/(\d+), can redirect to new/path/$1/edit/$2

Other Params

• Only 404: Only redirect if a page is 404, if page URL exists, won't redirect.
• Handle Locale: If this site is multi-language, this params will auto auto detect the starting ;anguage prefix and auto add it to dest path, you may use {lang} in dest path to custom set lang alias position.

Use Different Type from DB

Redirect tables has type colimn, you can use admin/redirect/list/{type} to manage different types.

And if you want to choose types for middleware, you can do this:

    // ...

    'middlewares' => [
        \Windwalker\DI\create(
            RedirectMiddleware::class,
            type: 'other_type',
            excludes: [
                'admin/*'
            ]
        ),
        
        // ...
    ],

The type supports string|Enum|array|null|false, if you send NULL into it, means all redirect records. If you send FALSE, means don't use DB records.

Use Custom List

You can use custom redirect list, custom list will auto-enable the regex:

This settings will merge DB list and custom list.

    // ...

    'middlewares' => [
        \Windwalker\DI\create(
            RedirectMiddleware::class,
            type: 'flower',
            list: [
                'foo/bar' => 'hello/world',            
                'foo/yoo/*' => 'hello/mountain/$1',            
            ],
            excludes: [
                'admin/*'
            ]
        ),
        
        // ...
    ],

This settings will disable DB list and only use custom list.

    // ...

    'middlewares' => [
        \Windwalker\DI\create(
            RedirectMiddleware::class,
            type: false,
            list: [
                'foo/bar' => 'hello/world',            
                'foo/yoo/*' => 'hello/mountain/$1',            
            ],
            excludes: [
                'admin/*'
            ]
        ),
        
        // ...
    ],

Custom List can use Closure to generate list:

// ...

    'middlewares' => [
        \Windwalker\DI\create(
            RedirectMiddleware::class,
            // ...
            list: raw(function (FooService $fooService) {
                return ...; 
            });
        ),
        
        // ...
    ],

The custom list redirect status code default is 301, if you want to use other status, set it to
REDIRECT_DEFAULT_STATUS env varialbe.

Instant Redirect

If there has some reason you can not wait RedirectResponse return, you may use instant redirect:

    // ...

    'middlewares' => [
        \Windwalker\DI\create(
            RedirectMiddleware::class,
            // ...
            instantRedirect: true,
        ),
        
        // ...
    ],

Disable

If you wanr to disable this middleware in debug mode, add this options:

        \Windwalker\DI\create(
            RedirectMiddleware::class,
            enabled: !WINDWALKER_DEBUG
        ),

Hook

Add afterHit hook that you can do somthing or log if redirect hit.

        \Windwalker\DI\create(
            RedirectMiddleware::class,
            afterHit: raw(function (string $dest, \Redirect $redirect) {
                \Windwalker\Core\Manager\Logger::info('Redirect to: ' . $dest);
            })
        ),

RedirectMiddleware params

    public function __construct(
        protected RedirectService $redirectService,
        protected AppContext $app,
        protected bool $enabled = true,
        protected string|\BackedEnum|array|false|null $type = 'main',
        protected array|\Closure|null $list = null,
        protected bool $instantRedirect = false,
        protected array $excludes = [],
        protected ?\Closure $afterHit = null,
        protected int $cacheTtl = 3600,
    ) {
    }

IP Allow/Block (Firewall)

To enable IP Rules, add FirewallMiddleware to front.route.php

use Lyrasoft\Firewall\Middleware\FirewallMiddleware;

    // ...

    ->middleware(
        FirewallMiddleware::class,
        // ...
        defaultAction: \Lyrasoft\Firewall\Enum\IpRuleKind::ALLOW, // Or BLOCK, default is ALLOW
        logger: 'firewall/blocks' // Or LoggerInterface instance, default is NULL
    )

    // ...

Admin IP Rules Management

Select Allow or Block, and enter the IP Range format:

The supported formats:

And you can use , to separate multiple IPs or IP Ranges. For example, 0.0.0.0/0,::/0 means all IPs includes both IPV4 and IPV6.

We use mlocati/ip-lib as IP Range parser.

Paths and Domains

After 0.2.0 there has a paths textarea, you can set domains / URLs or paths that this rule will effect, 1 line for 1 path.

For example, if you only want to block some IPs to access admin panel, you can set paths to /admin/*, or /admin/login if you only want to block access to login page.

You can also set domains or full URLs, for example, you can block some IPs to access https://*.foo.com/bar, or https://foo.com/bar/*/baz.

Select DB Type

You can also access different type from ip-rule/list/{type}.

And set type name to middleware

    ->middleware(
        FirewallMiddleware::class,
        type: 'foo',
    )

type can also supports string, array and enum. Use NULL to select all, FALSE to disable DB.

Custom List

If you want to manually set ip list, FirewallMiddleware custom list must use 2 lists, allowList and blockList.

    ->middleware(
        FirewallMiddleware::class,
        type: false,
        allowList: [
            '0.0.0.0',
            '144.122.*.*',
        ],
        blockList: [
            '165.2.90.45',
            '222.44.55.66',
        ],
        allowAsFirst: true, // Or false, default is false
    )

Disable

If you wanr to disable this middleware in debug mode, add this options:

        \Windwalker\DI\create(
            FirewallMiddleware::class,
            enabled: !WINDWALKER_DEBUG
        ),

Hook

Add afterHit hook that you can do somthing or log if an IP was be blocked.

        \Windwalker\DI\create(
            FirewallMiddleware::class,
            afterHit: fn () => function (AppRequest $appRequest) {
                \Windwalker\Core\Manager\Logger::info('Attack from: ' . $appRequest->getClientIp());
            }
        ),

FirewallMiddleware params

Cache

Cache Lifetime

Both middlewares has a cacheTtl param, default is 3600 seconds.

        \Windwalker\DI\create(
            FirewallMiddleware::class,
            cacheTtl: 3600,
            clearExpiredChance: 1 / 100 // Default is 1/100, means every 100 request will clear expired cache once, set it to 0 to disable auto clear expired cache
        ),

Cache Clear

Everytime you edit Redirect or IpRule will auto clear all caches.

The cache files is located at caches/firewall/, and you can add firewall to clear cache command in composer.json

        "post-autoload-dump": [
        ...
        "php windwalker cache:clear renderer html firewall" <-- Add firewall
],

Cache Disable

Cache will disable in debug mode or when ttl set to 0.

Honeypot

Add Honeypot Middleware to front.route.php, also add FirewallMiddleware below it.

If Honeypot matched, it will auto add am IpRule which blocked current IP. The type must match the FirewallMiddleware type.

use Lyrasoft\Firewall\Middleware\HoneypotMiddleware;
use Lyrasoft\Firewall\Service\Honeypot;

$router->group('front')
    ->namespace('front')
    ->middleware(
        HoneypotMiddleware::class,
        type: 'bot',
        matchParams: fn() => [
            '_ref' => 'preview'
        ],
        // Or use matchCallback to do more complex check:
        matchCallback: fn () => function (#[Input] string $foo) {
            return $foo === 'bar';
        },
        expires: '10minutes', // Default is 1 hour.
    )
    ->middleware(
        FirewallMiddleware::class,
        type: 'bot'
        // ...
    )

Then you can add an invisible link in your frontend page:

<a href="/path/to/any?_ref=preview" style="position: absolute; left: -9999px;">Preview</a>

If a bot click this link, it will be blocked for 10 minutes. You can also set multiple block words:

matchParams: fn() => [
    '_ref' => [
        'preview',
        'internal',
        'test'
    ],
    'from' => [...],
    'f' => [...]
]

Allow Good Bot

It is recommended to use the Honeypot for malicious bots that use random IPs and fake User-Agent strings to mimic real users. Legitimate bots can be identified by their User-Agent and will not click hidden links, so HoneypotMiddleware by default allows requests whose User-Agent contains the keyword bot, preventing accidental blocking of legitimate search engine crawlers and other good bots.

use Lyrasoft\Firewall\Middleware\HoneypotMiddleware;
use Lyrasoft\Firewall\Service\Honeypot;

// ...
    ->middleware(
        HoneypotMiddleware::class,
        // ...
        allowGoodRobot: true, // Default is true.
    )

If you want to detect bot by yourself, you can set allowGoodRobot to false, and use excludes to check if this request is an allowed bot:

use Lyrasoft\Firewall\Middleware\HoneypotMiddleware;
use Lyrasoft\Firewall\Service\Honeypot;

// ...
    ->middleware(
        HoneypotMiddleware::class,
        // ...
        allowGoodRobot: false,
        excludes: fn () => function (\Windwalker\Core\Http\AppRequest $appRequest) {
            $ua = $appRequest->getHeader('user-agent');

            // Allow Googlebot and Amazonbot, you can add more rules here.
            return str_contains($ua, 'googlebot') || str_contains($ua, 'amazonbot');
        }
    )

Built-in Block Words

We provides a set of built-in block words, you can use Honeypot::getBlockWords() to get this list, and use it in matchParams:

use Lyrasoft\Firewall\Middleware\HoneypotMiddleware;
use Lyrasoft\Firewall\Service\Honeypot;

$router->group('front')
    ->namespace('front')
    ->middleware(
        HoneypotMiddleware::class,
        matchParams: fn() => [
            '_ref' => Honeypot::getBlockWords()
        ]
    )

And add auto link to page:

{!! $app->retrieve(\Lyrasoft\Firewall\Service\Honeypot::class)->link() !!}

Honeypot class provides a set of words will randomly add to the link, but only first 3 words will be block words, so you can add some fake words to make it more difficult for bots to detect the honeypot link.

You can set your own block words by:

HONEYPOT_BLOCK_WORDS=preview,internal,test,foo,bar,baz

Honeypot will auto use first 3 words as block words.

HoneypotMiddleware params

public function __construct(
        protected AppContext $app,
        protected FirewallService $firewallService,
        protected BrowserNext $browserNext,
        protected string|\UnitEnum $type = 'bot',
        protected ?array $matchParams = null,
        protected ?\Closure $matchCallback = null,
        protected ?\Closure $blockHandler = null,
        protected bool $allowGoodRobot = true,
        protected \Closure|array|null $excludes = null,
        protected \DateTimeInterface|string $expires = '1hour',
    ) {
    }