perimeter_x 1.0.6.pre.alpha → 1.1.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (39) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +5 -3
  3. data/Dockerfile +5 -3
  4. data/Gemfile +1 -1
  5. data/Gemfile.lock +44 -2
  6. data/LICENSE.txt +9 -12
  7. data/Rakefile +9 -2
  8. data/changelog.md +20 -0
  9. data/examples/app/controllers/home_controller.rb +9 -0
  10. data/examples/app/views/home/index.html.erb.dist +20 -0
  11. data/examples/config/initializers/perimeterx.rb.dist +8 -0
  12. data/examples/{routes.rb → config/routes.rb} +0 -0
  13. data/lib/perimeter_x.rb +109 -33
  14. data/lib/perimeterx/configuration.rb +25 -17
  15. data/lib/perimeterx/internal/clients/perimeter_x_activity_client.rb +92 -0
  16. data/lib/perimeterx/internal/clients/perimeter_x_risk_client.rb +28 -0
  17. data/lib/perimeterx/internal/exceptions/px_cookie_decryption_exception.rb +5 -0
  18. data/lib/perimeterx/internal/perimeter_x_context.rb +81 -53
  19. data/lib/perimeterx/internal/perimeter_x_cookie.rb +140 -0
  20. data/lib/perimeterx/internal/perimeter_x_cookie_v1.rb +42 -0
  21. data/lib/perimeterx/internal/perimeter_x_cookie_v3.rb +37 -0
  22. data/lib/perimeterx/internal/validators/perimeter_x_captcha_validator.rb +65 -0
  23. data/lib/perimeterx/internal/validators/perimeter_x_cookie_validator.rb +76 -0
  24. data/lib/perimeterx/internal/validators/perimeter_x_s2s_validator.rb +114 -0
  25. data/lib/perimeterx/utils/px_constants.rb +45 -0
  26. data/lib/perimeterx/utils/px_http_client.rb +47 -26
  27. data/lib/perimeterx/utils/px_logger.rb +12 -6
  28. data/lib/perimeterx/utils/px_template_factory.rb +31 -0
  29. data/lib/perimeterx/utils/templates/block.mustache +146 -0
  30. data/lib/perimeterx/utils/templates/captcha.mustache +185 -0
  31. data/lib/perimeterx/version.rb +2 -2
  32. data/perimeter_x.gemspec +6 -1
  33. data/readme.md +218 -34
  34. metadata +90 -11
  35. data/bin/console +0 -14
  36. data/bin/setup +0 -8
  37. data/examples/home_controller.rb.dist +0 -23
  38. data/lib/perimeterx/internal/perimeter_x_risk_client.rb +0 -29
  39. data/lib/perimeterx/internal/perimeter_x_s2s_validator.rb +0 -67
