FPScanner

The fsid is a JA4-inspired, locality-preserving identifier structured into semantic sections. This allows for human readability and partial matching (e.g., comparing only the GPU section).

Format: FS1_<det>_<auto>_<dev>_<brw>_<gfx>_<cod>_<loc>_<ctx>

Section Breakdown

FPScanner identifies automation frameworks and bot-like environments by analyzing specific browser signals and cross-context consistency. It detects:

Automation Frameworks

• Webdriver: navigator.webdriver === true (Selenium, Puppeteer, Playwright)
• Webdriver Writable: Property descriptor checks (Puppeteer, Playwright)
• Selenium Properties: Presence of $cdc_ or $wdc_ in document
• CDP: Chrome DevTools Protocol runtime markers
• Playwright: Presence of __playwright or __pw_* markers

Environment & Hardware Signals

• Headless Chrome: Missing window.chrome object or default 800x600 resolution
• Virtualization/Containers: Unrealistic CPU core counts or impossible device memory values

Cross-Context Validation

Bots often fail to maintain consistency between different execution contexts. FPScanner checks for:

• Iframe/Worker Mismatches: Webdriver detected in an iframe or web worker but not in the main window.
• Platform Mismatches: Differences in platform identity between the main window and iframes or workers.
• WebGL Mismatches: Differences in the WebGL renderer between the main window and workers.

The library uses a simple XOR cipher with Base64 encoding to protect the fingerprint payload. You must implement this on your server to read the data.

Node.js Implementation

function decryptFingerprint(ciphertext, key) {
  const encrypted = Buffer.from(ciphertext, 'base64');
  const keyBytes = Buffer.from(key, 'utf8');
  const decrypted = Buffer.alloc(encrypted.length);

  for (let i = 0; i < encrypted.length; i++) {
    decrypted[i] = encrypted[i] ^ keyBytes[i % keyBytes.length];
  }

  let fingerprint = JSON.parse(decrypted.toString('utf8'));
  // Handle double-JSON-encoding if present
  if (typeof fingerprint === 'string') {
    fingerprint = JSON.parse(fingerprint);
  }
  return fingerprint;
}

Python Implementation

import base64
import json

def decrypt_fingerprint(ciphertext: str, key: str) -> dict:
    encrypted = base64.b64decode(ciphertext)
    key_bytes = key.encode('utf-8')

    decrypted = bytearray(len(encrypted))
    for i in range(len(encrypted)):
        decrypted[i] = encrypted[i] ^ key_bytes[i % len(key_bytes)]

    fingerprint = json.loads(decrypted.decode('utf-8'))
    # Handle double-JSON-encoding if present
    if isinstance(fingerprint, str):
        fingerprint = json.loads(fingerprint)
    return fingerprint

On your server, you must decrypt the fingerprint and validate it to prevent replay attacks and detect bots.

Note: The decryption logic uses a simple XOR cipher with the key provided during your build process (e.g., npx fpscanner build --key=your-key).

To secure your endpoint:

1. Decrypt the base64 ciphertext using your secret key.
2. Check fastBotDetection: If true, the request is likely from an automated tool.
3. Validate time: Compare the time field (Unix timestamp in ms) against the current time to ensure the fingerprint hasn't expired (e.g., older than 60 seconds) to prevent replay attacks.
4. Use fsid: Use the fingerprint ID for session correlation and tracking.

// Decrypt and validate the fingerprint
// Use the same key you provided when building: npx fpscanner build --key=your-key
const key = 'your-secret-key'; // Your custom key

function decryptFingerprint(ciphertext, key) {
  const encrypted = Buffer.from(ciphertext, 'base64');
  const keyBytes = Buffer.from(key, 'utf8');
  const decrypted = Buffer.alloc(encrypted.length);

  for (let i = 0; i < encrypted.length; i++) {
    decrypted[i] = encrypted[i] ^ keyBytes[i % keyBytes.length];
  }

  return JSON.parse(decrypted.toString('utf8'));
}

app.post('/api/fingerprint', (req, res) => {
  const fingerprint = decryptFingerprint(req.body.fingerprint, key);

  // Check bot detection
  if (fingerprint.fastBotDetection) {
    console.log('🤖 Bot detected!', fingerprint.fastBotDetectionDetails);
    return res.status(403).json({ error: 'Bot detected' });
  }

  // Validate timestamp (prevent replay attacks)
  const ageMs = Date.now() - fingerprint.time;
  if (ageMs > 60000) { // 60 seconds
    return res.status(400).json({ error: 'Fingerprint expired' });
  }

  // Use fingerprint.fsid for session correlation
  console.log('Fingerprint ID:', fingerprint.fsid);
  res.json({ ok: true });
});

For production, you should replace the placeholder key with your own and enable obfuscation to prevent attackers from forging payloads. Use the fpscanner build command.

Key Injection Priority

1. CLI Argument: --key=your-secret-key (Highest priority)
2. Environment Variable: FINGERPRINT_KEY=your-secret-key
3. .env file: FINGERPRINT_KEY=your-secret-key inside a .env file

Usage Examples

# Using a CLI argument
npx fpscanner build --key=your-secret-key-here

# Using a custom env file
npx fpscanner build --env-file=.env.production

# Skipping obfuscation (for development only)
npx fpscanner build --key=dev-key --no-obfuscate

CI/CD Integration

You can automate the build in your CI/CD pipeline by adding a postinstall script to your package.json:

{
  "scripts": {
    "postinstall": "fpscanner build"
  }
}

Then, set FINGERPRINT_KEY as a secret in your environment (e.g., GitHub Actions secrets).

To ensure the security of your fingerprinting implementation, follow these best practices:

1. Key Management: Use a strong, random key (at least 32 characters) and rotate it regularly. Since the key is shipped client-side, rotation forces attackers to re-analyze the bundle.
2. Obfuscation: Enable the library's built-in obfuscation for production builds to hide the encryption key and increase the cost of payload forgery.
3. Server-side Validation:
   • Reject fingerprints older than a reasonable threshold (e.g., 60 seconds) to prevent replay attacks.
   • Optionally track and reject duplicate nonces.
4. Monitoring: Monitor fingerprint distributions over time. Sudden spikes or unusual reuse patterns can indicate automated activity.
5. Defense in Depth: Combine fingerprinting with other controls like rate limiting, behavioral analysis, and CAPTCHAs on sensitive endpoints (login, signup, etc.).