Previous topic

securitylib.throttling.common — Throttling common functions

This Page

securitylib.throttling.server — Throttling server functions

class securitylib.throttling.server.StateUpdater(counters_storage, session_storage, config=None)

Use this class to update the throttling state of client requests.

Parameters:
  • counters_storage (securitylib.throttling.common.CountersStorage) – Storage to be used for storing throttling counters.
  • session_storage (securitylib.throttling.common.SessionStorage) – Storage to be used to store sessions.
  • config (dict) –

    A dictionary containing throttling parameters (dictionary keys are the parameter name and dictionary values are the parameter value). Allows defining the limits in requests before the throttling state changes to captcha or block, and the initial blocking time.

    You can omit the whole dictionary or some of its keys as the values for the missing keys will be taken from the default configuration.

    Structure:
    Key Type Description
    limits dictionary of dictionaries with integer values This parameter must have up to two dictionaries with keys 'captcha' and 'block', one that contains captcha limits, and another for block limits.

    If any of these dictionaries is missing, no limits will be imposed for that throttling method, which effectively disables the throttling method. This can be used, for example, to disable throttling by captcha for APIs.

    Each of these two dictionaries has up to five pairs of keys and values, where each key is a type of counter and its value is the limit for the value of the counter before the throttling state is updated, e.g. if limits['captcha']['user'] is 5, the state for the 'user' counter will change to 'captcha' when its value increases beyond 5.

    initial_blocking_time integer Duration in seconds for the first block (subsequent blocks will have its duration doubled each time).

    Default configuration:

    {
        'limits': {
            'captcha': {
                'ip': 20,
                'user': 20,
                'pwd': 20,
                'ip_user': 3,
                'ip_pwd': 3,
            },
            'block': {
                'ip': 100,
                'user': None,
                'pwd': None,
                'ip_user': 7,
                'ip_pwd': 7,
            },
        },
        'initial_blocking_time': 30,
    }
    
add_request(ip, user=None, pwd=None, session_id=None, success=False, ctx='')

Notifies the StateUpdater of the ocurrence of a request, which it will use to update the respective counters and their state.

Parameters:
  • ip (str) – The ip of the client that made the request.
  • user (str) – The user that the client sent in his login request. (used for login attempts)
  • pwd (str) – The password that the client sent in his login request. (used for login attempts)
  • session_id (str) – The session_id for the client’s session. Use the same session_id you used in the check_state() call. This session_id is used only for login requests and thus can be omitted for other requests.
  • success (bool) – Whether the given request succeeded or not. This applies to a login request, for example, where the login can either succeed or not. Most other requests have no such differentiation, and as such you should omit this parameter.
  • ctx – The context of the request. Use the same context you used in the check_state() call.