Ruby SDK for Castle

Build Status Coverage Status Gem Version

Castle analyzes device, location, and interaction patterns in your web and mobile apps and lets you stop account takeover attacks in real-time..

Installation

Add the castle-rb gem to your Gemfile

gem 'castle-rb'

Configuration

Framework configuration

Load and configure the library with your Castle API secret in an initializer or similar.

Castle.api_secret = 'YOUR_API_SECRET'

A Castle client instance will be made available as castle in your

  • Rails controllers when you add require 'castle/support/rails'

  • Padrino controllers when you add require 'castle/support/padrino'

  • Sinatra app when you add require 'castle/support/sinatra' (and additionally explicitly add register Sinatra::Castle to your Sinatra::Base class if you have a modular application)

require 'castle/support/sinatra'

class ApplicationController < Sinatra::Base
  register Sinatra::Castle
end
  • Hanami when you add require 'castle/support/hanami' and include Castle::Hanami to your Hanami application
require 'castle/support/hanami'

module Web
  class Application < Hanami::Application
    include Castle::Hanami
  end
end

Client configuration

Castle.configure do |config|
  # Same as setting it through Castle.api_secret
  config.api_secret = 'secret'

  # For authenticate method you can set failover strategies: allow(default), deny, challenge, throw
  config.failover_strategy = :deny

  # Castle::RequestError is raised when timing out in milliseconds (default: 500 milliseconds)
  config.request_timeout = 2000

  # Whitelisted and Blacklisted headers are case insensitive and allow to use _ and - as a separator, http prefixes are removed
  # Whitelisted headers
  # By default, the SDK sends all HTTP headers, except for Cookie and Authorization.
  # If you decide to use a whitelist, the SDK will:
  # - always send the User-Agent header
  # - send scrubbed values of non-whitelisted headers
  # - send proper values of whitelisted headers.
  # @example
  #   config.whitelisted = ['X_HEADER']
  #   # will send { 'User-Agent' => 'Chrome', 'X_HEADER' => 'proper value', 'Any-Other-Header' => true }
  #
  # We highly suggest using blacklist instead of whitelist, so that Castle can use as many data points
  # as possible to secure your users. If you want to use the whitelist, this is the minimal
  # amount of headers we recommend:
  config.whitelisted = Castle::Configuration::DEFAULT_WHITELIST

  # Blacklisted headers take precedence over whitelisted elements
  # We always blacklist Cookie and Authentication headers. If you use any other headers that
  # might contain sensitive information, you should blacklist them.
  config.blacklisted = ['HTTP-X-header']

  # Castle needs the original IP of the client, not the IP of your proxy or load balancer.
  # The SDK will only trust the proxy chain as defined in the configuration.
  # We try to fetch the client IP based on X-Forwarded-For or Remote-Addr headers in that order,
  # but sometimes the client IP may be stored in a different header or order.
  # The SDK can be configured to look for the client IP address in headers that you specify.
  # If the specified header or X-Forwarded-For default contains a proxy chain with public IP addresses,
  # then one of the following must be set
  # 1. The trusted_proxies value must match the known proxy IP's
  # 2. The trusted_proxy_depth value must be set to the number of known trusted proxies in the chain (see below)
  configuration.ip_headers = []

  # Additionally to make X-Forwarded-For and other headers work better discovering client ip address,
  # and not the address of a reverse proxy server, you can define trusted proxies
  # which will help to fetch proper ip from those headers

  # In order to extract the client IP of the X-Forwarded-For header
  # and not the address of a reverse proxy server, you must define all trusted public proxies
  # you can achieve this by listing all the proxies ip defined by string or regular expressions
  # in trusted_proxies setting
  configuration.trusted_proxies = []
  # or by providing number of trusted proxies used in the chain
  configuration.trusted_proxy_depth = 0

  # If there is no possibility to define options above and there is no other header which can have client ip
  # then you may set trust_proxy_chain = true to trust all of the proxy IP's in X-Forwarded-For
  configuration.trust_proxy_chain = false

  # *Note: default list of proxies which is always marked as trusted: Castle::Configuration::TRUSTED_PROXIES
end

Event Context

The client will automatically configure the context for each request.

Overriding Default Context Properties

If you need to modify the event context properties or if you desire to add additional properties such as user traits to the context, you can pass the properties in as options to the method of interest. An example:

request_context = ::Castle::Client.to_context(request)
track_options = ::Castle::Client.to_options({
  event: ::Castle::Events::LOGIN_SUCCEEDED,
  user_id: user.id,
  properties: {
    key: 'value'
  },
  user_traits: {
    key: 'value'
  }
})

Tracking

Here is a simple example of a track event.

begin
  castle.track(
    event: ::Castle::Events::LOGIN_SUCCEEDED,
    user_id: user.id
  )
rescue Castle::Error => e
  puts e.message
end

Signature

Castle::SecureMode.signature(user_id) will create a signed user_id.

Async tracking

By default Castle sends requests synchronously. To eg. use Sidekiq to send requests in a background worker you can pass data to the worker:

castle_tracking_worker.rb

class CastleTrackingWorker
  include Sidekiq::Worker

  def perform(context, track_options = {})
    client = ::Castle::Client.new(context)
    client.track(track_options)
  end
end

tracking_controller.rb

request_context = ::Castle::Client.to_context(request)
track_options = ::Castle::Client.to_options({
  event: ::Castle::Events::LOGIN_SUCCEEDED,
  user_id: user.id,
  properties: {
    key: 'value'
  },
  user_traits: {
    key: 'value'
  }
})
CastleTrackingWorker.perform_async(request_context, track_options)

Events

List of Recognized Events can be found here or in the docs

Impersonation mode

https://castle.io/docs/impersonation_mode

Exceptions

Castle::Error will be thrown if the Castle API returns a 400 or a 500 level HTTP response. You can also choose to catch a more finegrained error.

Documentation

Official Castle docs