Enrichment

Data Enrichment

The HUMAN NGINX plugin stores the data enrichment payload on the request context. The data enrichment payload can also be processed with additional_activity_handler.

Only requests that are not blocked will reach the backend server, so specific logic must be applied to the processing function.

The following example includes the pre-condition checks required to process the data enrichment payload and enrich the request headers.

...
_M.additional_activity_handler = function(event_type, ctx, details)
    -- verify that the request is passed to the backend
    if event_type == 'page_requested' then
      -- pxde - contains a parsed json of the data enrichment object
      -- pxde_verified - makes sure that this payload is trusted and signed by PerimeterX
      local pxde = ngx.ctx.pxde
      local pxde_verified = ngx.ctx.pxde_verified
      if pxde and pxde_verified then
          -- apply the data enrichment logic here
          -- the example below will set the f_type on the request header
          local f_type = ngx.ctx.pxde.f_type
          ngx.req.set_header("x-px-de-f-type", f_type)
      end
    end
end
...

For more information and the available fields in the JSON, refer to the Data Enrichment documentation.

Log Enrichment

Access logs can be enriched with the HUMAN bot information by creating an NGINX variable with the proper name. To configure this variable, use the NGINX map directive in the HTTP section of your NGINX configuration file. This should be added before additional configuration files are added.

The following variables are enabled:

Request UUID: pxuuid
Request VID: pxvid
Risk Round Trip: pxrtt
Risk Score: pxscore
Pass Reason: pxpass
Block Reason: pxblock
Cookie Validity: pxcookiets
Risk Call Reason: pxcall

....
http {
    map score $pxscore  { default 'none'; }
    map pass $pxpass  { default 'none'; }
    map uuid $pxuuid  { default 'none'; }
    map rtt $pxrtt { default '0'; }
    map block $pxblock { default 'none'; }
    map vid $pxvid { default 'none'; }
    map cookiets $pxcookiets { default 'none'; }
    map px_call $pxcall { default 'none'; }

    log_format enriched '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    '| perimeterx uuid[$pxuuid] vid[$pxvid] '
                    'score[$pxscore] rtt[$pxrtt] block[$pxblock] '
                    'pass[$pxpass] cookie_ts[$pxcookiets] risk_call[$pxcall]';

    access_log /var/log/nginx/access_log enriched;
  }
  ...

Updated 12 days ago