SDK Integration | Ruby - Monitor mode

Getting Started

This is a crisp and precise integration guide that will facilitate the integration of ShieldSquare - Real-time Bot Management Solution for Web Apps, Mobile & APIs at the application level using our Ruby on Rails SDK. Please login and download the connectors from here

Prerequisites

Ruby version >=2.0 and Rails >= 3

Integrating ShieldSquare in Monitor Mode

ShieldSquare integration in the monitor mode is divided into 3 simple steps

  1. Integrate the Code

  2. Verify Integration

  3. Move changes to production

Integrate the Code

On integrating the code, the SDK will start making API calls to ShieldSquare solution and the response received is in the form of a response code. The response code directly indicates the action to be taken based on the incoming request. All API calls made to ShieldSquare, (in monitor mode) by default would be asynchronous in nature, based on the compatibility of the website platform. In case your website platform does not support asynchronous calls, please reach out to support for further assistance.

Please follow the below-outlined steps to integrate the code in Monitor Mode:

  1. Set the configuration file

  2. Integrating the API call to the code

  3. Integrating the JS call to the code

1. Installation :

Add this line to your application's Gemfile:

1 gem 'ss2', :git => 'https://bitbucket.org/ss2ast/ror_v2.0', :tag => 'v3.1.0'

Run the bundle command to install the gem.

After you install the gem, run the generator:

1 rails generate ss2:install

The generator prompts for the following details to create ss2_config.rb:

            a) Server name - It lists down the available ShieldSquare servers. Please choose the server closest to your region by selecting the option.

            b) Sid - Enter the Subscriber Id available in your shield square account - https://admin.shieldsquare.com/subscriber_details/. Copy the Sandbox Id if it is Monitor mode or the Production Id for Active mode

Once the above options are entered ss2_config.rb will be created inside config/initializers folder.

2. Set the configuration file:

Change 1

Open thess2_config.rbfile and replace theconfig.sidparameter with your Sandbox ID. Refer the below snapshot

1 2 3 4 5 6 7 8 9 config.sid = “Your Sandbox ID” config.mode = “Monitor” config.async_http_post = true config.timeout_value = 100 config._ipaddr = "auto" config.ss2_domain = 'ss_sa.shieldsquare.net' config.domain_ttl = 3600 config.domain_cache_file = '/tmp/' config.deployment_number = '1234'

Change 2

Replace the config.ss2_domainin the ss2_config.rb file parameter with the ShieldSquare endpoint nearest to your server. Refer to the below snapshot.

1 2 3 4 5 6 7 8 9 config.sid = “Your Sandbox ID” config.mode = “Monitor” config.async_http_post = true config.timeout_value = 100 config._ipaddr = "auto" config.ss2_domain = 'ss_sa.shieldsquare.net' config.domain_ttl = 3600 config.domain_cache_file = '/tmp/' config.deployment_number = '1234'

Example :If your server is located in the US, config.ss2_domain = 'ss_scus.shieldsquare.net';

Note: Add the below line to the above configuration file for backward compatibility. If you are a new customer, ignore this line.
config.js_url='/getData'

In order to understand the function and use of each of the parameters listed in the ss2_config.rb file, refer to the below table.

Parameter

Description

Type

Required

Parameter

Description

Type

Required

_sid

This holds the subscriber id of the user and can be obtained by clicking on the Subscriber id details link on the dashboard. Choose Sandbox Id as you are integrating for the very first time

Important Note: Sandbox ID is meant for only testing and verification purposes and requests sent using this ID will not be persisted by ShieldSquare Service.

Alphanumeric

Yes

_mode

Sets the mode of the operation depending on the mode of activation. Set value to ‘Monitor’ in this case.

String

Yes

_async_http_post

This Boolean parameter is used to post the data asynchronously. In the Monitor mode, this has to be set as ‘true’.

Boolean

Yes

_timeout_value

This parameter indicates the time limit after which an API call has to be timed out. No synchronous API call would block for more than the value specified to this parameter.

Important Note: To know the optimum value to be set as timeout, run this jar file on your server and note the value. Refer to the guide for detailed steps to achieve the same.Download the ‘jar’ file.The jar may take about 15 minutes to run before it gives an output.

A numeric value (measured in milliseconds)

Yes

_ipaddress

This is set to the HTTP header which indicates the IP address of the user. The default value is “auto”.

String

Yes

_js_url

Set the _js_url to relative URL at which the “getData” file has been placed on the site. This file will collect the JavaScript data send it to the ShieldSquare site. You can find the getData file in the downloaded connector folder.

Quick Tip: The Relative path of “www.example.com/ShieldSquare/getData” is “/ShieldSquare/getData”. The simplest solution to work around this complexity is to place all the connector files in the root folder and set the _js_url parameter to “/getData”.

Important Note: This parameter is only used for backward compatibility. Kindly ignore.

String

Yes

_ss2_domain

Select the ShieldSquare server closest to the website's server and assign it to the _ss2_domain property. Available options are:

