castle / castle-ruby

Ruby gem for Castle

Ruby SDK for Castle

Castle analyzes user behavior in web and mobile apps to stop fraud before it happens.

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: 1000 milliseconds)
  config.request_timeout = 1500

  # Base Castle API url
  # config.base_url = "https://api.castle.io/v1"

  # Logger (need to respond to info method) - logs Castle API requests and responses
  # config.logger = Logger.new(STDOUT)

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

  # Denylisted headers take precedence over allowlisted elements
  # We always denylist Cookie and Authentication headers. If you use any other headers that
  # might contain sensitive information, you should denylist them.
  config.denylisted = ['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.

  # Sometimes, Cloud providers do not use consistent IP addresses to proxy requests.
  # In this case, the client IP is usually preserved in a custom header. Example:
  # Cloudflare preserves the client request in the 'Cf-Connecting-Ip' header.
  # It would be used like so: config.ip_headers=['Cf-Connecting-Ip']
  config.ip_headers = []

  # If the specified header or X-Forwarded-For default contains a proxy chain with public IP addresses,
  # then you must choose only one of the following (but not both):
  # 1. The trusted_proxies value must match the known proxy IPs. This option is preferable if the IP is static.
  # 2. The trusted_proxy_depth value must be set to the number of known trusted proxies in the chain (see below).
  # This option is preferable if the IPs are ephemeral, but the depth is consistent.

  # 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 the trusted_proxies setting
  config.trusted_proxies = []

  # or by providing number of trusted proxies used in the chain
  config.trusted_proxy_depth = 0

  # note that you must pick one approach over the other.

  # If there is no possibility to define options above and there is no other header that holds the client IP,
  # then you may set trust_proxy_chain = true to trust all of the proxy IPs in X-Forwarded-For
  config.trust_proxy_chain = false
  # *Warning*: this mode is highly promiscuous and could lead to wrongly trusting a spoofed IP if the request passes through a malicious proxy

  # *Note: the default list of proxies that are always marked as "trusted" can be found in: Castle::Configuration::TRUSTED_PROXIES
end

Multi-environment configuration

It is also possible to define multiple configs within one application.

# Initialize new instance of Castle::Configuration
config =
  Castle::Configuration.new.tap do |c|
    # and set any attribute
    c.api_secret = 'YOUR_API_SECRET'
  end

After a successful setup, you can pass the config to any API command as follows:

::Castle::API::GetDevice.call(device_token: device_token, config: config)

Usage

See documentation for how to use this SDK with the Castle APIs

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.

castle-ruby's Issues

Remove confusing `active`

I'm guessing in this test case @bartes wanted to test that unrecognized attributes don't get send in the payload. Since we do have the key active this test is getting confusing to read

castle-ruby/spec/lib/castle/commands/authenticate_spec.rb

Line 14 in 15c2499

active: 'ok',

Handle symbol header

Clearance sends a symbol header (:clearance) instead of string, which crashes the parsing.

[2] pry(#<Castle::HeaderFormatter>)>

From: /Users/brissmyr/.rvm/gems/ruby-2.2.4/gems/castle-rb-3.0.0/lib/castle/header_formatter.rb @ line 7 Castle::HeaderFormatter#call:

    5: def call(header)
    6:   binding.pry
 => 7:   header.gsub(/^HTTP(?:_|-)/i, '').split(/_|-/).map(&:capitalize).join('-')
    8: end

[1] pry(#<Castle::HeaderFormatter>)> header
=> "action_dispatch.request.content_type"
[2] pry(#<Castle::HeaderFormatter>)>

From: /Users/brissmyr/.rvm/gems/ruby-2.2.4/gems/castle-rb-3.0.0/lib/castle/header_formatter.rb @ line 7 Castle::HeaderFormatter#call:

    5: def call(header)
    6:   binding.pry
 => 7:   header.gsub(/^HTTP(?:_|-)/i, '').split(/_|-/).map(&:capitalize).join('-')
    8: end

[1] pry(#<Castle::HeaderFormatter>)> header
=> :clearance
[2] pry(#<Castle::HeaderFormatter>)>
Completed 500 Internal Server Error in 179877ms

NoMethodError (undefined method `gsub' for :clearance:Symbol):
  app/controllers/sessions_controller.rb:11:in `create'

Authenticate/Track: active should be part of context and of type boolean

castle-ruby/spec/lib/castle/commands/authenticate_spec.rb

Line 14 in 15c2499

active: 'ok',

Same goes for track endpoint

Track: Add test for additional traits attribute

castle-ruby/spec/lib/castle/commands/track_spec.rb

Line 11 in 15c2499

command_builder.build(event: 'approve', user_id: '1234', something: '1234',

try request.remote_ip instead request.ip if possible

if framework responds to remote_ip we should use it
in Castle::Extractors::IP

Too many dependencies

Woha, this was a worm can of dependencies! I don't want to pollute my project with activesupport etc. Would prefer if you minimized or didn't use any external dependencies, just use Net::HTTP, even if it can a be a pain, but it'll be a lot less pain for your customers. Writing my own custom integration now..

Add support for /approve and /report APIs

Our new APIs allow Admins to directly approve and report a device with a device token, not need to collect the request context. However, these APIs, included the Device fetching API, are not available via our SDK.

Can we add methods to the SDK that can handle these three APIs:
GET https://api.castle.io/v1/users/{user-id}/devices
PUT https://api.castle.io/v1/devices/{device_token}/approve
PUT https://api.castle.io/v1/devices/{device_token}/report

See more on each API here: https://castle.io/docs/device_management_tool

Remove tracked? from impersonate as it is not applicable

See: https://github.com/castle/castle-ruby/blob/master/lib/castle/client.rb#L72
Not applicable for castle.impersonate.

Rails 5 Rc1 Support

I have held off any attempts to upgrade to Rails 5 until I saw a release candidate. Now that the time has come, I am getting dependency conflicts mainly caused by the Her gem which this gem depends on:

-> bundle update rails

In Gemfile:
    devise_castle was resolved to 1.3.5, which depends on
      castle-rb (~> 1.2.13) was resolved to 1.2.13, which depends on
        her (~> 0.7) was resolved to 0.8.1, which depends on
          activemodel (<= 4.3.0, >= 3.0.0)

The Her gem has not made any progress on supporting Rails 5:

• remi/her#392
• remi/her#399

What are your thoughts? I am using the Devise_Castle gem and would imagine that other users will eventually want to upgrade to Rails 5 as well.

Track: doesn't pass on traits option

castle-ruby/lib/castle/commands/track.rb

Line 18 in 15c2499

request_args[:properties] = options[:properties] if options.key?(:properties)

Add a success? method on Castle::Response

Add a success? method returning true on any 2XX statuses. Helpful for castle.impersonate to check for success

GDPR/Privacy API for data access/purge requests

Hello, we're looking into some better integration with the privacy APIs, i.e. data access and delete requests, as described in https://docs.castle.io/docs/gdpr-compliance.

I could not find anything about those APIs in the library / source code on a brief search. Is there any support planned in the library for those APIs as well?

For the time being we might just trigger the requests to the specified endpoints ourselves, but it'd be nice to have out of the box support within the library. Thanks.

Prioritize assigned value for settings over ENV if assigned

https://github.com/castle/castle-ruby/blob/master/lib/castle/configuration.rb#L41

All endpoints: options should be with indifferent access

I should be able to use both symbols and string as key

castle-ruby/lib/castle/commands/identify.rb

Line 11 in 15c2499

user_id = options[:user_id]

Identify: active mode

The active flag should not be a string but a boolean value, also it should be sent as part of context

castle-ruby/spec/lib/castle/commands/identify_spec.rb

Line 13 in 15c2499

active: 'ok',

`X-Castle-Request-Token` missing from `DEFAULT_ALLOWLIST`

In line with the new API endpoints, shouldn't Castle ::Configuration::DEFAULT_ALLOWLIST contain the X-Castle-Request-Token header, since the mobile SDK docs mention it?

Context Merger: Should treat string and symbol keys as synonyms

castle-ruby/lib/castle/utils/merger.rb

Line 7 in 15c2499

second.each do |name, value|

Identify: unset active mode

Also add a test that the active key get's not send if not provided

castle-ruby/spec/lib/castle/commands/identify_spec.rb

Line 13 in 15c2499

active: 'ok',

Feature Request: Add support for multiple API environments

Consider the following:
Company A has a monolithic code base that serves more than one type of users that operate on the same data layer.
E.g.

• Admins
• Researchers
• Customers
  They want to implement account takeover prevention, but they want to serve each different type of user a different flow.

It would be great if castle could support multiple API environments. So that Admin events could go to one environment and Researchers could be sent to another.

make CF_CONNECTING_IP fetching configurable in config