Proxy/VPN Detection Integration Instructions

The documentation on this page demonstrates how the Proxy/VPN Detection Tests can be integrated in your website or app. Essentially, all you have to do is to include a JavaScript in your website and setup an API Callback to receive the Proxy/VPN detection results.

  • This service is free of charge. By integrating your website, you can help me make the detection tests better. All gathered detection data will be deleted after a couple of days.
  • By default, only positive sessions will be POSTed to the callback. This helps to reduce bandwidth. You can change this behavior in the configuration.
  • Your website should not have more than ~50,000 requests per day. This API is for demonstration purposes only and should not be used in mission critical scenarios.

Step 1: Configuration and Callback

You can configure the behavior of the Proxy and VPN Detection API. Below, you can see the default configuration: 

{
  "callbackPostUrl": "https://example.org/callback",
  "activatedTests": "all",
  "onlySendPositive": true,
  "onlySendTestResult": true,
  "enableActiveCallback": true,
  "enablePassiveCallback": false,
}

The explanation for the various configuration keys is as follows:

  • callbackPostUrl - This is the full URL of the HTTPS POST endpoint to which the Proxy/VPN detection results will be sent. This must be a HTTPS URL.
  • activatedTests - This is either an array of all activated tests or the string "all". It is suggested to leave this option set to "all".
  • onlySendPositive - If this option is set to true, only sessions with detected Proxy or VPN usage will be sent via callback.
  • onlySendTestResult - If true, then you will not receive test details for each of the Proxy and VPN detection tests. If this option is set to false, you will receive full details for each detection test.
  • enableActiveCallback - Active detection tests require the execution of JavaScript. If this option is set to true, you will receive a callback as soon as all tests (active and passive) are finished.
  • enablePassiveCallback - Passive tests do not require the execution of JavaScript. If true, you will receive a callback as soon as all passive detection tests are finished (Without waiting for the active tests). However, the passive callback CAN include tests that require JavaScript. The passive callback won't wait for them, but if they are available, they are included.

Step 2: Add the JavaScript to your Website

Add the following JavaScript to your website. Make sure that you use your own API Key (pdKey) and that your provide a custom value for pdVal.

  • pdKey: This is your API Key. This value is necessary in order for the detection server to know from where the request came from and in order to sent the results to the correct callbackPostUrl.
  • pdVal: This is your custom value. It can help you to identify a certain session or a certain user in your web application. The detection server just passes this value directly to the callback and does not use this value internally.

Currently, the Proxy/VPN detection can be used from two different servers:

  • Location US East with domain name pd-us-east.incolumitas.com and IP address 5.161.181.126
  • Location Germany with domain name pd-de.incolumitas.com and IP address 91.107.193.45

The code snippet below shows by example how you can dynamically load a JavaScript tag that includes the Proxy/VPN detection library. The example below is fairly complicated.

<html>
<head>
  <title>Proxy/VPN Detection Tests - Integration Example</title>

  <script>
    // First, specify your API key.
    const pdKey = 'bee2cf3b70e32e981b7b';
    // Optionally, you can specify any custom value. This value could for example identify 
    // the session of your user. The same value is provided in the API callback.
    // With this value, you can make any kind of action depending on whether a Proxy or VPN was detected.
    const pdVal = '12345';
    // Now the JavaScript integration URL is created and the JS is loaded dynamically
    const fullUrl = 'https://pd-us-east.incolumitas.com/pd-lib.js?pdKey=' + pdKey + '&pdVal=' + pdVal;
    let pdsScript = document.createElement("script");
    pdsScript.setAttribute("src", fullUrl);
    document.head.appendChild(pdsScript);
  </script>
</head>
</html>

The code snippet below shows a more straightforward way how to integrate the Proxy/VPN detection solution into your website. It is up to you to decide how you want to integrate the JavaScript.

