Cross-Site Request Forgery protection for Cuba applications.


This library adopts the Synchronizer Token pattern.

This scheme protects the application by including a token in the HTML forms of your application. This token is stored as a random string in the user's current session. When a request reaches the application, it verifies the received token with the token in the session. This scheme ensures that the user actually intended to submit the desired requests.

By default, GET and HEAD requests are not protected since they don't have side effects like writing to the database and don't leak sensitive information.


To enable Cuba::CSRF, do:

require "cuba"
require "cuba/csrf"


Cuba.define do
  on !csrf_safe? do

    res.status = 403
    res.write("Not Authorized")

Then, use the csrf_tag helper method to include the security token in your HTML forms:

<form action="/account/delete" method="post">
  {{ csrf_tag }}


BREACH is a security exploit against HTTPS when using HTTP compression (GZIP/DEFLATE). This means that if your page is served with HTTP compression enabled and reflects user input, an attacker can recover sensitive data from an HTTP response body (e.g. a CSRF token).

There are two effective ways to mitigate BREACH: disable HTTP compression or randomize secrets per request.

If it's possible, disable HTTP compression. In Nginx, you can use the gzip off directive.

By default, this plugin doesn't generate or mask CSRF tokens per request. This means that if you plan to use HTTP compression, your application might be vulnerable to BREACH. However, generation of new secrets per request can be done with:

Cuba.define do
  on !csrf_safe? do



We designed this library to fit our use case. We don't have HTTP compression enabled because we also have other sensitive information apart from the CSRF tokens that would require additional masking. Maybe we will add support for masking tokens per request in the future.

For more information about BREACH, see


$ gem install cuba-csrf