Skip to main content

​
Get started in three steps

Get your protection ready in 3 easy steps.

​
Step 1: Install the gem

Add this line to your application’s Gemfile:
gem "black_lab"
Then run:
bundle install
Add BlackLab to your middleware stack. For example, in config.ru:
require "black_lab"

use BlackLab::Middleware
run Rails.application

​
Step 2: Configure BlackLab

Create a file at config/initializers/black_lab.rb and configure it:
BlackLab.configure do |config|
  config.block_message = "Blocked by BlackLab WAF"
  config.block_duration = 3600 # seconds to block an IP/user in cache
  config.block_callback = ->(request) { puts "Blocked #{request.ip}" }
  config.callback_threshold = 15 # points threshold to trigger callback
  config.cache_store = Rails.cache # or any object responding to #write/#read
  config.plugins = [
    BlackLab::Plugins::SqliPlugin.new(weight: 3),
    BlackLab::Plugins::XssPlugin.new(weight: 3),
    BlackLab::Plugins::PathTraversalPlugin.new(weight: 3),
    # BlackLab::Plugins::LfiPlugin.new(weight: 1),
    # BlackLab::Plugins::RfiPlugin.new(weight: 2)
  ]
end
Only enable the plugins you need — keep it lightweight!
You can tweak:
  • block_message → What users see when blocked
  • block_duration → How long to block IPs
  • plugins → Choose detection plugins (SQLi, XSS, Path traversal, etc.)
  • callback_threshold → How many points until an IP is blocked
Start with defaults, then tighten rules based on your app’s needs.

​
Step 3: Go live

  1. Commit your changes.
  2. Deploy your app as usual.
  3. BlackLab WAF will automatically protect your endpoints against SQLi, XSS, and more!

​
Next steps

Now that BlackLab WAF is running, explore these key features:

Add more plugins

Extend BlackLab with additional security plugins.

Customize block actions

Run custom logic when a request is blocked (e.g., alerting).

Tuning thresholds

Balance security and usability by adjusting thresholds.

Monitoring & logs

Learn how to monitor and analyze blocked requests.
Need help? Create an issue in our Github repository.