Configuration

The Shieldon Firewall has a rich set of configurations that allows you to customize how it behaves. Below is a breakdown of the properties available for you to configure:

You can adjust the setting when initializing Shieldon instance, or using setProperty or setProperties API later.

Initializing

$config = [
    'time_unit_quota' => [
        ['s' => 2, 'm' => 10, 'h' => 30, 'd' => 60]
    ]
];

$kernel = new \Shieldon\Shieldon($config);

setProperty

$kernel->setProperty('time_unit_quota', [
    's' => 2, 'm' => 10, 'h' => 30, 'd' => 60
]);

setProperties

$config = [
    'time_unit_quota' => [
        ['s' => 2, 'm' => 10, 'h' => 30, 'd' => 60]
    ]
];

$kernel->setProperties($config);

Default values

key	type	value
time_unit_quota	array	['s' => 2, 'm' => 10, 'h' => 30, 'd' => 60]
time_reset_limit	integer	3600
interval_check_referer	integer	5
interval_check_session	integer	30
limit_unusual_behavior	array	['cookie' => 5, 'session' => 5, 'referer' => 10]
cookie_name	string	ssjd
cookie_domain	string	"

Parameters

time_unit_quota

This setting allows you to define the page view limits for users on your website based on a certain time unit. The keys of the array are 's' (second), 'm' (minute), 'h' (hour), and 'd' (day), with each key corresponding to the page view limit per user for that time unit. The default is ['s' => 2, 'm' => 10, 'h' => 30, 'd' => 60]

• array

key	value	description
s	integer	Page views per vistor per second
m	integer	Page views per vistor per minute
h	integer	Page views per vistor per hour
d	integer	Page views per vistor per day

• If you just want to limit an user to view 100 pages a day, just set s, m, h to a very high number, and set d to 100.

• To remember, when users reached the limit will just be banned temporaily, they can get unbanned by solving Captcha, so, do not set the values too loose, overwise it is no sense to use this library.

time_reset_limit

This is the time in seconds after which the filters flagged number is reset. The default value is 3600 (1 hour).

interval_check_referer

Similar to interval_check_referer, this property sets the delay in seconds before Shieldon starts checking the SESSION cookie for a user. The default is 30 seconds.

When an user first time visit to your website by entering URL on browser, the HTTP_REFERER is empty. After interval_check_referer seconds, Shieldon will start checking HTTP_REFERER.

You can ignore this value.

interval_check_session

When an user first time visit to your website, after interval_check_session seconds, Shieldon will start checking SESSION cookie.

limit_unusual_behavior

This setting allows you to define the limits for being flagged as unusual behavior based on certain conditions.

The default is ['cookie' => 5, 'session' => 5, 'referer' => 10].

Setting the limits and quotas of being flagged as unusual behavior for your vistors on your website.

• array

key	value	description
cookie	integer	Cookie generated by JavaScript.
session	integer	PHP Session
referer	integer	HTTP_REFERER

cookie_name

This property is used to specify the name of the cookie that Shieldon uses. The default is ssjd.

cookie_domain

This property defines the domain to which the cookie is restricted. By default, the cookie is available to all subdomains on the server.

deny_attempt_enable

If you enable this option, Shieldon will record every consecutive CAPTCHA failure. Once a user reaches the specified limit, Shieldon will classify them as a blocked IP in the rule table, which persists until the new data cycle begins.

Even when blocked, users can still access the warning page. However, if they consistently fail to solve the CAPTCHA, it is highly likely they are not human. In response, Shieldon adds them to the system firewall's blocklist, effectively banning them permanently.

Default:

'deny_attempt_enable' => [
        'data_circle'     => false,
        'system_firewall' => false,
    ],

record_attempt_detection_period

To prevent adding social platform bots to the iptables firewall, such as those from Facebook, Line, and others that scrape snapshots from your web pages, you should adjust the values below to fit your needs. (Unit: seconds)

Default:

'record_attempt_detection_period' => 5,

reset_attempt_counter

This parameter determines how long (in seconds) until the attempt counter is reset. In this case, the counter is reset every 30 minutes.

Default:

'reset_attempt_counter' => 1800,

iptables_watching_folder

This parameter is the directory that the iptables service monitors for commands from the Shieldon Firewall. In this case, it's watching the temporary '/tmp/' directory.

Others

For any properties not mentioned here, you can refer to the get_default_properties() function in the Shieldon\Firewall\Helpers class.

/**
 * The default settings of Shieldon core.
 *
 * @return array
 */
function get_default_properties(): array
{
    return [
        'time_unit_quota' => [
            's' => 2,
            'm' => 10,
            'h' => 30,
            'd' => 60
        ],
        'time_reset_limit' => 3600,
        'interval_check_referer' => 5,
        'interval_check_session' => 5,
        'limit_unusual_behavior' => [
            'cookie' => 5,
            'session' => 5,
            'referer' => 10
        ],
        'cookie_name' => 'ssjd',
        'cookie_domain' => '',
        'cookie_value' => '1',
        'display_online_info' => true,
        'display_user_info' => false,
        'display_http_code' => false,
        'display_reason_code' => false,
        'display_reason_text' => false,

        'deny_attempt_enable' => [
            'data_circle' => false,
            'system_firewall' => false,
        ],
        'deny_attempt_notify' => [
            'data_circle' => false,
            'system_firewall' => false,
        ],
        'deny_attempt_buffer' => [
            'data_circle' => 10,
            'system_firewall' => 10,
        ],
        'record_attempt_detection_period' => 5,
        'reset_attempt_counter' => 1800,
        'iptables_watching_folder' => '/tmp/',
    ];
}

Note: You can set these properties either during the initialization of the Shieldon instance, or later using the setProperty or setProperties API.