> ## Documentation Index
> Fetch the complete documentation index at: https://blacklab.windmotion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install BlackLab WAF fast and easy

## Get started in three steps

Get your protection ready in 3 easy steps.

***

### Step 1: Install the gem

<AccordionGroup>
  <Accordion icon="copy" title="Install via the Gemfile">
    Add this line to your application's **Gemfile**:

    ```ruby theme={null}
    gem "black_lab"
    ```

    Then run:

    ```bash theme={null}
    bundle install
    ```
  </Accordion>

  <Accordion icon="rectangle-terminal" title="Require in your Rack/Rails app">
    Add BlackLab to your **middleware stack**. For example, in `config.ru`:

    ```ruby theme={null}
    require "black_lab"

    use BlackLab::Middleware
    run Rails.application
    ```
  </Accordion>
</AccordionGroup>

***

### Step 2: Configure BlackLab

<AccordionGroup>
  <Accordion icon="gear" title="Create an initializer">
    Create a file at `config/initializers/black_lab.rb` and configure it:

    ```ruby theme={null}
    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
    ```

    <Tip>
      Only enable the plugins you need — keep it lightweight!
    </Tip>
  </Accordion>

  <Accordion icon="palette" title="Customize behavior">
    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

    <Tip>
      Start with defaults, then tighten rules based on your app’s needs.
    </Tip>
  </Accordion>
</AccordionGroup>

***

### Step 3: Go live

<Accordion icon="rocket" title="Deploy with protection">
  1. Commit your changes.
  2. Deploy your app as usual.
  3. BlackLab WAF will automatically protect your endpoints against SQLi, XSS, and more!
</Accordion>

***

## Next steps

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

<CardGroup cols={2}>
  <Card title="Add more plugins" icon="shield" href="/plugins/overview">
    Extend BlackLab with additional security plugins.
  </Card>

  <Card title="Customize block actions" icon="code" href="/guides/block-callbacks">
    Run custom logic when a request is blocked (e.g., alerting).
  </Card>

  <Card title="Tuning thresholds" icon="sliders" href="/guides/tuning">
    Balance security and usability by adjusting thresholds.
  </Card>

  <Card title="Monitoring & logs" icon="file-text" href="/guides/logging">
    Learn how to monitor and analyze blocked requests.
  </Card>
</CardGroup>

<Note>
  **Need help?** Create an issue in our [Github repository](https://github.com/windmotion-io/black-lab/issues).
</Note>