WebDecoy SDKs: TLS Fingerprinting for Node, Go & PHP

We’re excited to announce the release of WebDecoy’s official SDKs for Node.js, Go, and PHP (WordPress)! These SDKs bring enterprise-grade bot detection to your backend applications with a powerful new capability: TLS fingerprinting.

In this post, we’ll introduce the new SDKs, explain what TLS fingerprinting is, dive deep into JA3 and JA4 fingerprinting techniques, and show you how WebDecoy uses these technologies to protect your applications from sophisticated botnets.

What’s New: WebDecoy SDKs

Our new SDKs make it incredibly easy to integrate WebDecoy’s AI-powered bot detection into your server-side applications:

🟢 Node.js SDK

Perfect for Express, Next.js, and other Node.js frameworks. Simple middleware integration with full TypeScript support.

🔵 Go SDK

Lightweight and performant, designed for high-throughput Go applications with native support for standard net/http handlers.

🟣 PHP SDK (WordPress)

Built specifically for WordPress, with seamless integration into your existing plugins and themes. Protect your WP admin, forms, and API endpoints.

All three SDKs now support comprehensive TLS fingerprinting, allowing WebDecoy to detect bots with unprecedented accuracy.

Understanding TLS Fingerprinting

TLS (Transport Layer Security) fingerprinting is a technique for identifying clients based on the unique characteristics of their TLS handshake—the initial “hello” message sent when establishing an HTTPS connection.

Why TLS Fingerprinting Matters

Every TLS client (browser, bot, script) has a unique “signature” based on:

• TLS version (1.2, 1.3)
• Cipher suites (encryption algorithms it supports)
• Extensions (additional TLS features)
• Supported groups (elliptic curves for key exchange)
• Signature algorithms
• ALPN protocols (Application-Layer Protocol Negotiation)

Real browsers like Chrome, Firefox, and Safari have very specific TLS configurations. Automated tools like curl, wget, python-requests, and headless browsers have distinctly different fingerprints.

The Problem with Traditional Bot Detection

Traditional bot detection methods rely on:

• User-Agent strings (easily spoofed)
• IP reputation (VPNs and proxies bypass this)
• Behavioral analysis (sophisticated bots can mimic human behavior)

TLS fingerprinting is different. It’s based on low-level cryptographic handshake details that are extremely difficult to fake without completely reimplementing a browser’s TLS stack.

JA3 Fingerprinting: The Foundation

JA3 is a standardized method for creating TLS fingerprints, developed by Salesforce in 2017.

How JA3 Works

JA3 creates a fingerprint from the TLS ClientHello message by concatenating:

1. TLS Version
2. Cipher Suites (in order)
3. Extensions (in order)
4. Elliptic Curves (supported groups)
5. EC Point Formats

These values are joined with commas and hyphens, then MD5 hashed to create a unique fingerprint.

Example:

771,4866-4865-4867,0-11-10-35-23,29-23-24,0

↓ MD5 Hash ↓

e7d705a3286e19ea42f587b344ee6865

This fingerprint uniquely identifies the TLS client.

JA3 in Action: Detecting curl

Let’s say a bot sends this request:

{
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0",
  "tls_info": {
    "version": 771,
    "cipher_suites": [49195, 49199, 52393, 52392, 49196],
    "extensions": [0, 23, 65281, 10, 11, 35, 16]
  }
}

The User-Agent claims to be Chrome on Windows, but when we generate the JA3 fingerprint:

JA3: e7d705a3286e19ea42f587b344ee6865

This fingerprint matches curl 7.x, not Chrome!

Result: WebDecoy detects the mismatch and blocks the request.

Limitations of JA3

While powerful, JA3 has some limitations:

• ❌ TLS 1.3 Challenges: TLS 1.3 encrypts more of the handshake, hiding some details
• ❌ Extension Ordering: JA3 doesn’t capture the full ordering complexity
• ❌ GREASE Values: Modern browsers use randomized GREASE values that can change fingerprints
• ❌ Evasion: Sophisticated attackers can use tools like uTLS to mimic browser fingerprints

This is where JA4 comes in.

JA4 Fingerprinting: The Next Generation