<html>
<head>
  <title>Proxy/VPN Detection Tests - Integration Example</title>
  <script src="https://pd-us-east.incolumitas.com/pd-lib.js?pdKey=bee2cf3b70e32e981b7b&pdVal=12345"></script>
</head>
</html>

Step 3: Receiving Callbacks

After successfully placing the JavaScript and configuring your callback, your are ready to receive callbacks. There are two different kinds of callbacks:

  • Passive Callbacks: Some of the detection test do not require data obtained with JavaScript. Therefore, passive tests can be sent as soon as a client has made the first request to the server (After the JavaScript was requested). Passive callbacks can also include active test results.
  • Active Callbacks: Active callbacks need to wait for the arrival of information obtained with JavaScript. Active Callbacks also include passive test results.

Callback Format

Each callback payload (regardless whether it is active or passive) has the following basic callback structure.

Example Passive Callback

Example Active Callback

How to interpret callback results

The callback gives a detailed result wether a client sessions is a Proxy or a VPN. Furthermore, it gives a general client threat score that specifies whether the client committed abusive actions.

The Proxy Score looks as follows: 

"proxy": {
  // Whether the connection comes from a proxy
  // This is the only value you need to determine if the connection was proxied
  "isProxy": true,
  // How many tests were positive
  "numPositiveTests": 2,
  // How many tests were evaluated in total
  "numTests": 9,
  // The proxy detection score
  "score": 55,
  // The informal message to display in your client side application
  "informal": "55/100 - Very likely a Proxy"
}

The VPN Score looks as follows: 

"vpn": {
  // Whether the connection comes from a VPN
  // This is the only value you need to determine if the connection was running through a VPN
  "isVpn": false,
  // How many tests were positive
  "numPositiveTests": 1,
  // How many tests were evaluated in total
  "numTests": 3,
  // The VPN detection score
  "score": 15,
  // The informal message to display in your client side application
  "informal": "15/55 - Could be a VPN (But Unlikely)"
}

The client score looks as follows: 

"client": {
  // Whether the client behaves in an abusive fashion 
  // You can ignore this boolean, since it is used internally
  "isClientThreat": true,
  // How many tests were positive
  "numPositiveTests": 1,
  // How many tests were evaluated in total
  "numTests": 25,
  // The informal message to display in your client side application
  "informal": "client threats: NOT_ALL_WEBSOCKET_MESSAGES_RECEIVED"
}

The most important proxy detection tests with the highest accuracy are:

  • Latency Test - latency - This test is extremely effective at detecting proxy connections. It works both for residential and datacenter proxies. The reason why this test is effective: It is very hard to spoof and fake the latency test effectively. Furthermore, this test captures the very essence of proxy connections.
  • TCP/IP Fingerprint Test - tcpip_fp - This test is also capable to detect both residential and datacenter proxy connections. Although it is possible to spoof the TCP/IP fingerprint of a proxy server, most commercial proxy providers don't do it.
  • Timezone Test - timezone - The timezone test detects both VPN and Proxy connections. Clients can prevent the leaking of their locale and timezone, so this test can be bypassed rather easily.

Step 4: Ban or Rate Limit Proxy/VPN Usage

It is up to you to decide what action to take when a user was detected using a Proxy or VPN. For example, most web services don't want to serve users that are using Anonymizing Proxies. In order to ban a user that is using a proxy, your custom action could look like the example below. Node.js and Express is used for the example below:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: false }));

app.post('/callback', (req, res) => {
  let payload = req.body;

  if (payload.pdKey && payload.pdVal) {
    // how this is implemented depends on your backend logic
    const user = getUserByPdVal(payload.pdVal);

    if (user) {
      if (payload.proxy.isProxy) {
        user.displayCaptcha();
      }
    }
    // In this example, we don't care if users are using VPN's
  }

  res.header('Content-Type', 'application/json');
  return res.send({ 'msg': 'ok' });
});


app.listen(3000, () => {
  console.log('Example app listening on port 3000!');
});