data/lib/perimeterx/utils/px_template_factory.rb ADDED
@@ -0,0 +1,31 @@
1
+ require 'mustache'
2
+ require 'perimeterx/utils/px_constants'
3
+ module PxModule
4
+ module PxTemplateFactory
5
+
6
+ def self.get_template(px_ctx, px_config)
7
+ logger = px_config[:logger]
8
+ if (px_config[:challenge_enabled] && px_ctx.context[:block_action] == "challenge")
9
+ logger.debug("PxTemplateFactory[get_template]: px challange triggered")
10
+ return px_ctx.context[:block_action_data].html_safe
11
+ end
12
+
13
+ logger.debug("PxTemplateFactory[get_template]: rendering template")
14
+ template_type = px_config[:captcha_enabled] ? PxModule::CAPTCHA_TEMPLATE : BLOCK_TEMPLATE
15
+
16
+ Mustache.template_file = "#{File.dirname(__FILE__) }/templates/#{template_type}"
17
+ view = Mustache.new
18
+
19
+ view[PxModule::PROP_APP_ID] = px_config[:app_id]
20
+ view[PxModule::PROP_REF_ID] = px_ctx.context[:uuid]
21
+ view[PxModule::PROP_VID] = px_ctx.context[:vid]
22
+ view[PxModule::PROP_UUID] = px_ctx.context[:uuid]
23
+ view[PxModule::PROP_CUSTOM_LOGO] = px_config[:custom_logo]
24
+ view[PxModule::PROP_CSS_REF] = px_config[:css_ref]
25
+ view[PxModule::PROP_JS_REF] = px_config[:js_ref]
26
+ view[PxModule::PROP_LOGO_VISIBILITY] = px_config[:custom_logo] ? PxModule::VISIBLE : PxModule::HIDDEN
27
+
28
+ return view.render.html_safe
29
+ end
30
+ end #end class
31
+ end #end module
data/lib/perimeterx/utils/templates/block.mustache ADDED
@@ -0,0 +1,146 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Access to this page has been denied.</title>
7
+ <link href="https://fonts.googleapis.com/css?family=Open+Sans:300" rel="stylesheet">
8
+ <style>
9
+ html,body{
10
+ margin: 0;
11
+ padding: 0;
12
+ font-family: 'Open Sans', sans-serif;
13
+ color: #000;
14
+ }
15
+
16
+ a{
17
+ color: #c5c5c5;
18
+ text-decoration: none;
19
+ }
20
+
21
+ .container{
22
+ align-items: center;
23
+ display: flex;
24
+ flex: 1;
25
+ justify-content: space-between;
26
+ flex-direction: column;
27
+ height: 100%;
28
+ }
29
+
30
+ .container > div {
31
+ width: 100%;
32
+ display: flex;
33
+ justify-content:center;
34
+ }
35
+
36
+ .container > div > div {
37
+ display: flex;
38
+ width: 80%;
39
+ }
40
+
41
+ .customer-logo-wrapper{
42
+ padding-top: 2rem;
43
+ flex-grow: 0;
44
+ background-color: #fff;
45
+ visibility: {{logoVisibility}};
46
+ }
47
+
48
+ .customer-logo{
49
+ border-bottom: 1px solid #000;
50
+ }
51
+
52
+ .customer-logo > img{
53
+ padding-bottom: 1rem;
54
+ max-height: 50px;
55
+ max-width: auto;
56
+ }
57
+
58
+ .page-title-wrapper{
59
+ flex-grow: 2;
60
+ }
61
+ .page-title {
62
+ flex-direction: column-reverse;
63
+ }
64
+
65
+ .content-wrapper{
66
+ flex-grow: 5;
67
+ }
68
+ .content{
69
+ flex-direction: column;
70
+ }
71
+
72
+ .page-footer-wrapper{
73
+ align-items: center;
74
+ flex-grow: 0.2;
75
+ background-color: #000;
76
+ color: #c5c5c5;
77
+ font-size: 70%;
78
+ }
79
+ @media (min-width:768px){
80
+ html,body{
81
+ height: 100%;
82
+ }
83
+ }
84
+ </style>
85
+ <!-- Custom CSS -->
86
+ {{# cssRef }}
87
+ <link rel="stylesheet" type="text/css" href="{{cssRef}}" />
88
+ {{/ cssRef }}
89
+ </head>
90
+ <body>
91
+ <section class="container">
92
+ <div class="customer-logo-wrapper">
93
+ <div class="customer-logo">
94
+ <img src="{{customLogo}}" alt="Logo"/>
95
+ </div>
96
+ </div>
97
+ <div class="page-title-wrapper">
98
+ <div class="page-title">
99
+ <h1>Access to this page has been denied.</h1>
100
+ </div>
101
+ </div>
102
+ <div class="content-wrapper">
103
+ <div class="content">
104
+ <p>
105
+ You have been blocked because we believe you are using automation tools to browse the website.
106
+ </p>
107
+ <p>
108
+ Please note that Javascript and Cookies must be enabled on your browser to access the website.
109
+ </p>
110
+ <p>
111
+ If you think you have been blocked by mistake, please contact the website administrator with the reference ID below.
112
+ </p>
113
+ <p>
114
+ Reference ID: #{{refId}}
115
+ </p>
116
+ </div>
117
+ </div>
118
+ <div class="page-footer-wrapper">
119
+ <div class="page-footer">
120
+ <p>
121
+ Powered by
122
+ <a href="https://www.perimeterx.com">PerimeterX</a>
123
+ , Inc.
124
+ </p>
125
+ </div>
126
+ </div>
127
+ </section>
128
+ <!-- Px -->
129
+ <script>
130
+ (
131
+ function (){
132
+ window._pxAppId = '{{appId}}';
133
+ var p = document.getElementsByTagName("script")[0], s = document.createElement("script");
134
+
135
+ s.async = 1;
136
+ s.src = '//client.perimeterx.net/{{appId}}/main.min.js';
137
+ p.parentNode.insertBefore(s, p);
138
+ } ()
139
+ );
140
+ </script>
141
+ <!-- Custom Script -->
142
+ {{# jsRef }}
143
+ <script src="{{jsRef}}"></script>
144
+ {{/ jsRef }}
145
+ </body>
146
+ </html>
data/lib/perimeterx/utils/templates/captcha.mustache ADDED
@@ -0,0 +1,185 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Access to this page has been denied.</title>
7
+ <link href="https://fonts.googleapis.com/css?family=Open+Sans:300" rel="stylesheet">
8
+ <style>
9
+ html,body{
10
+ margin: 0;
11
+ padding: 0;
12
+ font-family: 'Open Sans', sans-serif;
13
+ color: #000;
14
+ }
15
+
16
+ a{
17
+ color: #c5c5c5;
18
+ text-decoration: none;
19
+ }
20
+
21
+ .container{
22
+ align-items: center;
23
+ display: flex;
24
+ flex: 1;
25
+ justify-content: space-between;
26
+ flex-direction: column;
27
+ height: 100%;
28
+ }
29
+
30
+ .container > div {
31
+ width: 100%;
32
+ display: flex;
33
+ justify-content:center;
34
+ }
35
+
36
+ .container > div > div {
37
+ display: flex;
38
+ width: 80%;
39
+ }
40
+
41
+ .customer-logo-wrapper{
42
+ padding-top: 2rem;
43
+ flex-grow: 0;
44
+ background-color: #fff;
45
+ visibility: {{logoVisibility}};
46
+ }
47
+
48
+ .customer-logo{
49
+ border-bottom: 1px solid #000;
50
+ }
51
+
52
+ .customer-logo > img{
53
+ padding-bottom: 1rem;
54
+ max-height: 50px;
55
+ max-width: auto;
56
+ }
57
+
58
+ .page-title-wrapper{
59
+ flex-grow: 2;
60
+ }
61
+ .page-title {
62
+ flex-direction: column-reverse;
63
+ }
64
+
65
+ .content-wrapper{
66
+ flex-grow: 5;
67
+ }
68
+ .content{
69
+ flex-direction: column;
70
+ }
71
+
72
+ .page-footer-wrapper{
73
+ align-items: center;
74
+ flex-grow: 0.2;
75
+ background-color: #000;
76
+ color: #c5c5c5;
77
+ font-size: 70%;
78
+ }
79
+
80
+ @media (min-width:768px){
81
+ html,body{
82
+ height: 100%;
83
+ }
84
+ }
85
+ </style>
86
+ <!-- Custom CSS -->
87
+ {{#cssRef}}
88
+ <link rel="stylesheet" type="text/css" href="{{cssRef}}" />
89
+ {{/cssRef}}
90
+ <script src="https://www.google.com/recaptcha/api.js" async defer></script>
91
+ </head>
92
+
93
+ <body>
94
+ <section class="container">
95
+ <div class="customer-logo-wrapper">
96
+ <div class="customer-logo">
97
+ <img src="{{customLogo}}" alt="Logo"/>
98
+ </div>
99
+ </div>
100
+ <div class="page-title-wrapper">
101
+ <div class="page-title">
102
+ <h1>Please verify you are a human</h1>
103
+ </div>
104
+ </div>
105
+ <div class="content-wrapper">
106
+ <div class="content">
107
+ <p>
108
+ Please click "I am not a robot" to continue
109
+ </p>
110
+ <div class="g-recaptcha" data-sitekey="6Lcj-R8TAAAAABs3FrRPuQhLMbp5QrHsHufzLf7b" data-callback="handleCaptcha" data-theme="dark">
111
+ </div>
112
+ <p>
113
+ Access to this page has been denied because we believe you are using automation tools to browse the website.
114
+ </p>
115
+ <p>
116
+ This may happen as a result of the following:
117
+ </p>
118
+ <ul>
119
+ <li>
120
+ Javascript is disabled or blocked by an extension (ad blockers for example)
121
+ </li>
122
+ <li>
123
+ Your browser does not support cookies
124
+ </li>
125
+ </ul>
126
+ <p>
127
+ Please make sure that Javascript and cookies are enabled on your browser and that you are not blocking them from loading.
128
+ </p>
129
+ <p>
130
+ Reference ID: #{{refId}}
131
+ </p>
132
+ </div>
133
+ </div>
134
+ <div class="page-footer-wrapper">
135
+ <div class="page-footer">
136
+ <p>
137
+ Powered by
138
+ <a href="https://www.perimeterx.com">PerimeterX</a>
139
+ , Inc.
140
+ </p>
141
+ </div>
142
+ </div>
143
+ </section>
144
+ <!-- Px -->
145
+ <script>
146
+ (
147
+ function (){
148
+ window._pxAppId = '{{appId}}';
149
+ var p = document.getElementsByTagName("script")[0], s = document.createElement("script");
150
+
151
+ s.async = 1;
152
+ s.src = '//client.perimeterx.net/{{appId}}/main.min.js';
153
+ p.parentNode.insertBefore(s, p);
154
+ } ()
155
+ );
156
+ </script>
157
+ <!-- Captcha -->
158
+ <script>
159
+ window.px_vid = '{{vid}}';
160
+ function handleCaptcha(response){
161
+ var vid = '{{vid}}';
162
+ var uuid = '{{uuid}}';
163
+ var name = "_pxCaptcha";
164
+
165
+ var expiryUtc = new Date(Date.now()+1000*10).toUTCString();
166
+
167
+ var cookieParts = [
168
+ name,
169
+ "=",
170
+ response+":"+vid+":"+uuid,
171
+ "; expires=",
172
+ expiryUtc,
173
+ "; path=/"
174
+ ];
175
+
176
+ document.cookie = cookieParts.join("");
177
+ location.reload();
178
+ }
179
+ </script>
180
+ <!-- Custom Script -->
181
+ {{#jsRef}}
182
+ <script src="{{jsRef}}"></script>
183
+ {{/jsRef}}
184
+ </body>
185
+ </html>
data/lib/perimeterx/version.rb CHANGED
@@ -1,3 +1,3 @@
1
- module PerimeterX
2
- VERSION = '1.0.6-alpha'
1
+ module PxModule
2
+ VERSION = '1.1.0'
3
3
  end
data/perimeter_x.gemspec CHANGED
@@ -9,7 +9,7 @@ Gem::Specification.new do |gem|
9
9
  gem.description = "PerimeterX ruby module to monitor and block traffic according to PerimeterX risk score"
10
10
  gem.licenses = ['MIT']
11
11
  gem.homepage = "https://www.perimeterx.com"
12
- gem.version = PerimeterX::VERSION
12
+ gem.version = PxModule::VERSION
13
13
 
14
14
  gem.authors = ["Nitzan Goldfeder"]
15
15
  gem.email = "nitzan@perimeterx.com"
@@ -31,4 +31,9 @@ Gem::Specification.new do |gem|
31
31
  gem.required_ruby_version = '>= 2.3'
32
32
 
33
33
  gem.add_dependency('httpclient', '2.8.2.4')
34
+ gem.add_dependency('mustache', '~> 1.0', '>= 1.0.3')
35
+ gem.add_dependency('activesupport', '>= 4.2.0')
36
+
37
+ gem.add_development_dependency 'rspec', '~> 3.0'
38
+ gem.add_development_dependency 'mocha', '~> 1.2', '>= 1.2.1'
34
39
  end
data/readme.md CHANGED
@@ -10,6 +10,20 @@ Table of Contents
10
10
  * [Installation](#installation)
11
11
  * [Basic Usage Example](#basic-usage)
12
12
  - [Configuration](#configuration)
13
+ * [Configuring Required Parameters](#requireied-params)
14
+ * [Blocking Score](#blocking-score)
15
+ * [Custom Block Page](#custom-block-page)
16
+ * [Custom Block Action](#custom-block-action)
17
+ * [Enable/Disable Captcha](#captcha-support)
18
+ * [Extracting Real IP Address](#real-ip)
19
+ * [Custom URI](#custom-uri)
20
+ * [Filter Sensitive Headers](#sensitive-headers)
21
+ * [API Timeouts](#api-timeout)
22
+ * [Send Page Activities](#send-page-activities)
23
+ * [Additional Page Activity Handler](#additional-page-activity-handler)
24
+ * [Monitor Only](#logging)
25
+ * [Debug Mode](#debug-mode)
26
+ - [Contributing](#contributing)
13
27
 
14
28
  <a name="Usage"></a>
15
29
  <a name="dependencies"></a> Dependencies
@@ -17,66 +31,87 @@ Table of Contents
17
31
 
18
32
  - Ruby version 2.3+
19
33
  - Rails version 4.2
20
- - [httparty](https://github.com/jnunemaker/httparty)
34
+ - [httpclient](https://rubygems.org/gems/httpclient/versions/2.8.3)
35
+ - [mustache](https://rubygems.org/gems/mustache)
21
36
 
22
37
  <a name="installation"></a> Installation
23
38
  ----------------------------------------
24
- Install it through command line ```gem install perimeter_x --pre```
25
- Or add it in Gemfile ```gem 'perimeter_x', '~> 1.0.4.pre.alpha'```
39
+ Install it through command line ```gem install perimeter_x```
26
40
 
27
41
 
28
42
  <a name=basic-usage></a> Basic Usage Example
29
43
  ----------------------------------------
30
- On the Rails controller include the PerimeterX SDK via the before_action which will call your defined middleware function. This function is a wrapper for the px_verify method which takes a request and processes it. The verify method can return true if verified, or false if not verified.
31
44
 
32
- The default condition is to always return true for monitoring mode.
45
+ ### Configuration & Initialization
46
+ Create a configuration file at `<rails_app>/config/initializers/perimeterx.rb` and initialize PerimeterX instance on the rails application startup
47
+ ```ruby
48
+ params = {
49
+ :app_id => "APP_ID",
50
+ :cookie_key => "COOKIE_KEY",
51
+ :auth_token => "AUTH_TOKEN"
52
+ }
33
53
 
54
+ PxModule.configure(params)
34
55
  ```
56
+
57
+ On the Rails controller include the PerimeterX SDK via the before_action and call PerimterX middleware function.
58
+
59
+ ```ruby
35
60
  class HomeController < ApplicationController
36
- include PerimeterX
37
- attr_accessor :px
38
- ...
39
- ...
40
- before_action :px_middleware
61
+ include PxModule
62
+
63
+ before_filter :px_verify_request
41
64
  ...
42
65
  ...
43
- initialize()
44
- configuration = {
45
- "app_id" => <APP_ID>
46
- "auth_token" => <AUTH_TOKEN>
47
- }
48
- @px = PxModule.instance(params)
49
- end
66
+ end
67
+ ```
68
+
69
+ <a name="configuration"></a> Configuration options
70
+ ----------------------------------------
71
+ <a name="requireied-params"></a>**Configuring Required Parameters**
72
+ Configuration options are set on the ``params`` variable on the initializer file.
73
+
74
+ - ``app_id``
75
+ - ``cookie_key``
76
+ - ``auth_token``
77
+
78
+ All parameters are obtainable via the PerimeterX Portal. (Applications and Policies pages)
79
+
80
+ <a name="blocking-score"></a>**Changing the Minimum Score for Blocking**
81
+
82
+ >Note: Default blocking value: 70
83
+
84
+ ```ruby
85
+ params = {
50
86
  ...
87
+ :blocking_score => 100
51
88
  ...
52
- def px_middleware
53
- px.px_verify(request.env)
54
- end
89
+ }
55
90
  ```
56
91
 
57
- <a name="configuration"></a> Configuration
58
- ----------------------------------------
59
92
 
60
- ** Custom Verification Handler **
61
- A custom verification handler replaces the default handle_verification method and allows you to take a custom action based on the risk score returned by PerimeterX.
93
+
94
+ <a name="custom-block-action"></a>**Custom Verification Handler**
95
+
96
+ A custom verification handler is being executed inside ``px_verify_request`` instead of the the default behavior and allows a user to use a custom action based on the risk score returned by PerimeterX.
62
97
 
63
98
  When implemented, this method receives a hash variable as input which represents data from the PerimeterX context of the request (px_ctx).
64
99
 
65
- - `px_ctx[:score] ` contains the risk score
66
- - `px_ctx[:uuid] ` contains the request UUID
100
+ - `px_ctx[:score] ` contains the risk score
101
+ - `px_ctx[:uuid] ` contains the request UUID
102
+
103
+ >> Note: to determine whether to return a captcha/block page (HTML) or block JSON payload a reference key on the context will be available: ```px_ctx.context[:format]```
67
104
 
68
105
  To replace the default verification behavior, add the configuration a lambda member as shown in the example below.
69
106
 
70
107
  The method must return boolen value.
71
108
 
72
-
73
-
74
109
  ```ruby
75
- configuration = {
76
- "app_id" => <APP_ID>,
77
- "auth_token" => <AUTH_TOKEN>,
78
- "custom_verification_handler" => -> (px_ctx) {
79
- if px_ctx[:score] >= 60
110
+ params = {
111
+ :app_id => <APP_ID>,
112
+ :auth_token => <AUTH_TOKEN>,
113
+ :custom_block_handler => -> (px_ctx) {
114
+ if px_ctx.context[:score] >= 60
80
115
  # take your action and retun a message or JSON with a status code of 403 and option UUID of the request. Can return false and include action in the px_middleware method.
81
116
  end
82
117
  return true
@@ -84,7 +119,33 @@ configuration = {
84
119
  }
85
120
  ```
86
121
 
87
- ** Custom User IP **
122
+ **Example**
123
+ ### Serving a Custom HTML Page ###
124
+ ```ruby
125
+
126
+ params[:custom_block_handler] = -> (px_ctx)
127
+ {
128
+ block_score = px_ctx.context[:score];
129
+ block_uuid = px_ctx.context[:uuid];
130
+ full_url = px_ctx.context[:full_url];
131
+
132
+ html = "<html>
133
+ <body>
134
+ <div>Access to #{full_url} has been blocked.</div>
135
+ <div>Block reference - #{block_uuid} </div>
136
+ <div>Block score - #{block_score} </div>
137
+ </body>
138
+ </html>".html_safe
139
+ response.headers["Content-Type"] = "text/html"
140
+ response.status = 403
141
+ render :html => html
142
+ return false
143
+ };
144
+
145
+ PxModule.configure(params)
146
+ ```
147
+
148
+ <a name="real-ip"></a>** Custom User IP **
88
149
 
89
150
  > Note: IP extraction, according to your network setup, is very important. It is common to have a load balancer/proxy on top of your applications, in which case the PerimeterX module will send the system's internal IP as the user's. In order to properly perform processing and detection on server-to-server calls, PerimeterX module needs the real user's IP.
90
151
 
@@ -111,3 +172,126 @@ configuration = {
111
172
  }
112
173
  }
113
174
  ```
175
+ <a name="custom-block-page"></a>**Customizing Default Block Pages**
176
+
177
+ Adding a custom logo to the blocking page is by providing the `params` a key `custom_logo` , the logo will be displayed at the top div of the the block page The logo's `max-heigh` property would be `150px` and width would be set to `auto`
178
+
179
+ The key custom_logo expects a valid URL address such as https://s.perimeterx.net/logo.png
180
+
181
+ ```ruby
182
+ params = [
183
+ :app_id => 'APP_ID',
184
+ :cookie_key => 'COOKIE_SECRET',
185
+ :auth_token => 'AUTH_TOKEN',
186
+ :custom_logo => 'LOGO_URL'
187
+ ];
188
+ ```
189
+
190
+ **Custom JS/CSS**
191
+ The block page can be modified with a custom CSS by adding to the `params` the key `css_ref` and providing a valid URL to the css In addition there is also the option to add a custom JS file by adding `js_ref` key to the pxConfig and providing the JS file that will be loaded with the block page, this key also expects a valid URL
192
+
193
+ ```ruby
194
+ params = [
195
+ :app_id => 'APP_ID',
196
+ :cookie_key => 'COOKIE_SECRET',
197
+ :auth_token => 'AUTH_TOKEN',
198
+ :css_ref => 'CSS',
199
+ :js_ref => 'JS'
200
+ ];
201
+ ```
202
+ > Note: Custom logo/js/css can be added together
203
+
204
+ <a name="logging"></a>**No Blocking, Monitor Only**
205
+ Default mode: PxModule::ACTIVE_MODE
206
+
207
+ - PxModule::ACTIVE_MODE - Module blocks users crossing the predefined block threshold. Server-to-server requests are sent synchronously.
208
+
209
+ - PxModule::$MONITOR_MODE - Module does not block users crossing the predefined block threshold. The `custom_block_handler` function will be eval'd in case one is supplied, upon crossing the defined block threshold.
210
+
211
+ ```ruby
212
+ params[:module_mode] = PxModule::MONITOR_MODE
213
+ ```
214
+
215
+ <a name="captcha-support"></a>**Enable/Disable CAPTCHA on the block page**
216
+ Default mode: enabled
217
+
218
+ By enabling CAPTCHA support, a CAPTCHA will be served as part of the block page, giving real users the ability to identify as a human. By solving the CAPTCHA, the user's score is then cleaned up and the user is allowed to continue normal use.
219
+
220
+ ```ruby
221
+ params[:captcha_enabled] = false
222
+ ```
223
+
224
+ <a name="custom-uri"></a>**Custom URI**
225
+
226
+ Default: 'REQUEST_URI'
227
+
228
+ The URI can be returned to the PerimeterX module, using a custom user function, defined on the ``params`` variable
229
+
230
+ ```ruby
231
+ params[:custom_uri] = -> (request) {
232
+ return request.headers['HTTP_X_CUSTOM_URI']
233
+ }
234
+ ```
235
+
236
+ <a name="sensitive-headers"></a>**Filter sensitive headers**
237
+ A list of sensitive headers can be configured to prevent specific headers from being sent to PerimeterX servers (lower case header names). Filtering cookie headers for privacy is set by default, and can be overridden on the `params` variable.
238
+
239
+ Default: cookie, cookies
240
+
241
+ ```ruby
242
+ params[:sensitive_headers] = ['cookie', 'cookies', 'secret-header']
243
+
244
+ ```
245
+
246
+ <a name="api-timeout"></a>**API Timeouts**
247
+ >Note: Controls the timeouts for PerimeterX requests. The API is called when a Risk Cookie does not exist, or is expired or invalid
248
+
249
+ The API Timeout, in seconds (int), to wait for the PerimeterX server API response.
250
+
251
+ Default: 1
252
+
253
+ ```ruby
254
+ params[:api_timeout] = 4
255
+ ```
256
+
257
+ <a name="send-page-activities"></a>**Send Page Activities**
258
+ Default: true
259
+ A boolean flag to enable or disable sending of activities and metrics to PerimeterX on each page request. Enabling this feature will provide data that populates the PerimeterX portal with valuable information, such as the amount of requests blocked and additional API usage statistics.
260
+
261
+ ```ruby
262
+ params[:send_page_activities] = false
263
+ ```
264
+
265
+ <a name="additional-page-activity-handler"></a>**Additional Page Activity Handler**
266
+
267
+ Adding an additional activity handler is done by setting `additional_activity_handler` with a user defined function on the `params` variable. The `additional_activity_handler` function will be executed before sending the data to the PerimeterX portal.
268
+
269
+ Default: Only send activity to PerimeterX as controlled by `params`.
270
+
271
+
272
+
273
+ ```ruby
274
+ params[:additional_activity_handler] = -> (activity_type, px_ctx, details){
275
+ // user defined logic comes here
276
+ };
277
+ ```
278
+
279
+ <a name="debug-mode"></a>**Debug Mode**
280
+ Default: false
281
+
282
+ Enables debug logging mode to STDOUT
283
+ ```ruby
284
+ params[:debug] = true
285
+ ```
286
+
287
+ <a name="contributing"></a># Contributing #
288
+ ------------------------------
289
+ The following steps are welcome when contributing to our project.
290
+ ###Fork/Clone
291
+ First and foremost, [Create a fork](https://guides.github.com/activities/forking/) of the repository, and clone it locally.
292
+ Create a branch on your fork, preferably using a self descriptive branch name.
293
+
294
+ ###Code/Run
295
+ Help improve our project by implementing missing features, adding capabilities or fixing bugs.
296
+
297
+ To run the code, simply follow the steps in the [installation guide](#installation). Grab the keys from the PerimeterX Portal, and try refreshing your page several times continously. If no default behaviours have been overriden, you should see the PerimeterX block page. Solve the CAPTCHA to clean yourself and start fresh again.