devise_sqreener 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8483e2152547f35ade4e0b7b592e87851a15804
-  data.tar.gz: 42ed8c93d34c07d2009831782306a5a4fa45a512
+  metadata.gz: fd8c549f4b58bc36ce9472751ee058c68c380770
+  data.tar.gz: e10015a600e3ccf712f6f6da8e8e4ad6fbe76f4a
 SHA512:
-  metadata.gz: 39e855247d68eff1ec23d0ddb00cd00821baaa702986aa79050a954234c3db48adb0646903ca1df155c71534f9d58c84a67578524a36f7263a4dc99f5db07f40
-  data.tar.gz: d5453a6319134d598a4bf50894aa20c32225f321ffad5d36b7da67ef47b42bf8a6b31eeb65c6f1e873c5216d6446d7d63c10458f87f4350919ed0b4b6005695b
+  metadata.gz: f6979035b284d536e6aa2f92625dbd64d7095f6517f73d754b34ea7d443cace06130fa73345275a1f4ba149ceb35c730b627ceea609b29aeac445932145010d8
+  data.tar.gz: cc2cf0503cc100fca46049a3ac7837dfcc16e6e8e104402dd93278c47d9c58b2352a8e71caebee9252a22efda9909b7599d5edc8bece946af7c1b34ba49efd3e

data/CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
-# Sqreen open source code of conduct
+# Sqreen Open Source Code of Conduct
 
 
 ## Introduction

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Sqreen
+Copyright (c) 2017 Société Sqreen
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,10 +1,19 @@
 # devise\_sqreener
 
-Add Sqreen API integration to Devise. Whenever a new user sign up or sign in its IP address and email addressed will be sqreened with security metadata. This plugin also provides the ability to block the said sign in/up using simple rules. Blocking people with disposable email, using TOR or geographically has never been easier. 
+Not everyone who signs up for your app wants to use your service. Wouldn’t it be nice if there was an easy way to automatically block abusers? This project adds the ability to block or flag potentially malicious users of your Rails app to the Devise user authentication module.
+
+Whenever a new user signs up or signs in, their IP address and email address are compared against Sqreen's extensive database of bad apples; you get back a chunk of actionable metadata on those addresses that can be used to set user policies. You can, for example:
+
+* Block users with a history of malicious abuse from signing up
+* Prevent users from signing in over TOR.
+* Discover whether someone is logging in from two distinct geographic locations at the same time.
+* Flag users signing up with disposable email addresses.
+
+Such fun!
 
 ## Installation
 
-Add this line to your application Gemfile:
+Of course, the best way to install is with RubyGems! Add this line to your application's Gemfile:
 
 ```ruby
 gem 'devise_sqreener'
@@ -15,106 +24,128 @@ and then execute
 $ bundle
 ```
 
-## Automatic Installation
+to download the latest version and install it.
 
-First if you want IP addresses to be sqreened (as it were) ensure your model use Devise `:trackable`.
+## Install devise_sqreener
 
-Add devise\_sqreener to any or you Devise models using the following generator:
+Let's assume your user model is called `User`.
+
+First we should note that `devise_sqreened` relies on the Devise `:trackable` strategy for tracking IP addresses. By default, `:trackable` is enabled, but if your use model doesn't include `:trackable`, and you want to enable the IP address filtering features, then you'll need to re-enable `:trackable`. Doing that is a bit beyond the scope of this tutorial, unfortunately. Anyway, the default Devise User model looks something like this, for reference purposes.
+
+```ruby
+class User < ActiveRecord::Base
+  # Include default devise modules. Others available are:
+  # :confirmable, :lockable, :timeoutable and :omniauthable
+  devise :database_authenticatable, :registerable,
+         :recoverable, :rememberable, :trackable, :validatable
+end
+```
+OK, so that out of the way, let's add `devise\_sqreener` to the `User` model using the following generator:
 
 ```bash
-$ rails generate devise_sqreener MODEL
+$ rails generate devise_sqreener User
 ```
 
