Directives

HUMANConfiguration

Interface NameDescriptionDefault valueValuesNote
appIdHUMAN custom application ID in the format of HUMAN__nullStringmandatory
cookieKeyKey used for cookie signing - Can be found \ generated in HUMANHUMAN portal - Policy page.nullStringmandatory
authTokenJWT token used for REST API - Can be found \ generated in HUMAN portal - Application page.nullStringmandatory
moduleModeSet the mode for HUMAN 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 HUMAN 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 HUMAN backends[cookie, cookies]Set
maxBufferLenSet the number of activities to send in batched activities10int
apiTimeoutResponse timeout after sending the request1000intMilliseconds
connectionTimeoutTCP connection with the HUMAN server timeout1000intMilliseconds
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 HUMAN 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
MonitoredRoutesA list of specific routes that should be monitored and not actively enforced (blocked) even if Monitor Mode is set to Active Blocking.[]A list of string representations of regex routes or a specific routeSet
EnforcedRoutesA list of specific routes that should be enforced even if Monitor Mode is set to Monitor.[]A list of string representations of regex routes or a specific routeSet
loginCredentialsExtractionEnabledFlag that enables/disables the extraction of login credentials.falseboolean
loginCredentialsExtractionDetailsMaps the json login credentials configuration array to a dedicate class. The map helps in determine if an incoming request is a login request or not.nullCILoginMap
ciProtocolCredentials Intelligence protocol determines the strcuture and content of the user login data.V2CIProtocol
pxCompromisedCredentialsHeaderThe name of the header that is sent to the client to mark that the account is breached."px-compromised-credentials"String
addRawUsernameOnAdditionalS2SActivityFlag that determines if raw username will be sent in the additional S2S activity.falseboolean
additionalS2SActivityHeaderEnabledFlag that determines if additional S2S activity will be sent from the client's origin to HUMAN.booleanfalse
loginResponseValidationReportingMethodMethod name that determines how to validate if the login was successful.nullLoginResponseValidationReportingMethod
loginResponseValidationRegexBodyRegex pattern that checks the response body in order to validate succussful login.nullString
headerNameToValidateLoginResponseHeader name that is used to validate if the login is succesful.x-px-login-successfulString
headerValueToValidateLoginResponseHeader value that is used to validate if the login is successful."1"String
loginResponseValidationStatusCodeArray of status codes that is used to validate if the login was successful.{200}int[]
customLoginResponseValidatorCustom class that validates if the login was successful. LoginResponseValidator must be implemented to be able to use this class.DefaultCustomLoginResponseValidatorLoginResponseValidator
credentialsCustomExtractorCustom class that extracts the login credentials. CredentialsExtractor must be implemented to be able to use this class.DefaultCredentialsCustomExtractorCredentialsExtractor

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 HUMAN service finished analyzing the requestDefaultVerificationHandlersetVerificationHandler
CustomParametersProviderAdds to all activities additional custom parametersCustomParametersProvidercustomParametersProvider
LoginResponseValidatorValidate if the Login response was successfulLoginResponseValidatorisSuccessfulLogin
CredentialsExtractorExtract credentials from login requestLoginCredentialsextractCredentials

The interfaces should be set after HUMAN 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
...

Monitored routes

PXConfiguration pxConf = new PXConfiguration.Builder()
    ...
       .monitoredRoutes(new HashSet<String>(Arrays.asList("/profile", "/profile.*")));
    ...

Enforced routes

PXConfiguration pxConf = new PXConfiguration.Builder()
   ...
      .enforcedRoutes(new HashSet<String>(Arrays.asList("/profile", "/profile.*")));
   ...

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

Custom Sensitive Request

Allows writing your own logic to decide whether the request is sensitive.

The custom sensitive request function gets the request object as a parameter and should return true, otherwise, return false. Throwing an exception is equivalent to `false`. Implementing this configuration does not override other `sensitive` configurations, like `sensitive_routes`.

Example

PXConfiguration pxConfiguration = new PXConfiguration.Builder()
        ...
        .customIsSensitiveRequest((req) -> req.getHeader("example-header") == "example-value")
        .build();

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();