JA4 is a modern TLS fingerprinting method developed in 2023 to address JA3’s limitations.

What Makes JA4 Better?

JA4 provides a more comprehensive fingerprint by including:

1. TLS ClientHello (like JA3, but improved)
2. HTTP/2 Headers and their ordering
3. TCP Metadata (window size, options)
4. TLS Server Response (JA4S - server fingerprint)
5. ALPN Protocol Negotiation
6. GREASE Handling (filters out randomized values)

JA4 Components

JA4 actually consists of multiple fingerprints:

• JA4 - Client TLS fingerprint
• JA4S - Server TLS fingerprint
• JA4H - HTTP client fingerprint
• JA4X - X.509 certificate fingerprint

Together, these create a multi-dimensional fingerprint that’s extremely difficult to spoof.

Why JA4 is Harder to Evade

Unlike JA3’s simple MD5 hash, JA4 uses a structured format that captures:

• Extension order (not just presence)
• Signature algorithm preferences
• ALPN protocol order
• TLS version negotiation patterns

This makes it nearly impossible for bots to perfectly mimic a real browser without using an actual browser engine.

How WebDecoy Uses TLS Fingerprinting

WebDecoy’s SDK integration brings TLS fingerprinting into your application’s detection flow:

1. Enhanced TLS Data Collection

Our SDKs capture comprehensive TLS parameters from incoming requests:

// Node.js SDK Example
const tlsInfo = {
  version: socket.getProtocol(),           // e.g., "TLSv1.3"
  cipherSuites: socket.getCipherSuites(),  // Array of supported ciphers
  extensions: socket.getExtensions(),       // TLS extensions
  supportedGroups: socket.getSupportedGroups(),
  signatureAlgorithms: socket.getSignatureAlgorithms(),
  alpnProtocols: socket.getALPNProtocols(),
  sniHostname: socket.getServerName()
};

2. Fingerprint Generation

WebDecoy automatically generates both JA3 and JA4 fingerprints from the TLS data:

SDK Request → Extract TLS Parameters
              ↓
              Generate JA3 Fingerprint
              Generate JA4 Fingerprint
              ↓
              Send to WebDecoy API

3. Known Bot Database

WebDecoy maintains a comprehensive database of known bot fingerprints:

• curl (all versions)
• wget
• python-requests
• Go http.Client
• Java HttpClient
• Scrapy
• Selenium (various configurations)
• Puppeteer (headless Chrome)
• Playwright
• And hundreds more…

4. Intelligent Mismatch Detection

WebDecoy compares the TLS fingerprint with the User-Agent header:

User-Agent: "Mozilla/5.0 (Chrome/120...)"
JA3 Fingerprint: e7d705a3286e19ea42f587b344ee6865 (curl)

→ MISMATCH DETECTED!

5. Weighted Threat Scoring

Based on the fingerprint analysis, WebDecoy adds score boosts:

• +40 points - Known bot fingerprint match
• +confidence/2 points - TLS/User-Agent mismatch
• +25 points - Outdated TLS version (TLS 1.0, 1.1)
• +15 points - Suspicious cipher suite combination

Real-World Detection Example

Let’s walk through a complete detection scenario:

The Attack

A sophisticated scraper tries to access your API:

POST /api/products HTTP/2
Host: yoursite.com
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) 
            AppleWebKit/537.36 Chrome/120.0.0.0 Safari/537.36

The User-Agent claims to be Chrome on macOS.

WebDecoy’s Analysis

Step 1: TLS Fingerprint Generation

TLS Version: 771 (TLS 1.2)
Cipher Suites: [49195, 49199, 52393, 52392, 49196]
Extensions: [0, 23, 65281, 10, 11, 35, 16]

→ JA3: e7d705a3286e19ea42f587b344ee6865

Step 2: Database Lookup

JA3 e7d705a3286e19ea42f587b344ee6865 matches:
  - curl 7.68.0
  - curl 7.74.0
  - curl 7.81.0

Step 3: Mismatch Detection

User-Agent: Chrome 120 on macOS
TLS Fingerprint: curl 7.x

→ CRITICAL MISMATCH

Step 4: Threat Score Calculation

