# Immunio Ruby Agent

## Installation

Add the private Immunio gem to your Gemfile:

```ruby
gem 'immunio'
```

Run Bundler to install the gem:

```sh
bundle install
```

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

```ruby
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.

```yaml
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:

```ruby
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](http://rack.github.io/):

```ruby
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](https://github.com/plataformatec/devise) or [Authlogic](https://github.com/binarylogic/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:

```ruby
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 1.9.3 and up
- Rails 3.2 to 4.2