-Replace `MODEL` with the class name you want to add devise\_sqreener. This will add the `:sqreenable` flag to your model's Devise modules. The generator will also create a migration file. Currently only ActiveRecord is supported. Then run:
+This will add the `:sqreenable` flag to your `User` model, and some new fields in the User table of your database. The generator will also create a migration file. Currently only ActiveRecord is supported.
+
+Let's get that migration knocked out, then? Run:
 
 ```bash
 $ rails db:migrate
 ```
 
-For the automatic sqreening to work you need to provide [your API token](https://my.sqreen.io) into you devise configuration (in `config/initializers/devise.rb`):
+## Get your API token
+
+For the automatic sqreening to work you need to provide [your Sqreen API token](https://my.sqreen.io) in your Devise configuration, `config/initializers/devise.rb`. You might need to create an account on Sqreen—and once you do you can choose between the 14-day free trial for the full product; if you just want to get straight to the API, however, create a new API Sandbox instead. The API Sandboxes are free forever, albeit rate-limited and with a limited number of requests per month. That will do for our purposes nicely.
+
+Anyway, we're not going to advocate for just leaving service credentials in your code, did you? Ha, of course not. No, we're going to pass it in as an environment variable. So add the following *_verbatim_* to the bottom of your Devise configuration.
+
 ```ruby
 Devise.setup do |config|
   #...
-  config.sqreen_api_token="TOKEN"
+  config.sqreen_api_token=ENV["SQREEN_API_TOKEN"]  # <- DO NOT PUT YOUR API TOKEN HERE!
   #...
 end
 ```
 
-## Manual Installation
-
-First if you want IP addresses to be sqreened (as it were) ensure your model use Devise `:trackable`.
-
-Add `:sqreenable` to the devise call in your model:
+And pass it in to your app's runtime environment with something like
 
-```ruby
-class User < ActiveRecord
-  devise :database_authenticable, :confirmable, :sqreenable
-end
 ```
-Add the necessary fields to your Devise model migration:
-
-```ruby
-class DeviseSqreenerAddToUser < ActiveRecord::Migration
-  def change
-    add_column :user, :sqreened_email, :text
-    # only if you use devise's :trackable
-    add_column :user, :current_sqreened_sign_in_ip, :text
-    # only if you use devise's :trackable
-    add_column :user, :last_sqreened_sign_in_ip, :text
-  end
-end
+export SQREEN_API_TOKEN="PASTE_YOUR_TOKEN_HERE"
 ```
-Then run:
 
-```bash
-$ rails db:migrate
-```
+There are lots of ways to get environment variables into your Rails app, of course—you should follow the practices used for your particular app if they aren't set in this way.
 
-For the automatic sqreening to work you need to provide [your API token](https://my.sqreen.io) into you devise configuration (in `config/initializers/devise.rb`):
-```ruby
-Devise.setup do |config|
-  #...
-  config.sqreen_api_token="TOKEN"
-  #...
-end
-```
 
-## Usage
+## Looking at security metadata
 
-Signups and Signins are automatically sqreened whenever needed. [Sqreened metada](https://www.sqreen.io/developers.html) are automatically added to your model as serialized fields.
+Sign-ups and sign-ins are automatically sqreened whenever needed. [Sqreened metada](https://www.sqreen.io/developers.html) are automatically added to your model as serialized fields.
 ![Activeadmin Screenshor](/doc/activeadmin.png)
 
-## Blocking signups or signins
+## Configuring your user Sqreening policy
+
+Policies are implemented as predicates in your Devise configuration, `config/initializers/devise.rb`. There are two predicates, one for signing up and one for signing in. The predicates can do really anything you like, including firing off notifications, or flagging the user in some way. But the most important thing is deciding whether to block the user from completing the sign-up or sign-in action.
+
+The arguments to the predicates are:
+* `email`: Current email sqreened metadata (a Hash or nil)
+* `ip`: Current ip address sqreened metadata (a Hash or nil)
+* `user`: The current instance of your MODEL class trying to sign in/up.
 
-Blocking sign up or sign in is as easy as adding a predicate in your devise configuration.
+The return value should be a boolean. If your predicate returns `true`, the action will be blocked. If your predicate returns `false`, the action will not be blocked.
+
+The `email` hash passed to the predicate has the following structure:
+
+* `email`: string The email address queried.
+* `risk_score`: number The assessed risk that this email address is being used by a malevolent actor. Values range from 0 to 100. Anything greater than 80 is really bad and should be dropped; anything greater than about 40 is worth flagging and keeping an eye on.
+* `is_email_harmful`: boolean Does the email address itself pose a direct security risk? E.g., does the email address contain embedded JavaScript?
+* `is_known_attacker`: boolean Was this email address used as part of a security attack?
+* `high_risk_security_events_count`: number The number of high-risk security events (e.g. SQL injection attacks) involving this email address.
+* `security_events_count`: number The number of all security events (both high-risk and low-risk) involving this email address.
+* `is_disposable`: boolean Does this email's domain belong to a known vendor of disposable, temporary, or anonymized email addresses?
+* `is_email_malformed`: boolean Is the email malformed according to RFC 5322?
+
+The `ip` hash passed to the predicate has the following structure:
+
+* `ip`: string The IP address queried.
+* `ip_version`: number The version of the IP address queried. Either 4 or 6.
+* `risk_score`: number The assessed risk that this IP address is being used by a malevolent actor. Values range from 0 to 100. Anything greater than 80 is really bad and should be dropped; anything greater than about 40 is worth flagging and keeping an eye on.
+* `is_known_attacker`: boolean Was this IP address used as part of a security attack?
+* `high_risk_security_events_count`: number The number of high-risk security events (e.g. SQL injection attacks) originating from this IP address.
+* `security_events_count`: number The number of all security events (both high-risk and low-risk) originating from this IP address.
+* `ip_geo`: object The geographical location associated with this IP address.
+* `ip_geo.latitude` number The latitude of the location.
+* `ip_geo.longitude `number The longitude of the location.
+* `ip_geo.country_code` string The ISO ALPHA-3 Code for the country that this location exists within.
+* `is_datacenter`: boolean Does this IP address belong to a known datacenter, such as AWS or Google Cloud?
+* `is_vpn`: boolean Does this IP address belong to a known VPN?
+* `is_proxy`: boolean Does this IP address belong to a known proxy server?
+* `is_tor`: boolean Is this IP address a known Tor exit point?
+
+Let's suppose that we want to block all sign-ups and sign-ins over TOR:
 
 ```ruby
 Devise.setup do |config|
   #...
   # Block signing in from TOR
   config.sqreen_block_sign_in =  -> (email, ip, user)  {ip && ip["is_tor"] }
-  # Block signing up with a disposable email address 
-  config.sqreen_block_sign_up =  -> (email, ip, user)  {email && email["is_disposable"] }
+  # Block signing up from TOR 
+  config.sqreen_block_sign_up =  -> (email, ip, user)  {ip && ip["is_tor"] }
   #...
 end
 ```
 
-The arguments always are:
-* `email`: Current email sqreened metadata (a Hash or nil)
-* `ip`: Current ip address sqreened metadata (a Hash or nil)
-* `user`: The current instance of your MODEL class trying to sign in/up.
-
-## Contributing to devise\_sqreener
- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
-* Fork the project.
-* Start a feature/bugfix branch.
-* Commit and push until you are happy with your contribution.
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+Or perhaps you just want to look at Sqreen's pre-calculated risk score for the email address to make this determination:
+```ruby
+Devise.setup do |config|
+  #...
+  # Block signing up with a risky email address 
+  config.sqreen_block_sign_up =  -> (email, ip, user)  {email && email["risk_score"] > 70 }
+  #...
+end
+```
 
-## Copyright
+The possibilities are...well, let's be honest, they're not exactly endless, but there is a great deal of flexibility in crafting these policies.
 
-Copyright (c) 2017 Sqreen. See LICENSE.txt for further details.
+## Let us know how it works for you
 
+So, that's about all there is to it! Having a problem? Have an idea for how we could improve this Devise plugin? [Open an issue](https://github.com/sqreen/devise_sqreener/issues/new), and let us know what we can do better. 

data/config/locales/en.yml

@@ -0,0 +1,7 @@
+en:
+  devise:
+    failure:
+      user:
+        forbidden: "Signing in was forbidden by current policy"
+    registrations:
+      forbidden: "Signing up was forbidden by current policy"

data/lib/devise_sqreener/model.rb

@@ -63,7 +63,7 @@ module Devise
         return false if oracle.blank? || !oracle.respond_to?(:call)
         if oracle.call(current_sqreened_email,
                        current_sqreened_ip_address, self)
-          errors[:base] = I18n.t(:forbidden, :scope => %i(devise registrations))
+          errors[:base] << I18n.t(:forbidden, :scope => %i(devise registrations))
           return true
         end
         false

data/lib/devise_sqreener/sqreen.rb

@@ -1,4 +1,6 @@
 require 'net/http'
+require 'devise_sqreener/version'
+
 module DeviseSqreener
   # sqreen an email of ip
   class Sqreen
@@ -28,9 +30,10 @@ module DeviseSqreener
 
     def sqreen(kind, value)
       uri = URI(format(BASE_URL, kind, value))
+      user_agent = "DeviseSqreener/#{DeviseSqreener::VERSION} #{Gem::Platform.local.os}/#{Gem::Platform.local.version} Rails/#{Rails::VERSION::STRING} Ruby/#{RUBY_VERSION}"
       response = Net::HTTP.start(uri.hostname, uri.port,
                                  :use_ssl => uri.scheme == 'https') do |http|
-        http.request_get(uri, 'x-api-key' => sqreen_api_token.to_s)
+        http.request_get(uri, 'x-api-key' => sqreen_api_token.to_s, 'User-Agent' => user_agent)
       end
 
       handle_response(kind, value, response)

data/lib/devise_sqreener/version.rb

@@ -1,3 +1,3 @@
 module DeviseSqreener
-  VERSION="0.1.0"
+  VERSION="0.1.1"
 end

data/lib/generators/active_record/devise_sqreener_generator.rb

@@ -6,7 +6,13 @@ module ActiveRecord
       source_root File.expand_path("../", __FILE__)
 
       def copy_devise_migration
-        migration_template "migration.rb", "db/migrate/devise_sqreener_add_to_#{table_name}.rb"
+        migration_template "migration.rb", "db/migrate/devise_sqreener_add_to_#{table_name}.rb", migration_version: migration_version
+      end
+
+      def migration_version
+        if Rails::VERSION::MAJOR >= 5
+          "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+        end
       end
     end
   end

data/lib/generators/active_record/migration.rb

@@ -1,4 +1,4 @@
-class DeviseSqreenerAddTo<%= table_name.camelize %> < ActiveRecord::Migration
+class DeviseSqreenerAddTo<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
   def change
     add_column :<%= table_name %>, :sqreened_email, :text
     if <%= class_name %>.devise_modules.include?(:trackable)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: devise_sqreener
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Benoit Larroque
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-01 00:00:00.000000000 Z
+date: 2017-06-05 00:00:00.000000000 Z
 dependencies: []
 description: Sqreen emails/ips that are seen by Devise through the Sqreen API, and
   block bad actors from signing up to your Rails app.
@@ -23,6 +23,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- config/locales/en.yml
 - lib/devise_sqreener.rb
 - lib/devise_sqreener/hook.rb
 - lib/devise_sqreener/model.rb
@@ -30,7 +31,7 @@ files:
 - lib/devise_sqreener/version.rb
 - lib/generators/active_record/devise_sqreener_generator.rb
 - lib/generators/active_record/migration.rb
-- lib/generators/devise_sqreener/devise_enricher_generator.rb
+- lib/generators/devise_sqreener/devise_sqreener_generator.rb
 homepage: https://github.com/sqreen/devise_sqreener
 licenses:
 - MIT