Base Score: 0
+ Known Bot Fingerprint: +40
+ TLS/UA Mismatch: +45 (confidence 90 / 2)
+ TLS 1.2 (Chrome 120 uses TLS 1.3): +15
─────────────────────────────────
Final Threat Score: 100

→ VERDICT: HIGH THREAT - BLOCK

The Result

WebDecoy blocks the request and logs the detection:

{
  "threat_score": 100,
  "verdict": "block",
  "reasons": [
    "Known bot fingerprint: curl 7.x",
    "TLS fingerprint mismatch with User-Agent",
    "Outdated TLS version for claimed browser"
  ],
  "ja3": "e7d705a3286e19ea42f587b344ee6865",
  "ja4": "t13d1516h2_8daaf6152771_b0da82dd1658"
}

Why This Matters: The Arms Race

Bot developers are getting more sophisticated:

❌ What Doesn’t Work Anymore

• Simple User-Agent spoofing - Too easy to detect
• IP rotation - VPNs and proxies are cheap
• Behavioral mimicry - AI can generate human-like patterns

✅ What Still Works: TLS Fingerprinting

TLS fingerprinting is effective because:

1. Low-level protocol details - Requires deep TLS stack knowledge
2. Hard to fake - Can’t just change a header string
3. Consistent - Same tool = same fingerprint
4. Multi-layered - JA4 combines multiple signals

Even sophisticated tools like Selenium and Puppeteer have distinctive fingerprints because they use different TLS implementations than real browsers.

Getting Started with WebDecoy SDKs

Ready to add TLS fingerprinting to your application?

Node.js

npm install @webdecoy/express

const { webdecoy } = require('@webdecoy/express');

app.use(webdecoy({
  apiKey: 'your-api-key',
  enableTLSFingerprinting: true
}));

For the core SDK without Express, install @webdecoy/node and call webdecoy.protect(metadata) directly.

Go

go get github.com/webdecoy/go-sdk

import "github.com/webdecoy/go-sdk"

wd := webdecoy.New(webdecoy.Config{
    APIKey: "your-api-key",
    EnableTLSFingerprinting: true,
})

http.Handle("/", wd.Middleware(yourHandler))

PHP (WordPress)

composer require webdecoy/wordpress-plugin

use WebDecoy\WordPress\WebDecoy;

$webdecoy = new WebDecoy([
    'api_key' => 'your-api-key',
    'enable_tls_fingerprinting' => true
]);

add_action('init', [$webdecoy, 'protect']);

Advanced Configuration

All SDKs support flexible TLS fingerprinting options:

{
  enableTLSFingerprinting: true,
  
  // Fallback mode for environments where full TLS data isn't available
  tlsFallbackMode: 'simple',
  
  // Custom fingerprint database
  customBotFingerprints: [
    { ja3: 'abc123...', name: 'Custom Bot' }
  ],
  
  // Adjust scoring weights
  scoringWeights: {
    knownBotFingerprint: 40,
    tlsUaMismatch: 45,
    outdatedTls: 15
  }
}

Conclusion: The Future of Bot Detection

TLS fingerprinting represents a significant leap forward in bot detection technology. By analyzing the cryptographic handshake that happens before any HTTP data is exchanged, WebDecoy can identify bots with exceptional accuracy—even when they perfectly mimic browser behavior at the application layer.

Combined with WebDecoy’s honeypot technology and AI-powered behavioral analysis, TLS fingerprinting creates a multi-layered defense that’s extremely difficult for bots to bypass.

Key Takeaways

✅ TLS fingerprinting analyzes low-level handshake details
✅ JA3 provides basic fingerprinting (MD5 hash of TLS parameters)
✅ JA4 offers advanced, multi-dimensional fingerprinting
✅ WebDecoy SDKs make implementation effortless
✅ Known bot database catches common automation tools
✅ Mismatch detection identifies spoofed User-Agents
✅ Weighted scoring provides nuanced threat assessment

Get Started Today

Ready to protect your application with advanced TLS fingerprinting?

Try WebDecoy for free and see how our SDKs can stop even the most sophisticated bots.

Have questions? Join our Discord community or read the full SDK documentation.