Skip to Content
Proof & ValidationCanvasLab

CanvasLab: Canvas Forensics and Tracking Analysis

Record Canvas 2D, WebGL, and WebGL2 API calls to study tracking techniques and verify fingerprint protection.

Prerequisites

  • BotBrowser installed and running. See Installation Guide.
  • A profile file (.enc for production).

Quick Start

Record all Canvas API calls to a JSONL file:

chromium-browser \
    --bot-profile="/path/to/profile.enc" \
    --bot-canvas-record-file=/tmp/canvaslab.jsonl \
    --user-data-dir="$(mktemp -d)" \
    "https://example.com"

After the session, /tmp/canvaslab.jsonl contains every Canvas 2D, WebGL, and WebGL2 API call the page made. Open it in the Replay Viewer  to inspect calls interactively.

How It Works

When --bot-canvas-record-file is set, BotBrowser intercepts every Canvas API call at the browser engine level and writes it to a JSONL file. Each line is a JSON object representing one API call, including:

  • Event type: canvas_init, context_create, state, draw, read, resize
  • Full parameters: all arguments serialized (ImageData as base64, Path2D as command arrays, gradients as color stops)
  • Return values: synchronous returns, callback results, and promise resolutions
  • Source location: URL, line number, column number, and function name of the calling code
  • Execution context: sequence number, timestamp, thread ID, canvas ID

Noise variance is disabled during recording so captured data reflects the raw API calls.

Common Scenarios

Record and analyze with Playwright

import { chromium } from "playwright-core";
 
const browser = await chromium.launch({
    executablePath: process.env.BOTBROWSER_EXEC_PATH,
    headless: true,
    args: [
        `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
        "--bot-canvas-record-file=/tmp/canvaslab.jsonl",
    ],
});
 
const page = await browser.newPage();
await page.goto("https://example.com");
// Let the page run its Canvas operations
await page.waitForTimeout(5000);
await browser.close();
 
// Now inspect /tmp/canvaslab.jsonl

View recordings in the Replay Viewer

Open the HTML-based replay viewer to inspect recordings interactively:

  1. Navigate to the Live Replay Viewer 
  2. Load your .jsonl file
  3. Scrub through events, view generated code, and watch canvas rendering step by step

Identify which tracking library made each call

Every recorded event includes a caller field with the source location:

{
  "type": "draw",
  "method": "fillRect",
  "args": [0, 0, 300, 150],
  "caller": {
    "url": "https://example.com/fingerprint.js",
    "line": 42,
    "column": 16
  }
}

Use this to trace which scripts are performing Canvas fingerprinting operations.

Cross-platform protection validation

Record the same page on multiple platforms and compare the JSONL output to verify that BotBrowser’s noise and rendering produce consistent protection:

# Record on Linux host
chromium-browser \
    --bot-profile="/path/to/win-profile.enc" \
    --bot-canvas-record-file=/tmp/canvaslab-linux.jsonl \
    --user-data-dir="$(mktemp -d)" \
    "https://example.com"
 
# Compare with recording from macOS host
diff /tmp/canvaslab-linux.jsonl /tmp/canvaslab-macos.jsonl

Troubleshooting / FAQ

ProblemSolution
JSONL file is emptyEnsure the page actually uses Canvas APIs. Try a known fingerprint test site like CreepJS .
File path not writableUse an absolute path and ensure the directory exists. BotBrowser does not create parent directories.
Noise is different during recordingNoise variance is intentionally disabled during recording to capture raw API calls. This is expected behavior.
Large JSONL filePages with heavy Canvas or WebGL usage (games, 3D visualizations) can generate large files. Filter by event type when analyzing.

Next Steps

Related documentation: CanvasLab Tool  | CLI Flags: —bot-canvas-record-file

Legal Disclaimer & Terms of Use  • Responsible Use Guidelines . BotBrowser is for authorized fingerprint protection and privacy research only.

BenchmarkAudioLab