Browser Fingerprinting

bl0ck provides sophisticated browser fingerprinting capabilities as an additional layer of security intelligence. Browser fingerprinting generates a unique identifier (a 32-character hexadecimal string) based on various browser attributes, such as hardware, software, and behavioral characteristics. This can help detect bots, fraud, or suspicious activities beyond IP-based blocking.

Fingerprints are computed client-side using a customizable JavaScript module and can be checked or reported server-side via the API. This feature integrates with bl0ck's threat intelligence to identify known malicious browser configurations.

🔧 Prerequisites

  • Sceptive bl0ck account with API access (generate an API token from the dashboard under "Tokens").

  • A security code (scode): This is a user-defined string used to customize the fingerprinting algorithm for your integration. It ensures the module is tied to your account and prevents tampering. Choose a strong, unique code (e.g., a UUID or secret key). If not provided default bl0ck scode is used. Setting a custom scode is only be applicable if you want to create your own database of fingerprints. In this case querying fingerprints from bl0ck API will not be working.

  • Access to your web application's frontend to include the JavaScript module.

🔧 Steps for Integration

You can access documentation for all OpenAPI directory for bl0ck API services please reach out bl0ck OpenAPI Specifications

1. Fetch the JavaScript Module

Download the obfuscated JavaScript module. This module computes the browser fingerprint client-side.

Endpoint: GET /bfp/jsmodule

Headers:

  • x-api-token: Your API token.

Example API Call:

curl -H "x-api-token: YOUR_API_TOKEN" \
  "https://api.bl0ck.sceptive.com/bfp/jsmodule" -o bl0ck_fp.js

Response: Plain text JavaScript file (obfuscated for security). Save it as bl0ck_fp.js and host it on your web server.

2. Include the Module in Your Web Page

Add the JavaScript module to your HTML pages where you want to compute fingerprints (e.g., login or checkout pages).

Example HTML Integration:

<script src="/path/to/bl0ck_fp.js"></script>
<script>
    // Compute the fingerprint asynchronously
     document.addEventListener('DOMContentLoaded', function() {


          // Initialize the fingerprinting lib at application startup.
          var bfp = BioFP.load()

          // Get and display the fingerprint
          bfp
          .then(fp => fp.get())
          .then(result => {
              const fingerprint = result.bioFp;

          });
      });
</script>

  • The module exposes a global function bioFp that returns a Promise resolving to the 32-character hex fingerprint.

  • Send the computed fingerprint to your backend server via AJAX/Fetch for API checks.

Note: The module is obfuscated to prevent reverse engineering. Do not modify it.

3. Test the Integration

Download a test package to verify the fingerprinting works in a local environment.

Endpoint: GET /v1/browserfp/jstest.zip

Headers: - x-api-token: Your API token.

Example API Call:

curl -H "x-api-token: YOUR_API_TOKEN" \
 "https://api.bl0ck.sceptive.com/bfp/jstest.zip" -o jstest.zip

Response: ZIP file containing: - bl0ck_fp.js: The obfuscated module. - block_fp_test.html: A test HTML page that loads the module and displays the computed fingerprint.

Usage: 1. Unzip the file. 2. Open block_fp_test.html in a browser. 3. View the console or on-page output for the fingerprint.

4. Query a Fingerprint (Server-Side)

For complete examples please refer to Github | bl0ck Backend Examples

Query the API to check if a computed fingerprint is known (e.g., associated with threats).

Endpoint: GET /bfp/query/{fp}

Parameters:

  • fp: The 32-character hex fingerprint to check.

Headers:

  • x-api-token: Your API token.

Example API Call:

curl -H "x-api-token: YOUR_API_TOKEN" \
 "https://api.bl0ck.sceptive.com/bfp/query/abcdef1234567890abcdef1234567890"

Response (JSON):

  • If known: {"status": "known", "details": {...}} (details may include threat tags or last seen).

  • If unknown: {"status": "unknown"}.

  • Errors: 400 for invalid fp or scode.

5. Report a Suspicious Fingerprint (Server-Side)

For complete examples please refer to Github | bl0ck Backend Examples

Submit a new fingerprint for potential inclusion in bl0ck's threat database (e.g., if you detect suspicious behavior).

Endpoint: POST /bfp/report/{fp}

Headers: - x-api-token: Your API token.

Body (JSON): - details: Optional object with additional context (e.g., {"ip": "192.168.1.1", "reason": "bot detected"}).

Example API Call:

curl -X POST \
 -H "x-api-token: YOUR_API_TOKEN"  \
  -d '{"details": {"ip": "192.168.1.1", "reason": "suspicious login"}}' \
  "https://api.bl0ck.sceptive.com/bfp/report/abcdef1234567890abcdef1234567890"

Response (JSON): {"status": "reported"}.

Note: Reports are reviewed before adding to the database. Abuse may lead to account restrictions.

Supported Features

  • Customization: The scode alters the fingerprinting algorithm, making it unique to your integration.
  • Obfuscation: The JS module is obfuscated to resist tampering.
  • Validation: Fingerprints must be 32 hex characters; invalid ones return 400 errors.
  • Caching/Rate Limits: API responses may be cached; respect rate limits from your subscription.

Usage Tips

  • Security: Keep your scode secret; rotate if compromised.
  • Privacy: Inform users about fingerprinting per privacy laws (e.g., GDPR).
  • Error Handling: Handle 400 (invalid input) and 401 (auth errors) in your code.
  • Automation: Use scripts to fetch/update the JS module periodically.
  • Limitations: Fingerprinting isn't foolproof (e.g., incognito modes or VPNs may alter it).

For issues or custom integrations, contact support@sceptive.com.