Handle brute force on key backed by Redis.
Add this line to your application's Gemfile:
gem 'fail_to_ban', git: 'https://github.com/jobteaser/fail_to_ban.git', tag: 'v0.2.1'And then execute:
$ bundle
Or install it yourself as:
$ gem install fail_to_ban
We provide a default backoff strategy, see: backoff_strategy.rb
You can make your own custom strategy and inject it, your strategy will be initialized with the following parameters: key, storage, config
The following methods should be implemented:
| Name | Type | Description |
|---|---|---|
| attempt | symbol | Make a connection attempt, could increment a retry_count for example. |
| blocked? | boolean | Should Tell wether the key should be blocked for another attempt. |
| reset | symbol | Should remove the key in storage. |
| unlock_at | Time | Should return the time when the lock will be lifted. |
$redis = Redis.new
FailToBan.new(
key: 'hello/42', # Can be any string, should be unique
storage: $redis, # A key value storage compatible with the redis api
strategy: Strategies::BackoffStrategy, # Optionnal
config: { permitted_attempts: 3, backoff_step: 15 } # Optionnal
)| Parameter | Type | Description | Default |
|---|---|---|---|
| permitted_attempts | Integer | The number of permitted attemps before locking the key. | 3 |
| backoff_step | Integer | The time the key will be locked for, in seconds, and incrementing after every fail. | 15 |
| backoff_cap | Integer | The time after which the unlock_at will stop being incremented. (nil = no limit) | nil |
$redis = Redis.new
FailToBan.new(
key: '[email protected]',
storage: $redis,
strategy: Strategies::BackoffStrategy, # By default
config: { permitted_attempts: 3, backoff_step: 15 }
)
protection.blocked?
# => false
protection.attempt
# => :ok
# Backoff : after 3 failed attempts there is a 15 seconds wait
# If it fails again then it's 30 seconds, then 45,
# In any case, set a +/- 10% jitter on the wait (e.g 14, 28, 47, ...)
protection.attempt
# => :blocked
# this method reset blocked key
protection.reset
# => :ok
# this method returns ETA when account
# will be unblocked
protection.unlock_at
# => timestamp
# this method returns the time left before
# the account will be unblocked
protection.unlock_at
# => timestampAfter checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/jobteaser/fail_to_ban. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.