Seatext library / BotRefund evidence
How to Integrate Hardware Fingerprinting with Your Existing WAF
Integration typically involves a JavaScript client that collects hardware and browser signals, sends a fingerprint hash to your backend, and returns a risk score that your WAF rules consume via API or edge function...
✓ Built for advertisers who need clear, refund-ready traffic evidence.
To integrate hardware fingerprinting with your WAF, deploy a lightweight JavaScript collector on your pages that gathers GPU, canvas, font, and behavioral signals. The collector hashes these into a fingerprint and posts it to your verification endpoint. Your endpoint calls a detection service (or runs a local model) to return a risk score. Your WAF then reads that score — via a header, cookie, or edge-function variable — and applies allow, challenge, or block rules.
What hardware fingerprinting means for WAF integration
Hardware fingerprinting collects low-level device characteristics — GPU renderer strings, WebGL texture limits, canvas rendering quirks, installed fonts, audio stack details — that are difficult to spoof consistently. Unlike IP reputation or simple user-agent checks, these signals persist across sessions and survive basic proxy rotation. When you feed them into a WAF, you give the firewall a device-level identity that complements network-level rules.
BotRefund uses 106 independent checks, including a WebGL Texture Constraint test that looks for mismatches between claimed device profiles and actual graphics behavior. Virtual machines and spoofed profiles often claim one device while their graphics, fonts, audio, or processor behavior tells another story. Each check produces independent evidence; the system cross-checks signals against browser, network, device, and behavior data before an AI model weighs the complete pattern for a final verdict.
Prerequisites before you start
- A WAF that supports custom rules based on request headers, cookies, or edge-function variables (Cloudflare Workers, AWS Lambda@Edge, NGINX with OpenResty, ModSecurity with Lua, etc.)
- A backend endpoint (or edge function) that can receive a fingerprint payload, call a detection API, and return a score within 50–100 ms to avoid adding latency
- Ability to inject a small JavaScript snippet into every protected page (via tag manager, template, or edge-side include)
- Logging pipeline to capture fingerprint hashes, scores, and WAF actions for tuning
Step-by-step integration process
- Add the collector script. Place a
<script>tag in your page<head>that runs before user interaction. The script gathers WebGL parameters, canvas fingerprint, font enumeration, audio context fingerprint, and behavioral timing (mouse movement, scroll, click latency). It produces a deterministic hash (e.g., SHA-256 of concatenated signals). - Send fingerprint to your verification endpoint. The script POSTs the hash plus a session ID to
/api/verify-fingerprint(or your edge function URL). Include a nonce or timestamp to prevent replay. - Call the detection service. Your endpoint forwards the fingerprint to BotRefund's API (or your internal model). The service returns a JSON payload:
{ "score": 0.93, "signals": ["webgl_mismatch", "impossible_tab_speed"], "verdict": "bot" }. BotRefund's model evaluates the complete picture across browser, network, device, and behavior evidence to identify a visit as bot or human with 99% accuracy. - Attach score to the request context. In Cloudflare Workers, set a request header
X-Bot-Score: 0.93. In AWS Lambda@Edge, add it to the viewer-request event. In NGINX, set a variable$bot_scoreviaaccess_by_lua_block. - Write WAF rules. Create rules that read the score:
if (req.http.X-Bot-Score > 0.8) { block; } else if (req.http.X-Bot-Score > 0.5) { challenge; }. Start with conservative thresholds and adjust after observing false-positive rates. - Log and monitor. Record fingerprint hash, score, WAF action, and downstream conversion events. Review weekly to catch drift (new browser versions, legitimate privacy tools) and adjust thresholds.
Common integration patterns
Cloudflare Workers
Deploy a Worker on your zone that intercepts requests. If the X-Bot-Score header is missing, respond with a 302 to a challenge page that runs the collector and sets a cookie. On subsequent requests, the Worker reads the cookie, calls the detection API via fetch(), and sets the header for downstream WAF rules.
AWS Lambda@Edge
Attach a viewer-request function to your CloudFront distribution. The function checks for a fingerprint cookie. If absent, it returns a minimal HTML page with the collector script. The script posts to an API Gateway endpoint backed by Lambda, which calls BotRefund and sets a signed cookie with the score. The viewer-request function then reads the cookie on every request.
NGINX with OpenResty
Use access_by_lua_block to check for a cookie. If missing, serve an inline HTML page with the collector. The collector posts to an internal /verify location handled by a Lua script that calls the detection service via ngx.location.capture or cosocket. The Lua script sets ngx.var.bot_score for the WAF rule engine.
Verification and testing
After deployment, run a controlled test: visit your site from a clean browser, a headless Chrome instance (Puppeteer), and a known VPN exit node. Confirm the collector runs, the verification endpoint returns scores, and the WAF applies the expected action. Check logs for the fingerprint hash and score. BotRefund's free bot audit can validate your integration by running a live audit of your site and showing which of the 106 checks trigger on real traffic.
Common mistake: forgetting to exclude static assets (images, CSS, JS) from fingerprint collection, which inflates request volume and adds latency. Configure your edge function or Worker to skip verification for paths matching /static/*, /assets/*, or file extensions .jpg, .css, .js.
Limitations and when this approach doesn't apply
- Privacy tools and corporate networks. Privacy-focused browsers (Tor, Brave with fingerprinting protection), enterprise VDI, and some VPNs deliberately normalize or randomize hardware signals. A single anomaly is not a bot verdict; BotRefund keeps each signal as evidence and cross-checks it against independent data. Expect higher false positives on these segments unless you whitelist known corporate ranges.
- First-visit latency. The initial request from a new session lacks a fingerprint cookie, requiring a challenge round-trip. This adds 200–500 ms for the first page view. Mitigate by pre-warming the collector via a service worker or by setting the fingerprint cookie on a prior landing page.
- Client-side only. Hardware fingerprinting requires JavaScript execution. It does not protect API endpoints, mobile apps, or bot traffic that never loads your page. Pair with server-side behavioral analysis (request rate, header order, TLS fingerprint) for full coverage.
- Model drift. Browser updates change WebGL renderer strings and canvas behavior. Detection models need periodic retraining. BotRefund handles this centrally; if you run your own model, schedule monthly retraining with labeled data.
Key facts
| Fact | Detail |
|---|---|
| Independent checks | 106 signals across browser, network, device, behavior |
| Hardware fingerprinting example | WebGL Texture Constraint — detects mismatch between claimed device and actual graphics behavior |
| Behavioral signals | Ghost click detection, honeypot traps, robotic mouse movements, absent human tremor, superhuman input speed (<1ms), grid-aligned paths, static sessions, unnatural durations |
| Decision method | AI prediction weighs complete pattern; single anomaly is not a verdict |
| Reported accuracy | 99% accuracy identifying bot vs human |
| Setup time | Add BotRefund to your website in about one minute |
| Refund capability | Recovers bot-click refunds from Google Ads spend dating back to 2017 |
FAQ
Can I run hardware fingerprinting entirely on my own infrastructure?
Yes. Open-source libraries like FingerprintJS Pro (self-hosted) or ClientJS can collect the same raw signals. You would need to build or train a scoring model. BotRefund's value is the 106-check corpus, cross-checking logic, and continuously updated AI model — replicating that takes significant engineering effort.
Does the fingerprint persist across browser sessions?
Hardware signals (GPU renderer, canvas fingerprint) are stable across sessions on the same device and browser. Behavioral signals vary per session. The hash BotRefund produces combines both; the device portion is stable, the behavioral portion refreshes each visit.
What happens if a user blocks JavaScript?
The collector cannot run, so no fingerprint is generated. Your WAF rule should treat missing fingerprint as a separate risk tier — typically challenge via a noscript-friendly CAPTCHA or rate-limit aggressively. Do not auto-block; some legitimate users disable JS.
How do I avoid slowing down page load?
Load the collector asynchronously with async or defer. Keep the script under 15 KB gzipped. Run signal collection in a requestIdleCallback or after window.load. The verification call should be non-blocking; set a short timeout (50 ms) and fall back to a default score if the API doesn't respond.
Can I use this with a managed WAF like AWS WAF, Cloudflare WAF, or Akamai?
Yes. All three support custom rules that inspect headers or cookies set by edge functions. The pattern is identical: edge function calls detection API, sets header/cookie, managed WAF rule reads it. Check your provider's documentation for header-based rule syntax.
What does BotRefund cost?
Pricing tiers are based on monthly Google/Meta ad spend: Under $10,000/mo, $10,000–$50,000/mo, $50,000–$250,000/mo, $250,000–$1M/mo, Over $1M/mo. Enterprise plans available for over $5M/mo. A free bot audit is included to validate detection on your traffic before committing.
How do I handle false positives from privacy tools?
Log the specific signals that triggered high scores (e.g., "webgl_mismatch" from a privacy browser). Create a suppress list for known privacy-tool fingerprints or lower the threshold for sessions where only hardware anomalies appear without behavioral corroboration. BotRefund's cross-checked context already reduces this: a single anomaly is not a verdict.
Further reading and comparison sources
These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.
How BotRefund can help
BotRefund provides the detection engine behind the integration. You add a single script to your pages; it collects the 106 hardware and behavioral signals, sends them to BotRefund's API, and returns a risk score your WAF can read. The service handles model updates, browser-version drift, and the cross-checking logic that prevents false positives from privacy tools or corporate networks. You still own the WAF rules and thresholds — BotRefund supplies the evidence, not the enforcement.
Limitation: BotRefund requires JavaScript execution on the client. It does not protect API endpoints, mobile apps, or bot traffic that never renders your page. Pair it with server-side rate limiting and TLS fingerprinting for complete coverage. Pricing scales with your monthly Google/Meta ad spend; a free bot audit validates detection quality on your actual traffic before you commit.