authtrail 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ca58a6ac201b761a2cf30bed995135a44690ac7616770f9f1d2e74c45e23080
-  data.tar.gz: 3ab3c476d2b75e1697a0a1e08cdc6e0356c07e266b1839c74eea1c1c4d818023
+  metadata.gz: fc8ae231bde9d10834ea6a7fa2fb0cd50a12e351ba2296abb15b743975fad197
+  data.tar.gz: c52435deca659cd45a8ed647daccaf8b19e9d7d92374db06be69c63cbcc6b1e3
 SHA512:
-  metadata.gz: b7a769b8963f67a9cc0d37e194dd1e9b936271cfbc7c88ee0f1fe72252926fc6184c01bd9abad0420231507bc99e54fc22b85916c9a0cb3cc1611c402e3436f3
-  data.tar.gz: 5cad0685a4773c31ef10f78380c9e64b4ca56828f9ba9eae8b4471a1b7cdd5d827b6f33c27a4963926003b199bbffad3971c98269e87c7cb850db33ad342a352
+  metadata.gz: 8531404800e70b37e0f6bca1fd79f690bfe36434efe768c926fa7248f1f50d803de16aa3324ecaa656c142940e69de35f80d2c5f4699f5408fbd92f41e5c24b0
+  data.tar.gz: bd4daf16b7ad615477cdbf0592f45d789fa7b6b0ba759c417f6e4e89888e2b4014dae6a2b48333a9863b6b1b0670082f9b9808da327dc790f2e0f173d6d63714

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.4.0 (2021-08-13)
+
+- Disabled geocoding by default
+- Made the `geocoder` gem an optional dependency
+- Added `country_code` to geocoding
+
+## 0.3.1 (2021-03-03)
+
+- Added `--lockbox` option to install generator
+
+## 0.3.0 (2021-03-01)
+
+- Disabled geocoding by default for new installations
+- Raise an exception instead of logging when auditing fails
+- Removed support for Rails < 5.2 and Ruby < 2.6
+
+## 0.2.2 (2020-11-21)
+
+- Added `transform_method` option
+
 ## 0.2.1 (2020-08-17)
 
 - Added `job_queue` option

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017-2020 Andrew Kane
+Copyright (c) 2017-2021 Andrew Kane
 
 MIT License
 

data/README.md

@@ -2,9 +2,11 @@
 
 Track Devise login activity
 
