Bot protection

Block headless browsers and scripted input.

10 minutes

Scripts that sign up, log in, scrape or buy faster than people do usually run in a headless or automated browser. Trace detects the automation itself, not just the IP, so it still works when the bot rotates proxies.

What you will build: a check in front of a sensitive endpoint that blocks automated browsers and sends doubtful ones to a challenge.

The signals that matter

SignalDetectsDefault weight
botHeadless Chrome, navigator.webdriver, Puppeteer, Playwright and Selenium traces60
automatedInputClicks and keys created by scripts, ruler-straight pointer paths30
antiDetectBrowsers that contradict themselves, like anti-detect profiles40
tlsMismatchA TLS fingerprint that no real browser sends (needs a proxy header)30
datacenterIpTraffic from cloud and hosting ranges15
velocityToo many events per visitor, IP or account in a short window20
  1. 1

    Identify late

    Call get() right before the protected action (the submit, not the page load). automatedInput watches input between the SDK starting and get(), so the gap gives it something to look at.

    TypeScript
    const trace = createClient({ apiKey, endpoint }); // on page load
    // ...
    const { eventId } = await trace.get({ tags: { action: 'login' } }); // on submit
  2. 2

    Decide on the server

    TypeScript
    const event = await verifyEvent(eventId, { secretKey, endpoint, timeoutMs: 1500 }).catch(() => null);
    const s = event?.signals;
    
    if (s?.bot.detected || s?.tlsMismatch.detected) return res.status(403).end();
    if (s?.automatedInput.detected || s?.antiDetect.detected || (event?.suspectScore ?? 0) >= 40) {
      return res.status(401).json({ next: 'captcha' });
    }

    event.reasons lists which signals added how much, for example [{ "signal": "bot", "contribution": 60 }]. Log it with every decision so you can explain a block later.

  3. 3

    Make it hard to skip

    A bot can simply not run your JavaScript. Make the eventId required on the endpoint:

    TypeScript
    if (!eventId) return res.status(400).json({ error: 'missing_device_check' });

    Then a missing or made-up eventId fails verification, and a replayed one is still tied to the original visitor. Events expire after 60 minutes.

    Mind the false positives

    Accessibility tools, some privacy extensions and corporate VPNs can trip weaker signals. Block only on strong ones (bot, tlsMismatch) and challenge on the rest.

Next steps

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.