immunio

Immunio Ruby Agent

Support

• Ruby 1.9.3 and up
• Rails 3.2 to 4.2

Compilation

To compile the agent and its dependencies:

bundle exec rake build

Installation

Add the private Immunio gem to your Gemfile:

gem 'immunio'

Run Bundler to install the gem:

bundle install

Note that if your application is not using Bundler, require the Immunio package:

require 'immunio'

Configuration

The agent key and secret can be configured in a configuration file at config/immunio.yml.

Optionally, the agent key and secret can be set using the IMMUNIO_KEY and IMMUNIO_SECRET environment variables, which will take precedence.

key: "my-key"
secret: "my-secret"

The Immunio agent is enabled by default in all rails environments. It can be enabled in production only in your Gemfile:

gem immunio', group: :production

You can also modify the secret and key for different environments to report to different apps, or you can disable the agent by setting agent_enabled: false in the configuration or IMMUNIO_AGENT_ENABLED=0 in the environment.

Unicorn configuration

In order for the agent to function correctly in a pre-forked environment, use the Immunio.reset! method. For example, in your config/unicorn.rb:

after_fork do |server, worker|
  Signal.trap 'TERM' do
    puts 'Unicorn worker intercepting TERM and doing nothing. Wait for master to send QUIT'
  end

  defined?(ActiveRecord::Base) and ActiveRecord::Base.establish_connection

  Immunio.reset!
end

Handling blocked requests

By default, Immunio will return a plain text 403 Forbidden response whenever it blocks a request for security reasons.

To customize this behavior, use the Immunio.blocked_app option, which should be a valid Rack application:

Immunio.blocked_app = -> env do
  [
    403,
    { 'Content-Type' => 'text/html' },
    ActionController::DataStreaming::FileBody.new('public/403.html')
  ]
end

Authentication API

If you're using Devise or Authlogic, Immunio will automatically hook into your authentication system to protect you against attacks.

If you're not using one of the above frameworks, you will need to manually tell Immunio when authentication occurs. Use the following methods to do so.

• After a user logs in: Immunio.login user
• After a failed login attempt: Immunio.failed_login
• After a user logs out: Immunio.logout
• After the current user is changed (or set): Immunio.set_user
• After a user requests a password reset: Immunio.password_reset
• After a failed requests for resetting a password: Immunio.failed_password_reset

Note: Immunio.set_user should be called for every request where user data is available, not just when authentication mechanisms are used.

These methods take an options hash with the following information:

• user_id: String or Number
• username: String
• email: String
• user_record: ActiveRecord object for the user
• reason: String (for failures)

Here's an example:

class ApplicationController
  def current_user=(user)
    Immunio.set_user user_record: user
    # Store user ...
  end
end

class SessionsController < ApplicationController
  # POST /login
  def create
    if user = User.authenticate(params[:user])
      Immunio.login user_record: user
      self.current_user = user
      # ...
    else
      Immunio.failed_login username: params[:user]
      # ...
    end
  end

  # DELETE /logout
  def destroy
    Immunio.logout user_record: current_user
    # ...
  end
end