BlackRed 0.2.0

How does it work?

Example: A user tries to log on a system and fails because of bad credentials or an inactivated account. This failure can be recorded with BlackRed. After three failures within a certain time the account gets locked for an extended period of time. This limits brute force attacks. All time periods are configurable.

In a desktop application you would record the username in question with BlackRed. In a web environment, the requester’s IP address would be the perfect.

In the redis database, two lists are kept: A watchlist that records the failures, and the blacklist that contains blocked items.

Requirements

BlackRed runs only under Python 3.3, 3.4, 3.5 and PyPy3. There’s no support for Python 2.

The only thing BlackRed needs is the redis package >= 2.10.

Basic Usage

Installation can be done with pip install blackred. Usage is as easy, here an example for a simple user login:

import blackred

def login(username, password, request_ip):
    br = blackred.BlackRed()
    if br.is_blocked(request_ip):
        return False
    if not authenticate(username, password):
        br.log_fail(request_ip)
        return False
    return True

API Documentation

BlackRed has a very simple and intuitive API.

The constructor blackred.BlackRed accepts these parameters, all optional:

• redis_host: Hostname, IP Address or Socket, defaults to localhost

• redis_port: Port Number, defaults to 6397

• redis_db: DB Number, defaults to 0

• redis_use_socket: True, when a socket should be used instead the TCP/IP connection, defaults to False

To record a login or action failure, use the log_fail method. It requires one parameter:

• item: A username, an IP address or whatever you use to identify the failure

To check if some item is already on the blacklist, use the is_blocked method, or the is_not_blocked method to check for the opposite. Both methods require one parameter:

• item: A username, an IP address or whatever you use to identify the try

If you want to unblock something before it gets removed from the blacklist automatically, use the unblock method. It requires one parameter:

• item: A username, an IP address or whatever you use to identify the try

To find out how long an item on the watchlist or blacklist will stay there before it expires, use the get_watchlist_ttl method (for items on the watchlist) and the get_blacklist_ttl method (for items on the blacklist). Both methods return the number of seconds before expiry and None in case of a non-existing item. Both methods require one parameter:

• item: A username, an IP address or whatever you want to check

Redis Connection Parameters

The Redis connection parameters can be passed to the constructor blackred.BlackRed or configured as defaults for every new instance (see Settings and Defaults below). Typically, you should be fine with the defaults.

If you want to use a unix socket to connect, set the redis_use_socket constructor parameter to True and provide the absolute path to the socket with the redis_host parameter, example:

import blackred

br = blackred.BlackRed(redis_host='/var/run/redis/redis.sock', redis_use_socket=True)

Settings and Defaults

Besides the connection parameters, all settings are global for all instances of blackred.BlackRed. The settings are kept in the blackred.BlackRed.Settings class.

Links

• Author: Juergen Edelbluth, https://juergen.rocks/, @JuergenRocks

• Build Status: https://travis-ci.org/edelbluth/blackred

• Project Homepage: https://github.com/edelbluth/blackred

• PyPi Page: https://pypi.python.org/pypi/blackred

• German Description: https://juergen.rocks/art/mit-blackred-benutzer-logins-absichern.html

License

Copyright 2015 Juergen Edelbluth

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE.txt for complete License Text