Directives

🚧

PII (Personally Identifiable Information) Anonymization

Personally Identifiable Information (PII) is information that can be used on its own or with other information to identify a single person, or to identify an individual in context.

It is important for us to keep personal private information out of our servers. Therefore, by default, we do not send the request body and cookies to PerimeterX backend servers, the entire communication is based on headers data.

PII is not a recommended setting. If PII is essential for your organization, contact PerimeterX Support.

When PII is enabled, PerimeterX does not store a client’s full IP information (Client IP, HTTP Headers). In IPv4 this is done by zeroing 4th IP octet (for example, the IP 1.2.3.4 will be stored as 1.2.3.0). In IPv6 this is done by zeroing the last four (4) octets (for example, the IP 1:2:3:4:1:2:3:4 will be stored as 1:2:3:4:1:2:3:0).
Removing the IP's last octet can result small reduction of detection capability, usually for the models and signatures that are based on IPs.

PXConfiguration

Interface NameDescriptionDefault valueValuesNote
appIdPX custom application id in the format of PX__nullStringmandatory
cookieKeyKey used for cookie signing - Can be found \ generated in PX portal - Policy page.nullStringmandatory
authTokenJWT token used for REST API - Can be found \ generated in PX portal - Application page.nullStringmandatory
moduleModeSet the mode for PerimeterX module, Blocking or Monitor, setting to blocking mode meaning the module will be active blocking, monitor mode will only inspect the request but will not block itMonitorModuleMode.BLOCKING / ModuleMode.MONITORenum, mandatory for active blocking
moduleEnabledFlag for enabling \ disabling PerimeterX protectiontrueBoolean
encryptionEnabledFlag indicating the module to decode or decrypt a cookietrueBoolean
blockingScoreWhen requests with a score equal to or higher value they will be blocked.100int
sensitiveHeadersMarks which headers will not be send to PerimeterX backends[cookie, cookies]Set
maxBufferLenSet the number of activities to send in batched activities10int
apiTimeoutREST API timeout in milliseconds1000intMilliseconds
connectionTimeoutConnection timeout in milliseconds1000intMilliseconds
maxConnectionsPerRouteSet the maximum connection per route for risk api requests in the connections pool50int
maxConnectionsSet the total maximum connections for risk api client200int
sendPageActivitiesToggle sending asynchronous page activitiestrueBoolean
serverURLSet the base url for PerimeterX servershttps://sapi-\<app_id>.perimeterx.netString
customLogoThe logo will be displayed at the top div of the the block page. The logo' 's host nameString
proxyPortThe proxy's portNone - requiredint
testingModeRunning the Enforcer in dev environment for testing purposes, response returned as a JSON object. When you run the Enforcer in testing mode, please do not set custom verification handlerfalseboolean
validateRequestQueueIntervalInterval in seconds of cleaning requests queue. Solves HttpComponent reference leak bug.5int

Interfaces

perimeterx-java-sdk can be tuned and set a different types of interfaces in order to make the module more flexible
Below you can find a list of available interfaces and their setter

Interface NameDescriptionDefault Interfacemethod
ActivityHandlerHandler for all asynchronous activities from type enforcer_telemetry, page_requested and blockBufferedActivityHandlersetActivityHandler
BlockHandlerBlocking handle will be called when pxVerify will return that user is not verifiedDefaultBlockHandlerblockHandler
IPProviderHandles IP address extraction from requestCombinedIPProvidersetIpProvider
HostnameProviderHandles hostname extraction from requestDefaultHostnameProvidersetHostnameProvider
VerificationHandlerhandling verification after PerimeterX service finished analyzing the requestDefaultVerificationHandlersetVerificationHandler
CustomParametersProviderAdds to the risk api additional custom parametersCustomParametersProvidercustomParametersProvider