US – ss_scus.shieldsquare.net

Quick Tip:To help you find out our nearest servers use thisJar file. For other locations, refer to this Link.For further assistance, please reach us at botmanager_support@radware.com

String

Yes

_domain_cache_file

This parameter is the path to a cache file which stores the resolved IP of the _ss2_domain. The default path is "/tmp/"

Important Note: To use this feature your application server [Apache/Nginx] should have write access to the folder specified above.

String

No

_domain_ttl

This parameter indicates the time after which _domain_cache_file is reloaded. The default time is 3600 seconds

Important Note: To disable the caching feature, set the value as -1

Numeric value (measured in seconds)

No

_deployment_number

Identifier denoting different families of configuration settings in your servers

String

Yes


3. Integrate the API call to your code:

After making changes to the ss2_config.rb file parameters, the API code snippet needs to be added to the common header file of your website. The code snippet to be included is shown below:

1 2 3 4 5 6 7 8 9 10 11 12 13 def call_shield_square @shieldsquare_call_type ||= 1 // Update corresponding value as per CallType in the above table. @shieldsquare_response = Ss2.shieldsquare_ValidateRequest("shield_square_user_name", @shieldsquare_call_type, "", request, cookies) if @shieldsquare_response.responsecode == -1 logger.debug "Please reach out to ShieldSquare support team for assistance" logger.debug "Allow the user request" end redirect_url = @shieldsquare_response.url unless redirect_url.blank? redirect_to(redirect_url) and return end end

Once the code is inserted, the validate request function ( highlighted in the above code) takes the userid, call type, pid as inputs to process requests. Each of the parameters of the validate request function are defined below:

Parameter

Description

Parameter

Description

UserId

Set the user-name/user-id of the logged-in visitors to shieldsquare_userid.

CallType

The value of shieldsquare_calltype determines the type of the call and can have the below values:

1 - Set the value as 1 for this parameter when the current request is of type Page Load.
2 - Set the value as 2 for this parameter when the current request is a form submit request.
6 - Set the value as 6 for this parameter when the current request is from mobile APP.
7 - Set the value as 7 for this parameter when the current request is from feature phone.

PID

Uniquely identifies a request.

API call returns response in json format. The response code can be found as the value of “responsecode” field returned and is of the type integer.

Possible response codes are:

0

This indicates that the request should be allowed.This is the default response for monitor mode.

-1

Indicates that the ShieldSquare service is facing issues . The request should be allowed in case this response code is received. For eg. this response code will be returned in case a timeout occurs.

 

Note

A response code of -1 is usually received when a server timeout occurs.

3. Integrate the JS Tag to your code:

  • Go to 'Download Connectors' page and switch to 'JS Tag' tab to find your customized JS.

  • Integrate the JS in the starting of head section of web pages protected by ShieldSquare to ensure JS Tag executes immediately after the page loads. This will facilitate ShieldSquare to catch sophisticated bots. 

Note

Both the aforementioned code snippets (API & JS) need to be executed from the every page of the website. It is therefore mandatory to include both the snippets in the common header file.

Verify Integration

Visit the verify integration page in the ShieldSquare Admin Portal and green check marks for "API Data - IP Details" & "API Data - Session Details" will indicate the successful integration of ShieldSquare with your website. A minimum of 5 requests have to be made from the same machine using the same browser for the check marks to appear as an indication to the status of integration. In the event of a Red check mark, it indicates that a particular step might have been executed incorrectly.

Note

The verification will only be successful when the Sandbox ID is assigned in the ss2_config.rb file. Post successful verification, it is strongly recommended that you share the ss2_config.rb file with ShieldSquare Support

ShieldSquare Customer Onboarding team will verify and validate the configurations typically within 24 hours. This will ensure that the production site’s performance is not affected due to a wrong configuration set in the process of integration.

Move changes to Production

In order to move changes to production replace _sid parameter ( in the ss2_config file) with the Production ID. It takes about 2-3 hours for the production data to reflect in the ShieldSquare Dashboard. Refer the below snapshot:

1 2 3 4 5 6 7 8 9 config.sid = “Your Production ID” config.mode = “Monitor” config.async_http_post = true config.timeout_value = 100 config._ipaddr = "auto" config.ss2_domain = 'ss_sa.shieldsquare.net' config.domain_ttl = 3600 config.domain_cache_file = '/tmp/' config.deployment_number = '1234'

Note: The ShieldSquare Dashboard will not populate data if the Sandbox ID is used.

Next Steps

Please send an email to botmanager_support@radware.com confirming the changes moved to production. The Radware Bot Manager support team will verify the correctness of data received by the ShieldSquare servers. A dedicated data scientist will be assigned to your website to analyze site-specific bot patterns. Any fine-tuning required for bot classification rules specific to your site will be taken care of. Within 24 hours of successful replication of changes in the production, ShieldSquare Dashboard will be released, enabling exhaustive insights on bot traffic.