blackred package

The complete blackred.blackred module is imported in the __init__.py of the blackred module. So you can use blackred instead of blackred.blackred in your code.

For usage examples, please see the Examples Page.

blackred.blackred module

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

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.

class blackred.blackred.BlackRed(redis_host: str=None, redis_port: int=None, redis_db: int=None, redis_use_socket: bool=None, redis_auth: str=None)[source]

Bases: object

Create an Instance of BlackRed with configuration for Redis connection

Parameters:
  • redis_host (str) – Hostname, IP Address or Socket
  • redis_port (int) – Port Number
  • redis_db (int) – DB Number
  • redis_use_socket (bool) – True, when a socket should be used instead the TCP/IP connection
  • redis_auth (str) – If set, the redis AUTH command will be used with the given password
class Settings[source]

Bases: object

All the attributes of this class are used as default settings for new BlackRed instances.

ANONYMIZATION = False

If required, you can turn this on (set it to True) when BlackRed should not store IP addresses, usernames etc. as plain text. A hash value is used instead.

This setting might be necessary to get data protection policy compliant.

Type:bool
BLACKLIST_KEY_TEMPLATE = 'BlackRed:BlackList:{:s}'

Template for generating blacklist entries.

Defaults to 'BlackRed:BlackList:{:s}' and should only be changed when this collides with one of your namespaces.

Type:str
BLACKLIST_REFRESH_TTL_ON_HIT = True

If an item is already on the blacklist and is checked with BlackRed.is_blocked or BlackRed.is_not_blocked while on the blacklist, the time to live for the blacklist entry is reset to BlackRed.Settings.BLACKLIST_TTL_SECONDS.

So if this is set to True (that’s the default value) and a blocked user tries to login after 12 hours after blacklisting, his blacklist time is increased to another 24 hours.

Type:bool
BLACKLIST_TTL_SECONDS = 86400

Time in seconds for an item to stay on the blacklist.

Defaults to 86400 (24 hours). After that time, the entry is deleted automatically.

Type:int
REDIS_AUTH = None

If the redis connection requires authentication, the password can be predefined here.

If set to None (which is the default), authentication will not be used.

Type:str
REDIS_DB = 0

The Redis database number, defaults to 0

Type:int
REDIS_HOST = 'localhost'

Hostname, IP Address or socket, defaults to 'localhost'

Type:str
REDIS_PORT = 6379

TCP-Port for Redis, defaults to 6379

Type:int
REDIS_USE_SOCKET = False

Tell the BlackRed class to use a unix socket instead of a TCP/IP connection.

Defaults to False

Type:bool
SALT_KEY = 'BlackRed:AnonymizationListSecret'

The key for saving the individual salt for anonymization.

Defaults to BlackRed:AnonymizationListSecret and should only be changed when it collides with one of your namespaces.

Type:str
WATCHLIST_KEY_TEMPLATE = 'BlackRed:WatchList:{:s}'

Template for generating watchlist entries.

Defaults to 'BlackRed:WatchList:{:s}' and should only be changed when this collides with one of your namespaces.

Type:str
WATCHLIST_TO_BLACKLIST_THRESHOLD = 3

Number of fails for an item to get from the watchlist to the blacklist. Defaults to 3.

Type:int
WATCHLIST_TTL_SECONDS = 180

Time in seconds for an item to stay on the watchlist.

If after a logged failure a new failure appears within this time frame, the fail count is increased. If not, the entry is deleted automatically. Defaults to 180 (3 minutes).

Type:int
BlackRed.get_blacklist_ttl(item: str) → int[source]

Get the amount of time a specific item will remain on the blacklist.

Parameters:item (str) – The item to get the TTL for on the blacklist
Returns:Time in seconds. Returns None for a non-existing element.
Return type:int
BlackRed.get_watchlist_ttl(item: str) → int[source]

Get the amount of time a specific item will remain on the watchlist.

Parameters:item (str) – The item to get the TTL for on the watchlist
Returns:Time in seconds. Returns None for a non-existing element
Return type:int
BlackRed.is_blocked(item: str) → bool[source]

Check if an item is on the blacklist

Parameters:item (str) – The item to check
Returns:True, when the item is on the blacklist
Return type:bool
BlackRed.is_not_blocked(item: str) → bool[source]

Check if an item is _not_ already on the blacklist

Parameters:item (str) – The item to check
Returns:True, when the item is _not_ on the blacklist
Return type:bool
BlackRed.log_fail(item: str) → None[source]

Log a failed action for an item. If the fail count for this item reaches the threshold, the item is moved to the blacklist.

Parameters:item (str) – The item to log
BlackRed.unblock(item: str) → None[source]

Unblock an item and/or reset it’s fail count

Parameters:item (str) – The item to unblock
blackred.blackred.create_salt(length: int=128) → bytes[source]

Create a new salt

Parameters:length (int) – How many bytes should the salt be long?
Returns:The salt
Return type:bytes