Immunio Ruby Agent
Installation
Add the private Immunio Gemfury repo and the gem itself to your Gemfile:
gem 'immunio', source: 'https://[email protected]/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 via the IMMUNIO_KEY
and IMMUNIO_SECRET
environment variables.
Optionally, a configuration file can be provided in config/immunio.yml which will take precedence over the environment variables:
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.
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
Support
- Ruby 2.0 and up
- Rails 3.2 to 4.2
Building the gem
To build the pure Ruby gem:
$ rake gem
To build with bundled pre-compiled C extensions:
$ rake native gem
For cross-compilation, see https://github.com/luislavena/rake-compiler#cross-compilation---the-future-is-now.
Testing
To run tests (under Rails 4.2):
$ rake test
To run tests under Rails 3.2:
$ export RAILS_VERSION=3.2
$ bundle update rails
$ rake test