Contents x
    Configuration
    • 09 Nov 2023
    • Print
    • Dark
      Light
    Contents

    Configuration

    • Updated on 09 Nov 2023
    • Print
    • Dark
      Light
    Article Summary

    Configuration & Initialization

    Create a configuration file at <rails_app>/config/initializers/perimeterx.rb and initialize HUMAN instance on the rails application startup

    params = {
  :app_id => "APP_ID",
  :cookie_key => "COOKIE_KEY",
  :auth_token => "AUTH_TOKEN"
}

PxModule.configure(params)

    On the Rails controller include the HUMAN SDK via the before_action and call HUMAN middleware function.

    class HomeController < ApplicationController
  include PxModule

  before_action :px_verify_request
  ...
  ...
end

    Configuration Options

    Configuring Required Parameters

    Configuration options are set on the params variable on the initializer file.

    • app_id
    • cookie_key
    • auth_token

    All parameters are obtainable via the HUMAN Portal. (Applications and Policies pages)

    Changing the Minimum Score for Blocking

    Default blocking value: 100

    params = {
  ...
  :blocking_score => 100
  ...
}

    Custom Verification Handler

    Note
    This handler replaces the now deprecated custom_block_handler.

    A custom verification handler is being executed inside px_verify_request instead of the the default behavior and allows the user to use a custom action based on the risk score returned by HUMAN.

    When implemented, this method receives a hash variable as input which represents data from the HUMAN context of the request (px_ctx).

    • px_ctx.context[:score] - contains the risk score
    • px_ctx.context[:uuid] - contains the request UUID
    • px_ctx.context[:verified] - contains indication whether the request passed verification or was blocked (inspect px_ctx.context[:block_reason] for block reason)
    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]

    To replace the default verification behavior, add the configuration a lambda member as shown in the example below.

    params = {
  :app_id => <APP_ID>,
  :auth_token => <AUTH_TOKEN>,
  :custom_verification_handler => -> (px_ctx) {
    if px_ctx.context[:score] >= 60
      # take your action and render an html page or JSON with applicable status code.    
      render json: { :score => px_ctx.context[:score] }
    end
  }
}
    Note
    Unlike previous versions, the method no longer needs to return a boolean value.


    Example

    Serving a Custom HTML Page 

    params = {
  :app_id => <APP_ID>,
  :auth_token => <AUTH_TOKEN>,
  ...
  :custom_verification_handler => -> (px_ctx) {
    block_score = px_ctx.context[:score];
    client_uuid = px_ctx.context[:uuid];
    full_url = px_ctx.context[:full_url];

    html = "<html>
            <body>
            <div>Access to #{full_url} has been blocked.</div>    
            <div>Block reference - #{client_uuid} </div>
            <div>Block score - #{block_score} </div>
            </body>
            </html>".html_safe
    response.headers["Content-Type"] = "text/html"
    response.status = 403
    render :html => html
  }
}

    Custom User IP

    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 HUMAN 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, HUMAN module needs the real user's IP.

    By default the clients IP is taken from the REMOTE_ADDR header, in case the user decides to use different header or custom function that extract the header the following key should be added to the configuration

    Custom Header

    If there are multiple headers configured, the module will evaluate the headers in order and use the first value it finds.

    configuration = {
  "app_id" => <APP_ID>,
  "auth_token" => <AUTH_TOKEN>,
  "ip_headers" => [<HTTP_HEADER_NAME>, <BACKUP_HTTP_HEADER_NAME>],

    Custom Function

    The function receive as a first parameter the controller request and must return the ip at the end as string.

    configuration = {
  "app_id" => <APP_ID>,
  "auth_token" => <AUTH_TOKEN>,
  "ip_header_function" => -> (req) {
    # Method body
    return "1.2.3.4"
  }
}

    Customizing Default Block Pages

    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

    The key custom_logo expects a valid URL address

    params = [
    :app_id => 'APP_ID',
    :cookie_key => 'COOKIE_SECRET',
    :auth_token => 'AUTH_TOKEN',
    :custom_logo => 'LOGO_URL'
];

    Custom JS/CSS

    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

    params = [
    :app_id => 'APP_ID',
    :cookie_key => 'COOKIE_SECRET',
    :auth_token => 'AUTH_TOKEN',
    :css_ref => 'CSS',
    :js_ref => 'JS'
];

    Custom logo/js/css can be added together

    Module Mode

    • PxModule::ACTIVE_MODE - Module blocks users crossing the predefined block threshold. Server-to-server requests are sent synchronously.
    • 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.

    Default mode: PxModule::MONITOR_MODE

    params[:module_mode] = PxModule::ACTIVE_MODE

    Custom URI

    The URI can be returned to the HUMAN module, using a custom user function, defined on the params variable

    Default: 'REQUEST_URI'

    params[:custom_uri] = -> (request) {
  return request.headers['HTTP_X_CUSTOM_URI']
}

    Filter sensitive headers

    A list of sensitive headers can be configured to prevent specific headers from being sent to HUMAN servers (lower case header names). Filtering cookie headers for privacy is set by default, and can be overridden on the params variable.

    Default: cookie, cookies

    params[:sensitive_headers] = ['cookie', 'cookies', 'secret-header']

    API Timeouts

    Controls the timeout duration for HUMAN requests. The API is called when a Risk Cookie does not exist, or is expired or invalid

    The API Timeout, in seconds (int), to wait for the HUMAN server API response.

    Default: 1

    params[:api_timeout] = 4

    Send Page Activities

    A boolean flag to enable or disable sending of activities and metrics to HUMAN on each page request. Enabling this feature will provide data that populates the HUMAN portal with valuable information, such as the amount of requests blocked and additional API usage statistics.

    Default: true

    params[:send_page_activities] = false

    Additional Page Activity Handler

    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 HUMAN portal.

    Default: Only send activity to HUMAN as controlled by params.

    params[:additional_activity_handler] = -> (activity_type, px_ctx, details){
    // user defined logic comes here
};

    Debug Mode

    Enables debug logging mode to STDOUT

    Default: false

    params[:debug] = true

    Sensitive Routes

    An array of route prefixes that trigger a server call to HUMAN servers every time the page is viewed, regardless of viewing history. Strings are treated as route prefixes. Does not support regular expressions.

    params[:sensitive_routes] = ["/login/route", "/checkout/route"]

    Allowed Routes

    An array of route prefixes and/or regular expressions that are always allowed and not validated by HUMAN.
    A string value of a path will be treated as a prefix.
    A regex value of a path will be treated as is.

    Default: []

    params[:whitelist_routes] = ["/example", /\A\/example\z/]

    Configuration on Runtime

    As mentioned, HUMAN Module should be configured in <rails_app>/config/initializers/perimeterx.rb.
    However, it is possible to override configuration options on each request.
    Send the configuration options as an argument when calling to px_verify_request as described in the following example.
    In case of an invalid argument, the module will raise an error. Therefore, when using this feature, make sure to wrap the call to px_verify_request with begin and rescue. It is highly recommended to log the error message to follow such errors.

    Example:

    class HomeController < ApplicationController
  include PxModule

  before_action do call_perimeterx_verify_request end

  def call_perimeterx_verify_request
    params = {
    :blocking_score => 70,
    :module_mode => 2
    }
    begin
      px_verify_request(params) 
    rescue StandardError => e
      # $stdout.write(e.message)
    end
  end

end

    First Party

    To enable First Party on your Enforcer, add the following routes to your config/routes.rb file:

    get '/:appid_postfix/init.js', to: 'home#index', constraints: { appid_postfix: /XXXXXXXX/ }
get '/:appid_postfix/captcha/:all', to: 'home#index', constraints: { appid_postfix: /XXXXXXXX/, all:/.*/ }
post '/:appid_postfix/xhr/:all', to: 'home#index', constraints: { appid_postfix: /XXXXXXXX/, all:/.*/  }

    All occurrences of XXXXXXXX should be replaced with your px_app_id without the "HUMAN" prefix. For example, if your px_app_id is PX2H4seK9L, replace XXXXXXXX with 2H4seK9L.

    If you are using more than one px_app_id, provide all of them with a | between them.
    For example: 2H4seK9L|9bMs6K94|Lc5kPMNx

    First Party Configuration:

    Default: true

    params[:first_party_enabled] = false
    Was this article helpful?
    What's Next