The interfaces should be set after PerimeterX instance has been initialized

        BlockHandler exampleBlockHandler = new ExampleBlockHandler();
        PXConfiguration pxConf = new PXConfiguration.Builder(exampleBlockHandler)
                  // This will set the blocking handler from the default one to
                  // the our custom block handler
                .blockHandler()
                .build();
        this.enforcer = new PerimeterX(pxConf)
        this.enforcer.setActivityHandler(new BlockingActivityHandler());

Configuration Examples

Basic Active And Blocking Configuration

PXConfiguration pxConf = new PXConfiguration.Builder()
   .appId("APP_ID")
   .cookieKey("AUTH_TOKEN") // Should copy from RiskCookie section in https://console.perimeterx.com/botDefender/admin?page=policiesmgmt
   .moduleMode(ModuleMode.BLOCKING)
   .authToken("AUTH_TOKEN") // PX Server request auth token to be copied from Token section in https://console.perimeterx.com/botDefender/admin?page=applicationsmgmt
   .build();

Module Enabled/Disabled

PXConfiguration pxConf = new PXConfiguration.Builder()
...
   .moduleEnabled(false) // default is true
...

Tune Blocking Score Threshold

PXConfiguration pxConf = new PXConfiguration.Builder()
...
   .blockingScore(95)

Sensitive Headers

PXConfiguration pxConf = new PXConfiguration.Builder()
...
   .sensitiveHeaders(new HashSet<String>(Arrays.asList("cookie", "cookies")))
...

IP Headers

PXConfiguration pxConf = new PXConfiguration.Builder()
...
   .ipHeaders(new HashSet<String>(Arrays.asList("x-px-true-ip", "x-true-ip")))
...

Sensitive Routes

PXConfiguration pxConf = new PXConfiguration.Builder()
...
   .sensitiveRoutes(new HashSet<String>(Arrays.asList("/cartCheckout")))
...

Customizing Default Block Page

PXConfiguration pxConf = new PXConfiguration.Builder()
...
   .customLogo(URL_TO_LOGO)
   .cssRef(URL_TO_CSS)
   .jsRef(URL_TO_JS)
...

Custom Parameters Provider

Risk API requests can be enriched with custom parameters by implementing CustomParametersProvider and adding logic to extract the custom parameters from the request.
Before implementing the interface, please make sure to configure custom parameters on PX portal.
Make sure that the custom parameters are NOT marked as query strings

public class PerimeterxCustomParamsProvider implements CustomParametersProvider {
        public CustomParameters buildCustomParameters(PXConfiguration pxConfiguration, PXContext pxContext) {
            ... Some logic ...
            String cp2 = "PerimeterX_Custom_param2";
            String cp5 = "PerimeterX_Custom_param5";
            customParameters.setCustomParam2(cp2);
            customParameters.setCustomParam5(cp5);
            ... Some logic ...

            return customParameters;
        }
    }
PXConfiguration pxConf = new PXConfiguration.Builder()
PerimeterxCustomParamsProvider perimeterxCustomParamsProvider = new PerimeterxCustomParamsProvider();
...
    .customParametersProvider(PerimeterxCustomParamsProvider)
...

Proxy Integration

Providing a proxy allows the communication between the Enforcer and our backend service via
proxy. You can set the proxy as a hostname (with a domain name), or as an ip port combination.
If you choose to use the proxy's domain, do not enter a port in the configuration.
Make sure you have the proxy's certificate installed on the machine that is running the enforcer.

PXConfiguration config = new PXConfiguration.Builder()
        .appId("PXaBcDeFgH")
        .cookieKey("COOKIE_KEY")
        .authToken("AUTH_TOKEN")
        .useProxy(true)
        .proxyHost(127.0.0.1)
        .proxyPort(80)
        .build();
        
PXConfiguration config = new PXConfiguration.Builder()
        .appId("PXaBcDeFgH")
        .cookieKey("COOKIE_KEY")
        .authToken("AUTH_TOKEN")
        .useProxy(true)
        .proxyHost(yourdomain.com)
        .build();

Did this page help you?