{"id":30507750,"url":"https://github.com/humansecurity/perimeterx-java-sdk","last_synced_at":"2025-08-25T20:09:30.449Z","repository":{"id":9849556,"uuid":"62501630","full_name":"HumanSecurity/perimeterx-java-sdk","owner":"HumanSecurity","description":"PerimeterX JAVA SDK","archived":false,"fork":false,"pushed_at":"2025-06-15T09:37:48.000Z","size":1807,"stargazers_count":16,"open_issues_count":77,"forks_count":10,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-07-25T01:59:32.555Z","etag":null,"topics":["enforcer","java","java-sdk","perimeterx"],"latest_commit_sha":null,"homepage":"http://www.perimeterx.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HumanSecurity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-07-03T15:01:58.000Z","updated_at":"2025-07-24T05:06:10.000Z","dependencies_parsed_at":"2023-11-21T16:31:19.090Z","dependency_job_id":"e368fe98-1c86-422a-920f-f9fb2325c2e0","html_url":"https://github.com/HumanSecurity/perimeterx-java-sdk","commit_stats":null,"previous_names":["humansecurity/perimeterx-java-sdk"],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/HumanSecurity/perimeterx-java-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSecurity%2Fperimeterx-java-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSecurity%2Fperimeterx-java-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSecurity%2Fperimeterx-java-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSecurity%2Fperimeterx-java-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HumanSecurity","download_url":"https://codeload.github.com/HumanSecurity/perimeterx-java-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanSecurity%2Fperimeterx-java-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272124753,"owners_count":24877720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enforcer","java","java-sdk","perimeterx"],"created_at":"2025-08-25T20:09:29.093Z","updated_at":"2025-08-25T20:09:30.429Z","avatar_url":"https://github.com/HumanSecurity.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/PerimeterX/perimeterx-java-sdk.svg?branch=master)](https://travis-ci.org/PerimeterX/perimeterx-java-sdk) [![Javadocs](http://www.javadoc.io/badge/com.perimeterx/perimeterx-sdk.svg?color=brightgreen)](http://www.javadoc.io/doc/com.perimeterx/perimeterx-sdk)\n\n![image](https://storage.googleapis.com/perimeterx-logos/primary_logo_red_cropped.png)\n\n# [PerimeterX](http://www.perimeterx.com) Java SDK\n\n\u003e Latest stable version: [v6.14.2](https://search.maven.org/#artifactdetails%7Ccom.perimeterx%7Cperimeterx-sdk%7C6.15.0%7Cjar)\n\n## Table of Contents\n\n- [Usage](#usage)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Upgrading](#upgrading)\n- [Basic Usage Example](#basic-usage)\n- [Advanced Usage Examples](#advanced-usage)\n  - [Data Enrichment](#data-enrichment)\n  - [Custom Parameters](#custom-parameters)\n  - [Custom Sensitive Request](#custom-sensitive-request)\n  - [Multiple Application Support](#multi-app-support)\n- [Configuration](CONFIGURATIONS.md)\n- [Logging and Troubleshooting](#loggin-troubleshoot)\n- [Contributing](#contribute)\n- [Additional Information](#additional-information)\n\n\n\u003ca name=\"prerequisites\"\u003e\u003c/a\u003e Prerequisites\n----------------------------\n### JDK:\n\nUse `jdk 1.7` or higher.\n\n### Unlimited Strength Jurisdiction Policy:\n\nMake sure your JDK supports unlimited key length.\n\nIf the SDK is throwing `Unlimited Strength Jurisdiction Policy` assertion errors on startup, follow the instructions below:\n\n1. Download `JCE` for [jdk17](http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html) or for [jdk18](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).\n2. Replace `local_policy.jar` and `US_export_policy.jar` in your `$JAVA_HOME/jre/lib/security/` with those you have downloaded.\n3. Run your project again and the `Unlimited Strength Jurisdiction Policy` error should no appear.\n\n\n\u003ca name=\"installation\"\u003e\u003c/a\u003e Installation\n----------------------------------------\n\n### Maven:\n\n- Add `perimeterx-sdk` to `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n   \u003cgroupId\u003ecom.perimeterx\u003c/groupId\u003e\n   \u003cartifactId\u003eperimeterx-sdk\u003c/artifactId\u003e\n   \u003cversion\u003e${VERSION}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### gradle:\n\n- Add `perimeterx-sdk` to your `build.gradle`:\n\n```groovy\ncompile group: 'com.perimeterx', name: 'perimeterx-sdk', version: '${VERSION}'\n```\n\n\n\u003ca name=\"upgrading\"\u003e\u003c/a\u003e Upgrading\n----------------------------------------\n#### \u003ca name=\"4x\"\u003e\u003c/a\u003e SDK \u003e v4.x\n\nTo upgrade to the latest Enforcer version, run:\n\n`mvn versions:display-dependency-updates`\n\nOpen the project’s `pom.xml` and change the version number to the latest version.\n\nYour Enforcer version is now upgraded to the latest enforcer version.\n\n#### SDK \u003c v4.x\nThe PXContext on SDK v4.x has changed, following these changes, the implementation of PerimeterX SDK on the java filter must be changed accordingly.\n\nPerimeterX SDK reports now if handled the response instead of reporting if request was verified (using `ctx.isVerified()`) instead, its PXContext expose the following methods: `ctx.isHandledResponse()`.  \n\n`isVerified()` is deprecated and from now on, use `isRequestLowScore()`\n\n`isHandledResponse()` will return `true` in the following cases\n1. Request is blocked and PerimeterX handled the response by rendering a block page (because score was high)\n2. Response was handled by first party mechanism (not score related).\n\n* More information about First Party can be found in the [configurations page](CONFIGURATIONS.md)\n\nFollowing the instructions above, the filter should be changed according the the example below\n\n```java\n  // Verify the request\n  PXContext ctx = enforcer.pxVerify(req, new HttpServletResponseWrapper(resp);\n\n  // Notice that isVerified() changed to isHandledResponse()\n  if (ctx != null \u0026\u0026 ctx.isHandledResponse()) {\n\n     // Optional: check why response was handled\n     if (ctx.isFirstPartyRequest()) {\n       System.out.println(\"Incoming request was first party request\");\n     }\n\n     if (!ctx.isRequestLowScore()) {\n       System.out.println(\"Request score was higher than threshold\");\n     }\n\n    // Must return and not continue to filterChain.doFilter\n    return;\n\n }\n\n filterChain.doFilter(servletRequest, servletResponse);\n```\nOnce the filter is changed, follow the instructions [above](#4x).\n\nFor more information, contact [PerimeterX Support](mailto:support@perimeterx.com).\n\n### \u003ca name=\"basic-usage\"\u003e\u003c/a\u003e Basic Usage Example\n\n```java\n// Create configuration object\nPXConfiguration pxConfiguration = new PXConfiguration.Builder()\n     .cookieKey(COOKIE_KEY)\n     .authToken(AUTH_TOKEN)\n     .appId(APP_ID)\n     .blockingScore(SCORE)\n     .moduleMode(ModuleMode.BLOCKING)\n     .build();\n\n// Get instance\nPerimeterX enforcer = new PerimeterX(pxConfiguration);\n\n// Inside the request / Filter\n@Override\nprotected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOExcption {\n...\n    PXContext ctx = enforcer.pxVerify(req, new HttpServletResponseWrapper(resp);\n    if (ctx != null \u0026\u0026 !ctx.isHandledResponse()) {\n       // request should be blocked and BlockHandler was triggered on HttpServerResponseWrapper\n    }\n...\n}\n```\n\nPlease continue reading about the various configurations available on the sdk in the configurations [page](CONFIGURATIONS.md) .\n\n### \u003ca name=\"advanced-usage\"\u003e\u003c/a\u003e Advanced Usage Examples\n\n#### \u003ca name=\"data-enrichment\"\u003e\u003c/a\u003e Data Enrichment - pxde(PerimeterX Data Enrichment)\n\nUsers can use the additional activity handler to retrieve information for the request using the pxde object.\nFirst, check that the data enrichment object is verified, then you can access it's properties.\n\nMyVerificationHandler.java:\n```java\n...\npublic class MyVerificationHandler implements VerificationHandler {\n    PXConfiguration pxConfig;\n    VerificationHandler defaultVerificationHandler;\n\n    public AutomationVerificationHandler(PXConfiguration pxConfig) throws PXException {\n        this.pxConfig = pxConfig;\n        PXClient pxClient = new PXHttpClient(pxConfig);\n        ActivityHandler activityHandler = new DefaultActivityHandler(pxClient, pxConfig);\n        this.defaultVerificationHandler = new DefaultVerificationHandler(pxConfig, activityHandler);\n    }\n\n    public boolean handleVerification(PXContext pxContext, HttpServletResponseWrapper httpServletResponseWrapper) throws PXException, IOException {\n        if (pxContext.isPxdeVerified()) {\n            JsonNode dataEnrichmentPayload = pxContext.getPxde();\n            \u003chandle data enrichment payload here\u003e\n        }\n\n        return defaultVerificationHandler.handleVerification(pxContext, httpServletResponseWrapper);\n    }\n}\n```\n\nThen, in your filter:\n```java\n...\nPXConfiguration config = new PXConfiguration.Builder()\n     ...\n     .build();\nPerimeterX enforcer = new PerimeterX(config);\nenforcer.setVerificationHandler(new MyVerificationHandler(config));\n...\n```\n\n#### \u003ca name=\"custom-sensitive-request\"\u003e\u003c/a\u003e Custom Sensitive Request\nWith the  `customIsSensitive` predicate you can force the request to be sensitive.\nThe input of the function is the same request that sent to the method `pxVerify`.\nIf the function throws exception, it is equivalent to returning `false`.\nImplementing this configuration does NOT override other `sensitive` configurations, like `sensitive_routes`.\n\n\u003e **Note**\n\u003e The request body can only be read once by default. If your function requires reading the body\n\u003e consider using RequestWrapper which caches the body. Send the wrapped request to\n\u003e `pxVerify` instead of the native one.\n\nIn your filter: \n```java\n...\nPXConfiguration pxConfiguration = new PXConfiguration.Builder()\n        ...\n        .customIsSensitiveRequest((req) -\u003e req.getHeader(\"example-header\") == \"example-value\")\n        .build();\n\n```\n\n#### \u003ca name=\"custom-parameters\"\u003e\u003c/a\u003e Custom Parameters\n\nWith the `customParametersExtraction` function you can add up to 10 custom parameters to be sent back to PerimeterX servers.\nWhen set, the function is called before setting the payload on every request to PerimetrX servers.\nThe input of the function is the same request that sent to the method `pxVerify`. \nIf the function throws exception, it is equivalent to returning empty custom params.\nImplementing this configuration overrides the deprecated configuration `customParameterProvider`.\n\n\u003e **Note**\n\u003e The request body can only be read once by default. If your function requires reading the body \n\u003e consider using RequestWrapper which caches the body. Send the wrapped request to\n\u003e `pxVerify` instead of the native one.\n\nIn your filter:\n```java\n...\nPXConfiguration pxConfiguration = new PXConfiguration.Builder()\n     ...\n     .customParametersExtraction((req) -\u003e {\n          CustomParameters customParameters = new CustomParameters();\n          customParameters.setCustomParam1(\"example-value\");\n          customParameters.setCustomParam2(req.getHeader(\"example-header\"));\n          return customParameters;\n        })\n     .build();\n...\n```\n\n#### \u003ca name=\"multi-app-support\"\u003e\u003c/a\u003e Multiple Application Support\nSimply create multiple instances of the PerimeterX class:\n```java\nPerimeterX enforcerApp1 = new PerimeterX(new PXConfiguration.Builder().appId(APP_ID_1)...build(););\nPerimeterX enforcerApp2 = new PerimeterX(new PXConfiguration.Builder().appId(APP_ID_2)...build(););\n\n...\n\n// Inside route request handler for app 1:\n@Override\nprotected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOExcption {\n    PXContext ctx = enforcerApp1.px(req, new HttpServletResponseWrapper(resp);\n    ...\n}\n\n...\n\n// Inside route request handler for app 2:\n@Override\nprotected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOExcption {\n    PXContext ctx = enforcerApp2.pxVerify(req, new HttpServletResponseWrapper(resp);\n    if(ctx != null) {\n      ...\n    }\n}\n```\n\n### \u003ca name=\"loggin-troubleshoot\"\u003e\u003c/a\u003e Logging and Troubleshooting\n`perimeterx-java-sdk` is using SLF4J and Logback for logs.\n\nFor further information please visit [SLF4J](https://www.slf4j.org/manual.html) and [Logback](https://logback.qos.ch).\n\nIf you wish to use a basic logger which uses `System.out` and `System.err` to print debug and error accordingly,\nChange the value of the static variable to your desired level.\n```java\nimport com.perimeterx.models.configuration.PXConfiguration;\nimport com.perimeterx.utils.LoggerSeverity;\n\nPXConfiguration.setPxLoggerSeverity(LoggerSeverity.DEBUG);\n```\n\u003e **Note**\n\u003e This method can be executed once, no need to execute it every request.\n \n\n---\n\nThe following steps are welcome when contributing to our project.\n\n#### Fork/Clone\n\nFirst and foremost, [Create](https://guides.github.com/activities/forking/) a fork of the repository, and clone it locally. Create a branch on your fork, preferably using a self descriptive branch name.\n\n#### Code/Run\n\nCode your way out of your mess, and help improve our project by implementing missing features, adding capabilities or fixing bugs.\n\nTo run the code, simply follow the steps in the [installation guide](). Grab the keys from the PerimeterX Portal, and try refreshing your page several times continuously. If no default behaviors have been overriden, you should see the PerimeterX block page. Solve the CAPTCHA to clean yourself and start fresh again.\n\n#### Pull Request\n\nAfter you have completed the process, create a pull request to the Upstream repository. Please provide a complete and thorough description explaining the changes. Remember this code has to be read by our maintainers, so keep it simple, smart and accurate.\n\n### \u003ca name=\"additional-information\"\u003e\u003c/a\u003e Additional Information\n\n#### URI Delimiters\n\nPerimeterX processes URI paths with general- and sub-delimiters according to RFC 3986. General delimiters (e.g., `?`, `#`) are used to separate parts of the URI. Sub-delimiters (e.g., `$`, `\u0026`) are not used to split the URI as they are considered valid characters in the URI path.\n\n#### Thanks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumansecurity%2Fperimeterx-java-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhumansecurity%2Fperimeterx-java-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumansecurity%2Fperimeterx-java-sdk/lists"}