+**AuthTrail 0.4.0 was recently released** - see [how to upgrade](#upgrading)
+
 :tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
 
-[![Build Status](https://travis-ci.org/ankane/authtrail.svg?branch=master)](https://travis-ci.org/ankane/authtrail)
+[![Build Status](https://github.com/ankane/authtrail/workflows/build/badge.svg?branch=master)](https://github.com/ankane/authtrail/actions)
 
 ## Installation
 
@@ -14,13 +16,22 @@ Add this line to your application’s Gemfile:
 gem 'authtrail'
 ```
 
-And run:
+To encrypt email and IP addresses, install [Lockbox](https://github.com/ankane/lockbox) and [Blind Index](https://github.com/ankane/blind_index) and run:
+
+```sh
+rails generate authtrail:install --lockbox
+rails db:migrate
+```
+
+If you prefer not to encrypt data, run:
 
 ```sh
 rails generate authtrail:install
 rails db:migrate
 ```
 
+To enable geocoding, see the [Geocoding section](#geocoding).
+
 ## How It Works
 
 A `LoginActivity` record is created every time a user tries to login. You can then use this information to detect suspicious behavior. Data includes:
@@ -42,15 +53,31 @@ A `LoginActivity` record is created every time a user tries to login. You can th
 Exclude certain attempts from tracking - useful if you run acceptance tests
 
 ```ruby
-AuthTrail.exclude_method = lambda do |info|
-  info[:identity] == "capybara@example.org"
+AuthTrail.exclude_method = lambda do |data|
+  data[:identity] == "capybara@example.org"
+end
+```
+
+Add or modify data - also add new fields to the `login_activities` table if needed
+
+```ruby
+AuthTrail.transform_method = lambda do |data, request|
+  data[:request_id] = request.request_id
+end
+```
+
+Store the user on failed attempts
+
+```ruby
+AuthTrail.transform_method = lambda do |data, request|
+  data[:user] ||= User.find_by(email: data[:identity])
 end
 ```
 
 Write data somewhere other than the `login_activities` table
 
 ```ruby
-AuthTrail.track_method = lambda do |info|
+AuthTrail.track_method = lambda do |data|
   # code
 end
 ```
@@ -79,50 +106,82 @@ The `LoginActivity` model uses a [polymorphic association](https://guides.rubyon
 
 ## Geocoding
 
-IP geocoding is performed in a background job so it doesn’t slow down web requests. You can disable it entirely with:
+AuthTrail uses [Geocoder](https://github.com/alexreisner/geocoder) for geocoding. We recommend configuring [local geocoding](#local-geocoding) or [load balancer geocoding](#load-balancer-geocoding) so IP addresses are not sent to a 3rd party service. If you do use a 3rd party service and adhere to GDPR, be sure to add it to your subprocessor list.
+
+To enable geocoding, add this line to your application’s Gemfile:
 
 ```ruby
-AuthTrail.geocode = false
+gem 'geocoder'
 ```
 
-Set job queue for geocoding
+And update `config/initializers/authtrail.rb`:
 
 ```ruby
-AuthTrail.job_queue = :low_priority
+AuthTrail.geocode = true
 ```
 
-### Geocoding Performance
+Geocoding is performed in a background job so it doesn’t slow down web requests. Set the job queue with:
+
+```ruby
+AuthTrail.job_queue = :low_priority
+```
 
-To avoid calls to a remote API, download the [GeoLite2 City database](https://dev.maxmind.com/geoip/geoip2/geolite2/) and configure Geocoder to use it.
+### Local Geocoding
 
-Add this line to your application’s Gemfile:
+For privacy and performance, we recommend geocoding locally. Add this line to your application’s Gemfile:
 
 ```ruby
 gem 'maxminddb'
 ```
 
-And create an initializer at `config/initializers/geocoder.rb` with:
+For city-level geocoding, download the [GeoLite2 City database](https://dev.maxmind.com/geoip/geoip2/geolite2/) and create `config/initializers/geocoder.rb` with:
 
 ```ruby
 Geocoder.configure(
   ip_lookup: :geoip2,
   geoip2: {
-    file: Rails.root.join("lib", "GeoLite2-City.mmdb")
+    file: "path/to/GeoLite2-City.mmdb"
+  }
+)
+```
+
+For country-level geocoding, install the `geoip-database` package. It’s preinstalled on Heroku. For Ubuntu, use:
+
+```sh
+sudo apt-get install geoip-database
+```
+
+And create `config/initializers/geocoder.rb` with:
+
+```ruby
+Geocoder.configure(
+  ip_lookup: :maxmind_local,
+  maxmind_local: {
+    file: "/usr/share/GeoIP/GeoIP.dat",
+    package: :country
   }
 )
 ```
 
-## Data Protection
+### Load Balancer Geocoding
 
-Protect the privacy of your users by encrypting fields that contain personal data, such as `identity` and `ip`. [Lockbox](https://github.com/ankane/lockbox) is great for this. Use [Blind Index](https://github.com/ankane/blind_index) so you can still query the fields.
+Some load balancers can add geocoding information to request headers.
+
+- [nginx](https://nginx.org/en/docs/http/ngx_http_geoip_module.html)
+- [Google Cloud](https://cloud.google.com/load-balancing/docs/custom-headers)
+- [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/200168236-Configuring-Cloudflare-IP-Geolocation)
 
 ```ruby
-class LoginActivity < ApplicationRecord
-  encrypts :identity, :ip
-  blind_index :identity, :ip
+AuthTrail.geocode = false
+AuthTrail.transform_method = lambda do |data, request|
+  data[:country] = request.headers["<country-header>"]
+  data[:region] = request.headers["<region-header>"]
+  data[:city] = request.headers["<city-header>"]
 end
 ```
 
+Check out [this example](https://github.com/ankane/authtrail/issues/40)
+
 ## Other Notes
 
 We recommend using this in addition to Devise’s `Lockable` module and [Rack::Attack](https://github.com/kickstarter/rack-attack).
@@ -131,6 +190,18 @@ Check out [Hardening Devise](https://ankane.org/hardening-devise) and [Secure Ra
 
 ## Upgrading
 
+### 0.4.0
+
+There are two notable changes to geocoding:
+
+1. Geocoding is now disabled by default (this was already the case for new installations with 0.3.0+). Check out the instructions for [how to enable it](#geocoding) (you may need to create `config/initializers/authtrail.rb`).
+
+2. The `geocoder` gem is now an optional dependency. To use geocoding, add it to your Gemfile:
+
+  ```ruby
+  gem 'geocoder'
+  ```
+
 ### 0.2.0
 
 To store latitude and longitude, create a migration with:

data/app/jobs/auth_trail/geocode_job.rb

@@ -8,6 +8,9 @@ module AuthTrail
       result =
         begin
           Geocoder.search(login_activity.ip).first
+        rescue NameError
+          # geocoder gem not installed
+          raise
         rescue => e
           Rails.logger.info "Geocode failed: #{e.message}"
           nil
@@ -18,6 +21,7 @@ module AuthTrail
           city: result.try(:city),
           region: result.try(:state),
           country: result.try(:country),
+          country_code: result.try(:country_code),
           latitude: result.try(:latitude),
           longitude: result.try(:longitude)
         }

data/lib/auth_trail/manager.rb

@@ -2,34 +2,29 @@ module AuthTrail
   module Manager
     class << self
       def after_set_user(user, auth, opts)
-        # do not raise an exception for tracking
-        AuthTrail.safely do
-          request = ActionDispatch::Request.new(auth.env)
+        request = ActionDispatch::Request.new(auth.env)
 
-          AuthTrail.track(
-            strategy: detect_strategy(auth),
-            scope: opts[:scope].to_s,
-            identity: AuthTrail.identity_method.call(request, opts, user),
-            success: true,
-            request: request,
-            user: user
-          )
-        end
+        AuthTrail.track(
+          strategy: detect_strategy(auth),
+          scope: opts[:scope].to_s,
+          identity: AuthTrail.identity_method.call(request, opts, user),
+          success: true,
+          request: request,
+          user: user
+        )
       end
 
       def before_failure(env, opts)
-        AuthTrail.safely do
-          request = ActionDispatch::Request.new(env)
+        request = ActionDispatch::Request.new(env)
 
-          AuthTrail.track(
-            strategy: detect_strategy(env["warden"]),
-            scope: opts[:scope].to_s,
-            identity: AuthTrail.identity_method.call(request, opts, nil),
-            success: false,
-            request: request,
-            failure_reason: opts[:message].to_s
-          )
-        end
+        AuthTrail.track(
+          strategy: detect_strategy(env["warden"]),
+          scope: opts[:scope].to_s,
+          identity: AuthTrail.identity_method.call(request, opts, nil),
+          success: false,
+          request: request,
+          failure_reason: opts[:message].to_s
+        )
       end
 
       private

data/lib/auth_trail/version.rb

@@ -1,3 +1,3 @@
 module AuthTrail
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end

data/lib/authtrail.rb

@@ -1,5 +1,4 @@
 # dependencies
-require "geocoder"
 require "warden"
 
 # modules
@@ -9,9 +8,9 @@ require "auth_trail/version"
 
 module AuthTrail
   class << self
-    attr_accessor :exclude_method, :geocode, :track_method, :identity_method, :job_queue
+    attr_accessor :exclude_method, :geocode, :track_method, :identity_method, :job_queue, :transform_method
   end
-  self.geocode = true
+  self.geocode = false
   self.identity_method = lambda do |request, opts, user|
     if user
       user.try(:email)
@@ -22,7 +21,7 @@ module AuthTrail
   end
 
   def self.track(strategy:, scope:, identity:, success:, request:, user: nil, failure_reason: nil)
-    info = {
+    data = {
       strategy: strategy,
       scope: scope,
       identity: identity,
@@ -35,18 +34,22 @@ module AuthTrail
     }
 
     if request.params[:controller]
-      info[:context] = "#{request.params[:controller]}##{request.params[:action]}"
+      data[:context] = "#{request.params[:controller]}##{request.params[:action]}"
     end
 
+    # add request data before exclude_method since exclude_method doesn't have access to request
+    # could also add 2nd argument to exclude_method when arity > 1
+    AuthTrail.transform_method.call(data, request) if AuthTrail.transform_method
+
     # if exclude_method throws an exception, default to not excluding
-    exclude = AuthTrail.exclude_method && AuthTrail.safely(default: false) { AuthTrail.exclude_method.call(info) }
+    exclude = AuthTrail.exclude_method && AuthTrail.safely(default: false) { AuthTrail.exclude_method.call(data) }
 
     unless exclude
       if AuthTrail.track_method
-        AuthTrail.track_method.call(info)
+        AuthTrail.track_method.call(data)
       else
         login_activity = LoginActivity.new
-        info.each do |k, v|
+        data.each do |k, v|
           login_activity.try("#{k}=", v)
         end
         login_activity.save!

data/lib/generators/authtrail/install_generator.rb

@@ -6,17 +6,47 @@ module Authtrail
       include ActiveRecord::Generators::Migration
       source_root File.join(__dir__, "templates")
 
+      class_option :lockbox, type: :boolean
+
       def copy_migration
         migration_template "login_activities_migration.rb", "db/migrate/create_login_activities.rb", migration_version: migration_version
       end
 
+      def copy_templates
+        template "initializer.rb", "config/initializers/authtrail.rb"
+      end
+
       def generate_model
-        template "login_activity_model.rb", "app/models/login_activity.rb"
+        if lockbox?
+          template "model_lockbox.rb", "app/models/login_activity.rb"
+        else
+          template "model.rb", "app/models/login_activity.rb"
+        end
       end
 
       def migration_version
         "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
       end
+
+      def identity_column
+        if lockbox?
+          "t.text :identity_ciphertext\n      t.string :identity_bidx, index: true"
+        else
+          "t.string :identity, index: true"
+        end
+      end
+
+      def ip_column
+        if lockbox?
+          "t.text :ip_ciphertext\n      t.string :ip_bidx, index: true"
+        else
+          "t.string :ip, index: true"
+        end
+      end
+
+      def lockbox?
+        options[:lockbox]
+      end
     end
   end
 end

data/lib/generators/authtrail/templates/initializer.rb.tt

@@ -0,0 +1,14 @@
+# set to true for geocoding (and add the geocoder gem to your Gemfile)
+# we recommend configuring local geocoding as well
+# see https://github.com/ankane/authtrail#geocoding
+AuthTrail.geocode = false
+
+# add or modify data
+# AuthTrail.transform_method = lambda do |data, request|
+#   data[:request_id] = request.request_id
+# end
+
+# exclude certain attempts from tracking
+# AuthTrail.exclude_method = lambda do |data|
+#   data[:identity] == "capybara@example.org"
+# end

data/lib/generators/authtrail/templates/login_activities_migration.rb.tt

@@ -3,12 +3,12 @@ class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version
     create_table :login_activities do |t|
       t.string :scope
       t.string :strategy
-      t.string :identity
+      <%= identity_column %>
       t.boolean :success
       t.string :failure_reason
       t.references :user, polymorphic: true
       t.string :context
-      t.string :ip
+      <%= ip_column %>
       t.text :user_agent
       t.text :referrer
       t.string :city
@@ -18,8 +18,5 @@ class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version
       t.float :longitude
       t.datetime :created_at
     end
-
-    add_index :login_activities, :identity
-    add_index :login_activities, :ip
   end
 end

data/lib/generators/authtrail/templates/model_lockbox.rb.tt

@@ -0,0 +1,14 @@
+class LoginActivity < ApplicationRecord
+  belongs_to :user, polymorphic: true, optional: true
+
+  encrypts :identity, :ip
+  blind_index :identity, :ip
+
+  before_save :reduce_precision
+
+  # reduce precision to city level to protect IP
+  def reduce_precision
+    self.latitude = latitude&.round(1) if try(:latitude_changed?)
+    self.longitude = longitude&.round(1) if try(:longitude_changed?)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authtrail
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Andrew Kane
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-17 00:00:00.000000000 Z
+date: 2021-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: warden
   requirement: !ruby/object:Gem::Requirement
@@ -52,120 +52,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: geocoder
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5'
-- !ruby/object:Gem::Dependency
-  name: combustion
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: devise
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: 
-email: andrew@chartkick.com
+description:
+email: andrew@ankane.org
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -179,13 +67,15 @@ files:
 - lib/auth_trail/version.rb
 - lib/authtrail.rb
 - lib/generators/authtrail/install_generator.rb
+- lib/generators/authtrail/templates/initializer.rb.tt
 - lib/generators/authtrail/templates/login_activities_migration.rb.tt
-- lib/generators/authtrail/templates/login_activity_model.rb.tt
+- lib/generators/authtrail/templates/model.rb.tt
+- lib/generators/authtrail/templates/model_lockbox.rb.tt
 homepage: https://github.com/ankane/authtrail
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -193,15 +83,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.22
+signing_key:
 specification_version: 4
 summary: Track Devise login activity
 test_files: []