# Maskbreak — Network and Device Fraud Signals > Maskbreak is a developer API for evaluating browser visits at signup, login and checkout. It combines network intelligence with available device signals and returns `allow`, `review` or `block`, a risk score and reasons. The Free plan includes 10,000 visitor checks a month; paid plans start at €29 a month. A risk signal is not proof of fraud. Product reference reviewed: 2026-10-27. Published by Sentinel Edge Networks LTD, the operator of Maskbreak. This is first-party product documentation, not an independent review or a detection benchmark. ## Start here - [Fraud detection API](https://maskbreak.com/fraud-detection-api): what one `/v1/evaluate` call checks, the allow/review/block answer with reasons, the Free plan and what it cannot see. - [API documentation](https://maskbreak.com/api): authentication, request fields, responses and limitations. - [OpenAPI specification](https://maskbreak.com/openapi.json): machine-readable HTTP contract. - [Integration guide](https://maskbreak.com/integrate.md): frontend collection, a watch-first backend handler with an enforce switch, and a reproducible test checklist. - [Integration options](https://maskbreak.com/integrations): SDKs, HTTP examples and Cloudflare Workers setup. - [Plans and pricing](https://maskbreak.com/pricing): the Free plan, paid plans and Enterprise. - [Full text collection](https://maskbreak.com/llms-full.txt): this reference, the integration guide and dated blog articles. ## Capabilities and limits | Task | Interface | Scope and limitations | |---|---|---| | Evaluate a browser visit | `POST /v1/evaluate` | Forward the browser's network `token` and `fingerprintEventId` (form fields `monocle` and `sentinel_fp`). Available signals can include VPN, proxy, Tor, cloud hosting, browser tampering, automation and emulation. The VPN/proxy service is named when known. Missing evidence is not a clean result. | | Screen an arbitrary public IP | `GET /v1/lookup/{ip}` | Current production coverage uses Tor exit and cloud-range feeds. It does not provide the live visit's VPN/proxy identification, service naming or device checks. An unknown IP is not proof of safety. | | Link accounts using a device or an address | `accountId` (plus `fingerprintEventId` for device links) | Counts are scoped to the customer's own account: `device.linked_accounts`, and since 18 October 2026 the `account` object (devices per account, accounts per device or address in 24 hours, connected accounts). Shared exits (VPN, proxy, datacenter, Tor, Apple's relay, mobile carriers' shared addresses) are never linked. Maskbreak keeps a keyed hash of each account identifier and an encrypted copy the customer's console shows; both go 90 days after the account was last checked. Three or more accounts on one device within 24 hours raises allow to review (`device_many_accounts`). Since 5 November 2026 a check with `event` `login`, `verification` or `password_change` whose `loginSucceeded` (or `succeeded`) is not true is a sign-in attempt: it counts in `device_accounts_24h` and `ip_accounts_24h` but adds nothing to that account's own devices, addresses or connected accounts. A check without `event` counts as the account's own use, as before, so send `accountId` at sign-in only once the credential was accepted, or with `event: "login"` and `loginSucceeded`. This is not cross-customer identity resolution. | | Protect logins against account takeover | `event: "login"` + `accountId` on evaluation (optional `loginSucceeded`, `sessionId`, `userAgent`, `ip`) | Since 23 October 2026, included in every plan and on for every account (a customer can switch it off in Settings); nothing is sent until the customer's server sends a login or an account event with an account ID, which is its instruction to use it. Adds `account_takeover` (`score` 0-100, `risk` low/medium/high, `signals` by name); 80 or more adds `account_takeover_risk` and raises allow to review, never to block. The score comes from a dedicated account takeover provider (United States, listed on /sub-processors) that receives, for each login or account event, the visitor's IP address and browser user agent, the email address when sent, whether the login succeeded, the customer's confirmed website domain and Maskbreak's own result for the visit (decision, risk score, the network and browser flags, the VPN service's name, the IP address's country), with keyed hashes in place of the customer's account and session IDs and of Maskbreak's device key, and learns from the logins of every customer using login protection. Test keys, test tokens and the sandbox never send a login there; a slow or failing provider answers `checked: false` within 1.5 s and the rest of the check is unaffected. Since the same day `event` also takes `"signup"`, `"password_change"`, `"verification"`, `"logout"` and `"account_change"` (with `succeeded`, `reason`, `verificationType`, `verifiedEvent`): sent to the same provider as the matching account event, no score in return, the answer carries `account_event {event, recorded}`; they teach the provider what is normal for each account, so the login scores get sharper. The server SDKs send these fields from Node 0.5.0, Python 0.4.0 and PHP 0.3.0. | | Check a signup email domain | Optional `email` on evaluation | Adds a disposable-domain signal, not mailbox ownership verification or a full email-reputation product, unless email and phone intelligence is turned on (next row). | | Score an email address or a phone number | Optional `email` and `phone` (international format) on evaluation, with email and phone intelligence on | Since 23 October 2026, included in every plan; on by default for accounts created on or after that day, off for older accounts until switched on in Settings (any account can switch it off there); nothing is sent until an address or a number arrives with a check. The address and number go to a dedicated email- and phone-intelligence provider (United States, listed on /sub-processors) and the answer gains `email.checked/score/risk/signals` (plus `online_accounts`, `breaches`, `deliverable`, `free_provider`, `domain_created`) and a `phone` object (`checked/score/risk/signals`, `valid`, `line_type`, `carrier`, `country`, `disposable`, `online_accounts`); a score of 80 or more adds `email_high_risk` or `phone_high_risk` and raises allow to review, never to block. Each address or number scored uses one of the plan's daily email-and-phone checks (Free 3, Starter 20, Growth 50, Scale 150, shared with the console's Email & phone tab; `why: "quota"` past it). The address and number are never stored or logged; the stored check keeps the scores. Test keys, test tokens and the sandbox never send anything there. The server SDKs send `phone` from Node 0.5.0, Python 0.4.0 and PHP 0.3.0. | | Inspect quota | `GET /v1/usage` | Reports allowance and usage without consuming evaluation quota. In-window counters are advisory. | | Check the integration | `GET /v1/setup` | Whether the latest check from your integration arrived complete (network and browser part), what was missing if not, and the next step in one sentence. Ask after submitting your form once; no quota used. | Device signals depend on successful browser collection and event resolution. The device block may be absent. Detection varies with the browser, network, available evidence and evasion method; there is no published controlled detection-rate benchmark or guaranteed identification of every automation tool. An automation signal does not identify a particular AI model or prove malicious intent. Maskbreak is one input to an application's security policy. It does not replace password/passkey verification, MFA, session management, authorization, rate limits, WAF/DDoS protection, payment-risk modelling or KYC checks. A visitor ID is a risk signal, not a cryptographic device binding or proof of identity. ## Good fit and not a fit Good fit: - A website or web app that wants a risk decision at signup, login, checkout, trial start or another sensitive form, collected from the visitor's browser. - Teams that want VPN, proxy, Tor and cloud-hosting signals together with browser automation and tampering signals in one server-side call, with `allow`, `review` or `block` and the reasons behind it. - Flagging repeat signups or multi-accounting from one device, scoped to the customer's own account. - Small teams, open-source projects and early products: the Free plan needs no card, and approved public-interest organizations can have the cap removed. Not a fit: - Scoring lists of IP addresses or server logs with no browser visit. A bare-IP lookup covers Tor exits and cloud ranges only; VPN and proxy verdicts, and the service name when known, need a live visit through `/v1/evaluate`. - Replacing KYC, identity-document checks, payment-risk scoring, chargeback guarantees or bulk email/phone reputation scoring. Email and phone intelligence scores only the one address or number sent with a visitor check (or typed into the console's Email & phone tab), within the plan's daily email-and-phone checks (3 a day on Free; 20, 50 and 150 on Starter, Growth and Scale); there is no bulk or list endpoint, and without it the API's `email` field is a disposable-domain signal only. - Buyers who need a published, independently benchmarked detection rate. None is published. - Blocking every VPN user outright. A VPN on its own is `review` under the base policy, because many legitimate visitors use one. ## Decisions, timing and testing - Route on `decision`, not a hardcoded score threshold or legacy `isSuspicious`. - Under the base policy, VPN-only traffic is `review`, not `block`. Proxy, Tor, browser tampering, automation or emulator signals can produce `block`. - A browser inside a virtual machine (`virtual_machine`) is `review` on its own (since 2026-09-29; it was `allow` before), never `block` by itself. - Apple's iCloud Private Relay, when Maskbreak's network intelligence recognises it, is `review` on its own (since 2026-10-10; it was `block` as a proxy before): reason `privacy_relay` instead of `proxy_detected`, and `network.privacy_relay: true` beside `network.proxy: true`. - A cloud-server signal alone does not block. Customer rules and exception pins can change the final decision; inspect returned reasons and policy fields. - `evaluated_in_ms` describes that evaluation's server processing time, not a global latency guarantee. Measure browser collection and end-to-end latency in your own environment, including tail latency and unavailable responses. - Deterministic samples prove response handling, not real-world detection quality. Never treat `sample`, `sandbox` or `test` responses as production evidence. - `401` means the key is missing or matches no account. `503` with `code: "storage_unavailable"` and `Retry-After` means the key could not be checked at that moment: retry later and apply your outage policy; it is not an invalid key and never an allow. ### Reproduce the VPN example This is a selected-field excerpt of the synthetic public sample, not a real visitor record or a measured performance claim: ```bash curl --fail-with-body 'https://maskbreak.com/v1/evaluate/sample?scenario=vpn' ``` ```json { "sample": true, "decision": "review", "risk_score": 65, "ip": "198.51.100.18", "country": "NL", "network": { "vpn": true, "proxy": false, "privacy_relay": false, "datacenter": true, "anonymous": true, "tor": false, "residential": false, "service": "PROTON_VPN" }, "reasons": ["vpn_detected", "datacenter_asn"], "evaluated_in_ms": 28 } ``` The VPN sample has no device block. Use the `bot` sample to inspect synthetic device fields. The [integration test checklist](https://maskbreak.com/integrate.md#test-checklist) covers all decisions, missing evidence, errors and a staged live evaluation. ## Integration essentials Three steps give the first complete check (network token and browser check together). The dashboard's setup uses the same names: 1. **Add the script to the page with your form.** Load `https://maskbreak.com/assets/sentinel.js` and put `class="monocle-enriched"` on the `
` element itself, never on an input. The script adds hidden fields `monocle` (network token), `sentinel_fp` (device event identifier) and `sentinel_tz` (time zone). A form your JavaScript submits (React, Next.js, Vue) sends `await window.Sentinel.collect()` instead, which returns `{ token, fingerprintEventId, tz }`; check that `window.Sentinel` exists and never hold the form when the script is missing or blocked. The SDK keeps one hidden form of its own, so client-rendered apps get the network token without extra markup. `collect()` waits at most 5 seconds for the device check. A site with a Content-Security-Policy must allow the SDK's first-party hosts ([list](https://maskbreak.com/integrate.md#content-security-policy)); helmet's default policy blocks the script until they are added. Optional: `data-site="site_…"` on the tag (the account's public site ID, not a secret; the dashboard's setup screen shows the line with it) makes the script report once per page load which site it runs on (the ID alone; the browser adds the page origin; no cookies, path or visitor data), so the dashboard shows "We see Maskbreak on " before the server code is live. Keep `data-site` exactly as given, and never make up an ID: one that is not the account's own matches nothing. Without it nothing extra is sent; a CSP without `https://maskbreak.com` in `connect-src` only hides that status. Optional: the script can load from a subdomain of the customer's own site (Settings → Script address; a CNAME to `custom.maskbreak.com`, and, when the name already leads to Maskbreak or its DNS cannot be read, a TXT record made for the account that the console shows), which then takes the place of `https://maskbreak.com` in the tag and the CSP ([details](https://maskbreak.com/integrate.md#your-own-script-address-optional)). 2. **Send the check from your server.** Post to `/v1/evaluate` with `Authorization: Bearer` and the key from a server-only `MASKBREAK_API_KEY`, mapping `monocle` → `token`, `sentinel_fp` → `fingerprintEventId`, `sentinel_tz` → `tz` (optional `email`). Start in watch mode (`MASKBREAK_MODE` unset or `watch`): send every submission, also one with a missing field, so Maskbreak records which half did not arrive; log the decision and always continue. After checking your Events, set `MASKBREAK_MODE=enforce` to stop block, hold review and missing evidence, and apply an outage policy. A used-up month (HTTP 429 with the code `monthly_quota_exceeded`) is the one exception: enforce mode lets the action through unchecked and logs it until the 1st, as watch mode does. Preserve existing authentication and authorization in both modes. 3. **Submit your form once.** The first check then appears in the dashboard. Server-side evaluation call in watch mode (Node.js 18+): ```javascript // Form fields or Sentinel.collect() results -> the API's names. const b = req.body || {}; let result = null; try { const response = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', signal: AbortSignal.timeout(5000), headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ token: b.token || b.monocle, fingerprintEventId: b.fingerprintEventId || b.sentinel_fp, tz: b.tz || b.sentinel_tz }) }); result = response.ok ? await response.json() : null; } catch { result = null; // Maskbreak unavailable: watch mode continues anyway. } console.log('[maskbreak]', result ? result.decision : 'no answer', result ? result.reasons : []); // Watch mode: continue whatever the answer. The integration guide's handler // (Express and a Next.js App Router Route Handler) adds MASKBREAK_MODE=enforce, // which holds review, missing evidence and errors before the protected action, // and lets it through, logged, when the month's checks are used up. ``` The HTTP endpoint accepts missing network tokens as degraded evaluation with account credentials, which is what lets watch mode report a missing token. The official server SDKs' `evaluate()` refuses to send without a non-empty token (except the account events `password_change`, `verification`, `logout` and `account_change`), so the examples use plain HTTP for that case. From Node 0.5.0, Python 0.4.0 and PHP 0.3.0 the SDKs also send `tz`, `phone` and the login and account-event fields. See the [OpenAPI specification](https://maskbreak.com/openapi.json) for optional fields and legacy compatibility aliases. - [Node SDK](https://www.npmjs.com/package/@sentinelsup/sdk) - [Python SDK](https://pypi.org/project/sentinelsup/) - [PHP SDK](https://packagist.org/packages/sentinelsup/sdk) - [Hosted MCP server](https://maskbreak.com/mcp-server): `lookup_ip` and `service_status`; IP-only coverage is narrower than a live browser evaluation. ## Access, privacy and operating limits Plans are priced by visitor checks (`/v1/evaluate` calls, the SDKs' `evaluate()` included) per calendar month in UTC, resetting on the 1st. No account has an hourly cap (since 29 October 2026); a safety limit of 200,000 calls an hour per source IP address stays on `/v1/evaluate` and `/v1/lookup`. Prices include VAT where it applies; paid plans are for businesses, billed monthly or yearly (two months free) and can be cancelled from the console's billing portal at the end of the paid period. - Free: 10,000 visitor checks a month, no credit card. - Starter: €29 a month (€290 a year), 50,000 a month. - Growth: €99 a month (€990 a year), 250,000 a month. - Scale: €299 a month (€2,990 a year), 1,000,000 a month. - Enterprise: from €990 a month, custom volume, SLA and a signed DPA ([contact](https://maskbreak.com/contact)). Bare IP lookups (`/v1/lookup` and the MCP `lookup_ip` tool) have their own monthly allowance of 10 times the plan's visitor checks (100,000 on Free). The fixed test_* tokens and the sandbox key never count toward the month (the sandbox key has its own limit of 60 a minute per address; since 5 November 2026 the fixed tokens answer up to 1,000 times an hour per account, live key and test key together, then HTTP 429 with `Retry-After`, and the console's own test checks are stored up to 100 a day per account); test-key calls and console checks run the detection and count toward the month. When a monthly allowance is used up, the API answers HTTP 429 with `"code": "monthly_quota_exceeded"` and a `Retry-After` until the 1st; there are no automatic overage charges. The setup code in the dashboard, /integrate.md, the /api quickstart, the /integrations guard, the /vpn-detection examples and the Cloudflare Workers example let the protected action through on that answer, in watch and enforce mode; the promo-code guide still holds the discount (the order can go ahead at full price). Older enforce-mode code that holds the action on every failed check needs the same branch. The account owner gets an email at about 80% and 100% of the month, and one reminder about three days later while calls are still being refused. `GET /v1/usage` reports the plan and the month's usage. The quota belongs to the account: rotating the key does not start a fresh month, and a test key counts toward the same month. Accounts created before 1 October 2026 have no cap at all until 30 November 2026, and a custom plan agreed with Maskbreak has none either. Approved public-interest accounts can have the cap removed; eligibility review, acceptable-use terms and service safeguards still apply. Approval is not automatic and uncapped access is not an uptime guarantee. Processing locations: the application server and the primary database run on Cloudflare in the United States (Eastern North America), and the network- and device-intelligence providers are US-based; encrypted backups are stored in Cloudflare R2 in the EU. EU-only processing is not offered; transfers are covered by the DPA. - [Public-interest applications](https://maskbreak.com/public-interest): government, healthcare, education and other eligible organizations. - [Privacy notice](https://maskbreak.com/privacy): data categories, purposes, storage and rights. - [Cookie policy](https://maskbreak.com/cookies): browser storage and site services. - [Data processing agreement](https://maskbreak.com/dpa): contractual processing terms. - [Sub-processors](https://maskbreak.com/sub-processors): service providers. - [Security whitepaper](https://maskbreak.com/security-whitepaper): controls, limitations and open retention-assurance items. - [Terms of service](https://maskbreak.com/terms) and [SLA](https://maskbreak.com/sla): applicable terms and scope of commitments. - [Service status](https://maskbreak.com/status): current checks and their monitoring scope. Using a fraud API does not by itself make a deployment compliant. Assess the actual data flows and applicable requirements against the linked documents. Maskbreak does not claim independent compliance certification or offer a HIPAA BAA. ## Practical reading - [Account takeover prevention](https://maskbreak.com/blog/account-takeover-prevention-that-holds-up): use device and network evidence alongside authentication controls. - [Fraud API timeouts](https://maskbreak.com/blog/fraud-api-timeouts): outage and fallback handling. - [Staged fraud-detection rollout](https://maskbreak.com/blog/fraud-detection-rollout): observe, review and then enforce. - [Risk score thresholds](https://maskbreak.com/blog/risk-score-thresholds): decisions versus scores. - [Residential proxy evaluation guide](https://maskbreak.com/blog/residential-proxy-detection-guide-2026) - [Browser automation detection](https://maskbreak.com/bot-detection) - [Device fingerprinting](https://maskbreak.com/device-fingerprinting) - [Disposable email signals](https://maskbreak.com/blog/disposable-email-detection) - [Free VPN detection API](https://maskbreak.com/blog/free-vpn-detection-api): free VPN and proxy detection options by input type, live visit versus IP lookup, and a first live check. - [Blog](https://maskbreak.com/blog): dated articles; illustrative attack models are not customer outcome reports. - [Product comparisons](https://maskbreak.com/alternatives): sourced feature distinctions, including unknowns; written by Maskbreak, not an independent ranking. - [Alternatives](https://maskbreak.com/alternatives): what to weigh when replacing IPQS, Fingerprint, SEON, Sift and other fraud tools; written by Maskbreak, not an independent ranking. Compare vendors against required data inputs, documented outputs, failure handling and a representative test set. Do not infer that an undocumented competitor feature is absent. No controlled head-to-head benchmark is provided here. ## Company and contact - Product: Maskbreak. - Formerly: Sentinel (sntlhq.com), renamed August 2026. Same company and API; sntlhq.com links redirect to maskbreak.com. - Operator: Sentinel Edge Networks LTD, registered in England and Wales. - [About Maskbreak](https://maskbreak.com/about) - [Contact](https://maskbreak.com/contact) - [GitHub organization](https://github.com/sentinelsup) - [Company register](https://find-and-update.company-information.service.gov.uk/company/17150600) - [Changelog](https://maskbreak.com/changelog) --- Canonical integration reference: https://maskbreak.com/integrate.md # Maskbreak Integration Guide Reviewed against the HTTP contract and server SDKs on 2026-10-27. This guide is for developers and AI coding assistants adding a fraud check to an existing application. Keep the application's authentication, authorization, CSRF protection and rate limits in place. - [API reference](https://maskbreak.com/api) - [OpenAPI specification](https://maskbreak.com/openapi.json) - [SDKs and Cloudflare Workers](https://maskbreak.com/integrations) - [Product capabilities and limitations](https://maskbreak.com/llms.txt) Get an account at [signup](https://maskbreak.com/signup). Configure the API key in your server's environment or secret store as `MASKBREAK_API_KEY`. Never put it in frontend code, commit it, or paste it into a public AI conversation. If your app already uses another variable name, keep that name consistent in your deployment settings and server code. The dashboard and examples below use `MASKBREAK_API_KEY`. Three steps give you the first complete check, one that carries both the network token and the browser check. The dashboard's setup uses the same names: 1. **Add the script to the page with your form** (section 1). 2. **Send the check from your server** (section 2). 3. **Submit your form once.** Run your app where you can open the page, on your computer or on your site, and submit the form like a visitor would. The first check then appears in the dashboard (Integration tab and Events); if half of it did not arrive, the dashboard says which half. One field mapping applies everywhere, whichever way the browser part sends it: | Form field added by the script | `Sentinel.collect()` returns | Send to `POST /v1/evaluate` as | Layer | |---|---|---|---| | `monocle` | `token` | `token` | network | | `sentinel_fp` | `fingerprintEventId` | `fingerprintEventId` | device (browser check) | | `sentinel_tz` | `tz` | `tz` (optional) | browser time zone | `/v1/evaluate` also accepts `monocle`, `sentinel_fp` and `sentinel_tz` under their form names, so a server that forwards the raw form body works (the API name wins when both carry a value); prefer the API names. Optional `email` (disposable-domain check, scored as well while email and phone intelligence is on), `phone` and `accountId` (linked accounts) go in the same JSON body. ## 1. Collect browser evidence Load the unified SDK on the page containing the protected form, and put `class="monocle-enriched"` on the `` element itself (never on an input): ```html ``` `data-site` is optional. The dashboard's setup screen (Integration tab) shows this line with your account's own site ID in place of `YOUR_SITE_ID`: a public ID (`site_` and 20 letters and digits), not a secret and not the API key, so it belongs in the page. With it, the script tells Maskbreak once per page load which site it runs on: one request to `https://maskbreak.com/v1/site-seen` (or to [your own script address](#your-own-script-address-optional)) carrying only the ID, to which the visitor's browser adds the page's origin (scheme, host and port). No cookies, no page path or query and no visitor data are sent, nothing is stored in the browser, and the setup screen shows "We see Maskbreak on " before your server code is in place. Without the attribute, or with a value that is not a site ID (such as the placeholder above), the script works exactly the same and sends nothing extra. An AI coding assistant given the dashboard's setup instructions gets the line with the real ID: keep `data-site` exactly as given. Without that line, leave `data-site` out and never make up an ID: one that is not the account's own matches nothing, so the setup screen never shows the script on your site. Does your site send a `Content-Security-Policy` header? Many Express apps do through helmet, whose default policy blocks this script until you add Maskbreak's hosts: see [Content Security Policy](#content-security-policy) below. The fields fill in a second or two after the page loads; a form posted faster carries only what has arrived, and watch mode (section 2) reports that. Ordinary form submissions forward the injected `monocle`, `sentinel_fp` and `sentinel_tz` fields. For a form your JavaScript submits (fetch/XHR, React, Next.js, Vue), call `Sentinel.collect()` when the form is submitted and send its result with your existing form data. Check that the script is there first, and never hold the form because of it: a blocked or missing script only means the check runs without that evidence. ```javascript const evidence = window.Sentinel ? await window.Sentinel.collect() : {}; // evidence = { token, fingerprintEventId, tz }: send it with the form data. ``` The script keeps one hidden form of its own on the page (`#_sntl_net`), so a client-rendered app (React, Next.js, Vue, Svelte) gets the network token without any extra markup, also for forms it renders after the page has loaded, and `collect()` returns it. Read it with `collect()`: a form your app renders after the page has loaded may post its own fields without `monocle`. The hidden form is never submitted and is not one of your forms; it carries `data-sentinel-net`, so if your own tests select a bare `form`, use `form:not([data-sentinel-net])`. `collect()` waits at most 5 seconds for the device check, then returns what it has: `fingerprintEventId` is `null` when the check has not finished (it keeps running and still fills your forms when it does), and `token` is `null` until the network script has written it. Pass `collect({ timeout: 2000 })` to change the wait (milliseconds); `window.Sentinel.ready()` takes the same option. ### Content Security Policy If your site sends a `Content-Security-Policy` header, add these sources to the directives you already have (keep `'self'` and your own hosts). All of them are Maskbreak's own hosts. helmet's default policy (`script-src 'self'`) blocks the script until they are added: ``` script-src https://maskbreak.com https://mcl.maskbreak.com https://*.mcl.maskbreak.com https://mesu.maskbreak.com 'wasm-unsafe-eval' connect-src https://maskbreak.com https://mcl.maskbreak.com https://*.mcl.maskbreak.com wss://mcl.maskbreak.com wss://*.mcl.maskbreak.com https://mesu.maskbreak.com worker-src https://mesu.maskbreak.com blob: ``` `maskbreak.com` serves `sentinel.js` and the network script's loader, which continues on `mcl.maskbreak.com` and its measurement hosts, and receives the optional `data-site` report (the only reason it is in `connect-src`); `mesu.maskbreak.com` serves the device check, which compiles WebAssembly and starts a worker. A policy without one of them breaks nothing on your page: the browser blocks that part, and the evaluation goes on without it (no `token`, or `fingerprintEventId: null`; a blocked `data-site` report only means the setup screen cannot show where the script runs). Check your browser console for CSP reports after adding the script. With helmet, extend its defaults rather than replacing them: ```javascript app.use(helmet({ contentSecurityPolicy: { directives: { scriptSrc: ["'self'", 'https://maskbreak.com', 'https://mcl.maskbreak.com', 'https://*.mcl.maskbreak.com', 'https://mesu.maskbreak.com', "'wasm-unsafe-eval'"], connectSrc: ["'self'", 'https://maskbreak.com', 'https://mcl.maskbreak.com', 'https://*.mcl.maskbreak.com', 'wss://mcl.maskbreak.com', 'wss://*.mcl.maskbreak.com', 'https://mesu.maskbreak.com'], workerSrc: ["'self'", 'https://mesu.maskbreak.com', 'blob:'] } } })); ``` ### Your own script address (optional) The script can also load from a subdomain of your own site, such as `https://fp.example.com/assets/sentinel.js`. Add the subdomain in the console (Settings, "Script address"), then create the DNS record it shows at your DNS host (DNS only, not proxied, if your DNS is on Cloudflare): ``` fp.example.com. CNAME custom.maskbreak.com. ``` Since 5 November 2026, if the name already leads to Maskbreak when you add it (for example a CNAME record left from before), points at a Cloudflare address (as a proxied record does), or its DNS cannot be read, the console also shows a TXT record made for your account, and the address is set up only once that record is in place beside the CNAME record. Copy its whole value from the console (it starts with `maskbreak-verify=`): ``` _maskbreak.fp.example.com. TXT "maskbreak-verify=..." ``` Added in the order above, the name in Settings first and the CNAME record after, a name needs no TXT record. If another account holds the name, the console shows the TXT record for your account: add it, then press Add again, and the address moves to your account and keeps working for the pages that use it. Cloudflare, which runs these addresses for Maskbreak, issues the certificate once the record is in place, usually within minutes. The console says when the address is ready and gives the tag to use in place of the one above: ```html ``` Loaded from there, the script also fetches its network loader from your subdomain and sends the optional `data-site` report to it, so in a `Content-Security-Policy` your subdomain takes the place of `https://maskbreak.com` in `script-src` and `connect-src`. The browser and network checks still load from `mesu.maskbreak.com` and `mcl.maskbreak.com`: keep their sources. The subdomain serves only `/assets/sentinel.js`, `/assets/edge.js` and `/v1/site-seen` (any other path answers 404, apart from a `/robots.txt` that keeps crawlers to those three). A blocker that refuses `maskbreak.com` still loads the script from it; one that follows the DNS name to its target can still refuse it. One address per account; an address whose records never appear is removed after 7 days, and one whose record stops pointing to Maskbreak after 14. Send evidence to your own backend, not to the Maskbreak API with a secret key from the browser. Treat a missing collector, token or device event as unavailable evidence. Do not fabricate a token or replace it with a sample. ## 2. Evaluate before the protected action Roll out in two steps with one switch, `MASKBREAK_MODE`. The same handler serves both, so switching needs no code change. 1. **Watch (the default).** Deploy with `MASKBREAK_MODE` unset or `watch`. Every submission is sent to `/v1/evaluate`, also when a browser field is missing: Maskbreak then records which half did not arrive, and the dashboard shows it instead of waiting in silence. One log line records the decision, reasons, `risk_score`, the `X-Request-Id` response header and what enforce mode would have done. The existing handler always runs, including when browser evidence is missing, the check fails or Maskbreak is unavailable, so a mistake in the integration cannot lock real users out. 2. **Enforce.** After a few days, compare those log lines with the dashboard's Events. When they look right, set `MASKBREAK_MODE=enforce` and redeploy. The handler then stops `block`, holds `review`, missing or degraded evidence for your verification flow (a submission with a missing field is held without a call), rejects test, sample and sandbox responses, and holds the action when the check is unavailable. One exception: when the month's checks are used up (HTTP 429 with the code `monthly_quota_exceeded`), it lets the action through unchecked and logs it, as watch mode does, until the allowance resets on the 1st at 00:00 UTC or the plan changes. Running out of checks never takes your form offline. This Node.js/Express example uses the HTTP API so it can forward all three browser fields, including the optional timezone. The application must already define `existingLoginHandler`; it performs the actual credential verification, session creation and authorization. Configure your normal body-size limits. In enforce mode the example holds incomplete or review results instead of automatically allowing them. Connect that response to your own verification/review flow. For a lower-risk action, you may choose another documented fallback policy. ```javascript // Server-side only. Node.js 18+ (fetch and AbortSignal.timeout). // 'watch' (default): send every submission, log what Maskbreak would do, always continue. // 'enforce': stop block; hold review, missing evidence and errors // (a used-up month continues, logged). const MASKBREAK_MODE = process.env.MASKBREAK_MODE || 'watch'; app.use(express.json({ limit: '16kb' })); app.use(express.urlencoded({ extended: false, limit: '16kb' })); app.post('/your-login-endpoint', async (req, res, next) => { const body = req.body || {}; // Form fields -> API fields: monocle -> token, sentinel_fp -> fingerprintEventId, // sentinel_tz -> tz. Sentinel.collect() already returns the API names. const token = body.token || body.monocle; const fingerprintEventId = body.fingerprintEventId || body.sentinel_fp; const tz = body.tz || body.sentinel_tz; const missing = typeof token !== 'string' || !token || typeof fingerprintEventId !== 'string' || !fingerprintEventId; let result = null, requestId = null, hold = null, monthUsedUp = false; let status = null, apiError = null; // the HTTP status and the API's own error // Watch mode sends the check even with a field missing, so the dashboard // can say which half did not arrive. Enforce mode holds it without a call. if (!missing || MASKBREAK_MODE !== 'enforce') { try { const response = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', signal: AbortSignal.timeout(5000), headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ token, fingerprintEventId, tz }) }); requestId = response.headers.get('x-request-id'); status = response.status; if (!response.ok) { const refusal = await response.json().catch(() => null); apiError = refusal?.code ?? refusal?.error ?? null; // The month's checks are used up: let the action through unchecked // until the 1st (00:00 UTC) and log it, as watch mode does. if (response.status === 429 && refusal?.code === 'monthly_quota_exceeded') monthUsedUp = true; else throw new Error('Evaluation unavailable'); } else { result = await response.json(); if (!result || !['allow', 'review', 'block'].includes(result.decision) || result.test || result.sample || result.sandbox) { throw new Error('No production verdict'); } if (result.decision === 'block') { hold = [403, 'Request declined.']; } else if (result.decision === 'review' || result.degraded || !result.device) { hold = [409, 'Verification required.']; } } } catch { hold = [503, 'Verification unavailable. Try again later.']; } } if (missing) hold = [409, 'Verification required.']; // enforce never trusts half a check // One line per check. Never log the key, browser tokens or form data. // status 401: MASKBREAK_API_KEY is empty or wrong where this code runs. console.log('[maskbreak]', JSON.stringify({ mode: MASKBREAK_MODE, status, error: apiError, decision: result?.decision ?? null, reasons: result?.reasons ?? null, risk_score: result?.risk_score ?? null, request_id: requestId, month_used_up: monthUsedUp, enforce_would: hold ? 'return ' + hold[0] : 'continue' })); if (MASKBREAK_MODE === 'enforce' && hold) { return res.status(hold[0]).json({ error: hold[1] }); } return next(); // Watch, or a passed gate; existing authentication still runs. }, existingLoginHandler); ``` Watch mode is for rollout, not permanent protection: it records what would have happened and blocks nothing. Enforce mode is the fraud gate; keep its checks intact when you adapt the example. For signup or checkout, keep the same separation: a fraud gate followed by the existing action handler. Do not derive a trusted `accountId` from arbitrary client input; if linking accounts, use the application's server-validated identifier. ### Forms rendered by JavaScript: Next.js App Router A form your app renders and submits with `fetch` sends the evidence that `Sentinel.collect()` returns, already under the API's names. Load the script once in the root layout: ```jsx // app/layout.js import Script from 'next/script'; export default function RootLayout({ children }) { return ( {children}
``` On the server, the fraud gate runs before your existing handler, which still verifies credentials and creates the session. It is the [integration guide](https://maskbreak.com/integrate.md)'s handler in enforce mode (the guide's version adds a `MASKBREAK_MODE` switch that starts in watch mode and only logs): it accepts either field shape, holds `review` and incomplete evidence, refuses `block`, and never lets a test or sample response authorize a real action. JavaScript · Node.js / Express, server-side onlyCopy ``` // Server-side only. Node.js with fetch and AbortSignal.timeout. app.use(express.json({ limit: '16kb' })); app.use(express.urlencoded({ extended: false, limit: '16kb' })); app.post('/your-login-endpoint', async (req, res, next) => { const body = req.body || {}; const token = body.token || body.monocle; const fingerprintEventId = body.fingerprintEventId || body.sentinel_fp; if (typeof token !== 'string' || !token || typeof fingerprintEventId !== 'string' || !fingerprintEventId) { return res.status(409).json({ error: 'Verification required.' }); } try { const response = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', signal: AbortSignal.timeout(5000), headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ token, fingerprintEventId, tz: body.tz || body.sentinel_tz }) }); if (!response.ok) { const refusal = await response.json().catch(() => null); // The month's checks are used up: continue unchecked until the 1st // (00:00 UTC), logged. Every other error holds the login. if (response.status === 429 && refusal?.code === 'monthly_quota_exceeded') { console.warn('[maskbreak] monthly_quota_exceeded: continuing unchecked'); return next(); } throw new Error('Evaluation unavailable'); } const result = await response.json(); if (!result || !['allow', 'review', 'block'].includes(result.decision) || result.test || result.sample || result.sandbox) { throw new Error('No production verdict'); } if (result.decision === 'block') { return res.status(403).json({ error: 'Request declined.' }); } if (result.decision === 'review' || result.degraded || !result.device) { return res.status(409).json({ error: 'Verification required.' }); } return next(); // Fraud gate passed; existing authentication still runs. } catch { return res.status(503).json({ error: 'Verification unavailable. Try again later.' }); } }, existingLoginHandler); ``` For explanations and logs, read `network.vpn`, `network.proxy` and `network.tor`; `network.service` names the VPN or proxy service when known and may be `null`. For a full-device assessment, inspect `device.complete` and `device.checked_signals`; an unchecked boolean is not a verified negative. The [API reference](https://maskbreak.com/api) documents the full response contract. ## Should a detected VPN block the customer? Not automatically. Under Maskbreak’s base policy, VPN use alone produces `review`. Account rules and other signals can change the final recommendation. Your application can use a server-verified step, such as existing MFA, when the action warrants it. Read [how to avoid rejecting legitimate VPN users](https://maskbreak.com/blog/vpn-detection-false-positives). Handle an incomplete check or timeout separately from a completed check with no detected warning signs. Pick a fallback based on the action: pausing a sensitive change may be reasonable, while a low-risk page view may not need to wait. Show a useful retry or support path instead of an unexplained error. [When a fraud check times out](https://maskbreak.com/blog/fraud-api-timeouts) covers the fallback per action, and [rolling out without locking out customers](https://maskbreak.com/blog/fraud-detection-rollout) covers the move from watch mode to enforcement. ## How do you test it before going live? First exercise response handling with documented fixtures. The public sample endpoint needs no account, and the sandbox key `sk_test_sandbox` returns a fixed decision for each test token: ShellCopy ``` curl --fail-with-body 'https://maskbreak.com/v1/evaluate/sample?scenario=vpn' curl --fail-with-body https://maskbreak.com/v1/evaluate \ -H 'Authorization: Bearer sk_test_sandbox' \ -H 'Content-Type: application/json' \ -d '{"token":"test_vpn"}' ``` Sandbox tokens and their base decisionsSandbox tokenBase decisionWhat it exercises `test_clean`allowThe path to your existing handler `test_vpn`reviewYour step-up or review flow `test_datacenter`allowA signal without a base block `test_proxy`blockThe refusal path `test_tor`blockThe refusal path Your production guard should reject these results, because sandbox responses are marked as tests; run the fixtures in staging with the protected action stubbed out. Then test live collection on your own normal browser, a VPN connection and a privacy-restricted browser. Confirm that your server receives both evidence fields, and deliberately test what happens when either is absent. Fixture results cannot establish VPN detection coverage. Maskbreak’s [Free plan](https://maskbreak.com/pricing) includes 10,000 visitor checks a month with no credit card; paid plans start at €29 a month. Authenticated IP lookups have their own allowance, ten times the plan’s visitor checks. Start with a small live test, confirm the deployed endpoint actually enforces its decision, and measure successful customer completion as well as flagged traffic. To compare other free options, see [free VPN detection APIs compared](https://maskbreak.com/blog/free-vpn-detection-api). ## Questions people ask **Can JavaScript detect a VPN without an API?** JavaScript can collect browser and connection clues, but no browser-only check reliably identifies every VPN. Maskbreak combines live visit evidence with server-side network and device checks; results still depend on the evidence available. **Can JavaScript detect a VPN from the time zone?** It can spot a difference between the time zone the device reports and the country of the IP address. That is a clue, not a verdict: travellers, roaming phones, remote workers and people who set their clock by hand produce the same difference, and a VPN exit in the visitor’s own country produces none. Maskbreak accepts the time zone as the optional tz field and moves an allow to review on an eligible mismatch, never to a block. **Why does WebRTC no longer show local IP addresses?** Private addresses from WebRTC host candidates were used to fingerprint and track visitors, so current mainstream browsers replace them with random .local names or leave them out unless the page has camera or microphone permission. The public address a STUN server reports can still appear, but browser settings, extensions and VPN apps can suppress it. **Should I put my VPN detection API key in frontend JavaScript?** No. Keep the Maskbreak API key in your backend environment or secret store. Send browser evidence to your own backend, which calls the evaluation API and enforces the result. **Does a WebRTC IP address reveal every VPN?** No. Address exposure depends on the browser, permissions, network configuration and routing. A missing address or a different address does not by itself establish whether a VPN is in use; a dual-stack visitor can even show an IPv6 address to your server and an IPv4 address to STUN. **Can I try JavaScript VPN detection for free?** Yes. Maskbreak’s Free plan includes 10,000 visitor checks a month with no credit card; paid plans start at €29 a month. Check the current pricing and terms before rollout; the public sandbox tests response handling, not live detection accuracy. --- # Residential proxies and credential stuffing URL: https://maskbreak.com/blog/residential-proxy-credential-stuffing Published: 2026-09-17 > Protect logins from residential-proxy credential stuffing with layered limits, live network and device checks, MFA and a safe review flow. - A residential IP address is not evidence that a login is legitimate. - Use network and device signals alongside authentication, MFA and application-owned abuse limits. - Keep account-level and aggregate defenses effective when requests arrive from different addresses. - Verify your deployed login flow, including missing evidence and unsuccessful review checks. Maskbreak can add live network and device signals to a login flow facing residential-proxy credential stuffing. Use its recommendation alongside credential verification, MFA and your own abuse limits: a residential IP address is not proof that a request belongs to a legitimate customer. This playbook focuses on protecting a login endpoint, not operating proxies. Maskbreak’s Free plan includes 10,000 visitor checks a month with no credit card; paid plans start at €29 a month. For network background, start with [what a residential proxy is](https://maskbreak.com/blog/what-is-a-residential-proxy); for collection and request fields, use the [integration guide](https://maskbreak.com/integrate.md). ## Why an IP-only login limit misses the pattern Credential stuffing attempts to reuse credentials stolen elsewhere. Requests arriving through different addresses may never reach a single-IP threshold, even when they belong to one campaign. [OWASP recommends layered defenses](https://cheatsheetseries.owasp.org/cheatsheets/Credential_Stuffing_Prevention_Cheat_Sheet.html), including MFA, multiple observation windows and controls that do not rely on IP blocking alone. The opposite failure also matters: many real users may share an address. [RFC 6269 discusses the consequences of IP address sharing](https://www.rfc-editor.org/info/rfc6269/), including the limitations of address-based identification and controls. A busy shared network is not automatically an attack. Keep per-IP limits for basic resource protection, but also evaluate account-targeted failures and aggregate login pressure. Choose thresholds from your own traffic and recovery needs; there is no universal number that both stops distributed abuse and avoids every customer lockout. ## What a residential proxy detection API adds Maskbreak’s live evaluation combines network evidence with device evidence when available. That can give your backend more context than an address lookup alone: a known proxy, VPN, automation or fake-browser signal can influence the recommendation. The service name is returned when known, not for every connection. Do not read `network.residential` as “trusted household.” In the current evaluation response it is derived from the absence of datacenter and proxy flags. An unclassified exit may still look residential. Device evidence can also be missing or incomplete; neither an empty device result nor an unchanged user agent proves safety. Maskbreak does not own your application’s failed-login counters, password verification or MFA enrollment. Keep those controls in your app. A VPN alone returns `review` under the base policy; customer rules and exceptions can alter the final decision. The [VPN false-positive guide](https://maskbreak.com/blog/vpn-detection-false-positives) explains why network classification and fraud policy are different questions. ## A login flow with clear responsibilities - Collect current visit evidence. Load the browser SDK and send its network token and device event identifier with the login request to your own backend. A dashboard demo is not evidence from your application. - Apply application safeguards. Validate the request, enforce body-size and abuse limits, and retain CSRF protections where applicable. Cover alternate login routes as well as the visible form. - Evaluate server-side. Store MASKBREAK_API_KEY only in your backend environment. Call POST /v1/evaluate with a bounded deadline and handle non-success responses explicitly. - Use the recommendation. On block, decline the protected action. On review, hold it for the required verification. Treat missing required evidence as unavailable, not clean. - Finish authentication. An allow recommendation does not validate the password or authorize a session. Complete your existing credential, MFA and authorization checks before access is granted. If review requires MFA, only your backend can confirm that it passed. Bind completion to the pending login and account, expire it and prevent reuse. Do not turn a successful CAPTCHA into permission to skip a required second factor. ## Test outcomes, not only successful API calls Controlled testWhat to verify in your app Incorrect password with an allow recommendationNo authenticated session is created. Correct password with reviewThe required step-up cannot be bypassed by changing browser fields. Block recommendationEvery relevant login route refuses the protected action. Missing device evidence, timeout or HTTP 429Your documented fallback runs and the customer receives a useful response. Repeated attempts against a test account through different test sourcesApplication-level account and aggregate controls still apply. Legitimate test users sharing one networkOne user’s failures do not automatically permanently lock out every other user. Use staging, mocked recommendations and accounts you control for these checks. Synthetic samples prove response handling, not detection coverage. A live test should separately confirm that your deployed SDK supplies usable evidence and your server enforces the result. ## Roll out with a recovery path Track authentication failures, risk decisions, unavailable evidence and completed reviews as separate outcomes. Compare refusal and recovery rates before expanding enforcement, and ensure support can investigate an event reference without asking for passwords or API secrets. No detector can promise to identify every residential proxy, and a proxy signal does not prove credential theft. The goal is several independent controls around the login, with clear responsibility for each. Read the [Node.js login integration](https://maskbreak.com/blog/nodejs-suspicious-login-detection), then [create a free account](https://maskbreak.com/signup) and verify a real request from your deployed app. ## Questions people ask **Can residential proxies be used for credential stuffing?** Yes. They can carry login attempts through consumer-network addresses. The address type alone neither confirms nor rules out abuse, so use authentication controls and multiple risk signals. **Is an IP rate limit enough to stop credential stuffing?** No. Requests spread across addresses can evade a per-IP limit. Combine network limits with account and aggregate controls, MFA and monitoring; avoid permanent account lockouts that attackers can trigger against customers. **Does Maskbreak replace my login rate limiter or MFA?** No. Maskbreak supplies visit signals and an allow, review or block recommendation. Your application still owns rate limits, credential verification, authorization, sessions and step-up completion. **Does network.residential mean a visitor is trusted?** No. In Maskbreak’s evaluation response it is derived from the absence of datacenter and proxy flags. It is not a verified household identity or proof that the visit is safe. **Is residential proxy detection available on the Free plan?** Yes. Live visit evaluation runs the same checks on every plan, including Maskbreak’s Free plan of 10,000 visitor checks a month with no credit card. Detection depends on available evidence; no service can promise to identify every proxy. --- # VPN detection without blocking real customers URL: https://maskbreak.com/blog/vpn-detection-false-positives Published: 2026-09-17 · Updated: 2026-10-10 > Reduce VPN detection false positives with review decisions, verified step-up checks and a clear policy for privacy tools and shared networks. - Correctly detecting a VPN does not prove that its user is committing fraud. - A VPN alone returns review under Maskbreak’s base policy; your account rules can change the final decision. - Enforce review on your server and verify the next step before continuing the protected action. - Measure successful customer completion as well as flagged traffic. Maskbreak is a [VPN, proxy and fake-browser detection API](https://maskbreak.com/vpn-detection) for signup, login and checkout. To use VPN detection without unnecessarily blocking customers, separate the network signal from your response: a VPN alone returns `review` under the base policy, and your application decides which verified next step is appropriate. This guide is for SaaS developers and fraud teams whose customers use privacy tools, work networks or mobile connections. Maskbreak’s Free plan includes 10,000 visitor checks a month with no credit card; paid plans start at €29 a month. See the [current plans](https://maskbreak.com/pricing) and [terms](https://maskbreak.com/terms) before rollout. ## Is it a detection false positive, or a policy mistake? There are two different problems. A classification error means a connection is labelled as a VPN when it is not. A policy mistake means the connection really uses a VPN, but your app treats that fact as sufficient evidence to refuse a legitimate customer. Improving detection alone will not fix the second problem. Review the visit’s network signals, device evidence and final decision separately. Maskbreak names a VPN or proxy service when known; an absent name is not proof that no privacy tool is present. Likewise, a risk score is not the probability that a person is a fraudster. To see the answer for your own connection, run the [free VPN and proxy checker](https://maskbreak.com/ip-lookup). ## Account for privacy tools and shared connections A customer may use a VPN intentionally or reach you through a company network. Safari users can also use iCloud Private Relay, which is not the same product as a general-purpose VPN. [Apple explains](https://developer.apple.com/icloud/prepare-your-network-for-icloud-private-relay/) that relay addresses can be shared and recommends adapting IP-based fraud controls to avoid affecting legitimate users. When Maskbreak’s network intelligence recognises a visit as iCloud Private Relay, the base policy returns `review` with the reason `privacy_relay`, never `block` on the relay alone. A customer who asks why they were flagged can read [how websites tell a visitor is on a VPN](https://maskbreak.com/blog/can-websites-detect-vpn), written for their side of the screen. Do not infer an individual identity from a shared exit address, and do not treat a browser brand as a trust guarantee. Your policy should consider the action being attempted: reading public documentation, signing in and changing a payout destination need not have identical requirements. ## Use a decision policy customers can finish ResultApplication response `allow` with usable required evidenceContinue existing authentication and authorization. A fraud check does not replace either. `review`Hold the sensitive action and offer the additional verification your policy requires. `block`Decline the action and provide a safe support route without exposing detailed detection rules. Missing evidence or unavailable evaluationApply your documented fallback. Never display “safe” merely because a check failed. These are implementation responsibilities, not automatic screens that appear after you install an SDK. Account rules and exception pins can change Maskbreak’s final recommendation. Inspect the returned `decision`, rather than recreating policy from one flag or a hard-coded score threshold. ## Make review an actual verification flow For a login, your existing MFA can provide a next step. For another action, choose a check that establishes what you need to know; a bot challenge is not proof of account ownership. [OWASP’s authentication guidance](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) describes risk-based reauthentication and the importance of maintaining secure session handling. Record the pending action on your server. Verify completion on the server, bind it to the right account and action, expire it, and prevent replay. A browser flag such as `verified: true` must not unlock the action. Give the person a concise message, for example: “We need one more check before you continue,” followed by an actionable button and a support option. Keep `MASKBREAK_API_KEY` in your backend’s secret store. Collect live browser evidence and forward it to your backend for `POST /v1/evaluate`; follow the [integration guide](https://maskbreak.com/integrate.md) for status checks, incomplete evidence and error handling. A bare-IP lookup is not a substitute for that live evaluation. ## Measure friction, not just flagged visits Track how often review is requested, how often it is completed, where customers abandon it and how many support cases overturn a refusal. Separate unavailable checks from risk-based refusals. Otherwise a provider outage can look like an improvement in blocked traffic. Before enforcing a new policy broadly, test it on your own ordinary, VPN and privacy-relay sessions and a small approved rollout. Include a missing SDK, a failed evaluation and a failed verification attempt. The [VPN testing checklist](https://maskbreak.com/blog/vpn-detection-api-test-cases) distinguishes synthetic contract tests from live detection tests. Use narrow, reviewed exceptions where justified; do not permanently trust everyone who shares a commercial exit address. Start with [a free account](https://maskbreak.com/signup), confirm a real visit in the dashboard, then verify that your own backend enforces the next step. ## Questions people ask **Is a VPN detection result a false positive if the customer is legitimate?** Not necessarily. The VPN classification can be correct while a fraud-blocking decision is wrong. Check network classification and customer outcomes separately. **Does Maskbreak block every VPN user?** No. A VPN alone returns review under Maskbreak’s base policy. Account rules and exception pins can change the final recommendation, and your backend must enforce the resulting decision. **Can I use a VPN detection API without requiring a CAPTCHA?** Yes. Maskbreak does not require a CAPTCHA to return network and device signals. Your app can use an appropriate server-verified step, such as existing MFA, for review results. **Does an inconclusive check mean the visit is safe?** No. Missing or unavailable evidence is not a clean result. Use a documented fallback, such as holding a sensitive action for verification, and offer a clear retry or support route. **Can I start testing VPN detection for free?** Yes. Maskbreak’s Free plan includes 10,000 visitor checks a month with no credit card; paid plans start at €29 a month. Authenticated IP lookups have their own allowance, ten times the plan’s visitor checks. --- # Fraud protection for an AI-built app URL: https://maskbreak.com/blog/fraud-protection-ai-built-app Published: 2026-09-11 > Add Maskbreak to an AI-built app with a secret-free prompt, server-side decisions and a checklist that verifies your deployed site. - Identify every backend route that can perform the protected action, not just the visible form. - Store MASKBREAK_API_KEY server-side; keep secrets out of prompts and frontend code. - Require usable live network and device evidence while preserving authentication and rate limits. - Verify deployed collection and enforcement; fixtures and console events alone are not installation proof. Add fraud protection to an AI-built app by connecting Maskbreak's browser collection to a server-side evaluation before the action you want to protect. Keep the API key on your server, handle `allow`, `review` and `block`, and verify the result on your deployed site. Installing a script or producing a successful demo does not establish that signup, login or a valuable benefit is protected. Maskbreak provides a recommendation, not automatic authentication protection. Your app still verifies credentials, checks permissions and manages sessions. This Maskbreak-authored guide covers implementation and acceptance criteria rather than a particular AI builder. Linked guidance was checked on 11 September 2026 and pricing on 30 September 2026. ## What should you ask the AI builder to protect? Identify the action that releases value and the backend that performs it. For example, an AI-built study app might grant introductory tutoring credits after signup. Protect the server operation that grants those credits, including the path used after a social login. A check on a password form alone would miss that second entry point. Keep eligibility and duplicate-grant prevention in the application. [OWASP's business-logic guidance](https://cheatsheetseries.owasp.org/cheatsheets/Business_Logic_Security_Cheat_Sheet.html) recommends enforcing workflow state and one-time benefits on the server. A clean visitor can still attempt to redeem a promotion twice. If your builder has created only a frontend, identify or add an authenticated backend function before integrating the secret API call. Do not move a private key into the browser to make a demonstration work. ## Where should the Maskbreak API key go? Create an account at [Maskbreak signup](https://maskbreak.com/signup) and configure `MASKBREAK_API_KEY` in your hosting platform's server-side environment or secret store. Configure each environment deliberately; having a key in a local preview does not configure production. Give the assistant the variable name and public documentation, never the key value. Keep secrets out of prompts, screenshots, source files, browser-exposed environment variables and logs. [OWASP's secrets guidance](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) covers restricted access, managed storage and avoiding plaintext logging. If you already exposed a key, revoke or rotate it and update the affected deployment. ## What evidence must the actual site send? The [current integration guide](https://maskbreak.com/integrate.md) explains both ordinary forms and custom submissions. After the SDK loads, `window.Sentinel.collect()` returns `token`, `fingerprintEventId` and optional `tz`. Ordinary enriched forms use `monocle` and `sentinel_fp` for the first two fields. Forward the real values to your backend, which calls `POST /v1/evaluate`. Full evidence means checking the returned network and device fields, not merely sending two identifiers. Device resolution can fail; there is no API `complete` or `live` boolean to invent. The raw HTTP example forwards timezone; the current server SDK helpers do not. A bare-IP lookup is not a substitute for the live network-and-device check. ## What prompt can I copy into my AI coding assistant? The following is a secret-free implementation prompt, not executable application code. Identify your protected action in the conversation before using it. It asks for evidence the assistant can report without disclosing credentials or raw browser tokens. ``` Add Maskbreak protection to the action I identified in this app. Read https://maskbreak.com/integrate.md and the existing action handler first. If the action or backend is unclear, ask me to identify it. Keep authentication, authorization, MFA, CSRF protection, validation and rate limits. Identify every route that can perform the action, including social login callbacks or alternate submission paths where relevant. I will configure MASKBREAK_API_KEY in server-side secret storage. Use that variable name. Do not read secret files, print keys, request keys in chat, or expose secrets in frontend code, logs, screenshots or test reports. Collect real token and fingerprintEventId evidence on the actual page. Forward both through our backend to POST /v1/evaluate; preserve optional tz when supported. Never replace missing evidence with demo values. Validate the response against the documented contract. Require the network and device fields needed by our policy; reject malformed, degraded, test, sample and sandbox results as authorization for the protected action. Do not invent live or complete response flags. Route on decision: allow continues through existing controls; block refuses; review holds the action for server-verified additional checks. Bind review completion to the account and action. Never trust a browser passed flag. Use bounded timeouts and an explicit unavailable state. Preserve duplicate submission protection. Do not grant benefits on errors or HTTP 429. Test branches safely in staging. After an authorized deployment, verify the real page and backend with my test account. Report the deployed URL, action, routes, dated test results, sanitized evidence of collection and enforcement, and unresolved limitations. A build, console event or demo is not completion. ``` ## How should the generated app handle the result? For the tutoring-credit example, a usable live allow continues to the existing eligibility check. Review keeps credits pending while your backend verifies the required account check. Block refuses the grant. Missing evidence or an unavailable API leaves it pending with a recovery message. These are application rules you implement, not UI screens the API installs. A VPN alone yields review in the base policy; account rules and exceptions can change the final decision. Network service names appear when known. The risk score is not a fraud probability, and the legacy `isSuspicious` flag is not the final policy result. An allow never authenticates someone or authorizes another user's resources. Keep the layered controls described in [OWASP's authentication guidance](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html), including appropriate MFA and login throttling. ## What must pass before I accept the work? - Real collection: on the deployed page, both evidence fields reach your backend and required network/device results resolve. Check the site's content security policy and blocked-script behavior. - Real enforcement: correlate a controlled live evaluation with the protected action. A Maskbreak console event proves neither route coverage nor that a hold stopped a benefit. - Failure branches: in staging, test review, block, timeout, malformed responses, HTTP 401/403/429, missing evidence and test/sample/sandbox results. None may silently release the benefit. - Bypass resistance: try direct endpoint submissions, forged review flags, expired approval and duplicate requests. Verify account checks, permissions and existing rate limits still apply. - Clear evidence: retain the test date, deployed version, route, expected result and observed outcome without secrets. Separate fixture results from live checks and record unresolved failures. Use your own test accounts and harmless actions. Fixture success tests decision handling; a live check tests integration. Neither establishes a detection-rate or latency guarantee. ## Can I start without a paid plan? Yes. [Maskbreak's Free plan](https://maskbreak.com/pricing) includes 10,000 visitor checks a month with no card; paid plans start at €29 a month. Authenticated IP lookups have their own allowance, ten times the plan's visitor checks. Budget for repeated protected actions, handle quota exhaustion explicitly, and keep rate limits ahead of the external check. ## Questions people ask **Can an AI coding assistant integrate Maskbreak?** Yes. Give it the public integration guide, the protected action and the secret variable name, then verify its implementation on the deployed site. The assistant needs access to your application code, not your private API key in chat. **Where should MASKBREAK_API_KEY be stored?** Store it in the server-side environment or secret store, never in AI prompts, browser code or logs. Configure production separately from local previews. **Does an allow recommendation authenticate a user?** No. Existing credential checks, MFA, authorization and session controls must still run. An allow recommendation only passes your fraud gate when the evidence required by your policy is usable. **Is a successful demo enough to accept the integration?** No. Verify real evidence collection, backend enforcement, failure handling and alternate routes on the deployed application. A console browser check alone does not prove your own website is connected. **Is Maskbreak free for an AI-built app?** Maskbreak’s Free plan includes 10,000 visitor checks a month with no credit card; paid plans start at €29 a month. Authenticated IP lookups have their own allowance, ten times the plan’s visitor checks. --- # Marketplace fake accounts without CAPTCHAs URL: https://maskbreak.com/blog/marketplace-fake-account-protection Published: 2026-09-11 > Detect marketplace account abuse with live visitor checks, server-verified review and safeguards for listings, messages and referral rewards. - Protect publishing, messaging and rewards with marketplace-specific server rules, not only a signup check. - Network and device signals support review; they do not prove identity or fraud. - Review requires server-verified completion bound to the account and pending action. - Maskbreak’s Free plan includes 10,000 visitor checks a month with no card; paid plans start at €29 a month. A marketplace can use Maskbreak to assess live network and browser signals before an account publishes listings, contacts sellers or claims a promotion, without requiring a CAPTCHA. Maskbreak returns an `allow`, `review` or `block` recommendation. Your backend must enforce it alongside account permissions and marketplace rules. Suspicious signals help choose what to verify; they do not establish that a person or account is fake. This Maskbreak-authored guide focuses on account abuse and protecting marketplace actions. For other tools that do the same job, see the [fake account prevention software comparison](https://maskbreak.com/blog/best-fake-account-detection-software). The examples are proposed policies, not reported customer outcomes. Documentation was checked on 11 September 2026 and pricing on 30 September 2026. ## What does a fake account actually do to your marketplace? Start with the behavior you need to prevent. A seller may create replacement accounts after moderation, a buyer may send unsolicited messages, or a referral participant may register repeatedly for rewards. Those require different controls. Counting registrations alone misses the point at which an account causes harm. Write an enforceable rule for each benefit: a suspended seller cannot publish through another account; a referral reward requires an eligible transaction; a new member cannot message an unlimited number of sellers. Your application owns those rules. A fraud API cannot infer your promotion terms or decide whether a listing is truthful. ## Where should you check a marketplace account? Place the check before the server releases the relevant benefit. Checking only the signup screen leaves later publishing or messaging endpoints exposed. The following is an example policy for a second-hand camera marketplace, not a built-in Maskbreak workflow. ActionExisting safeguardPossible review handling Create an accountRegistration rate limits and email verification.Keep the account restricted until verification completes. Publish a first listingSeller permissions and listing moderation.Save a private draft; hold publication for review. Contact several sellersRecipient and messaging limits.Hold outgoing messages while checking the account. Claim a referral rewardServer-calculated eligibility and a single redemption record.Keep the reward pending until the required checks pass. Enforce eligibility and record redemption together so simultaneous submissions cannot claim the same benefit twice. [OWASP's business-logic guidance](https://cheatsheetseries.owasp.org/cheatsheets/Business_Logic_Security_Cheat_Sheet.html) covers server-owned state, repeated workflow steps and race conditions. These controls remain necessary even for an ordinary-looking visitor. ## What evidence can help identify repeat account abuse? Follow the [integration guide](https://maskbreak.com/integrate.md) to collect the network `token` and device `fingerprintEventId` at the real form, then forward both to your backend. It calls `POST /v1/evaluate` using `MASKBREAK_API_KEY` from server-side secret storage. Never expose that key in browser code. Live results describe VPN, proxy, Tor and cloud-server signals, plus available automation, fake-browser and device-tampering evidence. The VPN or proxy service is named when known. A bare-IP lookup currently checks Tor exits and cloud-server ranges in production; it does not replace live collection. Optional `accountId` can support linked-account counts within your own customer scope. Supply an identifier validated by your server, not an arbitrary browser field. Linking uses hashed account identifiers and does not connect identities across Maskbreak customers. Shared devices and household connections need context; neither an account count nor a shared IP proves abuse. ## How do you handle review without adding a CAPTCHA? A VPN alone produces `review` under Maskbreak's base policy. Customer rules and exceptions can change the final recommendation, so route on `decision`. Do not substitute the legacy `isSuspicious` flag or interpret `risk_score` as a probability of fraud. For a reviewed listing, hold publication and offer an appropriate path: existing MFA, verified email ownership or a moderator decision. Email ownership alone does not prove seller legitimacy. Bind verification to the account and pending action, check completion on your server, enforce expiry and prevent reuse. A browser-supplied “passed” value, dismissed dialog or successful redirect cannot release the hold. [OWASP's transaction-authorization guidance](https://cheatsheetseries.owasp.org/cheatsheets/Transaction_Authorization_Cheat_Sheet.html) explains why authorization and workflow order belong on the server. Suppose a seller using a VPN submits a camera listing. Your application saves the draft, verifies the required account check, then rechecks publishing permissions before making it public. If another submission arrives during review, it must not create a second listing. This preserves a recovery path without treating the VPN as proof of dishonesty. ## What should happen on block or missing evidence? A valid `block` recommendation refuses the protected action. Give a clear explanation and support route without revealing detailed evasion clues. An `allow` can continue through your existing controls only when the evidence required by your policy is present and valid. Sending a device event does not guarantee that device evidence resolves. Missing fields, `degraded` results, timeouts and API errors need an explicit unavailable state. For this example, hold publication or rewards until verification can complete. Test, sample and sandbox responses must never authorize real actions. ## Would a CAPTCHA or identity check solve the same problem? A bot challenge is an optional additional control. If you choose Turnstile, its [official validation guide](https://developers.cloudflare.com/turnstile/get-started/server-side-validation/) requires server-side Siteverify; tokens are single-use and expire after five minutes. Check the expected hostname and action. A completed challenge does not establish referral eligibility or clear a separate block decision. Account-abuse screening also does not establish legal identity, card ownership or payment authorization. Keep payment-provider controls, any required KYC checks and chargeback handling separate. An allowed visit is not a guarantee about a seller, payment or eventual dispute. ## How can you prove the marketplace action is protected? - In staging, exercise allow, review, block and unavailable responses with harmless test actions. - Confirm direct endpoint requests cannot skip the gate or forge review completion. - Try simultaneous submissions and expired approvals; verify no duplicate listing or reward appears. - Use your own live browser on the deployed form. Confirm both evidence fields reach the backend, then correlate the evaluation with the action's actual outcome. A dashboard event alone does not prove enforcement. Review legitimate users' difficulties as well as abuse attempts. Keep evidence private, limit logging and review your [privacy disclosures](https://maskbreak.com/privacy) and retention needs. ## What does it cost to start? Maskbreak's [Free plan](https://maskbreak.com/pricing) includes 10,000 visitor checks a month with no card; paid plans start at €29 a month. Authenticated IP lookups have their own allowance, ten times the plan's visitor checks. Count checks across protected actions, retain your own rate limits, and handle HTTP 429 as unavailable verification rather than permission to publish. ## Questions people ask **Can a marketplace use Maskbreak without CAPTCHAs?** Yes. Collect live browser evidence and evaluate it on your backend. Review can use existing MFA, email verification or moderator approval, with completion verified on the server. **Does a VPN automatically block a marketplace account?** No. A VPN alone produces review under Maskbreak’s base policy; customer rules and exceptions can change the final decision. A network signal is not proof that the account is fake. **How should a marketplace handle review?** Hold the protected action until the backend verifies the required check, bound to that account and action. Do not accept a browser-supplied passed flag or let repeated submissions duplicate a listing or reward. **Does Maskbreak replace KYC or chargeback protection?** No. Account-abuse screening does not establish legal identity, card ownership or payment authorization. Keep required identity checks, payment controls and dispute handling separate. --- # Suspicious login detection in Node.js URL: https://maskbreak.com/blog/nodejs-suspicious-login-detection Published: 2026-09-09 · Updated: 2026-10-27 > Add a server-side login risk check with Maskbreak’s Node.js SDK. Handle allow, review, block, missing evidence and API errors without bypassing authentication. - Use the official Node.js SDK to evaluate browser-collected evidence on your server before creating a login session. - Keep API keys out of the browser and preserve existing password, MFA, CSRF and rate-limit controls. - Only a usable production allow result passes this example’s fraud gate; review, failures and incomplete checks have separate paths. - Measure collection, network and server time in your own app instead of treating sample timing as a speed promise. Yes. Maskbreak can add a live login-risk check to a Node.js app at no cost on its Free plan. The Free plan includes 10,000 visitor checks a month with no credit card; paid plans start at €29 a month. Your server sends browser-collected evidence to the API and receives `decision`, `risk_score` and `reasons`, together with available network and device signals. The important part is what happens after the answer. A fraud API does not verify the user’s password, create a secure session or complete MFA. This guide adds a risk gate to an existing login flow and keeps those responsibilities in your application. ## 1. Collect evidence from the login page Load the browser SDK on your existing login page. For an ordinary form, the enrichment class adds `monocle` and `sentinel_fp` fields at submission. Keep your current inputs and CSRF protection; use your actual login URL. ```
``` For a custom JavaScript submission, wait until the SDK has loaded, call `window.Sentinel.collect()`, and include the returned `token` and `fingerprintEventId` in the request to your backend. If collection is blocked or unavailable, do not substitute a demo token. The server example below holds the login because its policy requires both kinds of evidence. ## 2. Install the official Node.js SDK ``` npm install @sentinelsup/sdk ``` The package keeps its original `@sentinelsup/sdk` name. Set `MASKBREAK_API_KEY` in your server’s environment or secret manager using your live account key. Do not use a frontend-exposed environment variable, commit the key, or copy it into a public support message. Use a supported Node.js release; the example uses CommonJS and SDK 0.3.1. ## 3. Add a risk gate without replacing authentication This is an Express integration fragment, not a standalone authentication system. Your app must already define `app`, `loginRateLimit` and `existingLoginHandler`. The latter verifies credentials, enforces required MFA and creates the session. Keep your existing CSRF/origin checks, and configure bounded JSON and URL-encoded body parsers before this route. The four-second timeout below is an example application budget, not a promised API latency. No session is created on review, missing evidence or an unavailable check. The JSON responses need to be connected to your login UI and its verification/recovery flow. ``` const Sentinel = require('@sentinelsup/sdk'); const apiKey = process.env.MASKBREAK_API_KEY; if (!apiKey || apiKey.startsWith('sk_test_')) { throw new Error('Configure a live server-side Maskbreak key.'); } const maskbreak = new Sentinel({ apiKey, timeoutMs: 4000 }); app.post('/login', loginRateLimit, async (req, res, next) => { const body = req.body || {}; const token = body.token || body.monocle; const fingerprintEventId = body.fingerprintEventId || body.sentinel_fp; if (typeof token !== 'string' || !token.trim() || token.startsWith('test_') || typeof fingerprintEventId !== 'string' || !fingerprintEventId.trim()) { return res.status(409).json({ error: 'Verification required.' }); } try { const result = await maskbreak.evaluate({ token, fingerprintEventId }); if (!result || !['allow', 'review', 'block'].includes(result.decision) || result.test || result.sandbox || result.sample) { throw new Error('No production verdict.'); } if (result.decision === 'block') { return res.status(403).json({ error: 'Request declined.' }); } if (result.decision === 'review' || result.degraded || typeof result.network?.vpn !== 'boolean' || typeof result.device?.antidetect !== 'boolean' || typeof result.device?.automation !== 'boolean') { return res.status(409).json({ error: 'Verification required.' }); } return next(); // Existing authentication still runs; this is not a session. } catch (err) { // The month's checks are used up: let the login continue unchecked until // the 1st (00:00 UTC), logged. Every other failure holds it. if (err && err.status === 429 && err.body?.code === 'monthly_quota_exceeded') { console.warn('[maskbreak] monthly_quota_exceeded: continuing unchecked'); return next(); } return res.status(503).json({ error: 'Verification unavailable. Try again later.' }); } }, existingLoginHandler); ``` The rate limiter runs before the paid-or-quota-bound dependency so a flood of login attempts cannot freely consume your allowance. The example also rejects fixture tokens and test-mode responses. Do not expose raw tokens, credentials or API keys in application logs. A trusted account identifier, if you later add account linking, must come from server-validated identity rather than an arbitrary field in the browser request. Express is only the HTTP adapter here. Fastify and NestJS can call the same SDK from their handlers or services; adapt their request, reply and authentication lifecycle explicitly. There is no special framework plugin required for this SDK call. From version 0.5.0 the SDK also forwards the collector’s optional `tz` field; with an older version, use the [raw HTTP example](https://maskbreak.com/integrate.md) if your integration needs that input. ## 4. Read the decision and the evidence separately FieldMeaning for your login flow `decision`Final allow, review or block recommendation, including applicable customer rules and exceptions. `risk_score` and `reasons`Signal score and machine-readable explanations. The score is not a probability of fraud. `network`VPN, proxy, Tor and related network evidence. The service is named when known. `device`Available browser/device evidence, which can include automation, antidetect and tampering signals. `degraded`Unavailable network evidence. Do not treat an otherwise allow response as a complete clean check. A VPN alone yields `review` in the base evaluation policy. Your account rules or exceptions may change the final decision, so route on `decision` rather than treating every VPN flag or legacy `isSuspicious` value as a block. Read the [full response contract](https://maskbreak.com/api#response-obj) for optional fields. For review, hold session creation and offer an additional check appropriate to the action, such as the account’s configured MFA. Bind the challenge to the attempted login and verify it on your server before completing authentication. A browser-supplied “passed” flag must never release the hold. [OWASP’s authentication guidance](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) covers layered controls, reauthentication and MFA. ## 5. Budget for latency, limits and failures Measure the complete journey: browser collection, the request to your backend, the API round trip and your authentication work. `evaluated_in_ms` measures server processing, not all of those steps. Neither a synthetic response’s timing value nor a single fast request establishes a global speed guarantee. The allowance is counted per calendar month, with no hourly cap: 10,000 visitor checks a month on the Free plan, more on paid plans. Authenticated IP lookups have their own allowance, ten times the plan’s visitor checks. HTTP 429 includes `Retry-After`; a used-up month answers with the code `monthly_quota_exceeded`. The SDK throws an error with `status` and `body` for HTTP failures but does not expose response headers, so use raw HTTP if you need those headers for capacity management. This login example returns a temporary unavailable state rather than automatically retrying or silently allowing the request, with one exception: when the month’s checks are used up it lets the login continue to your existing handler, unchecked and logged, until the 1st (00:00 UTC), so a used-up month, or a bot flood that used it up, never takes your login offline. Do not make people wait in a retry loop for the quota to reset. Offer a clear recovery path, investigate sustained capacity errors, and choose your application’s fallback deliberately. See [how to handle fraud API timeouts](https://maskbreak.com/blog/fraud-api-timeouts). The self-serve plans, the Free plan included, run under the [published terms](https://maskbreak.com/terms), not a contractual availability or latency guarantee; an SLA comes with Enterprise. ## How does this compare with other login tools? This is a Maskbreak-authored implementation guide, not a head-to-head accuracy test. These are different integration choices, checked against the linked product documentation on 9 September 2026: - Maskbreak: live browser collection plus server-side evaluation for network and available device signals; a Free plan of 10,000 visitor checks a month, no card, and paid plans from €29 a month. - [LoginLlama:](https://loginllama.app/) a login-focused API advertising 1,000 free checks each month without a card, with a risk score and codes for signals such as new devices and impossible travel. Compare its required inputs and fallback policy with your own. - [Cloudflare Turnstile:](https://developers.cloudflare.com/turnstile/get-started/server-side-validation/) a bot-challenge flow. Its token must be validated server-side, is single-use and expires after five minutes. Challenge validation is not a replacement for checking credentials or deciding how to handle account risk. If your main problem is choosing a free tool for signup, read [the fake account detection software comparison](https://maskbreak.com/blog/best-fake-account-detection-software). Whichever service you select, preserve the authentication controls you already depend on. ## 6. Prove the real flow before enforcing it Test allow, review, block, missing device evidence, timeout, invalid JSON, invalid credentials and quota exhaustion. Confirm that only the intended path reaches your existing session handler. Then run a controlled live browser visit and check the resulting event in your dashboard. A successful demo call tests branching; it does not prove your frontend is sending real evidence. Keep the tests and observations distinct. [Deterministic fixtures](https://maskbreak.com/blog/vpn-detection-api-test-cases) are useful for repeatable CI checks. Live tests establish that collection and your deployed backend are connected. Neither justifies claiming perfect detection, and both are worth doing before turning a new risk signal into a customer-facing refusal. ## Questions people ask **Is the Node.js login check free to start?** Yes. Maskbreak’s Free plan includes 10,000 visitor checks a month with no credit card; paid plans start at €29 a month. Authenticated IP lookups have their own allowance, ten times the plan’s visitor checks. **Does Maskbreak work with Express, Fastify or NestJS?** The framework-independent Node.js SDK and HTTP API can be called from those backends. This article includes an Express route example; Fastify and NestJS require adapting the request and response handling, not a separate Maskbreak plugin. **Does an allow result authenticate a user?** No. An allow recommendation only passes the fraud gate in this example. Your existing login handler must still verify credentials, apply MFA where required and create the session securely. **What should a Node.js app do with review?** Hold session creation and offer your application’s additional verification or review path. Verify that outcome on the server and bind it to the attempted login; do not accept a client-side passed flag. **Does Maskbreak guarantee a fixed login-check latency?** No global response-time guarantee is made here. Measure browser collection and server round trips in your deployment, set a deadline and give unavailable checks an explicit fallback. --- # Proxy detection API vs IP lookup URL: https://maskbreak.com/blog/proxy-detection-api-vs-ip-lookup Published: 2026-09-08 > Choose between IP screening and live visitor checks, protect API secrets, and handle review or missing evidence before granting signup benefits. - Match the evidence to the action: a bare IP address cannot reconstruct a live browser visit. - Keep lookup and evaluation parsers separate; their verdict and signal fields differ. - A VPN alone means review in the evaluation engine, not automatic refusal. - Give incomplete evidence its own state before releasing trial credits or account privileges. Your signup form is about to create an account and grant trial credits. You have the visitor’s IP address, so an IP lookup seems like the obvious check. But the question you need answered is broader: what evidence does this visit provide, and what should happen before the account receives something valuable? A [proxy detection API](https://maskbreak.com/proxy-detection) and an IP lookup can contribute different evidence (for the vendors side by side, see [proxy detection APIs compared](https://maskbreak.com/blog/proxy-detection-api-comparison)). Choose the integration by the decision your signup flow needs to make. In particular, do not treat a response containing a `vpn` field as proof that the endpoint checked for a live VPN tunnel. ## Choose the evidence your signup needs Maskbreak’s current production bare-IP lookup checks Tor exits and [cloud-server ranges](https://maskbreak.com/blog/datacenter-ip-detection). Live [VPN detection](https://maskbreak.com/vpn-detection) and [proxy detection](https://maskbreak.com/proxy-detection) use an SDK token through `POST /v1/evaluate`; the service is named when known. The [IP lookup reference](https://maskbreak.com/api#lookup) and [evaluation reference](https://maskbreak.com/api#evaluate) describe the separate interfaces. IntegrationInput and resultUseful signup question Bare-IP lookup`GET /v1/lookup/{ip}`; read `verdict`, `known`, and `signals`.Does this address match the available Tor or cloud-range evidence? Live network check`POST /v1/evaluate` with a browser `token`; read `decision`, `network`, and `reasons`.Does this visit show a VPN or proxy connection? Network plus device checkAdd `fingerprintEventId` to the evaluation; inspect returned `device` evidence.Are available device signals relevant to this signup policy? A lookup is useful when investigating an address from an existing event or screening a server-originated action with no browser collection. It cannot reconstruct a browser visit from an address in yesterday’s log. If the policy depends on browser evidence, collect it at the relevant interaction and handle collection failures explicitly. ## Avoid making the IP your entire signup gate [OWASP’s credential stuffing guidance](https://cheatsheetseries.owasp.org/cheatsheets/Credential_Stuffing_Prevention_Cheat_Sheet.html#ip-mitigation-and-intelligence) explains that distributed proxy traffic can evade per-IP controls and recommends layered defenses. That guidance addresses authentication attacks; applying its layering principle to signup is a design choice for your application. Consider two attempts from one workplace connection. One person signs up normally; another repeatedly claims an introductory offer. An address classification alone does not describe those actions. Keep your account and offer rules alongside the network check: verify the contact address, enforce eligibility on the server, and limit repeated attempts against the resource being claimed. Select controls around your actual abuse case. ## Collect in the browser, evaluate on the server After installing the SDK, call `window.Sentinel.collect()` at submission and forward its `token` and `fingerprintEventId` to your own signup backend. Your backend authenticates the evaluation. Secret account API keys stay server-only; neither the HTML nor the browser’s network requests should contain them. See [token collection](https://maskbreak.com/api#collect-token) and [authentication](https://maskbreak.com/api#authentication). This is the HTTP request shape from your server, with placeholders rather than working credentials. The device event field is optional; include it when collected, and decide whether your policy needs that evidence. ``` POST /v1/evaluate HTTP/1.1 Host: maskbreak.com Authorization: Bearer YOUR_SERVER_SIDE_API_KEY Content-Type: application/json { "token": "BROWSER_COLLECTED_TOKEN", "fingerprintEventId": "COLLECTED_DEVICE_EVENT_ID" } ``` Send evidence to the API and make the business decision on your server. Never accept a browser-supplied `decision: "allow"` as authorization. Reject fixture tokens in a production signup integration, and ensure test, sandbox, or sample responses cannot release real benefits. Repeated submissions should resolve to one signup operation, not repeated credit grants. ## Read the right response fields The two endpoints do not share a verdict parser. Evaluation uses `decision` and `network.proxy`; lookup uses `verdict` and `signals.proxied`. Preserve these distinctions when adapting responses into your own application model. Avoid fallback expressions that substitute `allow` when an expected field is missing. A lookup can return `known: false`, `signals: null`, and `verdict: "allow"`. Record that as no available IP evidence, not a verified clean connection. Likewise, a service name of `null` does not clear a live visit; use the classification and decision instead of requiring a recognizable operator name. Consult the [evaluation response fields](https://maskbreak.com/api#response-obj) when defining your parser. ## Give review a real signup path In the evaluation engine, a VPN alone leads to `review`, never `block`. Proxy or Tor evidence can produce `block`. Account rules and exceptions can change the final decision, so preserve decision-source details when present. Do not convert every VPN flag or legacy `isSuspicious` value directly into a refusal. For a trial product, a possible review path is to verify the email address before releasing credits. Another product may need a restricted account or a staffed queue. These are application policies, not automatic API actions. Write down what releases the restriction, how long it lasts, and what the applicant sees if verification cannot finish. ## Keep missing evidence visible An HTTP error, timeout, invalid JSON, or unexpected decision leaves your application without a usable verdict. A returned `degraded: true` marks unavailable network evidence and can coexist with a restrictive decision from other signals. Preserve that evidence; an `allow` with degradation does not establish a clean visit. Missing device data also needs attention if your policy requires it. Choose the fallback before granting credits. You might hold the grant while allowing account creation, provided the product supports that state. Keep the API outcome and your actual action separately in logs, without raw browser tokens or secret keys. The [fraud API timeout guide](https://maskbreak.com/blog/fraud-api-timeouts) covers deadlines and incomplete checks. ## Validate the whole signup journey Use the [deterministic public sandbox](https://maskbreak.com/api#sandbox) to check response handling, then test actual browser collection separately. Sandbox success is not evidence of real detection. Exercise a normal signup, VPN review, proxy block, unavailable collector, duplicate submission, and recovery from a hold. Observe proposed actions before enforcing them, following the [fraud detection rollout guide](https://maskbreak.com/blog/fraud-detection-rollout), and inspect whether each outcome leads to the intended customer journey. ## Questions people ask **Can IP lookup replace live proxy detection?** No. Maskbreak’s current production bare-IP checks cover Tor and cloud ranges. Live VPN and proxy checks require a browser token sent to /v1/evaluate; service names are provided when known. **Does an allow verdict prove a clean connection?** No. Check evidence availability, including known: false on lookup, degraded responses and missing device data required by your policy. An unavailable check is not proof that a visit is clean. --- # VPN Detection API Test Data: Fixtures and Cases URL: https://maskbreak.com/blog/vpn-detection-api-test-cases Published: 2026-09-08 > Test VPN API decisions with deterministic fixtures, verify customer outcomes, and handle missing evidence before testing controlled live visits. - Sandbox fixtures test response handling, not real detection quality or production speed. - Test the customer outcome after allow, review and block, not just the returned JSON. - Keep failures and missing evidence separate from clean visits. - Exercise account policy and live browser collection separately from public fixtures. A useful [VPN detection API](https://maskbreak.com/vpn-detection) test proves what your application does with the answer. A green check beside a JSON response does not show that the signup form offers a review path, that a blocked attempt receives no credits, or that a timeout stays separate from an approved visitor. Build three kinds of checks: deterministic fixtures for parsing and branching, application tests for customer outcomes, and controlled live visits for browser collection. Keep their results separate. If you are looking for a VPN test data API, start with fixtures, but do not present their predictable answers as evidence of detection quality. ## Start with the supported sandbox fixtures The [Maskbreak public sandbox](https://maskbreak.com/api#sandbox) accepts `POST /v1/evaluate` with `Authorization: Bearer sk_test_sandbox` and a supported `test_*` token. It returns deterministic simulated evidence, marked `test: true` and `sandbox: true`. It does not detect a real connection. Send only the token for your baseline tests. Additional email or timezone inputs can add signals and change the outcome. The following expectations apply to those token-only public sandbox requests. TokenDecisionEvidence to assert `test_clean``allow`VPN, proxy, and Tor flags are false. `test_vpn``review``network.vpn` is true; reasons include `vpn_detected`. `test_proxy``block``network.proxy` is true; reasons include `proxy_detected`. `test_datacenter``allow``network.datacenter` is true; reasons include `datacenter_asn`. `test_tor``block``network.tor` is true; reasons include `tor_exit_node`. The cloud-server fixture is a useful trap for accidental policy changes: evaluation does not block it merely for hosting classification. A production bare-IP cloud-range lookup instead returns `review` before exceptions. Keep endpoint expectations separate; do not copy a score threshold between them. ## Run a small contract check Run this as a Node.js module with built-in Fetch support. The key below is deliberately public. Your account’s secret API keys still belong only on your server. The deadline is a test-runner setting, not a performance claim or a recommended signup budget. ``` import assert from 'node:assert/strict'; const cases = [ ['test_clean', 'allow', null, null], ['test_vpn', 'review', 'vpn', 'vpn_detected'], ['test_proxy', 'block', 'proxy', 'proxy_detected'], ['test_datacenter', 'allow', 'datacenter', 'datacenter_asn'], ['test_tor', 'block', 'tor', 'tor_exit_node'], ]; for (const [token, decision, flag, reason] of cases) { const response = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { Authorization: 'Bearer sk_test_sandbox', 'Content-Type': 'application/json', }, body: JSON.stringify({ token }), signal: AbortSignal.timeout(5000), }); assert.equal(response.status, 200, `${token}: HTTP failure`); const data = await response.json(); assert.equal(data.test, true); assert.equal(data.sandbox, true); assert.equal(data.decision, decision, token); assert.ok(Array.isArray(data.reasons)); if (flag) assert.equal(data.network[flag], true); if (reason) assert.ok(data.reasons.includes(reason)); if (token === 'test_clean') { for (const key of ['vpn', 'proxy', 'tor']) { assert.equal(data.network[key], false); } } } console.log('Five sandbox cases passed; live detection was not tested.'); ``` [MDN’s Fetch guide](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#handling_the_response) explains that HTTP error responses do not automatically reject the promise. Check status before parsing and let failed assertions fail the run. Avoid a catch handler that prints success after a network error. Assert required fields and relevant reasons without requiring the entire response to remain byte-for-byte identical. ## Assert the customer outcome after the verdict The script checks the API contract. Your application tests must go further: - Allow: normal validation still runs, and repeated submissions grant a trial benefit once. - Review: the applicant sees the intended verification or restricted-account path. A VPN alone means review, never an automatic engine block. - Block: the protected operation does not execute, including through a background job or an alternative signup route. Do not route on `isSuspicious` alone: the VPN fixture sets that legacy flag while returning `review`. Test your decision mapping directly. Test the absence of a known service name too; production can name a VPN or proxy service when known, but your handler must work without one. See the [response reference](https://maskbreak.com/api#response-obj). ## Test missing evidence as its own condition Add local mocks for connection failure, deadline expiry, HTTP 401, HTTP 429, malformed JSON, and an unexpected decision. These are integration failures, not verdicts about the visitor. Include an HTTP 200 response carrying `allow` and `degraded: true`; it must not become “all checks passed.” Also test degraded review and block so available restrictive evidence is preserved. For authenticated live evaluation, an absent token can produce a degraded response, whereas a rejected token produces an error. Neither establishes a clean visitor. Test missing device evidence when your policy requires it, and simulate a late response after your application has already chosen a fallback. The [timeout guide](https://maskbreak.com/blog/fraud-api-timeouts) explains how to keep those states distinct. ## Separate account policy from public fixtures The public sandbox bypasses account rules and exceptions. Use account credentials in staging to test those settings; they can change the final decision for a fixture. Record the policy configuration and inspect `decision_source` and `engine_decision` when returned. A fixture test with an IP exception is different from a visitor exception needing real device context. An account test key with a real browser token exercises the live pipeline with test semantics; it is different from the public sandbox. See [account test keys](https://maskbreak.com/api#test-keys). Keep fixture runners isolated from production signup handlers. Reject test tokens and simulated response markers before granting real account privileges. ## Finish with controlled live visits Use your own test accounts and connections: a normal visit, a VPN connection, an authorized proxy setup, and a browser where collection is unavailable. Collect fresh SDK tokens and verify that your backend receives them. Current production raw-IP lookup only checks Tor and cloud ranges; it cannot substitute for live VPN or proxy testing. See [lookup limitations](https://maskbreak.com/api#lookup). Record the intended setup separately from the observed signals and customer outcome; investigate disagreements instead of relabeling the test. [OWASP recommends layered defenses](https://cheatsheetseries.owasp.org/cheatsheets/Credential_Stuffing_Prevention_Cheat_Sheet.html#defense-in-depth-metrics), including plans for individual controls failing. Keep your other signup safeguards active, then use the [rollout guide](https://maskbreak.com/blog/fraud-detection-rollout) to observe proposed decisions and verify recovery before broader enforcement. ## Questions people ask **Does sandbox success prove real VPN detection?** No. The public sandbox returns deterministic simulated evidence. Use it to test parsing and application branches, then exercise actual browser collection with controlled live visits. **Why does test_datacenter return allow?** Cloud-server classification alone does not trigger a restrictive evaluation-engine decision. The bare-IP lookup endpoint has separate rules. Account-specific rules and exceptions can also change evaluation decisions. --- # Fraud API timeouts: design the fallback URL: https://maskbreak.com/blog/fraud-api-timeouts Published: 2026-09-06 > A timeout is missing evidence, not an allow verdict. Choose fallbacks per action, bound retries and keep sensitive operations behind their authorization checks. - Track an unavailable check separately from a returned allow, review or block decision. - Choose the fallback per business action; a payout change needs a different boundary from reading account history. - Retrying a visitor check and retrying a business operation are separate decisions. - Keep partial signals from degraded responses, and test late answers, duplicate submissions and hold expiry. A customer submits a payout change. Your server asks Maskbreak for a visitor check, waits until its deadline, then gets no answer. The exception handler returns `allow` because someone wanted the integration to fail open. An infrastructure failure has just become permission to move money. A timeout tells you that an answer did not arrive in time. It says nothing about the visitor. Design the fallback around the action your customer is attempting, and keep that missing evidence visible. ## Keep unknown separate from the verdict Record two things independently: whether the check completed, and what your application decided to do. A completed check can return `allow`, `review`, or `block`. A timeout, connection failure, or unusable response leaves your application without a usable verdict. Give that condition an explicit local state such as `unknown`; it is not an additional Maskbreak API decision. Continuing is a policy choice. If your fallback permits an action, record “continued under timeout policy,” not “Maskbreak allowed.” Otherwise your reports cannot distinguish an assessed visitor from an outage. Keep HTTP errors distinct too. A rejected credential needs an integration fix, and a rate limit needs load control. Neither is evidence of customer fraud. Validate the response shape before using its decision; a successful HTTP status alone is insufficient. ## Budget the whole action Start with the time your application can spend completing this particular action. Reserve time for its own database work and response, then give the visitor check a bounded share. Measure from your backend, including connection setup and response reading. A timeout copied from a fast development laptop is not a production budget. [MDN documents AbortSignal.timeout()](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static) as a way to abort an operation after a specified duration, with a `TimeoutError` reason (accessed 2026-09-06). Use cancellation supported by your runtime and HTTP client. A browser timer is not the enforcement boundary; the server must own the deadline and fallback. Stopping your wait does not undo remote work. Also stop accepting late results into an action that has already reached its final state. Otherwise two asynchronous paths can try to complete the same customer operation. ## Choose a fallback for each action The following are starting points for your own policy, not Maskbreak defaults. Existing authentication, authorization, and abuse limits still apply. Customer actionPossible timeout fallbackBoundary to preserve Read account historyContinue within the existing session.Normal access checks still run. Create a trial accountCreate a restricted account if your product supports it.Hold valuable credits or bulk exports. Submit an orderKeep an order pending if fulfillment can wait.No shipment or digital delivery yet. Change payout detailsHold the change or require an approved verification path.No new destination becomes active automatically. Define who can release a hold, when it expires, and what the customer sees. A pending label needs an actual pending state behind it. If your system cannot safely hold an operation, refuse that operation temporarily and offer a clear retry path. [OWASP’s transaction authorization guidance](https://cheatsheetseries.owasp.org/cheatsheets/Transaction_Authorization_Cheat_Sheet.html) calls for server-side enforcement and a final authorization gate tied to execution (accessed 2026-09-06). Apply that principle when releasing a held action: check current authorization and the exact operation details again. A change to the destination or amount requires a new decision about that operation. ## Separate retries from business mutations Do not wrap “check visitor, create order, charge customer” in a generic retry. Retrying that sequence can repeat an operation that already succeeded. Use your application’s durable operation identifier and concurrency controls to reconcile existing state before attempting the business mutation again. Disabling a submit button alone does not prevent duplicate processing. [AWS guidance on controlling retries](https://docs.aws.amazon.com/wellarchitected/latest/framework/rel_mitigate_interaction_failure_limit_retries.html) recommends bounded attempts, backoff with jitter, and avoiding retries at multiple layers; it also warns about duplicated side effects (accessed 2026-09-06). Inspect any retries already performed by your HTTP client. A further attempt must fit the remaining deadline. Honor a returned `Retry-After`; if it exceeds that deadline, take the fallback. A repeated Maskbreak visitor check may create another event or consume additional quota. Do not assume it has deduplication semantics. Authentication and validation failures should not enter an automatic retry loop. ## Handle partial evidence without erasing it A returned response with `degraded: true` differs from receiving no response. Maskbreak can mark the network layer unavailable while another signal or a customer rule still produces `review` or `block`. Preserve the returned evidence. Conversely, `allow` with degraded network evidence does not establish that every layer checked the visitor successfully. See the [response reference](https://maskbreak.com/api#response-obj). Switching to [a bare-IP lookup](https://maskbreak.com/api#lookup) does not restore a live browser check. In the current production setup, bare-IP screening covers Tor exits and cloud-server ranges; VPN and proxy tunnel detection requires a live visit. A VPN by itself produces an engine decision of `review`, before customer overrides. Keep secret API keys on your backend. If a fallback uses a visitor IP, derive it through your framework’s trusted-proxy configuration. Accept forwarded headers only from proxies you control and trust; never use an arbitrary client-supplied IP as authoritative. ## Make fallbacks operable If you add a circuit breaker, it belongs to your integration: it can temporarily stop new checks and select the same endpoint-specific fallback. This article does not assume Maskbreak provides one. Define how limited recovery probes reopen normal checking and who owns an extended incident. Count eligible actions, attempted checks, unknown outcomes, degraded responses, and actual fallback actions by endpoint. Track pending age as well as pending count. Log an internal operation reference and policy version, not secret keys or raw browser tokens. Alert when missing evidence or waiting customers exceed the limits your team agreed to support. ## Before releasing the timeout policy - Force a timeout, connection failure, malformed response, and rate limit in staging. - Confirm unknown outcomes remain distinct from returned verdicts. - Verify sensitive mutations cannot bypass their final authorization gate. - Test duplicate submissions and a response arriving after the deadline. - Check degraded responses with both permissive and restrictive decisions. - Walk through hold release, expiry, customer messaging, and incident recovery. ## Questions people ask **Should a timeout become an allow verdict?** No. A timeout means no usable answer arrived within your deadline. If your application continues, record that as its own fallback choice rather than a Maskbreak allow verdict. **Does a degraded response always mean allow?** No. Missing network evidence can coexist with device signals, email signals or customer rules that produce review or block. Preserve those results and handle missing evidence explicitly. --- # Roll out fraud detection without lockouts URL: https://maskbreak.com/blog/fraud-detection-rollout Published: 2026-09-06 > Move from observation to enforcement with stable cohorts, a real review path, clear release gates and a rollback plan that restores customer journeys. - Observe mode belongs to your application, not an extra Maskbreak API parameter; existing safeguards stay active. - Sandbox fixtures test response handling, not live detection quality or production latency. - Give review an owner, capacity and a customer recovery path before enforcing a policy. - Measure missing evidence and legitimate completion, then rehearse rollback before expanding the cohort. A fraud integration can return perfectly valid JSON and still lock out customers. The missing step is often a rollout plan that connects each verdict to a usable customer journey, staffed review, and a way to recover when a policy behaves differently on real traffic. Start with one action you understand, such as granting trial credits. Write down what abuse you want to reduce, what legitimate completion looks like, and which existing safeguards must remain active throughout the release. ## Put observe mode in your application Observe mode is customer-side behavior. It is not a Maskbreak API parameter. Your backend performs the visitor check, records the proposed action, and continues using its existing enforcement policy. Maskbreak’s `decision` is advisory; your application controls what happens next. Use a server-controlled flag to separate observation from enforcement. Do not let a browser field select the mode. Record the eligible business action, whether a check ran, its returned `decision` and `reasons`, the candidate action, the actual action, and a policy version. Keep failures and degraded evidence visible. Record that history against an internal operation reference. Keep secret keys and raw SDK tokens out of logs. Observation still sends normal visitor checks to Maskbreak: it does not suspend normal usage, event processing, or configured alerts. Audit webhook consumers too; an automated suspension triggered downstream would make this an enforcement release. ## Test decision paths before real traffic The [public sandbox](https://maskbreak.com/api#sandbox) accepts deterministic `test_*` tokens through `sk_test_sandbox`. Use fixtures such as `test_clean`, `test_vpn`, and `test_proxy` to exercise your application’s allow, review, and block handling. They test wiring and response handling; they do not measure detection quality, live browser collection, or production latency. The public sandbox also bypasses account-specific rules and exception pins. Use account credentials with fixtures to test signal rules and IP exceptions; visitor exceptions need the corresponding live device context. Your personal test key can exercise the live pipeline with real browser tokens, with test events and without live webhooks. Validate webhook-dependent behavior separately. Keep account keys server-only; the public sandbox key is deliberately public. Add local failure fixtures for timeouts, malformed responses, missing tokens, and degraded evidence. Verify that a missing verdict selects your explicit fallback. Test a browser that blocks collection, and test trusted-proxy IP parsing: client-supplied forwarded headers must not determine the authoritative visitor IP. ## Keep cohorts coherent and comparisons honest Assign a cohort on the server using a stable internal account or tenant identifier. For anonymous flows, keep a server-controlled assignment stable through the relevant session or operation. Randomizing every HTTP request can make one checkout alternate between observe and enforce. Do not use an IP as a customer identifier: shared networks and changing mobile connections make it unstable. Choose the grouping that matches the product. A shared workspace may need one tenant-wide policy so colleagues receive consistent treatment. Record assignment before observing outcomes, and keep the policy version fixed while assessing that cohort. Compare equivalent actions and customer groups. A launch campaign, outage, or change in geography can alter completion independently of fraud controls. Report counts, denominators, and observation windows; a before-and-after change alone does not establish causation or statistical significance. ## Make review a real customer route Decide what `review` means for this endpoint: additional verification, a restricted capability, or a queue with an owner. A VPN alone produces `review` in Maskbreak’s engine, before customer overrides. Sending every review to the block screen turns that distinction into a customer lockout. [OWASP’s authentication guidance](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) describes reauthentication for sensitive features and risk events, with attention to unnecessary friction (accessed 2026-09-06). Use verification appropriate to the action and already-established account controls. A contact-change flow must not treat possession of the newly supplied address as proof of ownership. For manual review, estimate incoming cases against staffed handling capacity. Include weekends, escalations, and customers who cannot finish the normal challenge. Watch the oldest unresolved case; a modest queue can still contain someone forgotten for days. Give the customer a clear next step and support a safe recovery route. Define queue limits before launch. When capacity is exhausted, pause expansion or use the endpoint’s agreed restricted path. Do not silently approve sensitive operations because nobody is available, or leave every customer waiting indefinitely. ## Inspect traffic you have reason to trust Build a review sample from customers with independently established successful activity, plus your own controlled journeys. Include mobile networks, workplace VPNs, privacy browsers, shared devices, returning customers, and account recovery. Treat this as a diagnostic sample, not proof that every future visit from those accounts is safe. Inspect disagreements individually. Was the browser token missing? Did your policy convert review into refusal? Did a rule or exception change the engine decision? Preserve `decision_source` and matching-rule details when returned; `engine_decision` appears when an override changes the decision. Reproduce the journey before adding an exception. Use live visits for browser-dependent evidence. [Bare-IP screening](https://maskbreak.com/api#lookup) currently checks Tor exits and cloud-server ranges in production; it does not reproduce VPN or proxy tunnel detection from a browser visit. A clean-looking IP lookup cannot validate the full integration. ## Expand with explicit release gates Move from staging to observation, then enforce one understood policy for a small coherent cohort. Choose its size from operational capacity and exposure, not a universal percentage. Include support and the person who can stop the release. Avoid changing your challenge flow, matching rules, and cohort size simultaneously. Before expanding, inspect legitimate completion, challenge completion, support contacts, review age, unknown outcomes, and confirmed abuse outcomes where available. Give delayed outcomes time to arrive. Separate unlabeled activity from confirmed legitimate activity; the absence of a complaint is weak evidence. State which outcomes remain unresolved. Count eligible customer operations as the denominator for coverage, including operations whose checks failed. Report challenge completion against challenges started, and distinguish customer operations from repeated HTTP attempts. Agree stop conditions for lost coverage, growing queues, and interrupted legitimate journeys before enforcement begins. An improvement in one overall completion number must not hide a broken recovery flow. ## Measure rollback as part of the release Version the enforcement policy and keep the prior configuration available. Rehearse returning the affected cohort to its previous policy while retaining observation and baseline safeguards. Measure time to restore normal handling, customers still stuck in queues, repeated challenges, and actions needing manual repair. A flag change does not automatically reopen blocked accounts, restore expired reservations, or recall emails already sent. Assign ownership for those consequences. Confirm behavior across webhooks and background workers as well as the main endpoint before calling recovery complete. ## Before expanding the cohort - Observe mode and cohort assignment are controlled by your server. - Fixtures, account rules, live collection, and failure handling were checked separately. - Review has capacity, an expiry policy, and a customer recovery path. - Known-good journeys and policy disagreements have been inspected. - Measurements include denominators, delayed outcomes, and missing evidence. - Rollback restores the prior policy and assigns unfinished cases to an owner. ## Questions people ask **Does Maskbreak have an observe-mode request field?** No. Your server controls observation versus enforcement. It can record the returned verdict and proposed action while continuing to use its existing policy. Normal API processing, usage and configured alerts still apply. **Does a successful sandbox test prove detection quality?** No. The public sandbox returns deterministic fixtures. Test live browser collection, account rules, device context and production failure handling separately. --- # Gift Card Enumeration: How to Detect and Stop It URL: https://maskbreak.com/blog/gift-card-fraud-detection Published: 2026-08-29 · Updated: 2026-10-19 > Three gift card attacks that actually happen, why balance-check endpoints are your softest target, and where checks go without punishing real recipients. Gift cards are the only thing you sell that is already money. Nothing ships, nothing is named, and the balance moves the moment a code is known. That changes the attacker's problem: they are not trying to buy something and keep it, they are trying to turn stolen inputs into a clean, resellable balance. Three attacks account for almost all of it, and they need different answers. ## Draining: the balance-check endpoint is the target Your balance checker is usually a small form that takes a card number and a PIN and answers instantly. No login, no rate ceiling worth the name, and a response that differs depending on whether the card exists. That is an oracle, and it is the softest endpoint most retailers own. The attack is unglamorous: run millions of candidate numbers through it, keep the ones with money on them, and sell those. The cards were never stolen physically. They were guessed. What makes it work is that the endpoint is cheap to call and honest in its answers. Two fixes follow directly. Make the response uniform — the same shape and the same timing whether a card exists, has a balance, or does not exist at all. And put an infrastructure check in front of it, because a campaign that has to run at human pace from residential addresses costs a great deal more than one that runs from a rented box. ``` curl -X POST https://maskbreak.com/api/lookup \ -H 'Content-Type: application/json' \ -d '{"ip":"185.220.101.1"}' ``` ``` { "ip": "185.220.101.1", "known": true, "verdict": "block", "risk_score": 90, "signals": { "vpn": false, "proxied": false, "tor": true, "dch": false, "anon": true }, "network": { "asn": null, "org": "Tor exit node", "country": null, "city": null } } ``` ## Enumeration: why per-IP limits do nothing here Every retailer that has been hit tries per-IP rate limiting first, and it fails for the same arithmetic reason it fails against scrapers. A residential proxy pool spreads the guessing across thousands of home connections making a handful of requests each. No threshold you can set survives contact with that without also breaking the customer checking a card they were given at Christmas. The signal that survives rotation is the device. A card-checking run driven by one machine through a thousand addresses is still one machine, and the fingerprint does not rotate because the address did. Count attempts against the device identifier, not the IP, and the arithmetic reverses: the attacker now needs a thousand real machines instead of a thousand addresses, which is a different budget entirely. ``` // Count on what the attacker cannot cheaply change. let v = null; try { v = await sentinel.evaluate({ token: req.body.monocle, fingerprintEventId: req.body.sentinel_fp }); } catch (err) { // evaluate() throws without a token or when the API cannot be reached. // A used-up month (429, monthly_quota_exceeded) is the one failure that // goes ahead, unchecked and logged, until the 1st (00:00 UTC). if (!(err && err.status === 429 && err.body?.code === 'monthly_quota_exceeded')) { return res.status(503).json({ error: 'Balance check unavailable. Try again.' }); } console.warn('[maskbreak] monthly_quota_exceeded: continuing unchecked'); } const attempts = v ? await db.countRecent('giftcard_check', v.device?.visitor_id, '1 hour') : 0; if (attempts > 20) { return res.status(429).json({ error: 'Too many balance checks.' }); } if (v && v.decision === 'block') { return res.status(403).json({ error: 'Unavailable from this network.' }); } ``` Note the order. The velocity check runs on the device before the network verdict, because a patient attacker on a clean residential address is exactly the case the network layer will not catch. ## Laundering: buying cards with stolen cards The third attack runs in the other direction. Rather than draining your cards, the attacker buys them with a stolen payment card, because a gift card converts a card that will be charged back into a balance that will not be. Your chargeback arrives six weeks later; the code was resold on the day of purchase. This is the one where the fraud check has to sit at purchase, not redemption, and where the useful signals are the ordinary ones — a datacenter or tunnelled connection at checkout, a device that has bought gift cards under several different accounts, a billing country that has never matched this device before. The tell that separates it from ordinary card testing is the basket. Card testing wants the cheapest possible authorisation. Gift card laundering wants the highest denomination that will clear, often several at once, and it does not care about anything else in your catalogue. ## Where to put the checks Three surfaces, in the order they are worth doing. - Balance check. The highest-volume, lowest-friction target you own, and the one that is usually completely unguarded. Uniform responses plus a device-keyed velocity counter. - Gift card purchase. Where laundering is stopped, and where a review verdict should cost the buyer a verification step rather than the sale. - Redemption. Worth logging, rarely worth blocking. By redemption the money has usually already moved, and the person holding the code is often the innocent recipient of a resold card. That last point is the one teams get wrong. Blocking at redemption feels like enforcement and mostly punishes a customer who bought a card in good faith from a marketplace. The decision belongs earlier, where the attacker is, not later, where the victim is. ## Keep the recipient out of it Gift cards are given to people who are not your customers yet. They arrive with no account, no history, and no patience, often on a phone, often on a shared network. Anything that treats an unfamiliar device as suspicious by default will land hardest on exactly the person you most want to convert. Route on the decision rather than the score: block the unambiguous, add a step for the uncertain, and let everything else through untouched. A first-time device on a residential connection with no velocity behind it is the normal case, not the risky one. ## What this does not solve None of this recovers balances already drained, and none of it helps if your card numbers are sequential or your PINs are short. Guessability is a design problem, not a detection problem: enough entropy in the code space makes enumeration uneconomic before any of this runs. Detection buys you the time to fix that, and catches the campaigns that come anyway. ## Questions people ask **Why does rate limiting the balance-check endpoint not stop gift card draining?** Because rate limiting assumes the address is scarce and a residential proxy pool makes it abundant. The run spreads across thousands of home connections at a few attempts each, which sits under any threshold you can set without breaking real recipients checking a card they were given. Count attempts against the device identifier instead, which does not rotate when the address does. **Should I block gift card redemption if the risk score is high?** Usually not. By redemption the money has generally already moved, and the person holding the code is frequently an innocent buyer who got a resold card from a marketplace. Blocking there punishes the victim rather than the attacker. Put the decision at balance check and at purchase, and treat redemption as something to log rather than refuse. **How is gift card laundering different from card testing?** Card testing wants the cheapest authorisation that proves a stolen card works. Gift card laundering wants the highest denomination that will clear, often several at once, and ignores the rest of your catalogue. Both arrive at checkout with a stolen card, but the basket shape is the tell, and laundering converts a chargeback-able card into a balance that is gone the same day. **Does a uniform balance-check response really matter?** Yes, and the timing matters as much as the body. If a valid card with a balance answers differently, or faster, than a card that does not exist, the endpoint is an oracle and enumeration becomes a search problem with feedback. Make the shape and the latency identical across all three outcomes before you tune anything else. --- # Is an IP Address Personal Data Under GDPR? URL: https://maskbreak.com/blog/is-an-ip-address-personal-data Published: 2026-08-27 · Updated: 2026-10-21 > Yes, dynamic addresses included. What that means for a fraud check: lawful basis under Art. 6(1)(f), data minimisation, retention and processor questions. The short answer is yes, and it has been settled since 2016. The useful answer is that this does not stop you checking an address for fraud, because the Regulation names fraud prevention as a legitimate interest in its own recitals. This is a practical read of where the line sits, written by people who ship an IP check rather than by lawyers. It is not legal advice, and the balancing test at the end is one your own counsel should sign. ## The short answer, and where it comes from In Breyer v Bundesrepublik Deutschland (C-582/14, 2016) the Court of Justice held that a dynamic IP address is personal data in the hands of a website operator, provided that operator has legal means available to identify the subscriber behind it, typically by going through the access provider. The operator does not need to be able to do the identification alone, which is what killed the old argument that dynamic addresses were anonymous because they rotate. Treat every IP address you handle as personal data. The exceptions are narrow enough that building on them is not worth the exposure. ## Personal data is a starting point, not a prohibition A surprising number of teams stop at the classification and conclude they cannot run the check. That is the wrong inference. The GDPR does not forbid processing personal data. It requires a lawful basis, a purpose, proportionality, and limits on how long you keep it. For fraud work the basis is almost always legitimate interests, Art. 6(1)(f). Recital 47 says so directly: processing personal data strictly necessary for the purposes of preventing fraud constitutes a legitimate interest of the controller. That is unusually helpful language and it is worth quoting in your own documentation. Consent is the wrong basis here and you should resist reaching for it. A fraud check that a fraudster can decline is not a fraud check, and consent obtained under those conditions is not freely given, which makes it invalid twice over. ## What changes in practice Four things, and none of them are difficult. - Minimise. Send the address, and send it for a decision you actually make. Sending every request through a risk API so the data is there in case someone wants it later is not minimisation, and it is the pattern regulators find first. - Keep the answer, not the input. The verdict, the score and the boolean signals are what your fraud team reviews six weeks later. The raw address is rarely needed past the decision itself. Hashing or truncating it after a short window keeps the audit trail and drops the identifier. - Retain briefly and say the number out loud. A stated period you meet beats a vague one you exceed. It also forces the question of what the older rows are for, which usually turns out to be nothing. - Write the balancing test down. Not because anyone reads it, but because Art. 6(1)(f) is the basis that requires you to have done it, and reconstructing the reasoning two years later under pressure is miserable. ## Is your API vendor a processor or a controller? This determines what paperwork you need, and vendors are not always straight about it. A vendor that evaluates the address on your instruction, for your purpose, and does not reuse it for their own ends is acting as a processor. You need a data processing agreement under Art. 28, a sub-processor list, and transfer safeguards if the processing leaves the EEA. A vendor that feeds what you send into a shared reputation database used to score other customers is doing something for their own purposes as well. That makes them a controller for that part, and it means end-user data you sent is being used in ways your own privacy notice probably does not describe. Ask the question directly, in writing, before you integrate. The answer is a design decision on their side and they will know it immediately. ## Device fingerprinting is a different question Do not let the IP answer settle the device one. Reading an address off a connection is not storage of or access to information on terminal equipment, so ePrivacy Art. 5(3) and its consent requirement do not attach to it. A fingerprint gathered in the browser generally does, and the fraud-prevention exemption from consent is narrower than most implementations assume. Two adjacent techniques, two different legal analyses. [We wrote that one up separately](https://maskbreak.com/blog/is-device-fingerprinting-legal). ## What we do, specifically Stated plainly so you can compare it with whatever else you are evaluating. Evaluation records are retained for the life of the account, and the raw IP address in each row is one-way hashed after seven days, leaving the country code, the boolean signals and the score. Deletion from the Security page removes your data from live systems immediately under Art. 17, and encrypted backups stored in the EU (Cloudflare R2) are removed after 40 days, within a commitment of at most sixty days. Two caveats are in the privacy notice (Section 3): the copies made up to 16 October 2026 sit with our former backup provider, whose deletion rule we can no longer check, and the database keeps its own 30-day history, which would be used only to recover from a failure of the database. The full detail is in the [privacy notice](https://maskbreak.com/privacy) and the [data processing agreement](https://maskbreak.com/dpa), including the sub-processor list and the transfer position. ## The balancing test, in five lines If you need to produce one this afternoon, this is the shape of it. Have your own counsel check it. - Purpose. Preventing fraudulent signups, payments and account takeover on our service. - Necessity. The address is the minimum signal that distinguishes automated abuse from a customer at the moment of the decision. No less intrusive measure achieves it. - Impact. One address is processed per decision, hashed after a short retention window, never sold, never used for advertising or profiling unrelated to abuse. - Expectations. A user signing up for an account reasonably expects the operator to check whether the request is fraudulent. Recital 47 anticipates exactly this. - Safeguards. Stated retention, one-way hashing, no automated decision with legal effect without human review, and a documented route to object under Art. 21. That last safeguard is the one teams forget. If the check can refuse a signup on its own, look hard at Art. 22 and keep a human path available for anyone who asks for one. ## Questions people ask **Is a dynamic IP address personal data under GDPR?** Yes. The Court of Justice held in Breyer (C-582/14) that a dynamic IP address is personal data in the hands of a website operator where that operator has legal means available to identify the subscriber, usually through the access provider. Rotation does not make an address anonymous. Treat every address you handle as personal data. **Do I need consent to run an IP fraud check?** Generally no, and consent is the wrong basis to choose. Legitimate interests under Art. 6(1)(f) is the normal basis, and Recital 47 names fraud prevention as a legitimate interest directly. A fraud check a fraudster can decline is not a fraud check, and consent given under those conditions would not be freely given anyway. **How long can I keep IP addresses collected for fraud prevention?** The Regulation sets no number. It requires that you keep them no longer than necessary for the stated purpose and that you can justify the period you chose. In practice a short raw-address window followed by hashing or truncation covers the investigation need while dropping the identifier. State the number publicly and meet it. **Is my fraud API vendor a processor or a controller?** It depends on what they do with what you send. A vendor evaluating the address on your instruction and for your purpose is a processor, and you need an Art. 28 agreement with them. A vendor that also folds your traffic into a shared reputation product used for other customers is a controller for that part. Ask in writing before integrating. --- # Credential Stuffing Detection at the Login URL: https://maskbreak.com/blog/credential-stuffing-detection Published: 2026-08-19 > Why rate limits and CAPTCHAs push credential stuffing onto residential proxies, which signals still separate a replay from a real login, and what to do. Credential stuffing is a replay attack, not a guessing attack. The attacker already has valid username and password pairs from someone else’s breach and is testing which of them also work on you. Success rates are low per attempt and completely adequate in aggregate, because the list is free and the attempts are cheap. The two controls everyone reaches for first — a per-IP rate limit and a CAPTCHA — do work, in the narrow sense that they raise the attacker’s cost. What they mostly do is change the shape of the attack into one your logs stop recognising. This is about what is left to detect after that has happened. ## What the attack looks like after your rate limit works A stuffing run against an unprotected login is loud: thousands of POSTs from a handful of datacenter addresses, over minutes. Add a per-IP limit and the run does not stop, it redistributes. The list moves onto a residential proxy pool and becomes: - One attempt per exit address. A pool of a few hundred thousand residential IPs makes a per-IP counter unreachable by construction. The counter is not broken; it is counting the wrong noun. - Plausible geography. Exits are real consumer ISP addresses in the country the account belongs to, because the pool lets the attacker choose. - Low and slow. A list of ten million pairs does not need to clear in an hour. Spread over a fortnight it never looks like a spike on any dashboard you have. What survives this is that the attacker has changed the network and kept everything else. The requests still come from a small number of machines, and machines are what a device layer measures. ## Why each standard control misses - Per-IP rate limiting. Keep it — it is cheap and it stops the lazy version — but stop treating it as the control. Against rotating residential exits the threshold is never reached. - CAPTCHA. Solving services price bulk work in [cents per thousand challenges](https://maskbreak.com/blog/captcha-farms). That is a tax on the attacker and a tax on every real customer who logs in, applied in the wrong ratio: the attacker pays it once per list, your users pay it once per session. - MFA. Genuinely effective, for enrolled accounts. Enrolment is rarely universal, and the unenrolled accounts skew towards the older, more valuable ones. - Breached-password screening. Stops future reuse. Does nothing about credentials that leaked last year and still work. ## The signals that still separate a replay from a real login Three layers, in the order they cost you something. Network. `network.datacenter` still catches the unsophisticated half, and it costs nothing to check. `network.tor` is a smaller population but a strong one at a login. `network.proxy` against a residential exit is the modern shape and the reason network signals alone are not enough — a good residential pool looks like a customer. Device. This is where the attack stops being able to hide, because the pool rotates addresses and not machines. - device.visitor_id is stable across cookie clears and incognito, so the same machine attempting account after account keeps the same id. - device.times_seen: 1 on a login to an account that has existed for two years is the tell. It is not proof — people buy laptops — but it is the single most useful number on the response at a login. - device.antidetect (and the antidetect_browser reason) means the browser is lying about itself, which is what an [antidetect browser](https://maskbreak.com/antidetect) is for. Route on the flag and the decision, not on a threshold of device.tampering_score: the score is the device check’s own 0–1 reading, not a probability of fraud. - device.linked_accounts is the only signal here that is literally the attack rather than a proxy for it: one device, many distinct accounts, inside your own tenant. You get it by passing your accountId alongside fingerprintEventId. Session shape. No token at all means no JavaScript ran, which for a login form is either a hardened browser or a script. Treat it as degraded rather than as guilt, and count how often it happens per account. ## Where the check goes Before the password comparison, and after the account lookup. That ordering is deliberate on both sides. Running it before the lookup means you cannot pass `accountId` and you lose `linked_accounts`, which is the signal worth the most. Running it after the password verify means you have spent a bcrypt round on every attempt in the run, which is a small denial-of-service the attacker gets for free. ``` // routes/login.js const Sentinel = require('@sentinelsup/sdk'); const sentinel = new Sentinel({ apiKey: process.env.MASKBREAK_API_KEY }); app.post('/api/login', loginRateLimit, async (req, res) => { const { email, password, monocle, sentinel_fp } = req.body; // Indexed read, no password work yet — but it gives the // verdict an accountId, which is what returns linked_accounts. const user = await findUserByEmail(email); let v = { decision: 'allow', degraded: true }; try { v = await sentinel.evaluate({ token: monocle, fingerprintEventId: sentinel_fp, accountId: user?.id, }); } catch (err) { req.log.error({ err }, 'sentinel unavailable'); // fail open } const ok = user && await verifyPassword(user, password); // One response for every failure, whatever caused it. if (!ok || v.decision === 'block') { await recordAttempt(email, v); return res.status(401).json({ error: 'Invalid login' }); } const newDevice = v.device?.times_seen === 1; if (v.decision === 'review' || newDevice) { await sendDeviceVerification(user); return res.json({ next: 'verify_device' }); } return issueSession(res, user); }); ``` ## What to do at each band - allow, returning device. Issue the session. This is the overwhelming majority of logins and it should feel like nothing happened. - allow, times_seen: 1. A new machine on an existing account. Send the new-device notice and let it through if the account holds nothing liquid; require an emailed code if it does. - review. Step up. An emailed code is enough, and it converts far better than a CAPTCHA because it only fires for the few percent that earned it. - block. Refuse — identically to a wrong password, see below. - device.multi_account with linked_accounts in double digits. That is the run itself, in progress. It deserves an alert and a look at what else that device touched, not just a 401. Bands and where to put the boundaries are covered properly in [the thresholds post](https://maskbreak.com/blog/risk-score-thresholds); the short version is to route on `decision` and use `risk_score` only for sorting a review queue. ## The mistake that undoes all of it If a blocked-but-correct credential produces a different status code, a different response body, or a visibly different latency than a wrong password, your defence has become a validation oracle. The attacker stops trying to log in and starts harvesting a verified credential list instead, which is worth more per line than the accounts are. Same status, same body, same rough timing — and do the step-up decision after both checks have run, not between them. ## Failing open, and what to watch instead Login is availability-critical in a way that signup is not: fail closed on a vendor blip and you have locked out every customer, including the ones with support contracts. Fail open, mark the verdict `degraded`, and alert on the rate of degraded logins rather than on individual ones. An absent verdict means “no opinion”, never “safe”, so the code around it has to be written as though it might be missing. Store `reasons` and `risk_score` on the attempt record, not just the outcome. Six weeks later, when you want to know whether the step-up threshold is too tight, the reason codes are the only thing that can answer it. ## Checklist - Account lookup, then evaluate, then password verify. - accountId and fingerprintEventId both sent, or linked_accounts is absent. - One identical failure response for wrong password and for blocked. - Step-up on review and on first-seen devices, not on every login. - Fail open, mark degraded, alert on the rate. - reasons persisted on the attempt row. - Per-IP rate limit still in place, but not counted on. ## Questions people ask **Is per-IP rate limiting still worth having?** Yes, but as hygiene rather than as the control. It stops unsophisticated runs from a handful of addresses for almost no cost. It cannot stop a run distributed across a residential proxy pool, because each exit makes one attempt and the counter never reaches its threshold. Keep it and add a signal that is not the IP. **Will blocking datacenter IPs stop credential stuffing?** It stops the cheap half and pushes the rest onto residential exits, which look like customers. Datacenter is worth checking because it costs nothing, but a policy built only on it degrades over a few weeks as the attacker notices. The device layer is what keeps working, because a proxy pool rotates addresses and not machines. **Should a first-seen device always trigger a step-up?** On accounts that hold money or personal data, yes — an emailed code fires for a small share of logins and is far cheaper than an account takeover. On low-value accounts a new-device notification is usually enough. What you should not do is treat times_seen: 1 as fraud on its own: people buy laptops, reinstall browsers and travel. **Does MFA make credential stuffing detection unnecessary?** For enrolled accounts it removes most of the risk. The problem is coverage: enrolment is rarely universal and the unenrolled accounts skew towards older, higher-value ones. Detection is also what tells you a run is happening at all, which MFA does not — a wall of failed second factors is a symptom you would rather see named. --- # Flask Fraud Detection: One Decorator URL: https://maskbreak.com/blog/flask-fraud-detection Published: 2026-08-15 · Updated: 2026-10-08 > A screening decorator for Flask that survives gunicorn forking, ad blockers and a dead upstream — with the session-reuse and timeout details. Flask makes this integration short enough that the interesting part is not the code. A decorator, a module-level client, and the fraud check runs before your view does. Three things around it decide whether it survives real traffic, and all three are Flask and WSGI concerns rather than fraud concerns. Those three: a `requests.Session` created in the wrong place relative to the gunicorn fork, a request with no timeout, and a view that returns 500 because the vendor had a bad minute. This walks through all of it, in the three steps the Maskbreak console lists: add the script to the page with your form, send the check from your server, and submit your form once. It starts in watch mode, where every check is logged and nothing is refused. ## Step 1: Add the script to the page with your form The server needs evidence only the browser can produce. In your templates, load the script and put `class="monocle-enriched"` on the `
` element itself (never on an input): ``` {{ form.csrf_token }}
``` The script adds three hidden inputs to that form, `monocle` (network token), `sentinel_fp` (browser check id) and `sentinel_tz` (time zone), so they arrive in `request.form` like any other field. For a JSON endpoint, call `await window.Sentinel.collect()` in the browser (check that `window.Sentinel` exists, and submit anyway when it does not) and send its `token`, `fingerprintEventId` and `tz` in the body. If you send a `Content-Security-Policy` (Flask-Talisman does), add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server The key is a server-side credential: put your live key in a `MASKBREAK_API_KEY` environment variable, never in the repository, and never in a template. ``` # .env (never committed) MASKBREAK_API_KEY=sk_live_your_key_here # MASKBREAK_MODE=enforce (later; unset means watch) ``` The client is `requests` (`pip install requests` if the app does not have it yet). One client for the process, created at import time, is right for the threaded and gevent workers people actually run. The function maps the form's names to the API's and calls even when a field is missing, because a check without a token or a browser check id is how the console tells you which half is missing. It never raises. ``` # app/fraud.py import logging import os import requests log = logging.getLogger("maskbreak") MODE = os.environ.get("MASKBREAK_MODE", "watch") # "watch" or "enforce" # Created at import, per worker (see the fork note below). session = requests.Session() def evaluate(data, account_id=None): """Returns the verdict (a dict), or None when there is none. None never means 'safe'. Never raises.""" email = data.get("email") payload = { "token": data.get("monocle") or data.get("token") or "", "fingerprintEventId": data.get("sentinel_fp") or data.get("fingerprintEventId"), "tz": data.get("sentinel_tz") or data.get("tz"), "email": email if isinstance(email, str) else None, "accountId": account_id, } result = None try: # Three seconds: this sits in front of a user-facing action. resp = session.post( "https://maskbreak.com/v1/evaluate", json={k: v for k, v in payload.items() if v is not None}, headers={ "Authorization": "Bearer " + os.environ.get("MASKBREAK_API_KEY", ""), "Content-Type": "application/json", }, timeout=3, ) if resp.ok: result = resp.json() elif resp.status_code < 500: # A 4xx is your bug (a bad key, a malformed body). Log it loudly. log.error("maskbreak rejected the request: HTTP %s", resp.status_code) else: log.warning("maskbreak unavailable: HTTP %s", resp.status_code) # their 5xx except (requests.RequestException, ValueError) as e: # Timeout, connection reset. Weather. Count it. log.warning("maskbreak unavailable: %s", type(e).__name__) # One line per check. Never log the key, the token or form data. log.info("maskbreak mode=%s decision=%s reasons=%s device_evidence=%s degraded=%s", MODE, result.get("decision") if result else None, result.get("reasons") if result else None, result.get("device_evidence") if result else None, bool(result.get("degraded")) if result else None) return result ``` Python's root logger drops `INFO` unless you configure it; `logging.basicConfig(level=logging.INFO)` in your app factory (or your gunicorn logging config) makes the line visible. Now the fork. If you create the connection pool in the gunicorn parent, which is what happens with `--preload`, every worker inherits the same open sockets and they interfere with one another. The symptoms are the confusing kind: occasional truncated responses, or SSL errors that never reproduce locally because your dev server never forks. Module-level creation in a module imported by the app factory is safe under the default gunicorn behaviour, because each worker imports it after forking. If you use `--preload`, rebuild the session per worker instead: ``` # gunicorn.conf.py def post_fork(server, worker): import requests import app.fraud app.fraud.session = requests.Session() ``` The same rule applies to any database pool you keep next to it. It is the most common production-only bug in this integration and it has nothing to do with fraud. ## The decorator ``` # app/fraud.py (continued) from functools import wraps from flask import abort, g, request, session as flask_session def clean_allow(v): """A complete, production allow.""" return bool(v) and v.get("decision") == "allow" and v.get("device_evidence") == "ok" \ and not v.get("degraded") and not v.get("test") def screen(strict=False): """Enforce mode: strict=False refuses a block only; strict=True continues only on a clean, complete allow. Watch mode never refuses anything.""" def outer(view): @wraps(view) def inner(*args, **kwargs): data = request.get_json(silent=True) if not isinstance(data, dict): data = request.form g.verdict = evaluate(data, account_id=flask_session.get("user_id")) if MODE == "enforce": if g.verdict and g.verdict.get("decision") == "block": abort(403) if strict and not clean_allow(g.verdict): abort(409) return view(*args, **kwargs) return inner return outer ``` `@wraps` is not decoration for its own sake here. Without it every screened view reports the same `__name__`, and Flask raises on the second one you register because it maps endpoints by function name. ## Applying it ``` # app/routes.py from flask import g from app.fraud import MODE, screen # Signup: in enforce mode, refuse only a block. VPN users are customers. @bp.post("/register") @screen() def register(): ... # Money leaving: in enforce mode, only a clean, complete allow continues. @bp.post("/withdraw") @screen(strict=True) def withdraw(): ... # Checkout: the review band costs a step, not the sale. @bp.post("/checkout") @screen() def checkout(): v = g.get("verdict") if MODE == "enforce" and v and v.get("decision") == "review": return step_up() # OTP, 3DS, manual queue return charge() ``` Decorator order matters and gets this wrong quietly. `@bp.post` must be outermost: it registers whatever function is beneath it, so putting `@screen()` above it registers the undecorated view and your screening never runs. The route still works, which is what makes it hard to notice. Put `@login_required` above `@screen()` too, so an unauthenticated request is rejected before you spend a check on it. A plain VPN returns `review` deliberately. Refusing it costs you a large population of privacy-conscious customers to catch a small number of abusers. See [risk score thresholds](https://maskbreak.com/blog/risk-score-thresholds) for where each band belongs. ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your log shows one `maskbreak` line. `degraded=True` means no network token arrived; `device_evidence=not_sent` means no browser check id arrived; `device_evidence=ok` with `degraded=False` is a complete check. ## The failure modes, decided in advance No token. The collector did not run: a content blocker, a content-security-policy mistake, JavaScript disabled, or a client that never loaded your page. It is common on real traffic and it is not evidence of anything. The check still goes out (Maskbreak answers it, marked `degraded`), so the console can show you how often it happens. Upstream unavailable. Timeout, reset, or a 5xx. `evaluate` returns `None` and the view continues. Count it and alert on the rate rather than on single events. Rejected request. A 4xx is your bug, a bad key or a malformed body, and it will not fix itself. It is logged at `error`, distinctly from the outage case, or it hides inside the noise for a month. ``` from prometheus_client import Counter eval_failures = Counter("fraud_eval_failures_total", "Fraud API calls that produced no verdict", ["kind"]) # ...in evaluate(), next to the log lines: # eval_failures.labels(kind="upstream").inc() ``` ## If you are on async views or ASGI Flask 2 supports `async def` views, but they run on a worker thread rather than on an event loop, so a blocking call inside one is not the disaster it would be in a native ASGI framework. If you run Flask under an ASGI server or have moved to Quart, push the blocking call off the loop explicitly: ``` import anyio verdict = await anyio.to_thread.run_sync(lambda: evaluate(data, account_id)) ``` ## Test the paths you hope never run The public sandbox key returns fixed answers for the test tokens, so the block path is an ordinary test. Run it with `MASKBREAK_MODE=enforce`: ``` def test_blocked_signup_is_refused(client, monkeypatch): monkeypatch.setenv("MASKBREAK_API_KEY", "sk_test_sandbox") monkeypatch.setattr("app.fraud.MODE", "enforce") r = client.post("/register", data={ "monocle": "test_proxy", # the sandbox answers block "email": "a@example.com", }) assert r.status_code == 403 def test_signup_survives_an_outage(client, monkeypatch): monkeypatch.setattr("app.fraud.MODE", "enforce") monkeypatch.setattr("app.fraud.evaluate", lambda *a, **k: None) r = client.post("/register", data={"email": "a@example.com"}) assert r.status_code in (200, 302) ``` The second test is the one that earns its place. Fail-open is a policy, and without a test asserting it, a later refactor turns it into fail-closed and nobody notices until the vendor has an incident. ## The short version - Script on the page, class on the
, three hidden fields forwarded as token, fingerprintEventId and tz. - Call every time, even without a token, and log one line. Watch mode never refuses. - @bp.post stays outermost. Above @screen() it registers the unscreened function and the check silently never runs. - Do not create the session before gunicorn forks. With --preload, rebuild it in post_fork. - Set a timeout on every call. There is no useful default in front of a user. - In enforce mode, review is a step-up, not a soft block. A plain VPN is a customer. ## Questions people ask **Why does my Flask fraud check work locally but fail under gunicorn?** Almost always the fork. If the HTTP client and its connection pool are created in the gunicorn master — which is what --preload does — every worker inherits the same sockets and they corrupt each other, producing intermittent SSL errors and truncated responses that never reproduce on the dev server because it does not fork. Create the client at import time in a module the app factory imports, or rebuild it in a post_fork hook. **What order do Flask decorators go in?** The route decorator must be outermost. @bp.post("/register") registers whatever function sits directly beneath it, so if @screen() is above the route the unscreened view gets registered and the check never runs — with no error to tell you. Put authentication above screening too, so an unauthenticated request is rejected before you spend an API call on it. **What if the user has an ad blocker and no token is sent?** That is normal traffic, not an attack signal. Content blockers, a strict CSP and disabled JavaScript all stop the script for real users. Send the check anyway (Maskbreak answers it marked degraded, and the console shows how often it happens) and let the request through. Only a strict route in enforce mode holds it for verification. **Should I use the SDK or plain requests?** Plain requests, for this decorator. The SDK helpers need a token and do not forward the time zone, and watch mode should send every check, including one without a token, so the console can show what is missing. Post JSON with a Bearer key to /v1/evaluate, keep one Session per worker so connections are reused, and pass a timeout on every call. --- # Spring Boot Fraud Detection Without a Java SDK URL: https://maskbreak.com/blog/spring-boot-fraud-detection Published: 2026-08-15 · Updated: 2026-10-08 > A RestClient bean, an interceptor, and the three Spring details that decide whether this survives production: pooling, timeouts, and failing open. There is no Java SDK. For an API with one endpoint that matters, the wrapper is a `RestClient` bean and a record, well under a hundred lines including the failure handling. Writing it yourself means the timeout, the pool size and the fail-open policy are decisions you made rather than defaults you inherited, and in Spring the defaults are exactly where this goes wrong. Three of those defaults will hurt you in production, and none of them has anything to do with fraud: `RestClient` ships with no read timeout, the stock HTTP client opens a fresh connection per call, and a `@ControllerAdvice` that has never seen a vendor outage will turn a detection blip into a 500 on your signup form. Written for Spring Boot 3.2 or later on Java 21, in the three steps the Maskbreak console lists: add the script to the page with your form, send the check from your server, and submit your form once. It starts in watch mode, where every check is logged and nothing is refused. ## Step 1: Add the script to the page with your form One script tag in your layout, and `class="monocle-enriched"` on the `` element itself (never on an input): ```
``` The script adds three hidden fields to that form: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone). They arrive as ordinary request parameters. For a JavaScript frontend, call `await window.Sentinel.collect()` in the browser (check that `window.Sentinel` exists, and submit anyway when it does not) and post its `token`, `fingerprintEventId` and `tz` as form fields (`URLSearchParams` or `FormData`) alongside your own, so they still arrive as request parameters. No API key goes anywhere near the browser. If Spring Security writes a `Content-Security-Policy`, add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server Spring's `RestClient.builder()` gives you no read timeout at all unless you set one. A vendor whose TCP connect succeeds but whose response never arrives would hold your request thread until something else gives up, and on a signup endpoint "something else" is usually the user. ``` // src/main/java/com/example/fraud/FraudConfig.java @Configuration public class FraudConfig { @Bean // Empty when unset: the app still starts, and every check logs a 401 at error. RestClient maskbreakClient(@Value("${MASKBREAK_API_KEY:}") String key) { var factory = new JdkClientHttpRequestFactory(); // Short on purpose: this sits in front of a user-facing action. factory.setReadTimeout(Duration.ofSeconds(3)); return RestClient.builder() .baseUrl("https://maskbreak.com") .defaultHeader("Authorization", "Bearer " + key) .defaultHeader("Content-Type", "application/json") .requestFactory(factory) .build(); } } ``` `JdkClientHttpRequestFactory` wraps the JDK's own `HttpClient`, which keeps connections alive between calls; the older `SimpleClientHttpRequestFactory` does not pool at all and hands you a fresh TLS handshake on every signup. If Apache HttpClient 5 is on your classpath, size its pool explicitly. The key comes from the `MASKBREAK_API_KEY` environment variable (or your secrets manager), never `application.properties` in the repository. The response field is `risk_score` and your record component is `riskScore`. Jackson will not bridge that gap on its own, and the failure is silent: a valid object with a zero in it. Annotate the fields you read: ``` // src/main/java/com/example/fraud/Verdict.java @JsonIgnoreProperties(ignoreUnknown = true) public record Verdict( String decision, // allow | review | block @JsonProperty("risk_score") int riskScore, List reasons, @JsonProperty("device_evidence") String deviceEvidence, // ok | not_sent | unavailable boolean degraded, boolean test) { public boolean blocked() { return "block".equals(decision); } /** A complete, production allow: what a strict action needs in enforce mode. */ public boolean cleanAllow() { return "allow".equals(decision) && "ok".equals(deviceEvidence) && !degraded && !test; } } ``` The service sends whatever evidence arrived, including none: in watch mode a check without a token or a browser check id still has to reach Maskbreak, because that is how the console tells you which half is missing. It never throws. ``` // src/main/java/com/example/fraud/FraudService.java @Service public class FraudService { private static final Logger log = LoggerFactory.getLogger("maskbreak"); private final RestClient client; final String mode = Objects.requireNonNullElse(System.getenv("MASKBREAK_MODE"), "watch"); FraudService(RestClient maskbreakClient) { this.client = maskbreakClient; } public boolean isEnforcing() { return "enforce".equals(mode); } /** Returns null when the verdict is unavailable. Null means "no opinion", * never "safe". */ public Verdict evaluate(HttpServletRequest req, String accountId) { var body = new HashMap(); body.put("token", Objects.requireNonNullElse(first(req, "monocle", "token"), "")); putIfPresent(body, "fingerprintEventId", first(req, "sentinel_fp", "fingerprintEventId")); putIfPresent(body, "tz", first(req, "sentinel_tz", "tz")); putIfPresent(body, "email", req.getParameter("email")); putIfPresent(body, "accountId", accountId); Verdict v = null; try { v = client.post().uri("/v1/evaluate").body(body).retrieve().body(Verdict.class); } catch (HttpClientErrorException e) { // 4xx is our bug: bad key, malformed body. Loud. log.error("maskbreak rejected the request: {}", e.getStatusCode()); } catch (RestClientException e) { // Timeout, DNS, connection reset, their 5xx. Countable, not fatal. log.warn("maskbreak unavailable: {}", e.getClass().getSimpleName()); } // One line per check. Never log the key, the token or form data. log.info("maskbreak mode={} decision={} reasons={} device_evidence={} degraded={}", mode, v == null ? null : v.decision(), v == null ? null : v.reasons(), v == null ? null : v.deviceEvidence(), v == null ? null : v.degraded()); return v; } private static String first(HttpServletRequest req, String a, String b) { var x = req.getParameter(a); return (x != null && !x.isBlank()) ? x : req.getParameter(b); } private static void putIfPresent(Map m, String k, String v) { if (v != null && !v.isBlank()) m.put(k, v); } } ``` Those two catch clauses are the whole failure design. A 4xx is a mistake you made and it will not fix itself, so it belongs at `error` where someone will see it. A timeout is weather. Returning `null` for both is deliberate: the calling code decides what an absent verdict means, and that differs between a newsletter form and a withdrawal. Do not let this method throw; if a detection outage propagates out of here, your `@ControllerAdvice` turns it into a 500. ## Wire it once, not per controller A `HandlerInterceptor` runs after Spring has worked out which handler serves the request, which means you can key the policy off an annotation instead of a URL list that drifts. In watch mode it records the verdict and always continues. ``` // Screen.java @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface Screen { /** Enforce mode: true continues only on a clean, complete allow. */ boolean strict() default false; } // FraudInterceptor.java @Component public class FraudInterceptor implements HandlerInterceptor { private final FraudService fraud; FraudInterceptor(FraudService fraud) { this.fraud = fraud; } @Override public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) throws IOException { if (!(handler instanceof HandlerMethod hm)) return true; var screen = hm.getMethodAnnotation(Screen.class); if (screen == null) return true; var verdict = fraud.evaluate(req, currentAccountId(req)); req.setAttribute("verdict", verdict); if (!fraud.isEnforcing()) return true; // watch: log only boolean refuse = (verdict != null && verdict.blocked()) || (screen.strict() && (verdict == null || !verdict.cleanAllow())); if (refuse) { res.setStatus(verdict != null && verdict.blocked() ? 403 : 409); res.setContentType("application/json"); res.getWriter().write("{\"error\":\"refused\"}"); return false; } return true; } } ``` Register it against the paths that need it, not against everything; screening a health check is a per-request cost with no upside: ``` @Configuration class WebConfig implements WebMvcConfigurer { private final FraudInterceptor interceptor; WebConfig(FraudInterceptor i) { this.interceptor = i; } @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(interceptor) .addPathPatterns("/register", "/login", "/checkout", "/withdraw"); } } ``` Then the policy lives on the handler, where the person changing it can see what it protects: ``` // Signup: in enforce mode, refuse only a block. VPN users are customers. @Screen @PostMapping("/register") public String register(@Valid SignupForm form) { ... } // Money leaving: in enforce mode, only a clean, complete allow continues. @Screen(strict = true) @PostMapping("/withdraw") public String withdraw(@Valid PayoutForm form) { ... } ``` ## The review band is not a block Most of the value is in what you do with `review`, and the common mistake is treating it as a soft block. It is the band where you do not have enough evidence to refuse and should buy some: ``` @Screen @PostMapping("/checkout") public String checkout(@Valid Order order, HttpServletRequest req) { var verdict = (Verdict) req.getAttribute("verdict"); if (verdict != null && "review".equals(verdict.decision()) && fraud.isEnforcing()) { return stepUp(order); // OTP, 3DS, manual queue } return charge(order); } ``` A plain VPN lands in `review` on purpose. There is more on where to put each threshold in the [risk score thresholds](https://maskbreak.com/blog/risk-score-thresholds) post. ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your log shows one `maskbreak` line. `degraded=true` means no network token arrived (the script was blocked, or the class is missing or on an input); `device_evidence=not_sent` means no browser check id arrived; `device_evidence=ok` with `degraded=false` is a complete check. When the lines look right after a few days, set `MASKBREAK_MODE=enforce` and redeploy. A fixed test token such as `test_clean` comes back with `test: true` and never passes a strict route. ## Virtual threads, and why the timeout still matters On Java 21 with `spring.threads.virtual.enabled=true`, blocking on this call no longer pins a platform thread, and the instinct is to conclude that timeouts stopped mattering. They matter more. Virtual threads make it cheap to accumulate thousands of requests all waiting on the same dead upstream, and the thing that runs out is not threads but connections and heap. The read timeout is what bounds that, and it is still not set by default. If the upstream is properly down rather than slow, a circuit breaker (`resilience4j-spring-boot3`) saves you the queue entirely; make its fallback return `null`, the same "no opinion" the catch blocks return. ## The short version - Script in the layout, the class on the
, three hidden fields forwarded as token, fingerprintEventId and tz. - Call every time, even without a token, and log one line. Watch mode never refuses. - Set the read timeout. There is no default, and virtual threads make an unbounded wait worse. - Annotate risk_score and device_evidence. A silent default is the worst failure mode in this integration. - 4xx is your bug and belongs at error; a timeout is weather and belongs at warn. Both mean "no opinion", never "safe". - In enforce mode, treat review as a step-up, not a soft block. A plain VPN is a customer. ## Questions people ask **Is there an official Java or Spring Boot SDK?** No. There are official Node, Python and PHP SDKs; Java integrations use plain HTTP. For a single endpoint that is a RestClient bean and a record — under a hundred lines with the error handling — and it leaves the timeout, pool and fail-open policy as decisions you made rather than defaults you inherited. **Why does my Verdict record always show a risk score of zero?** The JSON field is risk_score and the record component is riskScore, so Jackson has nothing to bind and leaves the primitive at its default. Annotate the component with @JsonProperty("risk_score"). Do not fix it by switching the whole application to SNAKE_CASE, which silently renames every other DTO you own. **What timeout should a fraud check use in Spring Boot?** A few seconds at most for a user-facing action (the guide uses three), and you must set it explicitly because RestClient and WebClient both default to unbounded. Enabling virtual threads does not remove the need: it makes it cheap to pile up thousands of requests against a dead upstream, so the timeout is what bounds the damage. **Should the signup fail if the fraud API is down?** For signup and login, no — fail open, count the failure, and alert on the rate. A detection outage that takes registration down with it costs more than the abuse it would have caught. For irreversible money movement the trade flips: queue the payout for manual review rather than approving it blind. Either way the absent verdict means "no opinion", never "safe", and the calling code has to be the one that decides. --- # Blocking Fake Signups in Supabase URL: https://maskbreak.com/blog/supabase-fraud-detection Published: 2026-08-15 · Updated: 2026-10-08 > auth.signUp runs on Supabase infrastructure, not yours — so the fraud check has to go somewhere else. Three places it can go, and which one to pick. Every framework guide about screening signups starts from the same assumption: you own the endpoint, so you put a check in front of it. Supabase breaks that assumption. `supabase.auth.signUp()` goes from the browser straight to Supabase's own auth service. There is no server of yours in the path, so there is nothing to wrap. That leaves three places the check can actually live, and they are not equivalent. One runs before the user exists, one runs after, and one moves the signup onto infrastructure you control. Picking the wrong one is how teams end up deleting fraudulent accounts on a schedule instead of never creating them. ## The three options, ranked 1. A Before User Created auth hook. Supabase calls your endpoint before it writes the user, and an error response aborts the signup. This is the only option where the fraudulent account never exists, and it is the right default. 2. An Edge Function that owns the signup. The client calls your function, the function checks and then creates the user with the service role key. More control, more code, and you inherit responsibility for everything the built-in signup handles: rate limits, email confirmation, error messages. 3. A database webhook after the fact. Fires after the row is written. Useful for enrichment and analytics, wrong as a gate: by the time it runs, the account exists, the confirmation email has gone out, and you are cleaning up rather than preventing. The rest of this walks through the first, then the second for the cases the hook cannot cover, in the three steps the Maskbreak console lists: add the script to the page with your form, send the check from your server (here, an Edge Function), and submit your form once. It starts in watch mode, where every check is logged and nothing is refused. ## Step 1: Add the script to the page with your form Wherever the check ends up, it needs evidence the visitor's browser produced. Load the script on the page with your signup form: ``` ``` A Supabase signup is a JavaScript call, so ask the script for the evidence when the visitor submits and pass it through the signup call's metadata. `Sentinel.collect()` resolves to `{ token, fingerprintEventId, tz }` and waits at most five seconds for the browser check. Check that `window.Sentinel` exists, and never hold the signup back when it does not: a content blocker or a strict CSP removes it for real visitors. ``` // src/signup.ts const evidence = window.Sentinel ? await window.Sentinel.collect().catch(() => null) : null; // script missing or blocked: sign up anyway const { data, error } = await supabase.auth.signUp({ email, password, options: { // Arrives on the hook payload as user.user_metadata.maskbreak. data: { maskbreak: { token: evidence?.token ?? null, fingerprintEventId: evidence?.fingerprintEventId ?? null, tz: evidence?.tz ?? null, }, }, }, }); ``` Two things to be clear-eyed about. User metadata is client-supplied, and a determined attacker can put whatever they like in it. The token is verified server-side when it is evaluated, so a forged one cannot pass as a clean reading: Maskbreak answers it with an error, which the hook below treats like missing evidence. And the evidence can legitimately be missing: content blockers stop the script for real users, so the hook has to have an answer for that case rather than treating it as guilt. The values stay in the user's metadata after signup; they are opaque, and you can clear them later with the admin API if you would rather not keep them. If your site sends a `Content-Security-Policy`, add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server (an Edge Function) Both options share one helper. It sends whatever evidence arrived, including none: in watch mode a check without a token or a browser check id still has to reach Maskbreak, because that is how the console tells you which half is missing. It never throws, and it logs one line per check to the function's logs. ``` // supabase/functions/_shared/maskbreak.ts export const MODE = Deno.env.get("MASKBREAK_MODE") ?? "watch"; // "watch" | "enforce" type Evidence = { token?: string | null; fingerprintEventId?: string | null; tz?: string | null }; // Returns the verdict, or null when there is none. Never throws. export async function checkVisitor(ev: Evidence | null | undefined, email?: string) { let result: Record | null = null; try { const res = await fetch("https://maskbreak.com/v1/evaluate", { method: "POST", headers: { Authorization: "Bearer " + Deno.env.get("MASKBREAK_API_KEY"), "Content-Type": "application/json", }, body: JSON.stringify({ token: ev?.token || "", fingerprintEventId: ev?.fingerprintEventId || undefined, tz: ev?.tz || undefined, email: typeof email === "string" ? email : undefined, }), // Supabase is waiting on this, and so is a person at a spinner. signal: AbortSignal.timeout(2500), }); if (res.ok) result = await res.json(); else console.warn("[maskbreak] HTTP", res.status); // 401: the key, 400: the body } catch (err) { console.warn("[maskbreak] unavailable:", (err as Error).name); } // One line per check. Never log the key, the token or form data. console.log("[maskbreak]", JSON.stringify({ mode: MODE, decision: result?.decision ?? null, reasons: result?.reasons ?? null, device_evidence: result?.device_evidence ?? null, degraded: result ? !!result.degraded : null, })); return result; } ``` ### Option 1: the Before User Created hook The hook is an HTTP endpoint you host, an Edge Function here, that Supabase calls synchronously before writing the user. Supabase signs each call; verify the signature before trusting a byte of it. ``` // supabase/functions/screen-signup/index.ts import { Webhook } from "https://esm.sh/standardwebhooks@1.0.0"; import { MODE, checkVisitor } from "../_shared/maskbreak.ts"; const hook = new Webhook(Deno.env.get("HOOK_SECRET")!.replace("v1,whsec_", "")); Deno.serve(async (req) => { const raw = await req.text(); let payload; try { payload = hook.verify(raw, Object.fromEntries(req.headers)); } catch { return new Response("unauthorized", { status: 401 }); // not from Supabase } const user = payload.user ?? {}; const verdict = await checkVisitor(user.user_metadata?.maskbreak, user.email); if (MODE === "enforce" && verdict?.decision === "block") { // Supabase surfaces this to the client and aborts the signup. return new Response(JSON.stringify({ error: { http_code: 403, message: "Sign-up unavailable from this connection." }, }), { status: 403, headers: { "Content-Type": "application/json" } }); } // Watch mode, no verdict (outage), allow or review: the signup goes ahead. return new Response("{}", { status: 200, headers: { "Content-Type": "application/json" } }); }); ``` Register it in the dashboard under Authentication, Hooks, pointing at the function URL, and copy the signing secret into `HOOK_SECRET`. Deploy with `--no-verify-jwt`, because Supabase calls the hook with its own signature rather than a user JWT: ``` supabase functions deploy screen-signup --no-verify-jwt supabase secrets set MASKBREAK_API_KEY=sk_live_... HOOK_SECRET=v1,whsec_... ``` `--no-verify-jwt` makes the endpoint publicly callable, which is exactly why the signature check at the top is not optional. Without it, anyone who finds the URL can post arbitrary payloads to your screening logic. Three constraints worth knowing before you commit to this route. The hook is synchronous and Supabase enforces its own timeout, so keep your deadline comfortably inside it. It only fires for signups that go through Supabase Auth, so a user you insert with the admin API bypasses it entirely. And refusing on `review` rather than `block` is a mistake here: a plain VPN lands in `review`, and this path has no way to ask the user for a second factor. ### Option 2: an Edge Function that owns the signup When you want more than a yes or no (a step-up for the middle band, your own rate limiting, a row in your own table), move the signup into a function and call it instead of `auth.signUp`. The client posts `{ email, password, ...evidence }`, with `evidence` from `Sentinel.collect()` as above. ``` // supabase/functions/signup/index.ts import { createClient } from "jsr:@supabase/supabase-js@2"; import { MODE, checkVisitor } from "../_shared/maskbreak.ts"; const admin = createClient( Deno.env.get("SUPABASE_URL")!, Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!, // server only ); const json = (body: unknown, status: number) => new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } }); Deno.serve(async (req) => { const { email, password, token, fingerprintEventId, tz } = await req.json(); const verdict = await checkVisitor({ token, fingerprintEventId, tz }, email); if (MODE === "enforce" && verdict?.decision === "block") { return json({ error: "refused" }, 403); } const { data, error } = await admin.auth.admin.createUser({ email, password, email_confirm: false, user_metadata: { risk_score: verdict?.risk_score ?? null, needs_review: MODE === "enforce" && verdict?.decision === "review", }, }); if (error) return json({ error: error.message }, 400); return json({ user_id: data.user.id }, 200); }); ``` The service role key bypasses row-level security completely. It belongs in function secrets and nowhere else: never in a `VITE_` or `NEXT_PUBLIC_` variable, never in the client bundle. Note what you have taken on by choosing this path: the built-in signup handles email confirmation, password strength, captcha integration, rate limiting and consistent error codes, and every one of those is now yours to reproduce. Choose it when you genuinely need the control, not because the hook felt indirect. ## Step 3: Submit your form once Deploy, open your app in an ordinary browser, wait a moment, and sign up once. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and the function's logs show one `[maskbreak]` line. `degraded: true` means no network token arrived (the script was blocked, or `collect()` was not called); `device_evidence: "not_sent"` means no browser check id arrived; `"ok"` with `degraded: false` is a complete check. When the lines look right after a few days, set `MASKBREAK_MODE=enforce` with `supabase secrets set`. ## What to do with the review band The value in screening is not only refusing the obvious. Persisting the verdict lets you treat the middle band as what it is: not enough evidence to refuse, and a good reason to ask for more. ``` -- Everything the app reads goes through this, not through -- auth.users directly. create table public.profiles ( id uuid primary key references auth.users(id) on delete cascade, risk_score int, needs_review boolean default false, created_at timestamptz default now() ); alter table public.profiles enable row level security; -- A flagged account can read itself but cannot act. Enforce that -- once, in the database, rather than in every client. create policy "own profile" on public.profiles for select using (auth.uid() = id); ``` Then gate the actions that matter (posting, withdrawing, inviting) on `needs_review` being false, and clear the flag after an email or phone confirmation. That is a far better outcome than a block for a customer who happens to use a VPN, and it costs an abuser real effort. More on band-by-band policy in [risk score thresholds](https://maskbreak.com/blog/risk-score-thresholds). ## This is not the same thing as Supabase's captcha Supabase has built-in captcha support for auth endpoints, and it is worth enabling; it is also a different measurement. A captcha asks whether something at the other end can solve a puzzle. Commercial solving services clear that cheaply, and it says nothing about whether the connection is a residential proxy or the browser an antidetect profile with a spoofed canvas, which is what a professional multi-accounting operation looks like. Run both: the captcha filters crude automation, and the check answers questions the captcha cannot ask. There is more in [bot detection without CAPTCHA](https://maskbreak.com/blog/bot-detection-without-captcha). ## The short version - You do not own auth.signUp, so there is no middleware slot. Pick a hook, a function, or a webhook. - Collect { token, fingerprintEventId, tz } with Sentinel.collect() and send all three, every time, even when one is missing. - The Before User Created hook is the default: the fraudulent account never exists. - Verify the hook signature. --no-verify-jwt makes the endpoint public, and that check is what protects it. - Watch first. In enforce mode refuse on block only: the hook cannot step a user up, and a plain VPN lands in review. - The service role key never leaves function secrets. - Database webhooks fire after the row exists. That is enrichment, not prevention. ## Questions people ask **How do I block fake signups in Supabase Auth?** Use a Before User Created auth hook. Supabase calls your endpoint synchronously before writing the user, and a non-2xx response aborts the signup, so the fraudulent account is never created at all. Host the hook as an Edge Function, verify the signing secret on every request, and keep your own timeout comfortably inside the hook timeout so a slow check does not stall registration. **Can I run a fraud check inside a Supabase Edge Function?** Yes. Edge Functions run Deno with normal fetch, so calling the API is an ordinary HTTPS request with the key read from function secrets. Always attach a deadline (AbortSignal.timeout): without one, a slow upstream holds the function until the platform kills it, and the user sees a hung form rather than a signup. **Is a database webhook good enough for blocking signups?** No. Webhooks fire after the row is committed, so the account already exists and the confirmation email has already gone out. That makes them useful for enrichment, scoring and analytics, and unsuitable as a gate. If the requirement is that the account is never created, the check has to run before the write, which means an auth hook. **Does Supabase captcha protection already cover this?** It covers a different question. A captcha establishes that something at the other end could solve a puzzle, which stops crude automation and is cleared cheaply by commercial solving services. It cannot tell you the connection came through a residential proxy or that the browser is an antidetect profile with a spoofed fingerprint. Enable both: they fail in different places. --- # SvelteKit Bot Detection in hooks.server.ts URL: https://maskbreak.com/blog/sveltekit-bot-detection Published: 2026-08-15 · Updated: 2026-10-08 > One server hook, typed locals, and the SvelteKit details that decide whether it holds: form actions versus endpoints, and what not to screen. SvelteKit has one server-side chokepoint, `handle` in `hooks.server.ts`, and everything that reaches your server goes through it. That makes the integration short. It also makes it easy to screen things you never meant to screen, which costs you an API call per favicon request and a slower page load for the privilege. This covers the browser half, the hook, the typing, form actions versus `+server.ts` endpoints, and the adapter differences that matter once you deploy, in the three steps the Maskbreak console lists: add the script to the page with your form, send the check from your server, and submit your form once. It starts in watch mode, where every check is logged and nothing is refused. ## Step 1: Add the script to the page with your form Load the script once in the root layout: ``` ``` Then mark the forms that matter, with `class="monocle-enriched"` on the `` itself. On a full page load the script adds three hidden fields to such a form: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone). But SvelteKit usually reaches a page by client-side navigation, and a form rendered after the page loaded posts without `monocle`. So ask the script for the evidence at submit time and put it in the form data. `use:enhance` lets you do that before the post goes out: ``` ``` A form that was on the page when it loaded also carries the hidden fields the script added, so a post that skips `enhance` (a submit before the page has hydrated) arrives with the same field names. Without JavaScript nothing is added, and the check goes out without evidence. If your app sends a `Content-Security-Policy` (`kit.csp` in `svelte.config.js`), add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server ``` // src/lib/server/maskbreak.ts: server-only, never imported by client code import { MASKBREAK_API_KEY } from '$env/static/private'; import { env } from '$env/dynamic/private'; // Optional, so it comes from the dynamic module: a static import of a // variable that is not set fails the build. export const MODE = env.MASKBREAK_MODE ?? 'watch'; // 'watch' | 'enforce' // Form posts carry monocle / sentinel_fp / sentinel_tz; a JSON endpoint // gets token / fingerprintEventId / tz from Sentinel.collect(). export async function readFields(request: Request): Promise> { try { if ((request.headers.get('content-type') ?? '').includes('application/json')) { const body = await request.json(); return body && typeof body === 'object' ? body : {}; } return Object.fromEntries(await request.formData()); } catch { return {}; } } const str = (v: unknown) => (typeof v === 'string' && v ? v : undefined); // Sends whatever evidence arrived, including none: a check without a token // or a browser check id is how the console tells you which half is missing. // Returns the verdict, or null. Never throws. export async function checkVisitor(b: Record, accountId?: string) { let result: App.Verdict | null = null; try { const res = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { Authorization: 'Bearer ' + MASKBREAK_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ token: str(b.monocle) ?? str(b.token) ?? '', fingerprintEventId: str(b.sentinel_fp) ?? str(b.fingerprintEventId), tz: str(b.sentinel_tz) ?? str(b.tz), email: str(b.email), accountId, }), signal: AbortSignal.timeout(3000), // in front of a user-facing action }); if (res.ok) result = await res.json(); else console.warn('[maskbreak] HTTP', res.status); // 401: the key, 400: the body } catch (err) { console.warn('[maskbreak] unavailable:', (err as Error).name); // outage: no opinion } // One line per check. Never log the key, the token or form data. console.log('[maskbreak]', JSON.stringify({ mode: MODE, decision: result?.decision ?? null, reasons: result?.reasons ?? null, device_evidence: result?.device_evidence ?? null, degraded: result ? !!result.degraded : null, })); return result; } ``` The hook runs the check on the few POST paths that need it and puts the verdict on `event.locals`: ``` // src/hooks.server.ts import type { Handle } from '@sveltejs/kit'; import { checkVisitor, readFields } from '$lib/server/maskbreak'; // Screen these paths only. Screening every request buys you an API // call per favicon and a slower page. const SCREENED = [/^\/signup/, /^\/login/, /^\/checkout/, /^\/api\/(withdraw|invite)/]; export const handle: Handle = async ({ event, resolve }) => { const wanted = event.request.method === 'POST' && SCREENED.some((re) => re.test(event.url.pathname)); if (!wanted) return resolve(event); // Read the body without consuming it: clone first, or the action // that runs next finds an empty stream. const fields = await readFields(event.request.clone()); event.locals.verdict = await checkVisitor(fields, event.locals.user?.id); return resolve(event); // the hook gathers; actions and endpoints decide }; ``` The `clone()` is not optional and its failure mode is unpleasant. A request body is a stream that can be read once; consume it in the hook and the form action downstream receives an empty `formData`, so every field looks missing and validation rejects a perfectly good signup. `$env/static/private` (inside `$lib/server`) is what guarantees the key cannot reach the browser: SvelteKit refuses at build time if a private or server-only module is pulled into client code. Importing the key from `$env/static/public` would ship it in the bundle. Set `MASKBREAK_API_KEY` to your live key in your host's environment variables. ## Type the locals Without this, `event.locals.verdict` is a type error and people reach for `any`, which defeats the reason you are using TypeScript on the risky path: ``` // src/app.d.ts declare global { namespace App { interface Verdict { decision: 'allow' | 'review' | 'block'; risk_score: number; reasons: string[]; device_evidence?: 'ok' | 'not_sent' | 'unavailable'; degraded?: boolean; test?: boolean; } interface Locals { user?: { id: string }; verdict?: Verdict | null; } } interface Window { Sentinel?: { collect(opts?: { timeout?: number }): Promise<{ token: string | null; fingerprintEventId: string | null; tz: string | null; }>; }; } } export {}; ``` Note the union on `decision`. It is what makes a typo in a comparison a compile error rather than a branch that silently never runs. ## Using the verdict in a form action Deciding belongs in the action, where you can see what is at stake. In watch mode nothing is refused: ``` // src/routes/signup/+page.server.ts import { fail } from '@sveltejs/kit'; import type { Actions } from './$types'; import { MODE } from '$lib/server/maskbreak'; export const actions: Actions = { default: async ({ request, locals }) => { const v = locals.verdict; // No verdict: a blocked script or an outage. Degraded, not hostile. if (MODE === 'enforce' && v?.decision === 'block') { return fail(403, { error: 'Sign-up unavailable from this connection.' }); } const data = await request.formData(); const user = await createUser(data, { needsReview: MODE === 'enforce' && v?.decision === 'review', }); return { success: true, id: user.id }; }, }; ``` `fail` rather than `error` is deliberate: it returns the message to the same page with the form state intact, so a false positive is a sentence the user can read rather than an error page they bounce from. For a JSON endpoint the client posts the `collect()` values in the body, and the hook reads them the same way: ``` // src/routes/api/withdraw/+server.ts import { json } from '@sveltejs/kit'; import type { RequestHandler } from './$types'; import { MODE } from '$lib/server/maskbreak'; export const POST: RequestHandler = async ({ locals, request }) => { const v = locals.verdict; // Money leaving: in enforce mode, only a clean, complete, production allow. const clean = v?.decision === 'allow' && v.device_evidence === 'ok' && !v.degraded && !v.test; if (MODE === 'enforce' && !clean) { return json({ error: 'Additional verification required' }, { status: 409 }); } return json(await payout(await request.json())); }; ``` Two different thresholds on two routes, and that is the point: signup refuses only a hard block because VPN users are customers, while an irreversible payout holds the middle band, missing evidence and test results too. There is more on picking those lines in [risk score thresholds](https://maskbreak.com/blog/risk-score-thresholds). ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your server log shows one `[maskbreak]` line. `degraded: true` means no network token arrived (the script was blocked, or the form posted without the `enhance` function); `device_evidence: "not_sent"` means no browser check id arrived; `"ok"` with `degraded: false` is a complete check. When the lines look right after a few days, set `MASKBREAK_MODE=enforce` and redeploy. ## What changes per adapter The hook code is identical across adapters; the runtime around it is not. adapter-node. Ordinary Node, with a caveat about addresses: behind a reverse proxy, `event.getClientAddress()` returns the proxy's address unless the server is started with `ADDRESS_HEADER=X-Forwarded-For` and a correct `XFF_DEPTH`. Get that wrong and every visitor appears to come from your load balancer, which quietly ruins any per-address logic you build alongside this. adapter-cloudflare and adapter-vercel edge. The hook runs on a Workers-style runtime with no Node built-ins, which the code above already respects: it uses only `fetch` and `AbortSignal`. Watch the subrequest and CPU limits if you add anything heavier. adapter-static. There is no server, so `hooks.server.ts` never runs. A prerendered route cannot be screened at all, which is worth knowing before you mark a signup page `prerender = true` for the page-speed number. ## What the hook does not do Screening a form submission answers one question at one moment. It does not stop someone scraping your product pages, and it should not: a `GET` on a public page is not where this belongs, and running the check on every navigation makes your site slower for everyone in exchange for very little. If content scraping is the problem, that is an edge concern; see [bot detection at the Cloudflare edge](https://maskbreak.com/blog/cloudflare-workers-bot-detection). It also does not replace rate limiting: per-address and per-account attempt limits remain the cheapest control you own. ## The short version - Script in the root layout, the class on the
, and Sentinel.collect() in use:enhance so a client-rendered form still carries the evidence. - One handle hook, screening a short list of POST paths, sending token, fingerprintEventId and tz every time, even when one is missing. - clone() the request before reading the body, or the form action downstream sees nothing. - Import the key from $env/static/private. The public equivalent ships it to the browser. - Watch first. In enforce mode the hook gathers and the action decides: block-only on signup, strict on money. - Adapters differ: the address header on Node, the runtime limits at the edge, and no hook at all when prerendered. ## Questions people ask **Where does bot detection go in a SvelteKit app?** In the handle function in src/hooks.server.ts, which every server request passes through. Screen a short list of POST paths rather than everything: running the check on asset and navigation requests costs an API call each and slows the site for no benefit. Put the verdict on event.locals and let each form action or endpoint decide what to do with it. **Why is my form action receiving empty form data?** The hook read the request body first. A body is a stream that can only be consumed once, so calling formData() in hooks.server.ts leaves nothing for the action. Call event.request.clone().formData() instead and the original stream stays intact. **How do I keep the API key out of the client bundle?** Import it from $env/static/private. SvelteKit fails the build if a private environment module is reachable from client code, which turns the mistake into a compile error rather than a leaked credential. $env/static/public is bundled into the browser and must never hold a server key. **Does this work on Cloudflare Pages or Vercel Edge?** Yes, provided the hook uses only Web APIs (fetch and AbortSignal), which the code here does. There are no Node built-ins involved. Keep the timeout tight, because the platform terminating a long invocation is less graceful than your own deadline, and mind the subrequest limits if you call more than one service from the same hook. --- # WooCommerce Fraud Detection Guide URL: https://maskbreak.com/blog/woocommerce-fraud-detection Published: 2026-08-15 · Updated: 2026-10-08 > Two WordPress hooks, one HTTP call, and the caching and checkout details that decide whether it works — including the form that empties your token. A WooCommerce checkout is a public, scriptable endpoint with the same shape on a very large number of stores. That is why card testing finds it: a script posts stolen card numbers through the ordinary order flow, keeps the ones that authorise, and leaves you with the gateway fees and the chargebacks. Registration spam and coupon farming arrive through the same door. The fix is a small plugin: the script on the checkout and account pages, one HTTP call, and two hooks. What makes it fail in production is rarely the hook. It is a form that never gets the browser evidence, a page cache serving a stale nonce, a `wp_remote_post` with WordPress's default five-second timeout in front of a customer, and refusing the order in the wrong place, after the payment has already been taken. This guide follows the three steps the Maskbreak console lists (add the script to the page with your form, send the check from your server, submit your form once) and starts in watch mode, where every check is logged and nothing is refused. It covers the classic checkout (the `[woocommerce_checkout]` shortcode) and the My Account registration form. The Cart and Checkout blocks are covered at the end. ## Step 1: Add the script to the page with your form Enqueue the script on the checkout and account pages from a small plugin, rather than pasting a tag into a theme file that the next update overwrites. The script fills only forms that carry `class="monocle-enriched"` on the `` element itself, and WooCommerce renders both forms without it, so one inline line adds the class before the script runs. Never put the class on a hidden input: the input stays empty, and an empty `monocle` field on the page also hides the real one from `Sentinel.collect()`. ``` true, 'strategy' => 'async']); // The class goes on the elements themselves, before the script runs. wp_add_inline_script('maskbreak', "document.querySelectorAll('form.woocommerce-checkout, form.woocommerce-form-register')" . ".forEach(function (f) { f.classList.add('monocle-enriched'); });", 'before'); }); ``` The script then adds three hidden fields to those forms: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone). The classic checkout posts every field of its form, so they reach PHP in `$_POST`. If your site sends a `Content-Security-Policy` (a security plugin, or your host), add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. If an optimisation plugin delays or combines JavaScript, exclude `sentinel.js` and the inline line above from it. ## Step 2: Send the check from your server The key belongs in `wp-config.php` as a constant, not in the options table where it lands in every database export you send to a developer: ``` // wp-config.php, above "That's all, stop editing!" define('MASKBREAK_API_KEY', 'sk_live_your_key_here'); // define('MASKBREAK_MODE', 'enforce'); // later; unset means watch ``` WordPress ships an HTTP client, so there is no dependency to add. The function maps the form's names to the API's (`monocle` to `token`, `sentinel_fp` to `fingerprintEventId`, `sentinel_tz` to `tz`) and calls even when a field is missing: a check that arrives without a token or a browser check id is how the console tells you which half is missing. It runs once per request, whichever hook asks first, and it never throws. ``` // store-guard.php (continued) function sg_mode() { return defined('MASKBREAK_MODE') ? MASKBREAK_MODE : 'watch'; } function sg_field($name) { return isset($_POST[$name]) && is_string($_POST[$name]) ? sanitize_text_field(wp_unslash($_POST[$name])) : ''; } /** Returns the verdict (an array), or null when there is none. */ function sg_check($email = '') { static $done = false, $verdict = null; if ($done) { return $verdict; // one check per request } $done = true; $body = ['token' => sg_field('monocle')]; // sent even when it is empty $optional = [ 'fingerprintEventId' => sg_field('sentinel_fp'), 'tz' => sg_field('sentinel_tz'), 'email' => is_string($email) ? $email : '', 'accountId' => is_user_logged_in() ? (string) get_current_user_id() : '', ]; foreach ($optional as $key => $value) { if ($value !== '') { $body[$key] = $value; } } $res = wp_remote_post('https://maskbreak.com/v1/evaluate', [ 'timeout' => 3, // the default is 5 s: long in front of a checkout button 'headers' => [ // A missing constant is a 401 in the log, never a fatal error at checkout. 'Authorization' => 'Bearer ' . (defined('MASKBREAK_API_KEY') ? MASKBREAK_API_KEY : ''), 'Content-Type' => 'application/json', ], 'body' => wp_json_encode($body), ]); if (is_wp_error($res)) { error_log('[maskbreak] unavailable: ' . $res->get_error_code()); // weather } elseif ((int) wp_remote_retrieve_response_code($res) !== 200) { // 401 is the key, 400 the body: a bug that will not fix itself. error_log('[maskbreak] HTTP ' . wp_remote_retrieve_response_code($res)); } else { $json = json_decode(wp_remote_retrieve_body($res), true); $verdict = is_array($json) ? $json : null; } // One line per check. Never log the key, the token or form data. error_log('[maskbreak] ' . wp_json_encode([ 'mode' => sg_mode(), 'decision' => $verdict['decision'] ?? null, 'reasons' => $verdict['reasons'] ?? null, 'device_evidence' => $verdict['device_evidence'] ?? null, 'degraded' => $verdict === null ? null : !empty($verdict['degraded']), ])); return $verdict; } ``` ## Registration The My Account form runs `woocommerce_registration_errors` before the customer is created, and adding an error there stops it: ``` add_filter('woocommerce_registration_errors', function ($errors, $username, $email) { $verdict = sg_check($email); // Watch mode, or no verdict (a blocked script, an outage): never refuse. if (sg_mode() === 'enforce' && ($verdict['decision'] ?? null) === 'block') { $errors->add('sg_blocked', __('Registration is unavailable from this connection.')); } return $errors; }, 10, 3); ``` Refuse on `block` only. A plain VPN comes back as `review`, and turning away every customer who uses one to catch a handful of abusers is a trade that rarely pays. ## Checkout: refuse before the charge, not after This is where the money is, and where the hook choice matters most. `woocommerce_after_checkout_validation` runs after the fields validate and before the payment gateway is called. Adding an error here stops the order with nothing charged. ``` add_action('woocommerce_after_checkout_validation', function ($data, $errors) { $verdict = sg_check($data['billing_email'] ?? ''); if (sg_mode() !== 'enforce' || !$verdict) { return; // watch mode, or no verdict: the order goes ahead } if ($verdict['decision'] === 'block') { $errors->add('sg_blocked', __('We cannot process this order. Contact support.')); } elseif ($verdict['decision'] === 'review') { WC()->session->set('sg_review', true); // not enough to refuse; enough to hold } }, 10, 2); ``` A `review` order should not flow straight to fulfilment. Mark it when it is created, then keep it `on-hold` when the payment completes, which is the moment WooCommerce would otherwise move it to processing: ``` add_action('woocommerce_checkout_order_processed', function ($order_id, $posted, $order) { if (WC()->session && WC()->session->get('sg_review')) { $order->update_meta_data('_sg_review', 'yes'); $order->add_order_note(__('Maskbreak answered review: check before fulfilling.')); $order->save(); WC()->session->set('sg_review', null); } }, 10, 3); add_filter('woocommerce_payment_complete_order_status', function ($status, $order_id, $order) { return ($order && $order->get_meta('_sg_review') === 'yes') ? 'on-hold' : $status; }, 10, 3); ``` Refusing in `woocommerce_thankyou` or on an order-status transition instead is the common mistake, and it is expensive: by then the gateway has authorised, you have paid the fee, and a card-testing script has already got the answer it came for. The point of card testing is the authorisation response, not the goods. ## Step 3: Submit your form once Activate the plugin, open the checkout in an ordinary browser, wait a moment, and place one order with an offline method such as bank transfer or cash on delivery (or register an account on My Account). The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and the PHP error log (`wp-content/debug.log` with `WP_DEBUG_LOG` on, or your host's log) shows one `[maskbreak]` line. `"degraded":true` means no network token arrived: the script was blocked, a cache or optimisation plugin got in the way, or the class is missing. `"device_evidence":"not_sent"` means no browser check id arrived; `"ok"` with `degraded` false is a complete check. After a few days of comparing those lines with the console's Events, add `define('MASKBREAK_MODE', 'enforce');` to `wp-config.php`. The same hooks then refuse a `block` and hold a `review`. ## The cheap control that needs no API Card testing is a volume attack, and a limit on failed payment attempts per address costs nothing and needs no vendor. It runs in the same validation hook, before the gateway: ``` add_action('woocommerce_after_checkout_validation', function ($data, $errors) { $key = 'sg_fail_' . md5(WC_Geolocation::get_ip_address()); if ((int) get_transient($key) >= 5) { $errors->add('sg_rate', __('Too many attempts. Please try again later.')); } }, 5, 2); add_action('woocommerce_order_status_failed', function ($order_id) { $order = wc_get_order($order_id); if (!$order) { return; } $key = 'sg_fail_' . md5($order->get_customer_ip_address()); set_transient($key, (int) get_transient($key) + 1, HOUR_IN_SECONDS); }); ``` Five failures an hour from one address slows a single-address script to five tries an hour. It is not sufficient on its own: a residential proxy network rotates addresses precisely to defeat per-address counting, which is the gap the screening call fills. But it is the first thing to ship. ## The caching problem WooCommerce tells page caches to skip cart, checkout and account pages, and plenty of stacks ignore it: an over-eager cache rule, a CDN page rule that matches too broadly, or an optimisation plugin that decided your checkout looked static. When the checkout is served from cache, the nonce is stale and WooCommerce rejects submissions with an unhelpful error. Check it directly rather than trusting a settings screen: ``` curl -sI https://example.com/checkout/ | \ grep -iE 'cache|age|cf-cache-status' ``` Anything reporting a hit, or an `age` above zero, means the page is being cached. Exclude `/cart/`, `/checkout/`, `/my-account/` and any URL containing `wc-ajax` at every layer (plugin, host and CDN), because it only takes one of the three. Object caching is fine; it is page caching that does the damage. ## The Cart and Checkout blocks Newer stores use the Cart and Checkout blocks. They submit through WooCommerce's Store API, so the classic form, the inline line that marks it and `woocommerce_after_checkout_validation` are not part of that path, and this plugin does not check those orders. View the checkout page's source: a `form.woocommerce-checkout` means the classic checkout. Until you pass the evidence through the Store API yourself, switch the checkout page back to the `[woocommerce_checkout]` shortcode on stores that need the check. Security plugins often attach to the same registration filter, and priority decides who runs first. Keep yours at the default 10 and check for double refusal: two plugins adding errors for the same request produce a wall of messages that nobody reads. ## The short version - The class goes on the , never on an input, and the script loads on the checkout and account pages. - Forward monocle, sentinel_fp and sentinel_tz as token, fingerprintEventId and tz, and call every time, even without a token. Watch mode never refuses. - Two hooks: woocommerce_registration_errors for accounts, woocommerce_after_checkout_validation for orders. Validation runs before the gateway. - Override the wp_remote_post timeout. Five seconds in front of a checkout button is not a default to keep. - In enforce mode, refuse on block; hold review orders on-hold. A plain VPN is a customer. - Rate-limit failed payments per address first, keep the checkout out of every page cache, and know whether your store runs the classic checkout or the blocks. - Store the key in wp-config.php, never in the options table. ## Questions people ask **How do I stop card testing on WooCommerce?** Rate-limit failed payment attempts per address first; it costs nothing. Then send the check in woocommerce_after_checkout_validation, which runs before the payment gateway is called, so a refusal in enforce mode costs no authorisation fee. Refusing later, at thankyou or on a status change, is too late: the attacker already got the authorisation response, which is what card testing is for. **Which WooCommerce hook should the fraud check run on?** woocommerce_after_checkout_validation for orders and woocommerce_registration_errors for accounts made on the My Account page. Both run before the thing you want to prevent (the charge and the customer record), and both take an error object, so refusing is a matter of adding a message rather than dying mid-request. **Why does my checkout screening never see a token?** Check three things. The class monocle-enriched must sit on the form element itself (form.woocommerce-checkout), never on a hidden input, which stays empty. The checkout must be the classic shortcode one: the Cart and Checkout blocks post through the Store API, where these hooks do not run. And no page cache or optimisation plugin may cache the checkout or delay sentinel.js; curl the checkout URL and read the cache headers rather than trusting a settings page. **Will this slow down my checkout?** One HTTPS call with a three-second ceiling; each response reports its own server processing time, so measure your own traffic. Set the timeout explicitly, because wp_remote_post defaults to five seconds and you do not want that in front of a customer. When the call fails, return no verdict and let the order proceed: an outage in a fraud check must not close your store. --- # Account Sharing Detection: Devices, Not IPs URL: https://maskbreak.com/blog/account-sharing-detection Published: 2026-08-12 > Counting IPs finds households and misses resale. What separates a shared family login from a credential being sold — and how to act without banning customers. Multi-accounting and account sharing look like the same problem and are not. Multi-accounting is one device wearing many accounts: trial abuse, referral farming, bonus hunting, and the person on the other end was never going to pay you. Sharing is the mirror image — one account worn by many devices — and almost everyone you detect is a paying customer. That difference should decide everything about how you respond, and it usually does not. The other reason to care: sharing and account takeover produce the same first observation. A new device on an existing account is either a partner's laptop, a password posted in a group chat, or someone who bought the credentials. Telling those apart is the whole exercise. ## Why counting IPs does not work The first instinct is to count distinct IPs per account and alert above some number. It fails in both directions, badly enough that the metric is worse than nothing. False positives. Mobile carriers put tens of thousands of subscribers behind carrier-grade NAT, and hand out a different address on every reconnection. One commuter checking your app on a train produces a dozen IPs before lunch. Add an office, a home connection, a coffee shop and a corporate VPN and an ordinary week for one person looks like a small botnet. False negatives. Anyone deliberately sharing a credential — especially anyone reselling one — already knows about IP checks. A shared account routed through one VPN exit shows a single stable address for every user of it, which reads as the tidiest account on your books. So the signal is not how many networks. It is how many devices, and what those devices do. ## Devices, not addresses A verdict from `/v1/evaluate` carries a device block (the [device fingerprinting API](https://maskbreak.com/device-fingerprinting)) when the client token came from a real browser session: ``` { "decision": "allow", "risk_score": 0, "network": { "vpn": false, "proxy": false, "residential": true }, "device": { "visitor_id": "…", // stable across sessions "times_seen": 14, "returning": true, "first_seen": "2026-06-30T09:12:44.000Z", "linked_accounts": 1, "multi_account": false } } ``` Three of those fields are the raw material for sharing detection. `visitor_id` is a stable identifier for that browser, so it survives logout, a cleared cookie and a new session — which is what makes "devices per account" countable at all. `first_seen` and `times_seen` separate a device that has been on the account for months from one that appeared this morning. One caveat worth stating plainly, because it is the difference between a working integration and a confusing afternoon: the device block only exists when a real browser produced the token. The sandbox tokens (`test_clean`, `test_vpn`, and the rest) return the decision and the network block with no `device` object at all, because there was no browser. Wire the collector into the page before you go looking for `visitor_id` in the response. ## The API answers the other direction `linked_accounts` counts how many of your accounts have been seen on this device, which is the multi-accounting question. Sharing is the transpose: how many devices have been seen on this account. That one you keep yourself, because it is a fact about your users and it belongs in your database. It is one table: ``` CREATE TABLE account_devices ( account_id TEXT NOT NULL, visitor_id TEXT NOT NULL, country TEXT, first_seen TIMESTAMPTZ NOT NULL DEFAULT now(), last_seen TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (account_id, visitor_id) ); ``` Upsert it on every login with the verdict you already have, then ask the question: ``` -- Active devices per account over a rolling 30 days. SELECT account_id, COUNT(*) AS devices, COUNT(DISTINCT country) AS countries, COUNT(*) FILTER (WHERE first_seen > now() - interval '7 days') AS new_this_week FROM account_devices WHERE last_seen > now() - interval '30 days' GROUP BY account_id HAVING COUNT(*) >= 6 ORDER BY devices DESC; ``` Note the rolling window. A lifetime device count only measures how long someone has been a customer — a loyal five-year user has replaced two phones and a laptop and will out-rank an actively shared account every time. The same 90-day ceiling applies on our side: the device-to-account links behind `linked_accounts` are pruned at ninety days, so that number is a rolling window too, not a permanent record. ## Separating a household from a resale Six devices is not evidence. A family of four with phones, a tablet and a TV is six devices and is exactly the customer you want. Four patterns separate normal sharing from the kind that costs you money, and they are much more convincing together than apart. Device churn. A household's device set is stable: the same six identifiers month after month, each with an old `first_seen`. A resold credential shows constant turnover — new devices every week, each seen a handful of times and never again. Churn is the strongest single tell, and it is why `first_seen` matters more than the raw count. Geographic dispersion beyond travel. Not "two countries" — people travel, people live near borders, people work remotely. The tell is dispersion that cannot be reconciled with one human body: sessions in three countries on the same afternoon, or a pair of logins whose distance and interval imply a speed nobody achieves. Compute it as a rate, not a count. Concurrency. Genuine sharing is usually sequential — a household takes turns. Simultaneous sustained use from several devices is the signature of a credential in circulation. We do not see your sessions, so this one is entirely yours to measure; it is also the cheapest, because you already log session start and end. The account arrives hidden. Cross-reference the network block. A residential connection from the customer's own country carries no information either way. A credential being resold is often used through a VPN or a residential proxy by people who know the account is not theirs — so `network.vpn` or `network.proxy` on devices that are also new and geographically scattered is a much stronger combination than any of those alone. Say that last one carefully, because it is where teams do real damage: a VPN on its own is not evidence of anything. Plenty of privacy-minded customers use one full time, which is why a plain VPN returns `review` rather than `block`. Treat it as one term in a sum, never as a trigger. ## Sharing or takeover? Before you act on a sharing signal, check whether you are actually looking at a compromise. The observation is identical; the correct response is not even close. What tips it toward takeover rather than sharing: the new device appears and the old ones stop, rather than continuing alongside; the session changes the email, password or payout details within minutes of logging in; the verdict carries hard signals — `automation_detected`, `antidetect_browser`, `emulator_detected` — which are the tools of credential stuffing, not of a spouse borrowing a login. Sharing is a pricing problem. Takeover is a security incident. Route them to different places, and when the evidence is genuinely ambiguous, treat it as the second one — a step-up on a shared account costs a customer thirty seconds, and a missed takeover costs considerably more. There is more on that path in [account takeover prevention that holds up](https://maskbreak.com/blog/account-takeover-prevention-that-holds-up). ## What to do about it, in order The instinct is to block the extra devices. For a paying account that is the most expensive option on the list, and it lands on the customer rather than the person who shared the credential. 1. Measure before you enforce. Run the query for a few weeks and act on nothing. You will find that your intuition about the threshold was wrong — usually far too low — and you will find a small number of accounts with thirty devices that are worth looking at by hand. 2. Verify the new device, not the account. An email or push confirmation on a device that has never been seen is cheap, expected by users, and does double duty against takeover. It is the only intervention here that a legitimate customer thanks you for. 3. Cap concurrency instead of devices. "Two streams at once" or "three active sessions" is enforceable, explainable, and matches how people think a subscription works. "You may only ever own four devices" does not survive contact with a phone upgrade. 4. Sell the thing they are trying to do. An account with eight stable devices across two households is a family plan you have not offered them, and an account with eleven devices on one corporate domain is a seat expansion. The message that converts is an invitation, not a warning — and unlike a block, it moves revenue in the right direction. 5. Enforce only on the tail. Reserve refusal for the accounts where the evidence is not ambiguous: high churn, impossible geography, sustained concurrency, hard device signals. That is a small set, and keeping it small is the point. Where you draw the line depends on what you sell. A B2B SaaS seat is a contractual matter and a conversation with the customer usually settles it. A consumer subscription is a churn calculation: the shared viewer often converts later, and an aggressive crackdown can cost more in cancellations than the sharing ever cost in revenue. ## Measure it as a distribution One number for "sharing" is useless; the shape of the distribution is where the decisions are. - Devices per active account at p50, p95 and p99, on a rolling thirty days. p50 tells you what normal is. The gap between p95 and p99 is where policy belongs. - Share of accounts whose device set turned over more than half in the last thirty days — the churn metric, and the one that actually correlates with resale. - Distinct countries per account per week, as a rate rather than a total. - Conversion on the upgrade nudge, split by device count. This is the number that tells you whether sharing is a leak or an underserved segment. - Cancellation rate among accounts you intervened on, against a holdout you left alone. Without the holdout you cannot tell recovered revenue from churn you caused. ## The constraints worth knowing Device linking here is per-customer: your accounts are never linked against another customer's, and the device key is stored as an opaque hash, and the account id you pass as a keyed hash for linking plus an encrypted copy that only your own console shows, deleted 90 days after the account was last checked. Links older than ninety days are pruned. If you build the account-side table described above, that one is yours — put it in your privacy notice and give it a retention period, because a device history per user is exactly the kind of processing users are entitled to know about. ## The short version - Sharing is the transpose of multi-accounting: many devices per account, and the account is usually paying you. - Counting IPs finds commuters and misses anyone behind a single VPN. Count devices. - The API gives you accounts-per-device; keep devices-per-account yourself, on a rolling window. - Churn in the device set, impossible geography, sustained concurrency and hidden networks separate a household from a resale. A VPN alone separates nothing. - Check for takeover first: same observation, completely different response. - Verify new devices, cap concurrency, sell the upgrade. Refuse only the unambiguous tail, and keep a holdout so you can tell whether the policy paid. ## Questions people ask **How do you detect account sharing without blocking real customers?** Count devices per account over a rolling window rather than IPs, then look at the pattern instead of the total. Six stable devices with old first-seen dates is a household; six devices that turned over in the last month, used from scattered locations, is a credential in circulation. Respond with a confirmation on the new device or a concurrency cap rather than a ban, and keep a holdout group so you can measure whether enforcement recovered more revenue than it churned. **Why is counting IP addresses a bad way to find shared accounts?** It is wrong in both directions. Mobile carriers rotate addresses behind carrier-grade NAT, so one commuter can produce a dozen IPs in a morning and look like a shared account. Meanwhile a credential deliberately shared through a single VPN exit shows one stable address for every user of it, which looks cleaner than your average legitimate customer. **What is the difference between account sharing and multi-accounting?** They are opposite directions of the same relationship. Multi-accounting is one device used across many accounts — trial abuse, referral farming, bonus hunting — and the API reports it directly as device.linked_accounts with a multi_account_device reason code. Sharing is one account used across many devices, which you count in your own database from the device visitor_id, and the people involved are usually paying customers rather than abusers. **How do I tell account sharing apart from account takeover?** Look at whether the old devices keep being used and at what the session does. Sharing adds devices alongside the existing ones and behaves normally; takeover typically replaces them and changes the email, password or payout details soon after login. Hard signals in the verdict — automation_detected, antidetect_browser, emulator_detected — point to credential stuffing rather than a borrowed password. When it is genuinely ambiguous, treat it as takeover: a step-up costs a real customer half a minute. --- # ASP.NET Core Fraud Detection Without a .NET SDK URL: https://maskbreak.com/blog/aspnet-core-fraud-detection Published: 2026-08-12 · Updated: 2026-10-08 > A typed HttpClient, an endpoint filter, and the two .NET details that decide whether this works in production: handler lifetime and the JSON property names. There is no .NET SDK. For an API with one endpoint that matters, the wrapper is a small typed `HttpClient` and a record, about eighty lines including the failure handling. Writing it yourself means the timeout and the fail-open policy are decisions you made rather than defaults you inherited. Two things in those eighty lines are where .NET integrations actually go wrong, and neither has anything to do with fraud: how the `HttpClient` is registered, and how the JSON maps onto your record. Written for .NET 8 or later with minimal APIs, in the three steps the Maskbreak console lists: add the script to the page with your form, send the check from your server, and submit your form once. It starts in watch mode, where every check is logged and nothing is refused. ## Step 1: Add the script to the page with your form Load the script on the page with your form and put `class="monocle-enriched"` on the `` element itself (never on an input): ``` @Html.AntiForgeryToken()
``` The script adds three hidden fields to the form: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone). A JavaScript frontend that posts JSON calls `await window.Sentinel.collect()` instead (after checking that `window.Sentinel` exists; submit anyway when it does not) and sends its `token`, `fingerprintEventId` and `tz` in the body. If you send a `Content-Security-Policy`, add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server The two obvious ways to get an `HttpClient` are both wrong, in opposite directions. A `new HttpClient()` per request exhausts sockets under load. A `static readonly HttpClient` for the lifetime of the process fixes that and never picks up DNS changes. `IHttpClientFactory` exists for exactly that pair, so register a typed client: ``` // Program.cs builder.Services.AddHttpClient((sp, c) => { // Read when a client is made, from the app's final configuration: // an environment variable, user secrets or a key vault (and a test host's settings). var key = sp.GetRequiredService()["MASKBREAK_API_KEY"] ?? ""; c.BaseAddress = new Uri("https://maskbreak.com/"); // Short: this sits in front of a user-facing action. c.Timeout = TimeSpan.FromSeconds(3); c.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", key); }); ``` The key is a server-side credential: user secrets in development, an environment variable or key vault in production, and never the browser. The client sends whatever evidence arrived, including none: a check without a token or a browser check id is how the console tells you which half is missing. It never throws a Maskbreak problem at your caller. ``` // Services/MaskbreakClient.cs using System.Net.Http.Json; using System.Text.Json; using System.Text.Json.Serialization; public sealed record Verdict( [property: JsonPropertyName("decision")] string Decision, [property: JsonPropertyName("risk_score")] int RiskScore, [property: JsonPropertyName("reasons")] string[]? Reasons, [property: JsonPropertyName("device_evidence")] string? DeviceEvidence, [property: JsonPropertyName("degraded")] bool Degraded, [property: JsonPropertyName("test")] bool Test) { public bool IsBlocked => Decision == "block"; // A complete, production allow: what a strict action needs in enforce mode. public bool IsCleanAllow => Decision == "allow" && DeviceEvidence == "ok" && !Degraded && !Test; } public sealed record Evidence(string? Token, string? FingerprintEventId, string? Tz, string? Email); public sealed class MaskbreakClient( HttpClient http, ILogger log, IConfiguration config) { public string Mode { get; } = config["MASKBREAK_MODE"] ?? "watch"; // or "enforce" public async Task CheckAsync( Evidence ev, string? accountId, CancellationToken ct) { var body = new Dictionary { ["token"] = ev.Token ?? "" }; if (!string.IsNullOrEmpty(ev.FingerprintEventId)) body["fingerprintEventId"] = ev.FingerprintEventId; if (!string.IsNullOrEmpty(ev.Tz)) body["tz"] = ev.Tz; if (!string.IsNullOrEmpty(ev.Email)) body["email"] = ev.Email; if (!string.IsNullOrEmpty(accountId)) body["accountId"] = accountId; Verdict? v = null; try { using var res = await http.PostAsJsonAsync("v1/evaluate", body, ct); if (res.IsSuccessStatusCode) v = await res.Content.ReadFromJsonAsync(ct); else log.LogWarning("maskbreak HTTP {Status}", (int)res.StatusCode); } catch (TaskCanceledException) when (ct.IsCancellationRequested) { // The caller went away. Not a vendor problem: do not log it as one. throw; } catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException or JsonException) { // Fail open. A detection outage must not become a checkout outage. log.LogWarning("maskbreak unavailable: {Type}", ex.GetType().Name); } // One line per check. Never log the key, the token or form data. log.LogInformation( "maskbreak mode={Mode} decision={Decision} reasons={Reasons} device_evidence={DeviceEvidence} degraded={Degraded}", Mode, v?.Decision, v?.Reasons is null ? null : string.Join(",", v.Reasons), v?.DeviceEvidence, v?.Degraded); return v; } } ``` The ordering of the two catches matters. `HttpClient` surfaces its own timeout as a `TaskCanceledException`, the same type you get when the browser disconnects mid-request. Filtering on `ct.IsCancellationRequested` separates "the vendor was slow, continue without a verdict" from "nobody is listening any more". Collapse them and your logs show a vendor incident every time someone closes a tab. ## The field that silently deserialises to zero The response uses snake_case: `risk_score`, `device_evidence`. `System.Text.Json` in ASP.NET Core is case-insensitive by default, which fools people into thinking the mapping is automatic. It is not: case insensitivity does nothing about an underscore, so a property called `RiskScore` matches nothing and lands on its default value. There is no exception, and a fraud check that always reads as clean is indistinguishable from one that is switched off. Annotate, as above; field names and reason codes on this API are a stability promise, and an explicit `JsonPropertyName` ties your record to that contract. ## An endpoint filter, not middleware Middleware runs on every request, including static files, health checks and Swagger. An endpoint filter attaches to the routes where a decision is worth making, and takes parameters. It reads the evidence from a posted form, or from a JSON request record that carries it. In watch mode it records the verdict and always continues. ``` // Filters/ScreenFilter.cs public interface IHasEvidence { string? Token { get; } string? FingerprintEventId { get; } string? Tz { get; } string? Email { get; } } public sealed class ScreenFilter(bool strict) : IEndpointFilter { public async ValueTask InvokeAsync( EndpointFilterInvocationContext ctx, EndpointFilterDelegate next) { var http = ctx.HttpContext; var client = http.RequestServices.GetRequiredService(); var verdict = await client.CheckAsync( await ReadEvidenceAsync(ctx), http.User.FindFirst("sub")?.Value, http.RequestAborted); http.Items["verdict"] = verdict; if (client.Mode != "enforce") return await next(ctx); // watch: log only if (verdict?.IsBlocked == true) return Results.Json(new { error = "Request declined" }, statusCode: StatusCodes.Status403Forbidden); if (strict && verdict?.IsCleanAllow != true) return Results.Json(new { error = "Additional verification required" }, statusCode: StatusCodes.Status409Conflict); return await next(ctx); } static async Task ReadEvidenceAsync(EndpointFilterInvocationContext ctx) { // A JSON endpoint binds the evidence into its own request record. var bound = ctx.Arguments.OfType().FirstOrDefault(); if (bound is not null) return new Evidence(bound.Token, bound.FingerprintEventId, bound.Tz, bound.Email); var req = ctx.HttpContext.Request; if (!req.HasFormContentType) return new Evidence(null, null, null, null); var form = await req.ReadFormAsync(); return new Evidence(form["monocle"].ToString(), form["sentinel_fp"].ToString(), form["sentinel_tz"].ToString(), form["email"].ToString()); } } ``` Now the policy is one readable line per endpoint: ``` // A JSON request record carries the values Sentinel.collect() returned. public sealed record SignupRequest(string Email, string Password, string? Token, string? FingerprintEventId, string? Tz) : IHasEvidence; public sealed record WithdrawRequest(decimal Amount, string? Token, string? FingerprintEventId, string? Tz, string? Email = null) : IHasEvidence; // The HTML form from step 1 posts its own fields, the three hidden ones included. app.MapPost("/signup", SignupFormHandler) .AddEndpointFilter(new ScreenFilter(strict: false)); // Signup: in enforce mode, refuse only a block. VPN users are customers. app.MapPost("/api/signup", SignupHandler) .AddEndpointFilter(new ScreenFilter(strict: false)); // Money leaving: in enforce mode, only a clean, complete allow continues. app.MapPost("/api/withdraw", WithdrawHandler) .AddEndpointFilter(new ScreenFilter(strict: true)); // Checkout: review costs a step, not the account. app.MapPost("/api/checkout", async (CheckoutRequest req, HttpContext http, MaskbreakClient mb) => { var verdict = http.Items["verdict"] as Verdict; if (mb.Mode == "enforce" && verdict?.Decision == "review") return await StepUpAsync(req); return await ChargeAsync(req); }) .AddEndpointFilter(new ScreenFilter(strict: false)); ``` A minimal API that binds a form validates antiforgery tokens on .NET 8 and later; keep that, it is your CSRF protection. On controllers the same shape is an `IAsyncActionFilter`, and on Razor Pages an `IAsyncPageFilter`. The rule worth holding onto: `review` must not route to the same place as `block`, or you have built a hard block with extra steps. There is more on that split in [route on the decision, sort on the score](https://maskbreak.com/blog/risk-score-thresholds). ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your log shows one `maskbreak` line. `degraded=True` means no network token arrived (the script was blocked, or the class is missing or on an input); `device_evidence=not_sent` means no browser check id arrived; `device_evidence=ok` with `degraded=False` is a complete check. When the lines look right after a few days, set `MASKBREAK_MODE=enforce` and redeploy. A fixed test token such as `test_clean` comes back with `test: true` and never passes a strict route. ## Pass an account id and get multi-accounting for free The account id argument is doing more than logging. When it is present, the same device arriving under a second account becomes linkable, and the response carries `device.linked_accounts` plus a `multi_account_device` reason code. Linking is per-customer and hash-only, and it only works with a stable id: the user's `sub` claim above is stable; a session id or an antiforgery token links nothing. ## Testing The public sandbox key returns fixed answers for the test tokens: `test_clean` allow, `test_vpn` review, `test_proxy` and `test_tor` block, each marked `test: true`. Point a `WebApplicationFactory` at it, in enforce mode: ``` public class ScreeningTests(WebApplicationFactory factory) : IClassFixture> { private HttpClient Client() => factory .WithWebHostBuilder(b => b .UseSetting("MASKBREAK_API_KEY", "sk_test_sandbox") .UseSetting("MASKBREAK_MODE", "enforce")) .CreateClient(); [Fact] public async Task Withdraw_IsRefused_ForAProxy() { var res = await Client().PostAsJsonAsync("/api/withdraw", new { amount = 100, token = "test_proxy" }); Assert.Equal(HttpStatusCode.Forbidden, res.StatusCode); } } ``` For the outage path, add a `DelegatingHandler` to the typed client in your test host that throws `HttpRequestException`, and assert what your policy says: a signup still goes through, a withdrawal is held. That is the test people leave out, and it is the one that documents your actual policy. ## The short version - Script on the page, the class on the
, three hidden fields forwarded as token, fingerprintEventId and tz. - Register a typed client with AddHttpClient. Never new HttpClient() per request, never a permanent static one. - Map risk_score and device_evidence explicitly with JsonPropertyName. - Call every time, even without a token, and log one line. Watch mode never refuses. - Rethrow TaskCanceledException when the caller cancelled; treat every other failure as no verdict. - Endpoint filter, not middleware. In enforce mode: strict on money, blocks only on signup, review to a step-up. ## Questions people ask **Is there a .NET SDK for Maskbreak?** No. The official SDKs are Node, Python and PHP. For .NET the integration is a typed HttpClient registered with AddHttpClient plus a record for the response — roughly eighty lines including error handling — which is enough for an API with one endpoint that matters, and it keeps the timeout and failure policy in your own code. **Why is risk_score always 0 in my C# integration?** The property name almost certainly does not match. System.Text.Json is case-insensitive in ASP.NET Core but that does nothing about the underscore, so a RiskScore property never binds to risk_score and takes its default value of zero. Annotate with [JsonPropertyName("risk_score")], or set PropertyNamingPolicy to JsonNamingPolicy.SnakeCaseLower on .NET 8 or later. There is no exception, so the integration looks healthy while every verdict reads as clean. **Middleware or an endpoint filter for fraud checks in ASP.NET Core?** An endpoint filter in almost every case. Middleware runs on every request including static files, health checks and Swagger, so you maintain path prefixes to keep it off the fast path. A filter attaches to the routes where a decision is worth making, takes parameters such as strictness, and short-circuits by returning a result. On controllers the equivalent is an IAsyncActionFilter. **How should a fraud check handle a timeout in ASP.NET Core?** Allow the request. Set HttpClient.Timeout to a few seconds on the typed client (the guide uses three), then catch HttpRequestException, TaskCanceledException and JsonException and return no verdict. One exception: rethrow TaskCanceledException when the request CancellationToken is already cancelled, because that is the caller disconnecting rather than a vendor problem, and swallowing it turns every closed tab into a false outage in your logs. --- # Cloudflare Workers Bot Detection: Edge Limits URL: https://maskbreak.com/blog/cloudflare-workers-bot-detection Published: 2026-08-11 · Updated: 2026-10-08 > A Worker sees the IP, ASN and TLS fingerprint before your origin wakes up — and never sees the device. Where each check belongs, and how to fail open. A Cloudflare Worker runs before your origin does, in a datacenter near the visitor, with the connection metadata already parsed. That makes it the cheapest place on the internet to answer some questions and a structurally impossible place to answer others. Getting the split right is most of the design work. This covers what the edge sees for free, what it cannot see, and a Worker that sends the full Maskbreak check for a form post in front of your origin, in the three steps the Maskbreak console lists: add the script to the page with your form, send the check from your server (here, the Worker), and submit your form once. It starts in watch mode, where every check is logged and nothing is refused. ## What you get for free Every request into a Worker arrives with a `cf` object and a set of headers that cost nothing to read: ``` export default { async fetch(request, env, ctx) { const ip = request.headers.get('CF-Connecting-IP'); const country = request.headers.get('CF-IPCountry'); // ISO-2, or XX / T1 const cf = request.cf || {}; // cf.asn, cf.asOrganization, cf.colo, cf.tlsVersion, cf.clientTcpRtt, // cf.botManagement.score (Enterprise entitlement only) // ... } }; ``` Two traps in that snippet. `CF-IPCountry` is not always a country: Cloudflare emits `T1` for Tor and `XX` when it has no idea, and both render as a broken flag if you pass them to a flag component. And `cf.botManagement` is only populated with the Enterprise Bot Management entitlement; on other plans the property is absent, so code that reads `cf.botManagement.score` throws rather than degrading. ## What the edge structurally cannot see A Worker sees a connection. It does not see a browser. Nothing in `request.cf` tells you whether the client is an antidetect profile with a spoofed canvas, a headless Chrome instance, an emulator, or a person. Those are properties of the runtime on the other end, and they only become visible when something running in that runtime reports them. This is also why the edge cannot answer the residential proxy question on its own. A residential proxy exits through a real consumer connection: the ASN is a real ISP, the country is real, the TCP round trip looks like a home line. There is nothing anomalous in the connection metadata, because the connection is genuinely ordinary. So the useful division is: - At the edge, before origin: known-bad networks, datacenter ASNs, Tor exits, obvious automation by user agent, and rate limiting. Cheap, no round trip, no cost to your origin. - At the action, with the browser's evidence: device signals (automation, emulator, antidetect browser, browser tampering), multi-account linking, and the VPN and proxy reading of the visitor's own connection. These need the browser to have spoken. ## Edge triage on facts you already have The first pattern needs no API: act at the edge, before the request reaches your application, on the connection facts. ``` const DATACENTER_ASNS = new Set([16509, 14618, 15169, 8075, 14061, 16276]); export default { async fetch(request, env, ctx) { const url = new URL(request.url); // Only guard what is worth guarding. Everything else passes through. if (!url.pathname.startsWith('/signup')) return fetch(request); const cf = request.cf || {}; if (DATACENTER_ASNS.has(cf.asn)) { // Friction, not a verdict: mark it for stricter handling downstream. const marked = new Request(request); marked.headers.set('X-Edge-Datacenter', '1'); return fetch(marked); } return fetch(request); } }; ``` Be careful how hard you lean on that list. A datacenter ASN is a fact about infrastructure, not a verdict about a person: corporate VPNs, mobile carrier gateways and privacy relays all live in ranges that look like hosting. Refusing signup outright on ASN alone costs real users. It is a reasonable trigger for a challenge or stricter downstream handling, and a poor trigger for a 403. If your origin reads a header like that one, make sure only the Worker can set it. ## Step 1: Add the script to the page with your form The full check needs evidence from the visitor's browser. On the page that holds the form, load the script and put `class="monocle-enriched"` on the `` element itself (never on an input): ```
``` The script adds three hidden fields to that form: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone). A JavaScript frontend calls `await window.Sentinel.collect()` instead (check that `window.Sentinel` exists, and submit anyway when it does not) and sends its `token`, `fingerprintEventId` and `tz` in a JSON body; the Worker below reads both. If the page sends a `Content-Security-Policy`, add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server (the Worker) The Worker reads the posted body once, sends the check, and forwards the original request to your origin. It sends whatever evidence arrived, including none: a check without a token or a browser check id is how the console tells you which half is missing. In watch mode, the default, it only logs. ``` // worker.js: in front of POST /signup on your zone export default { async fetch(request, env, ctx) { const url = new URL(request.url); if (request.method !== 'POST' || url.pathname !== '/signup') { return fetch(request); } // Read the body once, then rebuild the request for the origin. const raw = await request.arrayBuffer(); const fields = readFields(request.headers.get('Content-Type') || '', raw); const verdict = await checkVisitor(fields, env); if (env.MASKBREAK_MODE === 'enforce' && verdict?.decision === 'block') { return new Response(JSON.stringify({ error: 'Request declined' }), { status: 403, headers: { 'Content-Type': 'application/json' }, }); } // Watch mode, or anything short of a block in enforce mode: the origin // runs as before. A review is the origin's call (step up, not refuse). return fetch(new Request(request, { body: raw })); }, }; // Form posts carry monocle / sentinel_fp / sentinel_tz; JSON from // Sentinel.collect() carries token / fingerprintEventId / tz. function readFields(type, raw) { try { const text = new TextDecoder().decode(raw); if (type.includes('application/json')) { const body = JSON.parse(text); return body && typeof body === 'object' ? body : {}; } if (type.includes('application/x-www-form-urlencoded')) { return Object.fromEntries(new URLSearchParams(text)); } } catch (_) { /* unreadable body: send the check without evidence */ } return {}; } async function checkVisitor(b, env) { let result = null; try { const res = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { Authorization: `Bearer ${env.MASKBREAK_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ token: b.monocle || b.token || '', fingerprintEventId: b.sentinel_fp || b.fingerprintEventId || undefined, tz: b.sentinel_tz || b.tz || undefined, email: typeof b.email === 'string' ? b.email : undefined, }), // A deadline on every outbound call: no verdict beats a late one. signal: AbortSignal.timeout(3000), }); if (res.ok) result = await res.json(); else console.warn('[maskbreak] HTTP', res.status); // 401: the key, 400: the body } catch (err) { console.warn('[maskbreak] unavailable:', err.name); // fail open } // One line per check, in Workers Logs or wrangler tail. Never the key or token. console.log('[maskbreak]', JSON.stringify({ mode: env.MASKBREAK_MODE || 'watch', decision: result ? result.decision : null, reasons: result ? result.reasons : null, device_evidence: result ? result.device_evidence : null, degraded: result ? !!result.degraded : null, })); return result; } ``` Route it on the exact path, so the Worker never runs for your static files, and put the key in a secret. Worker code is not a browser bundle, but it is not a private server either: anyone with dashboard access can read the script, and it ends up in whatever repository you deploy from. ``` wrangler secret put MASKBREAK_API_KEY ``` `MASKBREAK_MODE` is an ordinary variable (`vars` in your Wrangler file), unset for now. Never `const MASKBREAK_API_KEY = 'sk_live_...'` at the top of the file, and never let the key reach the browser: a live key in client-side JavaScript is a key someone else is now using on your allowance. ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and `wrangler tail` shows one `[maskbreak]` line. `degraded: true` means no network token arrived (the script was blocked, the class is missing, or the body was neither a form nor JSON); `device_evidence: "not_sent"` means no browser check id arrived; `"ok"` with `degraded: false` is a complete check. After a few days of comparing those lines with the console's Events, set `MASKBREAK_MODE` to `enforce` and redeploy: the Worker then refuses a `block` and forwards everything else. For a stricter gate in front of a sensitive action, the [Worker example on the integrations page](https://maskbreak.com/integrations#cloudflare) forwards only a complete live allow in enforce mode. ## Failing open at the edge is not optional An origin that fails closed takes down one endpoint. An edge Worker that fails closed can take down everything on its route. Three rules worth holding to: - Deadline everything. An abort signal on every outbound call. No verdict beats a late verdict. - Catch broadly. Network error, abort, non-2xx, unparseable JSON: every one of them means "continue", not "throw". - Have a removal plan. Delete the Workers route in the dashboard and the origin serves the path directly. A rollback you can do from a phone at 2am is worth more than a clever retry. Also watch the Workers request allowance on your plan. Every request on the route counts, including the ones you pass straight through, and an account over its daily free allowance gets errors on the route unless the route is set to fail open. A busy route belongs on a paid plan. ## Use waitUntil for anything you do not need an answer from Logging a verdict to your own analytics endpoint should not add latency to the response. `ctx.waitUntil` keeps the Worker alive for the side effect after the response has already gone back: ``` ctx.waitUntil( fetch('https://your-collector.example/events', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ path: url.pathname, decision: verdict?.decision ?? null, asn: request.cf?.asn }), }).catch(() => {}) // never let telemetry break the request path ); ``` ## The short version - The edge sees the network: IP, ASN, country, TLS. Use it for cheap triage before the origin. - The edge never sees the device. Antidetect browsers, automation and emulators need the browser's evidence, sent with the form. - Read monocle, sentinel_fp and sentinel_tz (or the collect() names) and send all three as token, fingerprintEventId and tz, every time. - A datacenter ASN is a reason to add friction, not a reason to refuse outright. - Deadline every outbound call and treat every failure as allow. - Key in wrangler secret, read from env, never inline and never in the browser. ## Questions people ask **Can a Cloudflare Worker detect bots on its own?** Partly. A Worker sees the IP, ASN, country and TLS characteristics of the connection, which is enough to spot datacenter traffic, Tor exits and crude automation. It cannot see the browser, so headless frameworks, emulators and antidetect profiles are invisible to it unless a client-side signal is collected and passed in. Cloudflare Bot Management adds a bot score, but only on the Enterprise entitlement. **Where should I put the API key in a Cloudflare Worker?** In a secret, set with wrangler secret put MASKBREAK_API_KEY and read as env.MASKBREAK_API_KEY. Do not hard-code it in the script: Worker source is readable by anyone with dashboard access and usually lives in a repository. It must never reach browser-side JavaScript, where it becomes someone else’s free quota. **What happens if the fraud API is slow at the edge?** You should already have aborted. Put a deadline on every outbound call (the guide uses three seconds) and treat abort, network error, non-2xx and unparseable JSON as allow. A Worker sits in front of every request on its route, so failing closed there takes the whole route down rather than one handler. **Can a Worker detect residential proxies?** Not from connection metadata alone. A residential proxy exits through a genuine consumer connection, so the ASN belongs to a real ISP and the geolocation is real. Detecting it needs network-operator intelligence about proxy infrastructure, corroborated by device signals — neither of which is present in request.cf. --- # FastAPI Fraud Detection, Failing Open URL: https://maskbreak.com/blog/fastapi-fraud-detection Published: 2026-08-11 · Updated: 2026-10-08 > A screening dependency you would actually deploy: per-route strictness, the threadpool detail that keeps the event loop free, and a fail-open path. The call itself is one line. Everything that makes a fraud check safe to deploy is around it: which routes it runs on, what it does when the vendor is having a bad day, and, specific to FastAPI, which side of the event loop it waits on. This is written as a dependency rather than middleware, because dependencies are per-route, typed, and overridable in tests. Middleware sees every request including your static files and your health check, and then you spend the rest of the afternoon writing path prefixes to keep it off the fast path. It follows the three steps the Maskbreak console lists (add the script to the page with your form, send the check from your server, submit your form once) and starts in watch mode, where every check is logged and nothing is refused. ## Step 1: Add the script to the page with your form The check needs evidence from the visitor's browser. Load the script on the page with your form. For a server-rendered form, put `class="monocle-enriched"` on the `
` itself and the script adds three hidden fields: `monocle` (network token), `sentinel_fp` (browser check id) and `sentinel_tz` (time zone). ```
``` FastAPI usually sits behind a JavaScript frontend that posts JSON. Then ask the script for the values at submit time and put them in the body. Check that `window.Sentinel` exists, and never hold the form back when it does not: ``` const evidence = window.Sentinel ? await window.Sentinel.collect().catch(() => ({})) : {}; // script blocked: submit anyway await fetch('/signup', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, ...evidence }), // token, fingerprintEventId, tz }); ``` If your pages send a `Content-Security-Policy`, add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server Keep your live key in a `MASKBREAK_API_KEY` environment variable; nothing goes in your settings module, and the key never reaches the browser. ``` # .env (never committed) MASKBREAK_API_KEY=sk_live_... # MASKBREAK_MODE=enforce (later; unset means watch) ``` The client is an `httpx.AsyncClient` (`pip install httpx`; `fastapi[standard]` already includes it), so waiting on the network never blocks the event loop. The function maps the form's names to the API's and calls even when a field is missing: a check without a token or a browser check id is how the console tells you which half is missing. It never raises. ``` # app/maskbreak.py import logging import os import httpx log = logging.getLogger("maskbreak") MODE = os.environ.get("MASKBREAK_MODE", "watch") # "watch" or "enforce" # One client for the process, which runs one event loop: its pooled # connections belong to that loop. Short timeout: this sits in front of a # user-facing action, so a slow answer is worth less than no answer. client = httpx.AsyncClient(timeout=3.0) async def check_visitor(data: dict, email: str | None = None, account_id: str | None = None) -> dict | None: """Returns the verdict, or None when there is none. Never raises.""" payload = { "token": data.get("monocle") or data.get("token") or "", "fingerprintEventId": data.get("sentinel_fp") or data.get("fingerprintEventId"), "tz": data.get("sentinel_tz") or data.get("tz"), "email": email, "accountId": account_id, } result = None try: resp = await client.post( "https://maskbreak.com/v1/evaluate", json={k: v for k, v in payload.items() if v is not None}, headers={ "Authorization": "Bearer " + os.environ.get("MASKBREAK_API_KEY", ""), "Content-Type": "application/json", }, ) if resp.is_success: result = resp.json() else: log.warning("maskbreak HTTP %s", resp.status_code) # 401: the key except Exception as exc: # timeout, network, bad JSON, anything: no verdict, never a 500 log.warning("maskbreak unavailable: %s", type(exc).__name__) # One line per check. Never log the key, the token or form data. log.info("maskbreak mode=%s decision=%s reasons=%s device_evidence=%s degraded=%s", MODE, result.get("decision") if result else None, result.get("reasons") if result else None, result.get("device_evidence") if result else None, bool(result.get("degraded")) if result else None) return result ``` ## The dependency One factory, parameterised by how strict the route should be. It reads the evidence from a JSON body or a form (form parsing needs `python-multipart`), records the verdict, and in watch mode never refuses. ``` # app/deps.py from fastapi import HTTPException, Request from app.maskbreak import MODE, check_visitor async def _evidence(request: Request) -> dict: try: if request.headers.get("content-type", "").startswith("application/json"): data = await request.json() else: data = dict(await request.form()) except Exception: return {} return data if isinstance(data, dict) else {} def clean_allow(v: dict | None) -> bool: """A complete, production allow.""" return bool(v) and v.get("decision") == "allow" and v.get("device_evidence") == "ok" \ and not v.get("degraded") and not v.get("test") def screen(strict: bool = False): """Enforce mode: strict=False refuses only a block; strict=True continues only on a clean, complete allow. Watch mode never refuses anything.""" async def dependency(request: Request) -> dict | None: data = await _evidence(request) email = data.get("email") result = await check_visitor( data, email=email if isinstance(email, str) else None, account_id=getattr(request.state, "user_id", None), ) if MODE == "enforce": if result and result.get("decision") == "block": raise HTTPException(status_code=403, detail="Request declined") if strict and not clean_allow(result): raise HTTPException(status_code=409, detail="Additional verification required") return result return dependency screen_default = screen() screen_strict = screen(strict=True) ``` FastAPI has already read the body for your route by the time the dependency runs, and Starlette keeps it on the request, so reading it again here costs nothing and leaves your body model intact. ## The FastAPI-specific part The dependency is `async def` and the client is async. That pairing is deliberate, and it is the one detail in this post that is genuinely about FastAPI rather than about fraud. FastAPI runs `async def` dependencies on the event loop. Put a blocking client inside one (`requests`, `urllib`, a synchronous SDK) and you have moved a blocking network read onto the loop: one slow answer now stalls every concurrent request in the process, and the symptom under load is a latency cliff that looks nothing like a fraud problem. If you would rather use a blocking client, declare the dependency with plain `def`, and FastAPI runs it in a threadpool instead. Either shape is fine. Blocking the loop is not. ## Different actions, different strictness Attach the dependency where the decision matters, not globally. A single threshold across every route is always wrong somewhere: too tight on a newsletter form, too loose on a withdrawal. ``` # app/routes.py from fastapi import APIRouter, Depends from app.deps import screen_default, screen_strict from app.maskbreak import MODE router = APIRouter() # Signup: in enforce mode, refuse only a block. VPN users are customers. @router.post("/signup") async def signup(payload: SignupIn, verdict=Depends(screen_default)): ... # Money leaving: in enforce mode, only a clean, complete allow continues. @router.post("/withdraw", dependencies=[Depends(screen_strict)]) async def withdraw(payload: WithdrawIn): ... # Checkout: review costs a step, not the sale. @router.post("/checkout") async def checkout(payload: CheckoutIn, verdict=Depends(screen_default)): if MODE == "enforce" and verdict and verdict.get("decision") == "review": return await step_up(payload) # OTP, 3DS, manual queue return await charge(payload) ``` A JSON body model that forbids extra fields would reject `token`, `fingerprintEventId` and `tz`: either add them to the model as optional strings or keep extra fields allowed. The rule that matters here: `review` must not route to the same place as `block`. If it does, you have built a hard block with extra steps, and every VPN user in your funnel is a refused customer you will never hear about. There is more on that split in [route on the decision, sort on the score](https://maskbreak.com/blog/risk-score-thresholds). ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your log shows one `maskbreak` line (configure the logger at `INFO`; uvicorn's defaults do not show it). `degraded=True` means no network token arrived; `device_evidence=not_sent` means no browser check id arrived; `device_evidence=ok` with `degraded=False` is a complete check. When it looks right after a few days, set `MASKBREAK_MODE=enforce` and redeploy. ## Pass an account id and get multi-accounting for free The `account_id` argument is doing more than logging. When it is present, the same device arriving under a second account is linkable, which is the signal that catches trial abuse, referral farming and bonus abuse, none of which look wrong on any single request. Two constraints worth knowing before you wire it up. Linking is per-customer and hash-only: your accounts are never linked against another customer's, and the raw device identifier is not what gets stored. And it only works if you pass a stable id from your own server: a session id changes on every login and links nothing. ## Testing it in CI The public sandbox key returns fixed decisions for a set of test tokens, with no account and no live pipeline behind it: `test_clean` answers allow, `test_vpn` review, `test_proxy` and `test_tor` block. Every sandbox answer carries `test: true`, which is why a strict route never lets one through. ``` # tests/conftest.py import os os.environ.setdefault("MASKBREAK_API_KEY", "sk_test_sandbox") os.environ.setdefault("MASKBREAK_MODE", "enforce") import pytest from fastapi.testclient import TestClient from app.main import app @pytest.fixture(scope="session") def client(): # One TestClient held open runs every request on one event loop, as in # production. Without the with-block each request gets a new loop, and the # module's AsyncClient would reuse a connection from a closed one. with TestClient(app) as c: yield c # tests/test_withdraw.py def test_withdraw_refuses_a_proxy(client): r = client.post("/withdraw", json={"amount": 100, "token": "test_proxy"}) assert r.status_code == 403 def test_withdraw_holds_a_test_result(client): r = client.post("/withdraw", json={"amount": 100, "token": "test_clean"}) assert r.status_code == 409 ``` For the failure path, override the dependency instead of mocking the network. That is the reason to use a dependency in the first place: ``` app.dependency_overrides[screen_default] = lambda: None # vendor down: signup proceeds ``` Notice what that test asserts: when the fraud check is unavailable, the signup still goes through. If that makes you uncomfortable on a payout, the strict route already holds it; the fix elsewhere is a lower rate limit and a review queue, not a check that fails closed everywhere. ## The short version - Script on the page; collect() for a JSON frontend, the class on the
for a server-rendered one. - Forward token, fingerprintEventId and tz, and call every time, even when one is missing. - Use a dependency, not middleware: per-route, typed, overridable in tests. - An async client in an async def dependency, or a blocking client in a plain def one. Never a blocking call on the loop. - Watch first; in enforce mode, strict on money, block-only on signup, nothing on static routes. - Pass a stable account_id if multi-accounting is part of your problem. The same check in the other Python guides: [Flask](https://maskbreak.com/blog/flask-fraud-detection) and [Django](https://maskbreak.com/blog/django-fraud-detection). ## Questions people ask **Should the FastAPI dependency be async or sync?** Either, as long as nothing blocks the event loop. This guide uses an async def dependency with httpx.AsyncClient, so the wait happens on the loop without blocking it. If you use a blocking client (requests, urllib or the synchronous Python SDK), declare the dependency with plain def and FastAPI runs it in a threadpool. A blocking call inside an async def dependency stalls every concurrent request in the process. **Middleware or dependency for fraud checks in FastAPI?** A dependency, in almost every case. Middleware runs on every request including static files and health checks, so you end up maintaining path prefixes to keep it off the fast path. A dependency attaches to the specific routes where a decision is worth making, takes parameters such as strictness, and can be replaced with dependency_overrides in tests. **What should happen when the fraud API times out?** Allow the request. A check that fails closed converts a vendor incident into an outage of your signup, checkout or login, which is almost always the more expensive failure. Set a short client timeout, catch the error, return no verdict, and count the event so a quiet degradation still shows up on a dashboard. **How do I test fraud paths without hitting the live API?** Use the public sandbox key sk_test_sandbox with the deterministic test tokens: test_clean, test_datacenter, test_vpn, test_proxy, test_tor. Each returns a fixed decision and risk score, marked test: true, so allow, review and block paths become ordinary assertions in CI with no account and no live traffic, and a strict route that refuses test results is easy to assert too. --- # Rails Fraud Detection Without a Ruby SDK URL: https://maskbreak.com/blog/rails-fraud-detection Published: 2026-08-11 · Updated: 2026-10-08 > No Ruby SDK, and for a one-endpoint API that is fine. A Net::HTTP client, a controller concern, per-action strictness, and a fail-open path. There is no Ruby SDK. For an API with one endpoint that matters, that is less of an obstacle than it sounds: the wrapper is a few dozen lines of `Net::HTTP`, and writing it yourself means the timeout and the failure mode are decisions you made rather than defaults you inherited. What follows is the shape we would actually deploy in a Rails app: the form markup, a client object, a controller concern, and different strictness per action. It follows the three steps the Maskbreak console lists (add the script to the page with your form, send the check from your server, submit your form once) and starts in watch mode, where every check is logged and nothing is refused. ## Step 1: Add the script to the page with your form Load the script in your layout and put `class="monocle-enriched"` on the form itself: ``` <%# app/views/layouts/application.html.erb, in %> <%# app/views/registrations/new.html.erb %> <%= form_with url: registrations_path, class: "monocle-enriched" do |f| %> <%= f.email_field :email, required: true %> <%= f.password_field :password, required: true %> <%= f.submit "Create account" %> <% end %> ``` The script adds three hidden fields to the form: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone). They arrive as ordinary top-level params. With Turbo Drive, a page reached by a Turbo visit is swapped in without a full page load, so the script never fills the form on it and the post arrives without `monocle`. Make the page with the form load fully: put `` in that page's ``, or `data-turbo="false"` on the links that lead to it. If you set a Content Security Policy in `config/initializers/content_security_policy.rb`, add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and the string `"'wasm-unsafe-eval'"` to `script_src`, the `mcl` hosts (https and wss) and `mesu` to `connect_src`, and `https://mesu.maskbreak.com` plus `:blob` to `worker_src`. ## Step 2: Send the check from your server One class, one method, standard library only. It sends whatever evidence arrived, including none: a check without a token or a browser check id is how the console tells you which half is missing. It never raises. ``` # app/services/maskbreak.rb require "net/http" require "json" class Maskbreak ENDPOINT = URI("https://maskbreak.com/v1/evaluate").freeze MODE = ENV.fetch("MASKBREAK_MODE", "watch") # "watch" or "enforce" def initialize(api_key: ENV.fetch("MASKBREAK_API_KEY", ""), timeout: 3) @api_key = api_key @timeout = timeout end # Returns the verdict (a Hash), or nil when there is none. Never raises. def check(params, email: nil, account_id: nil) body = { token: params[:monocle].presence || params[:token].presence || "", fingerprintEventId: params[:sentinel_fp].presence || params[:fingerprintEventId].presence, tz: params[:sentinel_tz].presence || params[:tz].presence, email: email, accountId: account_id }.compact req = Net::HTTP::Post.new(ENDPOINT) req["Authorization"] = "Bearer #{@api_key}" req["Content-Type"] = "application/json" req.body = JSON.generate(body) res = Net::HTTP.start(ENDPOINT.host, ENDPOINT.port, use_ssl: true, open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(req) } result = res.is_a?(Net::HTTPSuccess) ? JSON.parse(res.body) : nil Rails.logger.warn("maskbreak HTTP #{res.code}") unless result result rescue StandardError => e # timeouts, refused connections, TLS errors, a body that is not JSON Rails.logger.warn("maskbreak unavailable: #{e.class}") nil ensure # One line per check. Never log the key, the token or form data. Rails.logger.info("maskbreak mode=#{MODE} decision=#{result&.dig('decision').inspect} " \ "reasons=#{result&.dig('reasons').inspect} " \ "device_evidence=#{result&.dig('device_evidence').inspect} " \ "degraded=#{result&.dig('degraded').inspect}") end # A complete, production allow: what a strict action needs in enforce mode. def self.clean_allow?(v) v.present? && v["decision"] == "allow" && v["device_evidence"] == "ok" && !v["degraded"] && !v["test"] end end ``` Both timeouts are set explicitly: Ruby's defaults are measured in tens of seconds, which is not a number you want in front of a checkout button. `StandardError` covers `Net::OpenTimeout` and `Net::ReadTimeout` along with every other way the call can fail, so a Maskbreak problem never becomes an error page of yours. Put your live key in `MASKBREAK_API_KEY` (Rails credentials or your host's secrets), never in the repository. ## The controller concern Rails already has the right shape for this: a concern with a `before_action`, included where it is needed and nowhere else. In watch mode it records the verdict and never renders anything. ``` # app/controllers/concerns/fraud_screened.rb module FraudScreened extend ActiveSupport::Concern included do attr_reader :verdict end class_methods do # screen_with strict: true → enforce mode continues only on a clean allow # screen_with → enforce mode refuses only a block def screen_with(strict: false, **options) before_action(**options) { screen!(strict: strict) } end end private def screen!(strict:) email = params[:email].is_a?(String) ? params[:email] : nil @verdict = Maskbreak.new.check(params, email: email, account_id: current_user&.id&.to_s) return unless Maskbreak::MODE == "enforce" if @verdict&.dig("decision") == "block" render json: { error: "Request declined" }, status: :forbidden elsif strict && !Maskbreak.clean_allow?(@verdict) render json: { error: "Additional verification required" }, status: :conflict end end end ``` ## Per-action strictness Now the policy is one readable line per controller, and it lives next to the actions it governs. ``` class WithdrawalsController < ApplicationController include FraudScreened screen_with strict: true, only: %i[create] # money leaving: nothing but a clean allow end class RegistrationsController < ApplicationController include FraudScreened screen_with only: %i[create] # signup: blocks only end class CheckoutsController < ApplicationController include FraudScreened screen_with only: %i[create] def create return step_up! if Maskbreak::MODE == "enforce" && verdict&.dig("decision") == "review" charge! end end ``` The reason signup is not strict: a plain VPN returns `review`, and VPN users are customers. Refusing them at registration is a cost you never see, because the person who could not sign up does not file a support ticket. The hard signals (proxy, Tor, automation, emulator, browser tampering) are the ones that return `block`. ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your log shows one `maskbreak` line. `degraded=true` means no network token arrived (the script was blocked, the class is missing, or a Turbo visit swapped the page in); `device_evidence="not_sent"` means no browser check id arrived; `"ok"` with `degraded` not true is a complete check. When the lines look right after a few days, set `MASKBREAK_MODE=enforce` and redeploy. ## Do not do this in a background job The temptation in Rails is to push the network call into Sidekiq and keep the request fast. It does not work for a gate: by the time the job runs, the account exists, the order is placed, or the withdrawal is queued. The verdict has to be in the request path if it is going to change what happens. What does belong in a job is everything after the decision: writing the verdict to your own analytics table, updating a risk queue, sending the alert. Decide inline, record asynchronously. Watch mode is the honest way to measure the latency first: the call is inline, and nothing is acted on until you switch. ## Testing The public sandbox key returns fixed answers for the test tokens (`test_clean` allow, `test_vpn` review, `test_proxy` and `test_tor` block), each marked `test: true`. Request specs then cover the block path: ``` # spec/requests/withdrawals_spec.rb before do stub_const("Maskbreak::MODE", "enforce") allow(ENV).to receive(:fetch).and_call_original allow(ENV).to receive(:fetch).with("MASKBREAK_API_KEY", "").and_return("sk_test_sandbox") end it "refuses a withdrawal from a proxy" do post "/withdrawals", params: { amount: 100, monocle: "test_proxy" } expect(response).to have_http_status(:forbidden) end it "holds the withdrawal when the vendor is down" do allow_any_instance_of(Maskbreak).to receive(:check).and_return(nil) post "/withdrawals", params: { amount: 100 } expect(response).to have_http_status(:conflict) end ``` That second test documents your actual policy for money leaving: no verdict, no payout without a human. On signup the same outage lets the request through. Write both down as assertions so nobody quietly changes them in six months. ## The short version - Script in the layout, class: "monocle-enriched" on the form, three hidden fields forwarded as token, fingerprintEventId and tz. - No gem needed. A few dozen lines of Net::HTTP, both timeouts set explicitly, every error rescued. - Call every time, even without a token, and log one line. Watch mode never refuses. - A concern plus before_action keeps the policy readable and per-controller. - In enforce mode: strict on money, blocks only on signup, review to a step-up rather than a refusal. - Decide inline; write the audit trail from a job. ## Questions people ask **Is there a Ruby SDK for Maskbreak?** No. The official SDKs are Node, Python and PHP. For Ruby the integration is a small Net::HTTP wrapper — about sixty lines including error mapping — which is enough for an API with one endpoint that matters, and it leaves the timeout and failure policy in your own code. **Should the fraud check run in a Sidekiq job?** Not as a gate. By the time a background job runs, the account already exists or the order is already placed, so the verdict cannot change the outcome. Make the call inline with a short timeout, and use a job for what comes after the decision: analytics writes, risk queues, alerts. **Why does my log show degraded=true on every check?** The network token is not reaching your server. Check, in order: the script tag is on the page with the form; class "monocle-enriched" sits on the form element itself, not on an input; a Content-Security-Policy is not blocking maskbreak.com or its hosts (the browser console shows CSP blocks); and the page was not reached by a Turbo visit, which swaps the page in without the token. **What is the right timeout for a fraud check in Rails?** Short: the guide uses three seconds on both open_timeout and read_timeout. Ruby's defaults are measured in tens of seconds, which is long enough for a vendor slowdown to become an outage of your own checkout. Pair the short timeout with a rescue that lets the request continue. --- # SMS Pumping Fraud: Stop OTP Abuse URL: https://maskbreak.com/blog/sms-pumping-fraud Published: 2026-08-11 > Artificially inflated traffic bills you for messages you sent yourself. How to spot it in your own OTP metrics, and where to stop it before the send. Most fraud shows up somewhere you are already looking: a chargeback, a stolen account, a shipped order nobody paid for. SMS pumping shows up on a telecom invoice, and the fraud team usually hears about it from finance. The mechanism is simple enough to explain in one sentence. Someone with a revenue share on terminating traffic to a particular number range drives your application to send one-time passcodes to numbers in that range, and gets paid a slice of what your messaging provider charges you. Nothing is stolen. You paid to send messages to yourself, and the industry name for it — artificially inflated traffic, or AIT — is more accurate than the popular one. ## Why it stays invisible for weeks Every alarm a fraud stack has is tuned for someone taking something. Pumping takes nothing: - No accounts are created. The attacker usually abandons the flow at the OTP step, so your signup conversion barely moves. - No chargebacks. No payment instrument is involved anywhere. - No support tickets. Nobody is a victim in a way that generates a complaint. - No traffic spike worth alerting on. A campaign that adds a few thousand sends a day disappears into normal volume on a busy service. The result is that the loss accumulates as a line item on a bill nobody in the fraud team reads until the bill is surprising. ## What it looks like in your own data You do not need a vendor to find out whether this is happening to you. Four queries against the OTP log you already have will tell you. 1. Send-to-verify ratio, by country. This is the single strongest tell. Real users request a code and type it in; the ratio sits somewhere in the high tens of percent. Pumped traffic requests codes and never verifies, so the ratio collapses. A country where 4% of sent codes are ever entered is not a country with a delivery problem — it is a country with a pumping problem. 2. Country mix over time. Plot sends per country per day for the last ninety days. Pumping campaigns show up as a country that was a rounding error becoming a top-five destination in a week, with no marketing spend or press coverage to explain it. 3. Number-range concentration. Group by the first several digits after the country code. Legitimate traffic spreads across the carriers and prefixes people actually use. Pumped traffic concentrates hard, because the attacker only earns on ranges they control — a handful of prefixes taking a large share of a country's volume is the signature. 4. Resend behaviour. Real users who do not get a code hit resend once or twice and then give up or switch channel. Automated pumping often walks the resend button to its limit on every attempt, because each resend is another billable message. Run those four and you will know within an hour whether you have a problem, and roughly what it costs per month. ## The fixes, in the order they pay off The instinct is to add a CAPTCHA. Do the cheap structural things first — they cost nothing and they do not tax every real user. Cap the resend path. One code per number per minute, a small number per hour, a hard daily ceiling per number and per account. Most campaigns lose most of their value to this alone, and no real user notices. Forms that send email need the same ceilings for a different reason: without them they can be used for [email bombing](https://maskbreak.com/blog/email-bombing), flooding someone else's inbox with your messages. Constrain the destinations. If you do not do business in a country, do not send to it. If you do business in twelve countries, an allowlist of twelve is not a restriction, it is a description of your business. For countries you do serve but where the ratio looks wrong, require a verified account or a second factor before the first SMS. Charge the flow something. Not money — friction that is cheap for a person and expensive for a script: require the email step to complete first, or make the phone step reachable only from an authenticated session. Screen before the send. The message costs money the moment it leaves. Everything you can learn about the session before that point is free, and the request that triggers an OTP is a request like any other: it comes from a network and from a device. ``` // POST /api/otp/send — screen BEFORE the message costs anything. let verdict; try { verdict = await sentinel.evaluate({ token, // the client token from the form accountId: user?.id, // stable id, if the user is known }); } catch (err) { return sendAfterChallenge(phone); // no token or no answer: evaluate() throws } // Automation, residential proxies and antidetect browsers are what // drives pumped traffic. A plain VPN is a customer on a train. if (verdict.decision === 'block') { return res.status(403).json({ error: 'blocked', reasons: verdict.reasons }); } if (verdict.decision === 'review') { return sendAfterChallenge(phone); // CAPTCHA or email confirmation first } return sendOtp(phone); ``` Note the shape: `review` does not refuse the code, it makes the sender do something cheap first. Refusing every ambiguous session from a login flow is how you lock out real customers, and a locked-out customer costs more than one SMS. Then talk to your provider. Most messaging platforms now offer geographic permissions, per-number rate controls and some form of pumping protection. They are worth enabling, and they are a backstop rather than a fix: the provider sees the message, you see the session, and the session is where the decision is cheaper. ## Alert on the ratio, not the volume Whatever you fix, leave the detector in place. A volume alert catches a burst and misses a slow campaign; a ratio alert catches both. - Send-to-verify ratio per country, alerting on a relative drop rather than an absolute floor — countries legitimately differ. - Share of daily sends going to the top five number prefixes per country. - New-country alert: any destination that was under 0.1% of sends last month and is over 2% this week. - Cost per completed verification, by country. This is the number to put in front of finance, because it converts the whole problem into one figure that either moves or does not. That last metric is also how you prove the fix worked. Volume charts after an intervention are ambiguous — traffic could have fallen for a dozen reasons. Cost per completed verification is not: if it drops and completions hold, you removed waste rather than customers. ## The short version - SMS pumping bills you for messages you sent yourself; nothing is stolen, so nothing alerts. - Find it with send-to-verify ratio by country, country mix over time, and prefix concentration. - Fix the cheap structural things first: resend caps, destination allowlists, ordering the flow so SMS is not the first step. - Screen the session before the send — automation and proxies are the traffic that pumps. - Route review to a challenge, not a refusal, or you will block real users out of a login flow. - Alert on ratios and cost per completed verification, not on volume. ## Questions people ask **What is SMS pumping fraud?** A scheme where someone with a revenue share on terminating traffic to certain number ranges drives an application to send one-time passcodes to those numbers, earning a slice of what the messaging provider bills. The industry term is artificially inflated traffic, or AIT. Nothing is stolen from users — the loss lands entirely on the sender’s telecom bill. **How do I know if my app is being used for SMS pumping?** Check the send-to-verify ratio by country in your own OTP logs: real users enter the code they asked for, pumped traffic never does, so the ratio collapses. Then look at country mix over the last ninety days and at how concentrated sends are within a few number prefixes. A country that jumped from nothing to top-five, with a low verify ratio and heavy prefix concentration, is the signature. **Does a CAPTCHA stop SMS pumping?** It helps, and it is rarely the best first move. Resend caps, destination allowlists and requiring an earlier step to complete cost nothing and remove most of the value without taxing real users. A challenge is well placed on the ambiguous middle — sessions that come back as review — rather than on everyone requesting a code. **Where in the flow should the fraud check run?** Before the message is sent. The SMS costs money the moment it leaves your provider, so the decision has to happen on the request that triggers it. Screening the session at that point catches the automation, residential proxies and antidetect browsers that drive pumped traffic, while the message is still free to not send. --- # Go Fraud Detection Middleware, Without an SDK URL: https://maskbreak.com/blog/go-fraud-detection Published: 2026-08-10 · Updated: 2026-10-08 > No Go SDK needed for a one-endpoint API. A net/http middleware with a real timeout, fail-open behaviour and a circuit breaker, in about seventy lines. There is no Go SDK for Maskbreak. There are Node, Python and PHP packages, and Go is conspicuously absent from that list, which comes up often enough that it is worth answering properly. The honest answer: for a one-endpoint JSON API, you do not want one. The wrapper is about seventy lines of standard library, it has no third-party dependencies, and writing it yourself means the timeout and the failure mode are decisions you made rather than ones you inherited. This follows the three steps the Maskbreak console lists (add the script to the page with your form, send the check from your server, submit your form once) and starts in watch mode, where every check is logged and nothing is refused. ## Step 1: Add the script to the page with your form Load the script on the page with your form and put `class="monocle-enriched"` on the `` element itself (never on an input): ```
``` The script adds three hidden fields: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone), so they arrive in `r.FormValue`. A JavaScript frontend calls `await window.Sentinel.collect()` instead (after checking that `window.Sentinel` exists; submit anyway when it does not) and posts its `token`, `fingerprintEventId` and `tz` as form fields alongside its own. If you set a `Content-Security-Policy`, add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server One POST, one JSON body, one bearer token. The client sends whatever evidence arrived, including none: a check without a token or a browser check id is how the console tells you which half is missing. ``` package fraud import ( "bytes" "context" "encoding/json" "fmt" "net/http" "os" "time" ) // "watch" (default) or "enforce". var Mode = func() string { if m := os.Getenv("MASKBREAK_MODE"); m != "" { return m } return "watch" }() type Client struct { Key string HTTP *http.Client } func New(key string) *Client { // One shared client keeps connections alive: a fresh TLS handshake // per signup is self-inflicted latency. return &Client{Key: key, HTTP: &http.Client{Timeout: 3 * time.Second}} } type Request struct { Token string `json:"token"` FingerprintEventID string `json:"fingerprintEventId,omitempty"` TZ string `json:"tz,omitempty"` Email string `json:"email,omitempty"` AccountID string `json:"accountId,omitempty"` } type Verdict struct { Decision string `json:"decision"` // allow | review | block RiskScore int `json:"risk_score"` Reasons []string `json:"reasons"` DeviceEvidence string `json:"device_evidence"` // ok | not_sent | unavailable Degraded bool `json:"degraded"` Test bool `json:"test"` } // CleanAllow is a complete, production allow: what a strict action needs. func (v *Verdict) CleanAllow() bool { return v != nil && v.Decision == "allow" && v.DeviceEvidence == "ok" && !v.Degraded && !v.Test } func (c *Client) Evaluate(ctx context.Context, in Request) (*Verdict, error) { body, err := json.Marshal(in) if err != nil { return nil, err } req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://maskbreak.com/v1/evaluate", bytes.NewReader(body)) if err != nil { return nil, err } req.Header.Set("Authorization", "Bearer "+c.Key) req.Header.Set("Content-Type", "application/json") res, err := c.HTTP.Do(req) if err != nil { return nil, err } defer res.Body.Close() if res.StatusCode != http.StatusOK { return nil, fmt.Errorf("maskbreak: status %d", res.StatusCode) // 401: the key } var v Verdict if err := json.NewDecoder(res.Body).Decode(&v); err != nil { return nil, err } return &v, nil } ``` ## The middleware The verdict belongs in the request context so the handler decides what to do with it. The middleware never refuses a request itself, and it calls on every request it wraps, even when the form carried no token. ``` // guard.go, in the same package package fraud import ( "context" "expvar" "log" "net/http" "time" ) // Failed calls, graphable from /debug/vars or your metrics exporter. var evalErrors = expvar.NewInt("maskbreak_eval_errors") type ctxKey struct{} // Guard evaluates the visit and stashes the verdict. It never refuses a // request itself: allow/review/block is a product decision, and the same // middleware has to serve a signup form and a payout endpoint. func (c *Client) Guard(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { // Its own deadline: a slow fraud check must not consume the // budget the handler needs to answer. ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second) defer cancel() _ = r.ParseForm() v, err := c.Evaluate(ctx, Request{ Token: first(r, "monocle", "token"), FingerprintEventID: first(r, "sentinel_fp", "fingerprintEventId"), TZ: first(r, "sentinel_tz", "tz"), Email: r.FormValue("email"), }) if err != nil { evalErrors.Add(1) // fail open, and make the failure countable log.Printf("maskbreak unavailable: %v", err) } // One line per check. Never log the key, the token or form data. if v != nil { log.Printf("maskbreak mode=%s decision=%s reasons=%v device_evidence=%s degraded=%t", Mode, v.Decision, v.Reasons, v.DeviceEvidence, v.Degraded) } next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), ctxKey{}, v))) }) } func first(r *http.Request, a, b string) string { if v := r.FormValue(a); v != "" { return v } return r.FormValue(b) } // FromContext returns the verdict, or nil when the check did not complete. func FromContext(ctx context.Context) *Verdict { v, _ := ctx.Value(ctxKey{}).(*Verdict) return v } ``` The nil return is the contract, and handlers have to respect it. `FromContext` returning nil means the check did not complete, not that the visit was clean. ## Using it ``` mux := http.NewServeMux() guard := fraud.New(os.Getenv("MASKBREAK_API_KEY")).Guard // Mounted per action, not globally. mux.Handle("/signup", guard(http.HandlerFunc(signup))) mux.Handle("/payout", guard(http.HandlerFunc(payout))) func signup(w http.ResponseWriter, r *http.Request) { v := fraud.FromContext(r.Context()) if fraud.Mode == "enforce" && v != nil { switch v.Decision { case "block": http.Error(w, "unable to complete signup", http.StatusForbidden) return case "review": requireEmailOTP(r) // step up, do not refuse } } createAccount(w, r) // watch mode: always reached } func payout(w http.ResponseWriter, r *http.Request) { v := fraud.FromContext(r.Context()) if fraud.Mode == "enforce" && !v.CleanAllow() { http.Error(w, "additional verification required", http.StatusConflict) return } sendPayout(w, r) } ``` Mounting per action rather than on the whole mux matters more in Go than in frameworks where middleware registration is centralised and invisible. Wrapping every route multiplies call volume, adds latency to endpoints that gain nothing, and converts a vendor slowdown into a whole-site problem instead of a checkout problem. Set `MASKBREAK_API_KEY` to your live key in the environment; it is never compiled in and never shipped to a browser, including via WebAssembly. ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your log shows one `maskbreak` line. `degraded=true` means no network token arrived (the script was blocked, or the class is missing or on an input); `device_evidence=not_sent` means no browser check id arrived; `device_evidence=ok` with `degraded=false` is a complete check. When the lines look right after a few days, set `MASKBREAK_MODE=enforce` and restart. A fixed test token such as `test_clean` comes back with `test: true`, which is why `CleanAllow` refuses it on a payout. ## A breaker for the bad afternoon Failing open on a single timeout is correct. Failing open on ten thousand consecutive timeouts, each costing seconds of a request handler, is a queue backing up. A few lines fix it: ``` // breaker.go, same package (imports "sync" and "time") type breaker struct { mu sync.Mutex fails int openTo time.Time } func (b *breaker) allow() bool { b.mu.Lock() defer b.mu.Unlock() return time.Now().After(b.openTo) } func (b *breaker) record(err error) { b.mu.Lock() defer b.mu.Unlock() if err == nil { b.fails = 0 return } if b.fails++; b.fails >= 5 { b.openTo = time.Now().Add(30 * time.Second) // skip the call entirely b.fails = 0 } } ``` To wire it in, give `Client` a `brk breaker` field; in `Guard`, skip the `Evaluate` call (and leave the verdict nil) while `c.brk.allow()` is false, and pass the call's error to `c.brk.record` afterwards. Five consecutive failures and the middleware stops calling out for thirty seconds, letting traffic through with no verdict at all. You lose detection for half a minute. You do not lose the site. ## Testing without an account The sandbox key is public and returns fixed decisions for the test tokens, so integration tests need no account: ``` func TestVerdictShapes(t *testing.T) { c := fraud.New("sk_test_sandbox") for token, want := range map[string]string{ "test_clean": "allow", "test_vpn": "review", "test_proxy": "block", "test_tor": "block", } { v, err := c.Evaluate(context.Background(), fraud.Request{Token: token}) if err != nil { t.Fatalf("%s: %v", token, err) } if v.Decision != want { t.Errorf("%s: got %q want %q", token, v.Decision, want) } if !v.Test { t.Errorf("%s: a sandbox answer must say test", token) } } } ``` Route on `Decision`, never on `RiskScore`: the score is a magnitude, the decision is the verdict, and your dashboard rules change only the decision. There is a [longer argument about why](https://maskbreak.com/blog/risk-score-thresholds). ## Before it ships - Script on the page, the class on the
, and token, fingerprintEventId and tz forwarded on every call. - Key read from the environment, never compiled in, never shipped to a browser. - One shared http.Client, not one per request, with a timeout. - Every error path continues and increments a counter you actually graph. - Watch first. In enforce mode, review steps up; it does not route to the same branch as block. The same check on the JVM, without an SDK: [Spring Boot](https://maskbreak.com/blog/spring-boot-fraud-detection). ## Questions people ask **Is there an official Go SDK?** Not today. The published SDKs are Node, Python and PHP. For a single-endpoint JSON API a Go wrapper is about seventy lines of net/http with no third-party dependencies, and writing it yourself means the timeout, the retry policy and the failure mode are decisions you made rather than ones you inherited. **Should the middleware run on every route?** No. Mount it on the handful of actions where abuse actually costs money: signup, login, checkout, payout, promo redemption. Wrapping every route multiplies your call volume, adds latency to endpoints that gain nothing from it, and makes a vendor slowdown a whole-site problem instead of a checkout problem. **What happens if the API times out?** The request is allowed. That is deliberate: a fraud check that fails closed turns a vendor incident into an outage of your own signup or checkout, which is nearly always the more expensive failure. The middleware in this post uses a three-second context deadline, allows on any error, and increments a counter so a silent degradation still shows up in your metrics. **Where does the token come from in a Go application?** From the browser script, which adds three hidden inputs to a form that carries class "monocle-enriched": monocle for the network layer, sentinel_fp for the device event id and sentinel_tz for the time zone. Your handler reads them off the parsed form and forwards them as token, fingerprintEventId and tz. Neither value is a secret and neither is trusted on its own: Maskbreak resolves both server-side before any verdict exists. **Does the API key ever belong in client-side Go or WASM?** No. A live key authenticates your account and belongs only in server-side code, read from the environment. Anything compiled to WebAssembly and shipped to a browser is client-side code, whatever language it started as, and a key embedded there is a key you have published. --- # Referral Fraud: Catching Self-Referral URL: https://maskbreak.com/blog/referral-fraud-detection Published: 2026-08-10 > Why email and IP checks miss modern referral farming, which signals separate a real invite from a second browser profile, and where to put the check. A referral programme is the one place in your product where the fraud has a published price list. You have written down, on a marketing page, exactly what you will pay for a new account. Someone will read that as an offer. The mechanic is old and the defences most teams ship are older: block duplicate emails, block duplicate IPs, cap rewards per account. Every one of those was defeated years ago by tooling that now costs less per month than the reward you are protecting. ## Three shapes, one root cause Self-referral. One person, their own link, a second account. Collects both the referrer bonus and the new-user credit. The overwhelming majority of what you will see, and the cheapest to run. Farming. The same attack, industrialised. Hundreds of accounts through an antidetect browser with a fresh profile and a fresh residential exit per identity, often against a programme that pays in a withdrawable currency rather than in-product credit. Affiliate collusion. A partner who sends traffic they manufactured. Harder to see because the volume looks like success, and it usually gets discovered by an analyst wondering why one channel converts at four times the rate of every other and retains at none of it. All three reduce to the same problem: you cannot tell whether two accounts are two people. Everything else is detail. ## Why the usual checks fail Email. Masked-relay addresses ship by default on iPhones and in Firefox. An attacker does not even need a burner domain, and if you block relays you refuse the privacy-conscious customer who was going to pay you. We wrote about that trade in [disposable email detection](https://maskbreak.com/blog/disposable-email-detection) and reached the same conclusion there: useful input, terrible gate. IP address. A residential proxy subscription is a consumer product. For a few dollars a month the second account arrives from a genuine home connection in a city you would never question. Meanwhile deduplicating on IP punishes university halls, offices behind one NAT and entire mobile carriers doing CGNAT. Browser fingerprint alone. Antidetect browsers exist precisely to defeat this. Each profile gets its own canvas, WebGL, fonts, timezone and user agent, and to a naive fingerprinting library those profiles are simply different computers. The pattern: every one of these checks tests something the attacker controls and can change for a few dollars. ## What actually separates the cases Two things survive the tooling, and they work because of how they are collected rather than what they measure. Network truth. Not “is this IP on a blocklist” but what the connection actually is: a residential proxy exit, a VPN, a datacenter range, a Tor node. A referral arriving through a residential proxy is not proof of fraud — but a referral pair where both sides arrive through different exits of the same proxy network, minutes apart, is not a coincidence anyone needs to argue about. Device linking that survives profile switching. The signal that matters is not the fingerprint hash, which spoofs, but whether the same device has been here before under other identities. Antidetect browsers change what the browser reports; they are markedly worse at changing what the machine underneath is. Tampering detection catches the act of lying itself — a profile whose declared platform, timezone and rendering behaviour do not agree with each other is a stronger signal than any of those values individually. In our pipeline the linking is deliberately narrow: device-to-account links are stored per customer and hash-only, so linking answers “has this device held other accounts on your platform” and nothing wider. That is the question a referral programme needs, and it is also the only version of it we are willing to build. ## Check at payout, not at signup The instinct is to evaluate the new account when it registers. It is the wrong moment for two reasons. First, signup is when you know least. The account has no history, no second session, no behaviour. Wait until the reward qualifies — first purchase, day-seven retention, whatever your terms say — and you are judging a richer record. Second, refusing at signup hands the attacker a debugging tool. Fail them at registration and they learn within seconds which profile tripped, adjust, and retry. Approve the signup, evaluate at qualification, and the feedback loop breaks: they cannot tell which of the last fifty accounts is going to be paid until the payout window closes. Both changes are free, and the second one is worth more than most detection improvements. ## In practice Evaluate the claiming session against the referrer’s account, and let the reason codes drive the decision rather than a single score: ``` // Runs when the referral QUALIFIES, not when the account is created. let v; try { v = await sentinel.evaluate({ token, // network token from the client SDK fingerprintEventId, // device event id, same call accountId: referredUser.id, }); } catch (err) { return hold(null); // no token or no answer: evaluate() throws } const linkedToReferrer = v.device?.visitor_id && await hasAccount(v.device.visitor_id, referrer.id); if (linkedToReferrer) return reject('self_referral'); if (v.decision === 'block') return reject('network_or_device'); if (v.decision === 'review') return hold(v.risk_score); // pay after review return payout(); ``` The `hold` branch is the one that pays for itself. Referral rewards are almost never time-critical — a 48-hour delay on a flagged claim costs a legitimate user nothing they will notice, and it removes the fast feedback that makes farming worth automating in the first place. ## Write the delay into the terms A detection stack you cannot act on is decoration. Before any of this helps, your programme terms need to permit a hold and a refusal: - A stated qualification window before a reward becomes payable at all. - An explicit right to withhold on suspected abuse, with a human appeal route. - Self-referral named as a violation, in plain words rather than by implication. - A cap on rewards per account and per payment instrument. None of that is fraud detection. All of it determines whether your fraud detection is allowed to do anything, and it is the part teams discover too late — usually in the week they first try to refuse a payout. ## What this cannot do Two friends, two phones, two networks, one agreement to split the reward: that is indistinguishable from the referral you were trying to buy, because structurally it is that referral. No signal separates them, and a programme tuned to catch that pair will refuse far more real customers than fraudsters. Aim somewhere more useful. The money is not lost to careful pairs, it is lost to the hundred accounts one person mints in an afternoon. Kill the cheap automated volume, add a delay before payout, and the arithmetic stops working for the farmer long before it starts inconveniencing anyone real. ## Questions people ask **What is referral fraud?** Claiming referral rewards for invitations that were never real. The common shape is self-referral: one person creates a second account through their own link and collects both sides. At scale it becomes farming, where hundreds of accounts are minted to harvest signup credit, and in affiliate programmes it becomes collusion, where a partner sends traffic they generated themselves. **Why do email and IP checks miss it?** Because both are trivially cheap to change and the tooling is consumer-grade now. A masked-email relay ships by default on every iPhone, and a residential proxy subscription costs a few dollars a month and hands out a clean home IP in whatever city you like. Blocking on burner domains or duplicate IPs catches the laziest attempt and nothing above it, while quietly refusing real customers who use a relay or share an office NAT. **Where in the funnel should the check run?** On the event that costs money, which is qualification or payout, not signup. Checking at signup measures the wrong moment and hands the attacker feedback: refuse them there and they learn immediately which profile tripped, then retry. Evaluate when the reward becomes claimable and you get a fuller history to judge and no free debugging loop. **Will this flag genuine referrals between family members?** Same household, same network, different devices is normal and should pass. Same device, two accounts, minutes apart, through a proxy is not. The distinction is device linking rather than IP: a shared home connection produces one network and several distinct devices, while self-referral usually produces one device wearing several identities. Judge the combination, never a single signal. **Can referral fraud be eliminated entirely?** No, and a programme that tried would be worse than the fraud. Two friends on separate phones on separate networks who agree to split a reward are indistinguishable from the referral you wanted, because that is exactly what a referral is. The goal is to make farming uneconomic, which is achieved by killing the cheap automated volume and adding a delay before payout, not by chasing the last honest-looking pair. --- # Risk Score Thresholds: Decision vs Score URL: https://maskbreak.com/blog/risk-score-thresholds Published: 2026-08-10 · Updated: 2026-10-05 > Why picking a number to block at is the wrong first question, what the score is actually made of, and the routing shape that survives contact with real traffic. Every integration reaches the same question within about ten minutes of the first successful call: what risk score should I block at? Sixty? Seventy-five? It is the wrong first question. Answering it directly is how teams end up with a threshold that refuses paying customers on Tuesday and waves a proxy farm through on Wednesday. `decision` and `risk_score` are two different outputs, computed on two different axes, and only one of them is meant to be compared against a number you picked. ## What the score is actually made of No model, no training set, no drift. `risk_score` is a weighted sum of the signals that fired, clamped to 0–100. The weights are fixed and worth knowing: - Network — Tor exit 60, residential proxy 50, VPN 35, datacenter ASN 30, otherwise-anonymous network 15. - Device — automation 40, browser tampering 35, emulator 30, antidetect browser 25, blocklisted IP seen on the device 25, virtual machine 15, high-activity device 10. - Email — disposable domain 15. They accumulate. A residential proxy carrying an antidetect browser is 50 plus 25 plus whatever the tampering score adds, and it saturates at 100 quickly. That is the intended behaviour: past a certain point the difference between 85 and 100 is not information you should be acting on. There is one more rule, and it is the one that surprises people. If neither the network nor the device threat flag is set, the score is capped at 15 regardless of what accumulated underneath. A datacenter ASN on its own scores 30 before the cap and reports 15 after it, because a server-hosted IP address is a fact about infrastructure, not a verdict about a person. ## The decision is a separate axis The decision does not read the score at all. It applies hard rules: - block — a residential proxy, a Tor exit, automation, an emulator, or browser tampering. Any one of them, on its own. - review — a threat signal fired but none of the hard ones did. A plain VPN lands here. - allow — nothing in the network or device layer flagged. Which means a high score can still be a customer and a low score can still be a block, and that is not a rounding error. Run the five sandbox tokens: ``` curl -X POST https://maskbreak.com/v1/evaluate \ -H "Authorization: Bearer sk_test_sandbox" \ -H "Content-Type: application/json" \ -d '{"token":"test_tor"}' # token decision risk_score reasons # test_clean allow 0 [] # test_datacenter allow 15 [datacenter_asn] # test_tor block 75 [tor_exit_node, anonymous_network] # test_vpn review 65 [vpn_detected, datacenter_asn] # test_proxy block 80 [proxy_detected, datacenter_asn] ``` Look at the VPN row. A threshold of 60 refuses the VPN user at 65, who is the single most likely person in that list to be a paying customer, while the engine only asks for a second look. The same threshold lets through automation on an otherwise clean visit, which scores 40 and which the engine blocks. That is the whole argument. The number is a magnitude, not a verdict. ## The shape that works Route on `decision`. Use `risk_score` for ordering and reporting, where a magnitude is exactly what you want. ``` let v; try { v = await sentinel.evaluate({ token, email, accountId }); } catch (err) { return proceed(); // fail open: evaluate() throws without a token or an answer } switch (v.decision) { case 'block': return refuse(); // hard signal fired case 'review': return stepUp(v.risk_score); // OTP, card check, queue default: return proceed(); } ``` The important property: `review` must not route to the same place as `block`. If it does, you have built a hard block with extra steps, and every VPN user in your funnel is now a refused signup you will never hear about. Where the score earns its keep is downstream of that switch. A manual review queue sorted by `risk_score` descending puts the worst sessions in front of an analyst first. A weekly histogram of scores by outcome tells you whether your pipeline is drifting. Neither of those needs a threshold. ## If you must have a number, have several Some platforms genuinely need a numeric gate — a rules engine that only speaks in integers, a risk committee that wants one dial. Fine. Then the rule is that there is no such thing as the threshold, only a threshold per action, set by what the action costs when it goes wrong: - Withdrawal, payout, [promo redemption](https://maskbreak.com/blog/promo-code-abuse-detection). Money leaves and does not come back. Escalate aggressively; the cost of a false positive is one annoyed user and a support ticket. - Checkout. A chargeback costs the goods plus the fee plus the ratio. Worth friction, not worth refusal. - Signup. The abuse is multi-accounting, and device linking answers that far more precisely than any score. Refusing here is usually the more expensive error. - Login. Step up, never block. A locked-out real customer calls support; a blocked attacker just tries again from another exit. - Newsletter, waitlist, free read. The cost of a fake row is a row. Log it and move on. ## Instrument before you tune Nobody can tell you the right number for your traffic, including us. What we can tell you is how to find it, and the method is unglamorous: run the check in shadow first. Call `/v1/evaluate` on the real action, log `decision`, `risk_score` and `reasons` against your own record id, and change nothing about the outcome. Two weeks of that, joined against what actually happened — chargebacks, refunds, bans, support contacts — and the answer stops being a guess. You will usually find two things: the volume at each decision is smaller than you feared, and a handful of reason codes account for nearly all the abuse you care about. At that point you are not choosing a threshold. You are choosing which reason codes deserve which action, which is a much better question and one you can actually defend in a meeting. ## Bind signals, not numbers When the shadow run says a specific signal is doing the damage, the fix is a rule rather than a threshold. In the dashboard Rules tab, a signal such as `antidetect` can be bound to `block`. That override runs after the engine builds its verdict and replaces only the `decision` field — `engine_decision` keeps the pipeline’s own answer and `rule_matched` names the signal that fired, so a month later you can still see what would have happened without your rule. This is strictly better than moving a global number, because it is reversible and legible. “We block antidetect browsers on withdrawal” is a policy. “We block above 70” is a number nobody in the room can explain. ## The threshold that matters most is your timeout One number does deserve attention, and it is not a risk score. Decide what happens when the check is slow or unreachable. Allow the request. A fraud check that fails closed converts a vendor incident into an outage of your signup, checkout or login, and that is almost always the more expensive failure. Set a short client timeout, treat the timeout as `allow`, and increment a counter so a quiet degradation still surfaces somewhere you look. Our own middleware examples do this in every language for a reason: it is the single most common way a good integration turns into an incident. ## The short version - decision is the verdict. Route on it. - risk_score is a magnitude. Sort, report and prioritise with it. - A low score can still be a block. A high score can still be a customer. - Set policy on reason codes and actions, not on a single global number. - Fail open, and count the failures. ## Questions people ask **What risk score should I block at?** None, if you can avoid it. Route on the decision field, which already applies the hard-signal rules, and use risk_score to order a review queue rather than to open and close the gate. If your platform genuinely needs a single number, derive it per action rather than globally, and only after you have logged a couple of weeks of real verdicts alongside your own outcome data. **Why can a session be blocked at a low risk score?** Because the two outputs are computed on different axes. The decision applies hard rules — a residential proxy, a Tor exit, automation, an emulator, browser tampering — while the score is a weighted sum that is deliberately capped when the network and device threat flags are clear. Automation detected on an otherwise clean visit returns decision block at risk_score 40. A threshold of 60 would wave it straight through. **Is the score a machine learning model?** No, and we would rather say so. It is a fixed weighted sum of the signals that fired, clamped to 0 to 100, with published weights. That makes it auditable and stable across releases: the same signals always produce the same number, which matters when you have to explain a refusal to a customer or a regulator. **How do I tighten enforcement without touching a threshold?** Bind a signal to an action in the dashboard Rules tab. Setting antidetect to block means any session carrying that signal is refused regardless of what the engine decided, while engine_decision preserves the pipeline’s own answer and rule_matched names the signal that fired. You get a targeted policy instead of a global number that moves everything at once. **What should happen when the API is slow or down?** Allow the request. A fraud check that fails closed converts a vendor incident into an outage of your signup, checkout or login, which is almost always the more expensive failure. Set a short timeout, treat a timeout as allow, and count those events so a quiet degradation still shows up on a dashboard. --- # Disposable Email Detection Guide URL: https://maskbreak.com/blog/disposable-email-detection Published: 2026-08-01 · Updated: 2026-10-10 > What burner-domain lists actually catch, why masked-email relays land on them, and how to use the signal without refusing real customers. Disposable email detection is the cheapest fraud signal to add and the easiest one to over-trust. A domain list, a set lookup, one boolean. It takes an afternoon, it flags real abuse, and teams routinely wire it straight into a hard block at signup. That last step is where it starts costing money. This is what the signal actually contains, what it cannot contain, and what our own signup form does with throwaway inboxes, which has changed twice. ## What the list actually is Every disposable email checker, ours included, is a domain membership test. We pull the [disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains) community blocklist, a little over nine thousand domains on 10 October 2026, refresh it every 24 hours, and hold it in memory as a set. An address is checked by taking everything after the `@`, lowercasing it, and testing the domain and its parent, so `x.mailinator.com` matches on `mailinator.com`. That is the whole mechanism. It is worth being blunt about the consequences: - It is a list, so it lags. New burner domains appear faster than any list absorbs them, and anyone motivated can register one for a few dollars. - It fails open by design. If the feed is unreachable we keep serving the last copy; if it is empty we flag nothing. A dead feed must never turn into a wall of refused signups. - It knows domains, not intent. This is the part that bites. ## The masked-email problem Ten-minute-mail and Apple's Hide My Email are structurally the same thing: a throwaway-looking address on a shared domain that forwards somewhere real. One is used to farm free trials. The other ships by default on every iPhone. Community blocklists are assembled from domain patterns, not intent, so they cannot separate them, and lists differ on whether they try. [One large community list](https://github.com/amieiro/disposable-email-domains) names Firefox Relay, iCloud Hide My Email, SimpleLogin and addy.io among its burners. The list we load names one alias service, Blur’s opayq.com, and none of those four on 10 October 2026. The users behind those addresses are not a marginal segment. They are the privacy-conscious, technically literate buyer — disproportionately the person evaluating a developer tool, and disproportionately the person who pays for one. ## What our own signup does with throwaway inboxes Maskbreak’s own signup form has changed its answer twice, and both turns are worth knowing before you copy either. 17 July 2026: the block came out. The form used to reject disposable domains outright. We removed the check because, as we read the list then, it also caught masked-email services, so it refused privacy-conscious people, the likeliest buyers of a developer tool, to stop an abuse case other limits already covered: the address still had to receive a one-time code, accounts and signup attempts were capped per network address, and the free allowance caps what an abusive account is worth. 7 October 2026: known throwaway inboxes are refused again. We decided that new accounts should be opened with a work address or a regular mail provider. Creating an account, or moving one to a new address, is now refused when the domain is on the public disposable list or on our own short list of temporary-inbox services that no public list carries yet. A company’s or a person’s own domain never goes on that list, however unused it looks, the major mailbox providers can never be refused, and existing accounts were left as they were. The refusal ends with a way out: “If this is your regular inbox, write to support@maskbreak.com.” 8 October 2026: email aliases too. Forwarding services, DuckDuckGo Email Protection, Firefox Relay, iCloud Hide My Email, SimpleLogin, addy.io, Proton Pass, Blur and 33mail among them, are refused as a class, from a list of our own, since the public list names only Blur. That cost is chosen, not missed: the privacy-conscious people the July change let in must now sign up with their real address. The customer-facing signal did not change with either decision. In the API a disposable domain still only moves a decision, as the next section describes, and an alias address is not flagged at all unless the public list names its domain. Our signup is a gate we chose for our own free plan; for yours, the advice below stands. ## Use it as an escalation, not a gate The useful framing: a burner domain slightly raises the probability that a session is abusive. It never establishes it. So the signal should move a decision, not make one. Concretely, in our pipeline a disposable domain adds 15 to the risk score, appends `disposable_email` to the reason list, and escalates a decision of `allow` to `review`. That is the entire effect. It cannot escalate `review` to `block`, and it cannot rescue a session that network or device signals already condemned. The asymmetry is intentional. A burner address on an otherwise clean residential session is a mild curiosity. The same address arriving from a datacenter range through an antidetect browser, on a device already linked to four accounts, is a different story — and in that case the network and device signals are what carry the verdict, with the email merely confirming it. ## In practice Pass the address to `evaluate()` and read the result. The address is checked transiently — it is never stored or logged, and only the boolean survives on the event record. ``` let verdict; try { verdict = await sentinel.evaluate({ token, email: req.body.email, // checked transiently, never stored accountId: req.user?.id, }); } catch (err) { return stepUp(); // no token or no answer: evaluate() throws } // verdict.email -> { disposable: true } // verdict.reasons -> [..., 'disposable_email'] // verdict.decision -> 'review' (escalated from 'allow') if (verdict.decision === 'block') return refuse(); if (verdict.decision === 'review') return stepUp(); // OTP, card check, manual queue return proceed(); ``` The important line is the middle one. If `review` routes to the same place as `block` in your application, you have built a hard block with extra steps, and you refuse the people the July change above was made for without having decided to. If you genuinely want burner domains refused outright — and for some businesses that is the right call — make it an explicit policy decision rather than a side effect. In the dashboard, `disposable_email` is one of the signals you can bind to a `block` action, which overrides the engine's decision while leaving `engine_decision` intact so you can still see what the pipeline actually thought. ## When blocking is the right call The test is whether the action has a real unit cost and no recovery path: - [Promotion and referral credit](https://maskbreak.com/blog/promo-code-abuse-detection). Money leaves on redemption. Refuse burners here. - Free trials that provision paid infrastructure. Each signup has a floor cost you cannot claw back. - Anything granting immediate withdrawal or transfer. Irreversible by definition. And where it is usually wrong: - Ordinary account signup. The abuse is multi-accounting, and device linking answers that far more precisely. - Login. The address already exists in your database; the domain tells you nothing new. - Newsletter and waitlist forms. The cost of a fake row is a row. The abuse these forms do attract is the opposite of a burner: in [email bombing](https://maskbreak.com/blog/email-bombing), a script enters someone else's real address on newsletter forms across many sites, and the confirmations pile up in that person's inbox. No domain list sees it, because the address is genuine. ## What it can never tell you A burner domain does not mean fraud, and a reputable domain does not mean safety. The overwhelming majority of card testing, account takeover and bonus abuse we see arrives on ordinary Gmail, Outlook and corporate addresses, because attackers operating at any scale buy aged accounts rather than register throwaways. Read the signal for what it is: weak evidence about intent to be contactable, useful in combination, dangerous alone. If disposable email is doing heavy lifting in your risk model, the model is thin — the questions that actually separate abuse from customers are whether the network is a proxy or datacenter exit, whether the browser is telling the truth about itself, and whether this device has been here before under other names. ## On storing the address A domain membership test needs no persistence. Ours is an in-memory set lookup: the address is not written to disk, not logged, and not retained after the request. Only the resulting boolean is kept on the event. This is worth checking with any vendor you evaluate, because the default is often worse. Shipping every signup address to a third party and having it retained for months is a real data-protection exposure, and it is a poor trade for a signal this weak. ## Questions people ask **Is disposable email detection worth adding at all?** Yes, as an input. A burner domain is a genuine signal that the person does not intend to be reachable, and on abuse-prone actions it correlates with trial farming and multi-accounting. The mistake is treating it as a verdict. Used as one escalation among several it costs you nothing; used as a gate it silently refuses privacy-conscious customers who are paying you money. **Why do masked-email services show up on burner lists?** Because structurally they look identical. DuckDuckGo Email Protection, Firefox Relay and iCloud Hide My Email all hand the user a throwaway-looking address on a shared domain that forwards to a real inbox. Community blocklists are built from domain patterns, not from intent, so relays land in the same file as ten-minute-mail. The domain cannot tell you which one you are looking at. **How current are disposable domain lists?** The widely used community list refreshes continuously and we re-pull it every 24 hours, but the ceiling is inherent: new burner domains appear faster than any list absorbs them, and an attacker who cares can register one. Treat coverage as good-not-complete. A list that flags nothing is failing open, which is the correct failure mode; a list you trust absolutely is the problem. **Should the email address be stored to check it?** No, and you should ask any vendor that does. The check is a domain lookup against an in-memory set, so the address never needs to be persisted, logged, or sent anywhere. We keep only the boolean result on the event record. Storing raw signup addresses in a fraud vendor's logs creates a data-protection liability that the signal does not come close to justifying. **When is it right to hard-block on a burner domain?** When the action has a real unit cost and no recovery path: redeeming a promotion, claiming free credit, or starting a trial that provisions paid infrastructure. There the cost of a false negative is money out the door and the cost of a false positive is one annoyed user who can retry with another address. For ordinary signup or login, blocking is almost always the more expensive error. --- # Django Fraud Detection Middleware URL: https://maskbreak.com/blog/django-fraud-detection Published: 2026-08-01 · Updated: 2026-10-08 > A production-shaped Django integration for VPN, proxy and antidetect detection: per-path strictness, DRF wiring, and the failure handling most examples omit. Most integration examples show the happy path and stop. This one is written the way you would actually deploy it in Django: a small client module, middleware guarded by path with different strictness for different actions, a DRF permission, and a check that never turns a Maskbreak problem into a failed request of your own. It starts in watch mode, where every check is logged and nothing is refused. Three steps, the same three the Maskbreak console lists: add the script to the page with your form, send the check from your server, and submit your form once. ## Step 1: Add the script to the page with your form Load the script on the page that holds the form and put `class="monocle-enriched"` on the `` element itself, never on an input inside it. ``` {% csrf_token %}
``` The script adds three hidden fields to the form: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone). They arrive in `request.POST` like any other field. If a JavaScript frontend posts JSON instead, call `await window.Sentinel.collect()` (after checking that `window.Sentinel` exists) and put its `token`, `fingerprintEventId` and `tz` in the body; the code below reads both spellings. If the site sends a `Content-Security-Policy` (django-csp, or a header from your proxy), add Maskbreak's hosts: `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com` and `https://mesu.maskbreak.com` plus `'wasm-unsafe-eval'` in `script-src`; the `mcl` hosts (https and wss) and `mesu` in `connect-src`; `https://mesu.maskbreak.com blob:` in `worker-src`. ## Step 2: Send the check from your server One function makes the call, with `requests` (`pip install requests` if the project does not have it yet). It maps the form's field names to the API's and calls even when a field is missing: a check that arrives without a token or a browser check id is how the console tells you which half is missing. It never raises. ``` # yourapp/maskbreak.py: server-side only import logging import os import requests log = logging.getLogger("maskbreak") MODE = os.environ.get("MASKBREAK_MODE", "watch") # "watch" or "enforce" _session = requests.Session() def check_visitor(data, email=None, account_id=None): """Send the browser evidence to Maskbreak. Returns the verdict (a dict), or None when there is none. Never raises.""" payload = { "token": data.get("monocle") or data.get("token") or "", "fingerprintEventId": data.get("sentinel_fp") or data.get("fingerprintEventId"), "tz": data.get("sentinel_tz") or data.get("tz"), "email": email, "accountId": account_id, } result = None try: resp = _session.post( "https://maskbreak.com/v1/evaluate", json={k: v for k, v in payload.items() if v is not None}, headers={ "Authorization": "Bearer " + os.environ.get("MASKBREAK_API_KEY", ""), "Content-Type": "application/json", }, timeout=3, ) if resp.ok: result = resp.json() else: log.warning("maskbreak HTTP %s", resp.status_code) # 401: the key except (requests.RequestException, ValueError) as exc: log.warning("maskbreak unavailable: %s", type(exc).__name__) # One line per check. Never log the key, the token or form data. log.info("maskbreak mode=%s decision=%s reasons=%s device_evidence=%s degraded=%s", MODE, result.get("decision") if result else None, result.get("reasons") if result else None, result.get("device_evidence") if result else None, bool(result.get("degraded")) if result else None) return result def clean_allow(result): """A complete, production allow: what a strict action needs in enforce mode.""" return bool(result) and result.get("decision") == "allow" \ and result.get("device_evidence") == "ok" \ and not result.get("degraded") and not result.get("test") ``` Django's default logging drops `INFO` from your own loggers, so turn this one on in `settings.py`, and set `MASKBREAK_API_KEY` to your live key in the environment, never in `settings.py` or the repository: ``` # settings.py LOGGING = { "version": 1, "disable_existing_loggers": False, "handlers": {"console": {"class": "logging.StreamHandler"}}, "loggers": {"maskbreak": {"handlers": ["console"], "level": "INFO"}}, } ``` ## The middleware One class, guarded by path prefix so product pages, static files and health checks never call out, and parameterised by how strict each group of routes should be. It reads the evidence from the posted form or a JSON body, so the submitted email travels with it. In watch mode it records the verdict on the request and always continues. ``` # yourapp/middleware.py import json from django.http import JsonResponse from .maskbreak import MODE, check_visitor, clean_allow # Enforce mode: a strict path continues only on a clean, complete allow; # a guarded path refuses only a block. A single global threshold is # always wrong somewhere. STRICT = ("/withdraw", "/transfer", "/promo/redeem") GUARDED = ("/signup", "/checkout") def _evidence(request): if request.content_type == "application/json": try: data = json.loads(request.body or b"{}") except ValueError: return {} return data if isinstance(data, dict) else {} return request.POST class MaskbreakMiddleware: def __init__(self, get_response): self.get_response = get_response def __call__(self, request): path = request.path strict = path.startswith(STRICT) # Cheap checks first: reads and unguarded paths never call out. if request.method != "POST" or not (strict or path.startswith(GUARDED)): return self.get_response(request) data = _evidence(request) email = data.get("email") result = check_visitor( data, email=email if isinstance(email, str) else None, account_id=str(request.user.pk) if request.user.is_authenticated else None, ) request.maskbreak = result if MODE == "enforce": if result and result.get("decision") == "block": return JsonResponse({"error": "Request declined"}, status=403) if strict and not clean_allow(result): return JsonResponse({"error": "Additional verification required"}, status=409) return self.get_response(request) # watch mode: always ``` Register it after authentication, so `request.user` is populated and device-to-account linking works: ``` # settings.py MIDDLEWARE = [ # ... "django.contrib.auth.middleware.AuthenticationMiddleware", "yourapp.middleware.MaskbreakMiddleware", ] ``` ## The view decides what review means The middleware refuses only what it was told to; what a `review` costs belongs in the view, where you can see what is at stake: ``` # yourapp/views.py from django.http import JsonResponse from django.views.decorators.http import require_POST from .maskbreak import MODE @require_POST def signup(request): form = SignupForm(request.POST) if not form.is_valid(): return JsonResponse({"errors": form.errors}, status=400) user = form.save() verdict = getattr(request, "maskbreak", None) # 'review' is not 'block': step up instead of refusing. if MODE == "enforce" and verdict and verdict.get("decision") == "review": require_email_verification(user) return JsonResponse({"ok": True}) ``` Passing `email` adds `email.disposable` to the result and escalates a clean verdict to `review` on a burner domain. It never blocks on its own, and it should not; the reasoning is in [flag it, don't block on it](https://maskbreak.com/blog/disposable-email-detection). The reason list goes to your logs, not to the response: telling a refused client which signal fired is free tuning feedback for whoever is probing you. ## Django REST Framework For DRF views, a permission class keeps the check declarative and per-view; use it instead of listing those paths in the middleware, or each request is checked twice. `request.data` is already parsed, JSON or form: ``` # yourapp/permissions.py from rest_framework.permissions import SAFE_METHODS, BasePermission from .maskbreak import MODE, check_visitor class VisitorCheck(BasePermission): message = "Request refused by risk checks." def has_permission(self, request, view): if request.method in SAFE_METHODS: return True data = request.data if hasattr(request.data, "get") else {} result = check_visitor( data, account_id=str(request.user.pk) if request.user.is_authenticated else None, ) request.maskbreak = result if MODE != "enforce": return True # watch: log only return not (result and result.get("decision") == "block") ``` ``` class CheckoutView(APIView): permission_classes = [IsAuthenticated, VisitorCheck] ``` A JSON client sends `token`, `fingerprintEventId` and `tz` from `Sentinel.collect()` in the body; `check_visitor` reads them under either name. ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your log shows one `maskbreak` line. `degraded=True` means no network token arrived (the script was blocked, or the class is missing or on an input); `device_evidence=not_sent` means no `sentinel_fp` arrived (submitted before the browser check finished, or blocked); `device_evidence=ok` with `degraded=False` is a complete check. ## Switching to enforce Do not enforce everywhere at once. A week of watch mode gives you your own baseline: what share of genuine traffic lands in review, which reasons dominate, and whether your own QA, staff tooling or office VPN trips it. Then set `MASKBREAK_MODE=enforce` and redeploy; the same code refuses a `block`, and the strict paths hold anything that is not a clean, complete, production allow (a fixed test token such as `test_clean` comes back with `test: true` and never passes them). A mis-set threshold discovered in production on every route at once is a revenue incident; discovered on one route in watch mode it is a config change. ## An IP address without a visit For log enrichment or batch review of yesterday's signups there is `GET /v1/lookup/`. It is an address lookup, not a visitor check: it covers Tor exits and cloud servers only, never a VPN, a proxy or the browser, and it is no substitute for the three steps above. The same check in the other Python guides: [Flask](https://maskbreak.com/blog/flask-fraud-detection) and [FastAPI](https://maskbreak.com/blog/fastapi-fraud-detection). ## Questions people ask **Should the middleware fail open or closed?** Open, for almost every action. If the detection API is unreachable and you fail closed, every signup and checkout during the outage fails; if you fail open, a window of traffic goes unscreened while your rate limits and post-hoc review still apply. The second is nearly always the cheaper incident. The exception is actions that are both irreversible and high-value, where the better answer is to queue for manual review rather than auto-approve or auto-refuse. **Where should the check live — middleware or the view?** Both, for different jobs. The middleware sends the check for the paths you list, reading the posted form or JSON body so the email travels with it, and in enforce mode refuses by path: a block everywhere, anything short of a clean allow on strict paths. The view decides what a review means for its action, such as a step-up at signup. DRF views can use a permission class instead, so a request is not checked twice. **Do I need the Python SDK?** No. This guide calls the HTTP API with requests, so the check goes out on every request, including one that arrived without a token, which is what lets the console show which half is missing. The SDK helpers need a token and do not forward the time zone. The SDK is on PyPI as sentinelsup, imported as sentinel, if you prefer it elsewhere. **How do I keep this off the fast path for anonymous browsing?** Guard by method and path, and return early. The middleware does a cheap check on request.method and request.path and hands straight back to get_response for anything that is not a POST to a listed path. Product pages, static assets and health checks should never reach an outbound call: a fraud check on a page view is latency you are paying for nothing. **How should I roll this out to an existing app?** In watch mode, the default: the middleware sends every check, logs the verdict and refuses nothing. After a few days you have your own baseline: what proportion of genuine traffic lands in review, which reason codes dominate, and whether internal QA or staff tooling trips it. Then set MASKBREAK_MODE=enforce, starting with the paths that are actually costing money, and expand. --- # DataDome vs Maskbreak: Perimeter vs Verdicts URL: https://maskbreak.com/blog/datadome-vs-sentinel Published: 2026-07-31 > DataDome mitigates bots at the perimeter. Maskbreak returns a verdict at the action. The distinction decides which one fits the abuse you actually have. These two are frequently shortlisted together and solve overlapping problems from opposite ends. DataDome sits in front of your traffic and mitigates automated requests. Maskbreak is called at a specific action and returns a decision about that one request. The choice usually comes down to a question worth answering before any demo: is your problem automated volume, or is it a small number of real people doing something they should not be able to do repeatedly? Those need different tools, and the second one is where most teams pick wrong. ## What DataDome is built for DataDome is a bot and online fraud protection platform that deploys inline — as a module or connector at your CDN, web server, or cloud edge — and evaluates requests as they arrive. It applies real-time machine learning across server-side and client-side signals, and it is designed to cover an entire surface: web, mobile apps, and APIs together. Its natural strengths follow from that placement. Content scraping, credential-stuffing floods, carding runs, inventory hoarding, and DDoS-adjacent automated volume are all problems of scale arriving at the perimeter, and a perimeter tool is the right shape for them. If your logs show millions of requests you never wanted, this is the category you want. ## What Maskbreak is built for Maskbreak is not inline. It is a REST call you make at the moments that matter — signup, login, checkout, promotion redemption — that returns individual signals plus a 0–100 risk score and an allow, review, or block verdict. Your code decides what to do with it. That placement suits a different problem: abuse where the request volume is unremarkable but the outcome is expensive. One operator running two hundred browser profiles through residential proxies generates no anomalous traffic pattern. Every request looks like a different ordinary person, because from the network's point of view it is. What connects them is device-level correlation, not rate. ## The distinction that actually decides it The row worth dwelling on is multi-accounting. It is not a bot problem. A person running two hundred profiles in Kameleo or Octo Browser is automating nothing — they are clicking, slowly, like a customer. Rate limiting and bot scoring have very little to say about it. What exposes it is noticing that forty accounts share one device environment. Your problem Better fit Why Scrapers taking your catalogue Perimeter (DataDome) High volume, all endpoints, needs blocking before origin Credential-stuffing floods Perimeter (DataDome) Volume-shaped, arrives everywhere at once Bonus and promo farming Action-level (Maskbreak) Low volume, real humans, needs account correlation Free-trial farming Action-level (Maskbreak) Each signup is individually plausible; linking exposes it Multi-accounting Action-level (Maskbreak) Not automation at all — one person, many identities Antidetect browser sessions Action-level (Maskbreak) Needs device-layer contradiction, not request-rate analysis Card testing at scale Either, often both Volume-shaped at the edge, correlation-shaped at checkout ## Integration model The practical differences are as large as the conceptual ones. - Deployment. DataDome installs as a module or connector in the request path, which gives it complete coverage and means it must be correct — a perimeter tool that misfires blocks real customers before your application ever sees them. Maskbreak is a call your code makes, so a bad verdict is something your rules can override. - Granularity. A perimeter tool naturally thinks in terms of allow or block for a request. An action-level API can return "this is a datacenter address, worth 40 points, which reaches review but not block" and let you enforce differently on a page view than on a promotion redemption. - Portability. Maskbreak is a REST endpoint and does not care where your application runs or what sits in front of it. Inline tooling is more tightly coupled to your infrastructure by design. - Scope of change. Adding a perimeter product is an infrastructure decision. Adding an action-level call is a code change on a handful of routes, which is why monitor-mode rollouts are straightforward. ## Where each is genuinely weaker A comparison that only lists strengths is marketing. The honest failure modes: - Perimeter bot mitigation, including DataDome, is structurally poor at abuse that is not automated. It is looking for signals of automation, and a human operator with many profiles emits none. This is not a defect — it is the category boundary. - Maskbreak is not a substitute for perimeter defence. It sees only the requests you choose to send it, so it will not stop a scraper hammering endpoints you never instrumented, and it does nothing about raw request volume. If your origin is falling over, an action-level API is the wrong tool. - Running both is a legitimate architecture. Perimeter tooling handles volume; the action-level verdict handles the expensive, low-volume decisions behind it. They are not mutually exclusive, and teams with both scraping and multi-accounting problems generally need both. ## How to evaluate either one Two tests separate the categories quickly. First, take a residential proxy exit — not a commercial VPN, which everything catches — and run a signup through it with a fresh antidetect profile. That is the case where network reputation reads clean and only device-layer contradiction and correlation have anything to say. Second, create several accounts from the same environment through different exits, then ask each tool whether it can tell you they are related. That is the question that decides whether you can stop bonus abuse, and it is a fundamentally different question from "is this a bot." And whichever you choose, check that a datacenter match does not short-circuit tunnel detection. VPN exits live in datacenters, so a tool that stops at "this is hosting space" will miss the tunnel underneath it. ## Questions people ask **Is DataDome or Maskbreak better for bot detection?** For high-volume automated traffic arriving across your whole surface — scraping, credential-stuffing floods, inventory hoarding — a perimeter product like DataDome is the right shape, because it sits inline and can block before requests reach your origin. Maskbreak only sees the requests your code chooses to send it, so it is not a substitute for perimeter defence. The two solve overlapping problems from opposite ends and are frequently run together. **Can bot detection stop multi-accounting?** Generally not, because multi-accounting usually is not automation. An operator running two hundred antidetect browser profiles is clicking manually at human speed through residential proxies, so there is no anomalous request rate and no automation signature to find. What exposes it is device-level correlation showing that many supposedly separate accounts share one environment, which is a different question from whether any individual request came from a bot. **Do I need both a perimeter tool and an action-level API?** If you have both volume-shaped and correlation-shaped abuse, yes, and that is a legitimate architecture rather than redundancy. Perimeter tooling absorbs scraping and credential-stuffing floods before they reach your origin; an action-level verdict handles the expensive low-volume decisions behind it, such as promotion redemption and trial signups, where the traffic looks entirely ordinary but the loss concentrates. **What should I test when evaluating either product?** Run a signup through a residential proxy exit with a fresh antidetect browser profile — commercial VPN ranges are well catalogued and nearly everything flags them, so they prove little. Then create several accounts from one environment through different exits and ask whether the tool can tell you they are related. Also confirm that a datacenter match does not short-circuit tunnel detection, since VPN exits are themselves hosted in datacenters. --- # Express Fraud Detection Middleware URL: https://maskbreak.com/blog/express-fraud-detection-middleware Published: 2026-07-31 · Updated: 2026-10-08 > A production-shaped Express integration for VPN, proxy, antidetect and automation detection — as middleware, with the failure handling most omit. Most integration examples show the happy path and stop. This one is written as middleware you would actually deploy: reusable across routes, never failing your own request because of the fraud check, starting in watch mode, and applying different strictness to different actions rather than one global rule. It takes three steps, the same three the Maskbreak console lists: add the script to the page with your form, send the check from your server, and submit your form once. The code calls the HTTP API with `fetch`, which Node 18 and later have built in, so there is nothing to install. ## Step 1: Add the script to the page with your form Load `sentinel.js` on the page that holds the form, and put `class="monocle-enriched"` on the `
` element itself, never on an input inside it. ```
``` The script adds three hidden fields to that form: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the browser's time zone). The browser check starts when the page loads with a marked form (or at the first click into a field) and writes `sentinel_fp` when it finishes, so a form submitted right after the page loads may arrive without it. If your frontend renders the form with JavaScript (React, Vue, a fetch submit), ask the script for the values instead and send them with your form data. Check that `window.Sentinel` exists first, and never hold the form back when the script is missing or blocked: ``` // In your submit handler, before the fetch() const evidence = window.Sentinel ? await window.Sentinel.collect().catch(() => ({})) : {}; // script blocked: send the form anyway await fetch('/signup', { method: 'POST', headers: { 'Content-Type': 'application/json' }, // collect() gives { token, fingerprintEventId, tz } body: JSON.stringify({ email, password, ...evidence }), }); ``` If your site sends a `Content-Security-Policy` header (helmet does by default), the browser blocks the script until you add Maskbreak's hosts to the directives you already have: ``` script-src https://maskbreak.com https://mcl.maskbreak.com https://*.mcl.maskbreak.com https://mesu.maskbreak.com 'wasm-unsafe-eval' connect-src https://mcl.maskbreak.com https://*.mcl.maskbreak.com wss://mcl.maskbreak.com wss://*.mcl.maskbreak.com https://mesu.maskbreak.com worker-src https://mesu.maskbreak.com blob: ``` ## Step 2: Send the check from your server One function does the call. It maps the form's field names to the API's (`monocle` to `token`, `sentinel_fp` to `fingerprintEventId`, `sentinel_tz` to `tz`), and it calls even when a field is missing: a check that arrives without a token or a browser check id is what lets the console tell you which half is missing. It never throws, which matters in Express 4, where an unhandled rejection in a handler ends the process. ``` // lib/maskbreak.js: server-side only const MODE = process.env.MASKBREAK_MODE || 'watch'; // 'watch' or 'enforce' // Returns the verdict, or null when there is none (timeout, network error, // wrong key). Never throws. async function checkVisitor(body = {}, extra = {}) { const payload = { token: body.monocle || body.token || '', fingerprintEventId: body.sentinel_fp || body.fingerprintEventId || undefined, tz: body.sentinel_tz || body.tz || undefined, email: extra.email, // optional: adds email.disposable accountId: extra.accountId, // optional: your own server-side user id }; let result = null; try { const res = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify(payload), signal: AbortSignal.timeout(3000), }); if (res.ok) result = await res.json(); else console.warn('[maskbreak] HTTP', res.status); // 401: the key, 400: the body } catch (err) { console.warn('[maskbreak] unavailable:', err.name); } // One line per check. Never log the key, the token or form data. console.log('[maskbreak]', JSON.stringify({ mode: MODE, decision: result ? result.decision : null, reasons: result ? result.reasons : null, device_evidence: result ? result.device_evidence : null, degraded: result ? !!result.degraded : null, })); return result; } module.exports = { MODE, checkVisitor }; ``` The middleware is a factory, parameterised by how strict the route should be. In watch mode, the default, it records the verdict on the request and always continues. ``` // middleware/maskbreak.js const { MODE, checkVisitor } = require('../lib/maskbreak'); // strict: false refuse only a block (enforce mode) // strict: true continue only on a clean, complete allow (enforce mode) function guard({ strict = false } = {}) { return async function maskbreakGuard(req, res, next) { const body = req.body || {}; const result = await checkVisitor(body, { email: typeof body.email === 'string' ? body.email : undefined, accountId: req.user ? String(req.user.id) : undefined, }); req.maskbreak = result; if (MODE !== 'enforce') return next(); // watch: log only, always continue if (result && result.decision === 'block') { return res.status(403).json({ error: 'Request declined' }); } if (strict) { const clean = result && result.decision === 'allow' && !result.degraded && !result.test && result.device_evidence === 'ok'; if (!clean) return res.status(409).json({ error: 'Additional verification required' }); } return next(); // a review on a normal route: the handler steps up }; } module.exports = { guard }; ``` Mount it per route, after the body parsers. An HTML form posts `application/x-www-form-urlencoded`, so `express.urlencoded` has to be there or `req.body` is empty. ``` const express = require('express'); const { MODE } = require('./lib/maskbreak'); const { guard } = require('./middleware/maskbreak'); const app = express(); app.use(express.urlencoded({ extended: false, limit: '64kb' })); // HTML forms app.use(express.json({ limit: '64kb' })); // fetch() posts // Public reads: no check at all. app.get('/api/products', listProducts); // Signup: refuse only a block, step up on review. app.post('/signup', guard(), async (req, res, next) => { try { const stepUp = MODE === 'enforce' && req.maskbreak?.decision === 'review'; await createUser(req.body, { requireEmailVerification: stepUp }); res.redirect('/welcome'); } catch (err) { next(err); // your own failures too: Express 4 does not catch a rejected handler } }); // Promo redemption: the strictest gate on the site. app.post('/api/promo/redeem', requireAuth, guard({ strict: true }), redeemPromo); // Password change: anything that is not clean is held. app.post('/api/account/password', requireAuth, guard({ strict: true }), changePassword); ``` Set `MASKBREAK_API_KEY` to your live key in your host's environment or secret store, never in the repository or in browser code, and deploy. ## Step 3: Submit your form once Open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your server logs one `[maskbreak]` line for it. That line says what is missing when something is: - decision: null after an HTTP warning: a 401 is the key; anything else, read the warning. - degraded: true: no network token reached your server (or the network check was unavailable). Usually the script was blocked by your CSP or a content blocker, the class is missing or sits on an input, or the form was rendered after the page loaded and needs Sentinel.collect(). - device_evidence: "not_sent": the form posted no sentinel_fp. The browser check had not finished, was blocked, or the value did not reach your server. - device_evidence: "unavailable": a sentinel_fp arrived, but Maskbreak could not resolve it: a value that is not a browser check id, or the browser check service did not answer. - device_evidence: "ok" and degraded: false: a complete check. ## Switching to enforce Leave it in watch mode for a few days and compare the log lines with the console's Events: what share of your real traffic lands in review, which reason codes dominate, whether your own staff or QA tooling trips it. Then set `MASKBREAK_MODE=enforce` and redeploy. Nothing in the code changes. In enforce mode a `block` is refused everywhere, a `review` on a normal route reaches your handler (which steps up rather than refusing), and a strict route continues only on a clean, complete, production `allow`. A strict route holds a check that came back without device evidence, without a network token, or with `test: true`: a fixed test token such as `test_clean` must never pass a production gate. Start enforcing on one action, whichever is costing you money, and expand from there rather than turning it on everywhere at once, which is how a bad threshold becomes a revenue incident. ## Why failing open is not a cop-out It is tempting to treat a failed fraud check as a reason to refuse. Work through the arithmetic before you do. If the API is unreachable for ten minutes and you fail closed, every signup and checkout in that window fails. If you fail open, ten minutes of traffic goes unscreened, and your existing controls, rate limits and post-hoc review still apply. The second outcome is almost always cheaper, and it is the one your on-call engineer will thank you for at 3am. That is why `checkVisitor` returns `null` on any failure and a normal route continues on `null`. The exception is an action that is both irreversible and high-value. For those, failing open is a real risk, which is what `strict: true` is for: it holds the action and lets you queue it for manual review rather than auto-approve it. ## Logging the reason, not just the outcome Store `reasons` and `risk_score` alongside your own decision. When someone reports that a legitimate customer was declined, you want to answer from evidence rather than reconstruct it. The response also carries `decision_source` and `engine_decision` when your own rules or allow-pins changed the outcome, which is what tells you whether a bad decision came from the engine or from a rule you wrote. ``` const v = req.maskbreak; await db.riskLog.insert({ userId: req.user?.id, action: 'promo_redeem', decision: v?.decision ?? null, engineDecision: v?.engine_decision ?? v?.decision ?? null, source: v?.decision_source ?? 'engine', score: v?.risk_score ?? null, reasons: v?.reasons ?? [], deviceEvidence: v?.device_evidence ?? null, }); ``` ## Questions people ask **Should fraud detection middleware fail open or closed?** Open, for almost every action. If the detection API is unreachable and you fail closed, every signup and checkout during the outage fails; if you fail open, a window of traffic goes unscreened while your rate limits and post-hoc review still apply. The second is nearly always the cheaper incident. The exception is actions that are both irreversible and high-value, where the better answer is to queue for manual review rather than auto-approve or auto-refuse. **What if the client never sends a token?** Send the check anyway and let the request through on ordinary routes. An ad blocker, a content-security-policy problem or a form rendered after the page loaded can stop the token for real visitors. Maskbreak answers such a check marked degraded, and the console shows that the network half is missing, which is how you find the cause. On a strict route in enforce mode, hold the action for verification instead. **How do I apply different strictness to different routes?** Make the middleware a factory with a strict option and mount it per route. Public reads need no check at all; signup refuses only a block in enforce mode and steps up on review; promotion redemption and password changes continue only on a clean, complete allow. A single global threshold is always wrong somewhere, because the cost of a false positive on a product page and on a checkout are not remotely comparable. **How should I roll this out to an existing app?** In watch mode, the default: every check is sent and logged, and nothing is refused. After a few days you have your own baseline: what share of genuine traffic lands in review, which reason codes dominate, and whether internal QA or staff tooling trips it. Then set MASKBREAK_MODE=enforce with the guard mounted on the action that is actually costing money, and expand from there. Enforcing everywhere at once is how a mis-set threshold becomes a revenue incident. --- # Is Device Fingerprinting Legal? GDPR & ePrivacy URL: https://maskbreak.com/blog/is-device-fingerprinting-legal Published: 2026-07-31 · Updated: 2026-10-21 > What EU and UK law says about device fingerprinting for fraud prevention — lawful basis, the ePrivacy consent question, and what to check first. This comes up in every procurement review and the answers online are uniformly bad — either "it is fine, fraud prevention is a legitimate interest" or "it is illegal without consent." Both are too simple, because two separate laws apply and they ask different questions. What follows is how the regime is structured and which questions to put to your own counsel. It is not legal advice, and anyone selling you a fraud tool who says otherwise is not being straight with you. ## Two laws, two questions Almost all confusion here comes from collapsing two separate regimes into one. GDPR asks whether you may *process personal data*, and requires a lawful basis. ePrivacy (in the UK, PECR) asks whether you may *store information on, or gain access to information stored on, a user's terminal equipment* — and that question has its own answer regardless of what your GDPR basis is. A fraud tool can be perfectly defensible under GDPR and still owe you an ePrivacy analysis. Getting a clean answer on one tells you nothing about the other. ## The GDPR side is the easier one Fraud prevention has unusually explicit support. Recital 47 of the GDPR states outright that processing personal data strictly necessary for fraud prevention purposes constitutes a legitimate interest of the controller. That is not a blank cheque — legitimate interest still requires a balancing test weighing your interest against the rights of the data subject, and you have to document it. But it does mean the usual starting point for fraud detection is Article 6(1)(f), not consent, and that position is well supported. Note also that an IP address is personal data where it can be linked to an individual, following the CJEU's decision in *Breyer* (C-582/14). So IP reputation checks are in scope even if you never touch a name or an email. ## The ePrivacy side is where it gets interesting Article 5(3) of the ePrivacy Directive requires consent for storing or accessing information on a user's device, with a narrow exemption for what is *strictly necessary* to provide a service the user explicitly requested. Crucially, this is technology-neutral. It is not a cookie rule. European regulators have been consistent that it captures device fingerprinting, local storage, and similar techniques, precisely because the alternative would have let everyone sidestep it by not using cookies. So the question becomes whether your fraud check falls inside the strictly-necessary exemption. Reasonable arguments exist that security measures a user would expect — protecting their own account at login — qualify. Regulators have not universally endorsed that reading, and it is weaker for, say, profiling a browsing session than for verifying a login. This is exactly the question to put to counsel rather than to a vendor blog. ## Questions worth asking any fraud vendor Independent of your own analysis, the vendor's architecture determines how hard your position is to defend. - Is identity correlated across customers? A vendor that links device identity across its whole customer base is building a cross-site profile of individuals, which is a substantially harder position to defend than one that keeps correlation inside each customer's own data. Ask directly, and get the answer in writing. - What is actually stored, and for how long? "We store a hash" and "we store a full fingerprint" are materially different claims. So is thirty days versus indefinitely. - Is there a DPA, and who are the sub-processors? You need both to complete your own Article 30 records, and a vendor who cannot produce a current sub-processor list on request is telling you something. - Where is data processed? Transfers outside the EEA need their own mechanism, and "our cloud provider has a region there" is not the same as a documented transfer basis. - Can you honour erasure? If a data subject requests deletion, can the vendor actually delete — including from backups — and how quickly? ## Where Maskbreak sits, concretely So you can evaluate the above against a real answer rather than a generic one: - Device-to-account linking is per-customer only, stored as keyed hashes; an account ID a customer sends is also kept encrypted, only so that customer’s console can show it, for 90 days after its last check. Links never cross between customers. The one device record shared across customers is a hashed device’s visit count and first-seen date, with no site, account or address attached, so Maskbreak does not build a cross-site profile of any individual. This is an architectural constraint, not a setting. - Signup email checks against disposable-domain feeds are transient — checked in the request, never stored or logged. - A DPA and a current sub-processor list are published rather than available on request. - The company is UK-registered (Sentinel Edge Networks LTD), and the retention position is documented in the privacy policy rather than described only in sales conversations. - None of that decides your ePrivacy question. It narrows what you have to defend. ## The practical position Most teams running fraud detection in the EU and UK land somewhere like this: legitimate interest under Article 6(1)(f) as the GDPR basis, with a documented balancing test; a considered position on whether the client-side collection falls inside the ePrivacy strictly-necessary exemption; transparency in the privacy notice about what is collected and why; and a vendor whose architecture does not create cross-site profiling. That is a defensible posture. It is also one you should reach with your own counsel, having read the actual texts, rather than by trusting a paragraph on a vendor's website — including this one. ## Questions people ask **Is device fingerprinting legal under GDPR?** GDPR does not prohibit it; it requires a lawful basis. For fraud prevention the usual basis is legitimate interest under Article 6(1)(f), and Recital 47 states explicitly that processing strictly necessary for fraud prevention purposes constitutes a legitimate interest of the controller. That still requires a documented balancing test weighing your interest against the data subject's rights. Separately, ePrivacy rules on accessing information stored on a user's device apply regardless of your GDPR basis, and that is a distinct question. **Do I need consent for device fingerprinting?** That is an ePrivacy question rather than a GDPR one, and it is genuinely unsettled. Article 5(3) of the ePrivacy Directive requires consent to store or access information on a user's terminal equipment, with a narrow exemption for what is strictly necessary to deliver a service the user explicitly requested. The rule is technology-neutral and regulators have consistently treated it as covering fingerprinting, not just cookies. Whether a security check falls inside the strictly-necessary exemption is arguable and is a question for your own counsel. **Is an IP address personal data?** It can be. The Court of Justice of the European Union held in Breyer (C-582/14) that a dynamic IP address is personal data in the hands of a party with the legal means to identify the individual behind it. In practice this means IP reputation checks fall within GDPR scope even where no name, email, or account is involved, so they need a lawful basis like any other processing. **What should I ask a fraud detection vendor about privacy?** Whether device identity is correlated across their customer base or kept within each customer's own data, since cross-customer linking builds a cross-site profile of individuals and is much harder to defend. Then: exactly what is stored and for how long, whether a DPA and a current sub-processor list are available, where processing happens and under what transfer mechanism, and whether erasure requests can actually be honoured including from backups. Get the cross-customer answer in writing. **Does Maskbreak link devices across different customers?** No. Device-to-account linking is per-customer and hash-only, and correlation never crosses between customers — it is an architectural constraint rather than a configuration option. That means Maskbreak does not build a cross-site profile of any individual. Disposable-email checks at signup are transient, performed within the request and never stored or logged. A DPA and a current sub-processor list are published rather than supplied on request. --- # Laravel Fraud Detection, No SDK URL: https://maskbreak.com/blog/laravel-fraud-detection Published: 2026-07-31 · Updated: 2026-10-08 > You do not need the PHP SDK: a production-shaped Laravel integration on the HTTP client, with a service class, middleware by strictness and Http::fake() tests. The API is a single POST, and Laravel's HTTP client handles it in a few lines. This is the integration written the way a Laravel application would actually structure it: a config entry, a service class, middleware with a strictness parameter, and the Blade side. It follows the three steps the Maskbreak console lists (add the script to the page with your form, send the check from your server, submit your form once) and starts in watch mode, where every check is logged and nothing is refused. There is an official PHP package (`sentinelsup/sdk` on Packagist). This guide uses Laravel's own HTTP client instead, so `Http::fake()` covers the tests and the call goes out on every request, including the ones that arrive without a token: those are the checks the console needs to tell you which half of the integration is missing. ## Step 1: Add the script to the page with your form Load the script in your layout and put `class="monocle-enriched"` on the `
` element itself, never on an input: ``` {{-- resources/views/layouts/app.blade.php --}} {{-- resources/views/auth/register.blade.php --}} @csrf
``` The script adds three hidden fields to the form: `monocle` (the network token), `sentinel_fp` (the browser check id) and `sentinel_tz` (the time zone). If a Livewire, Inertia or Vue frontend posts with JavaScript instead, call `await window.Sentinel.collect()` before the request (check that `window.Sentinel` exists, and submit anyway when it does not) and send its `token`, `fingerprintEventId` and `tz`; the middleware below reads both spellings. If you send a `Content-Security-Policy` (spatie/laravel-csp, or your web server), add `https://maskbreak.com`, `https://mcl.maskbreak.com`, `https://*.mcl.maskbreak.com`, `https://mesu.maskbreak.com` and `'wasm-unsafe-eval'` to `script-src`, the `mcl` hosts (https and wss) and `mesu` to `connect-src`, and `https://mesu.maskbreak.com blob:` to `worker-src`. ## Step 2: Send the check from your server Start with a config entry so the key is never inlined. Put your live key in `.env` as `MASKBREAK_API_KEY`; `MASKBREAK_MODE` stays unset (watch) for now. ``` // config/services.php 'maskbreak' => [ 'key' => env('MASKBREAK_API_KEY'), 'mode' => env('MASKBREAK_MODE', 'watch'), // 'watch' or 'enforce' 'timeout' => 3, ], ``` Then a small service class you can bind and fake in tests. It maps the form's names to the API's and calls even when a field is missing. It never throws. ``` (string) ($request->input('monocle') ?? $request->input('token') ?? ''), 'fingerprintEventId' => $request->input('sentinel_fp') ?? $request->input('fingerprintEventId'), 'tz' => $request->input('sentinel_tz') ?? $request->input('tz'), 'email' => is_string($request->input('email')) ? $request->input('email') : null, 'accountId' => $request->user() ? (string) $request->user()->getAuthIdentifier() : null, ], fn ($v) => $v !== null); $result = null; try { $response = Http::withToken((string) config('services.maskbreak.key')) ->timeout(config('services.maskbreak.timeout')) ->withHeaders(['Content-Type' => 'application/json']) ->acceptJson() ->post('https://maskbreak.com/v1/evaluate', $payload); if ($response->successful()) { $result = $response->json(); } else { Log::warning('maskbreak http error', ['status' => $response->status()]); } } catch (\Throwable $e) { // Timeout, DNS, connection reset: no verdict, never an error page. Log::warning('maskbreak unavailable', ['error' => get_class($e)]); } // One line per check. Never log the key, the token or form data. Log::info('maskbreak', [ 'mode' => config('services.maskbreak.mode'), 'decision' => $result['decision'] ?? null, 'reasons' => $result['reasons'] ?? null, 'device_evidence' => $result['device_evidence'] ?? null, 'degraded' => is_array($result) ? ! empty($result['degraded']) : null, ]); return is_array($result) ? $result : null; } /** A complete, production allow. */ public static function cleanAllow(?array $v): bool { return $v !== null && ($v['decision'] ?? null) === 'allow' && ($v['device_evidence'] ?? null) === 'ok' && empty($v['degraded']) && empty($v['test']); } } ``` ## Middleware, parameterised by strictness Laravel middleware parameters make the per-action threshold natural: `maskbreak:strict` on the routes that deserve it, `maskbreak` elsewhere. In watch mode it records the verdict and always continues. ``` maskbreak->check($request); $request->attributes->set('maskbreak', $verdict); if (config('services.maskbreak.mode') !== 'enforce') { return $next($request); // watch: log only } // Route on decision, never on the legacy isSuspicious flag. if (($verdict['decision'] ?? null) === 'block') { return response()->json(['error' => 'Request declined'], 403); } if ($level === 'strict' && ! Maskbreak::cleanAllow($verdict)) { return response()->json(['error' => 'Additional verification required'], 409); } return $next($request); } } ``` Register the alias, then apply it where the cost of being wrong justifies it. ``` // bootstrap/app.php (Laravel 11+) ->withMiddleware(function (Middleware $middleware) { $middleware->alias(['maskbreak' => \App\Http\Middleware\MaskbreakGuard::class]); }) // routes/web.php Route::post('/register', RegisterController::class) ->middleware('maskbreak'); // refuse only a block Route::post('/promo/redeem', RedeemController::class) ->middleware(['auth', 'maskbreak:strict']); // strictest gate on the site Route::post('/account/password', PasswordController::class) ->middleware(['auth', 'maskbreak:strict']); ``` In a controller, `$request->attributes->get('maskbreak')` gives you the verdict. In enforce mode, send a `review` to a step-up (email verification, a second factor) rather than refusing it: a plain VPN lands there, and VPN users are customers. ## Step 3: Submit your form once Run the app on your computer or deploy it, open the page in an ordinary browser, wait a moment, and submit the form. The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and `storage/logs` (or your log channel) shows one `maskbreak` line. `degraded: true` means no network token arrived (the script was blocked, or the class is missing or sits on an input); `device_evidence: "not_sent"` means no browser check id arrived; `"ok"` with `degraded` false is a complete check. After a few days of comparing those lines with Events, set `MASKBREAK_MODE=enforce`, run `php artisan config:cache` if you cache config, and deploy. A strict route then holds anything that is not a clean, complete, production allow, including a fixed test token such as `test_clean`, which comes back with `test: true`. ## Testing it without hitting the network Because the service uses Laravel's HTTP client, `Http::fake()` covers the whole thing, including the failure paths, which are the ones worth asserting. ``` use Illuminate\Support\Facades\Http; public function test_blocked_signup_is_refused_in_enforce_mode(): void { config(['services.maskbreak.mode' => 'enforce']); Http::fake(['*/v1/evaluate' => Http::response(['decision' => 'block', 'risk_score' => 95, 'reasons' => ['proxy_detected']], 200)]); $this->post('/register', ['email' => 'a@b.c', 'password' => 'x', 'monocle' => 'tok', 'sentinel_fp' => 'fp']) ->assertStatus(403); } public function test_signup_survives_a_detection_outage(): void { config(['services.maskbreak.mode' => 'enforce']); Http::fake(['*/v1/evaluate' => Http::response(null, 500)]); // Fail open: the signup must still succeed. $this->post('/register', ['email' => 'a@b.c', 'password' => 'x']) ->assertSuccessful(); } public function test_the_check_goes_out_without_a_token(): void { Http::fake(['*/v1/evaluate' => Http::response(['decision' => 'allow', 'degraded' => true], 200)]); $this->post('/register', ['email' => 'a@b.c', 'password' => 'x']); Http::assertSent(fn ($request) => str_contains($request->url(), '/v1/evaluate')); } ``` The last test is the one that keeps watch mode honest: a request with no token still reaches Maskbreak, so the console can show you that the browser half is missing instead of waiting for a check that never comes. ## Questions people ask **Is there an official PHP or Laravel SDK for Maskbreak?** Yes: sentinelsup/sdk on Packagist, alongside the Node and Python packages. This guide uses Laravel's own HTTP client instead, for two reasons: Http::fake() covers the tests, and the check goes out on every request, including one without a token (the SDK helpers need one), which is what lets the console show which half of the integration is missing. **Where should the Maskbreak check go in a Laravel app?** In middleware, parameterised by strictness, applied per route. Laravel middleware parameters map naturally onto action risk: plain maskbreak on registration, so enforce mode refuses only a block, and maskbreak:strict on promotion redemption and password changes, where anything short of a clean, complete allow is held. Putting it in a controller works but tends to get duplicated; putting it globally applies one threshold to actions whose costs are not comparable. **How do I test the integration without calling the API?** Use Http::fake() with a pattern matching */v1/evaluate. Because the service class goes through Laravel's HTTP client rather than raw cURL, faking covers both the success paths and the failure paths. The failure cases are the ones actually worth asserting: a 500 or a timeout should leave the signup succeeding, since failing closed turns a detection outage into a signup outage. **What should happen when the request has no token?** Send the check anyway and let the request through on ordinary routes. An ad blocker or a content-security-policy problem can stop the script for real visitors; Maskbreak answers the check marked degraded, and the console shows that the network half is missing. On a strict route in enforce mode, hold the action for verification instead of refusing it outright. --- # Bot and Fraud Detection in Next.js URL: https://maskbreak.com/blog/nextjs-bot-detection Published: 2026-07-31 · Updated: 2026-10-08 > Add VPN, proxy, antidetect and automation detection to a Next.js signup or checkout — Route Handlers, Server Actions, and why middleware is the wrong place. Next.js gives you three plausible places to run a fraud check: `middleware.ts`, a Route Handler, or a Server Action. Only two of them work. This walks through a real integration, including the mistake that costs people a week. The short version: the check needs evidence collected in the browser, so it cannot live in Edge middleware that runs before your form is submitted. Put it where the action happens, and start in watch mode, where every check is logged and nothing is refused. ## Why middleware is the wrong place Edge middleware runs on every matching request, before your route code, with access to headers and cookies but not to a form body. That is fine for coarse routing decisions and wrong for fraud detection, because the signals that matter are collected client-side and submitted with the request. The device layer in particular (automation, emulators, fake browsers, tampering) is only available once a browser has run the collector. Middleware sees the request too early for any of that to exist. That device layer is what Maskbreak's [bot detection API](https://maskbreak.com/bot-detection) adds to a server-side check. There is also a cost argument. Middleware runs on every request including static assets and prefetches, so putting an API call there spends your allowance on traffic that was never a decision point. ## Step 1: Add the script to the page with your form Load the script once in your root layout. It runs on every page, but it only starts the browser check where a form is used. ``` // app/layout.tsx import Script from 'next/script'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} `) on your checkout page. Put `class="monocle-enriched"` on the checkout `
` itself, and the script adds three hidden fields to it while the customer fills it in: `monocle` (a network token for the customer's own connection), `sentinel_fp` (the browser check: automation, emulators, tampered or fake browsers) and `sentinel_tz` (the time zone). A checkout your JavaScript submits gets the same values from `await window.Sentinel.collect()`. A server-side evaluate call that your backend makes before creating any Stripe object, forwarding those three fields as `token`, `fingerprintEventId` and `tz`. The answer is a decision (allow, review or block), a risk score, the reasons behind it and, when the browser check ran, a visitor ID you can count payment attempts against. Here is the integration before a Stripe charge. It starts in watch mode, where every attempt is checked and logged and nothing is refused; set `MASKBREAK_MODE=enforce` once the log lines match what you see in the console's Events: ``` // Node.js / Express: before stripe.paymentIntents.create const MODE = process.env.MASKBREAK_MODE || 'watch'; // 'watch' or 'enforce' app.post('/pay', express.urlencoded({ extended: false }), express.json(), async (req, res, next) => { const b = req.body || {}; let verdict = null; try { // Sent on every payment attempt, even when a field is missing. const r = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ token: b.monocle || b.token || '', // the network token fingerprintEventId: b.sentinel_fp || b.fingerprintEventId || undefined, // the browser check: device.* signals tz: b.sentinel_tz || b.tz || undefined, }), signal: AbortSignal.timeout(3000), }); if (r.ok) verdict = await r.json(); else console.warn('[maskbreak] HTTP', r.status); } catch (err) { console.warn('[maskbreak] unavailable:', err.name); // no verdict: the payment flow continues } console.log('[maskbreak]', JSON.stringify({ mode: MODE, decision: verdict ? verdict.decision : null, reasons: verdict ? verdict.reasons : null, device_evidence: verdict ? verdict.device_evidence : null, degraded: verdict ? !!verdict.degraded : null, })); try { if (MODE === 'enforce') { // A proxy, automation, an emulator or a fake or tampered browser is // what makes the decision block; a block never reaches Stripe. if (verdict && verdict.decision === 'block') { return res.status(402).json({ error: 'payment_declined' }); } // Cross-session velocity: key your own attempt counter (e.g. Redis) // on the visitor ID the browser check returns. const visitorId = verdict && verdict.device ? verdict.device.visitor_id : null; if (visitorId && await recentPaymentAttempts(visitorId) > 10) { return res.status(429).json({ error: 'too_many_attempts' }); } } // Proceed to Stripe, with the amount from your own cart, never from the request. const intent = await stripe.paymentIntents.create({ amount: await cartTotalFor(req), currency: 'usd', // ... rest of your Stripe params }); res.json({ clientSecret: intent.client_secret }); } catch (err) { next(err); // Express 4 does not catch a rejected promise: an uncaught one ends the process } }); ``` The response gives you enough granularity to tune your policy. A customer on a commercial VPN with a clean browser comes back as `review`, not `block`; a proxy, automation or a fake browser is what turns the answer into `block`. In enforce mode this sketch declines a `block` and lets a `review`, or a check that did not answer, go on to Stripe, where Radar and 3D Secure still apply. The stricter policy in the [Stripe notes](https://maskbreak.com/integrations#stripe) pauses a review or an unavailable check as well; choose it for payments you cannot step up. Evaluate the control with a staged rollout. Track authorization attempts per device, issuer-decline rate, challenge rate, confirmed fraud, chargebacks, and false positives. Compare against a holdout or the same traffic segment before deployment rather than assuming a universal reduction. ## Building a Layered Defense Card testing defense works best as a layered system, with each layer doing what it's architecturally suited for: - Cloudflare / WAF rules — drops unsophisticated bots using known bad ASNs and obvious attack patterns. Catches known infrastructure and obvious request patterns. - Maskbreak (application layer) — flags proxies (residential ones included), VPNs, Tor, automation, emulators and tampered or fake browsers, and returns a visitor ID your own counter can measure velocity against. Adds the device and connection context that a network-only rule may miss. - Stripe Radar rules — catches card-level signals: BIN velocity, billing address mismatches, issuer-level risk scores. Handles the fraud that slips through the upstream layers. - 3D Secure (3DS2) — for anything Radar scores above your threshold, trigger SCA. This pushes liability to the card issuer on successful charges, eliminating your chargeback exposure even if a live card transacts. The goal is to ensure Stripe Radar is only processing sessions that have already cleared application-layer checks. When you stop feeding Radar with junk traffic, its signal-to-noise ratio improves — and your legitimate customer conversion stays clean. ## Update: card testing through a clean-looking front end The pattern to add since publication is card testing routed through residential exits and driven by a real browser rather than a script. Every network signal reads consumer-grade, the browser environment is genuine, and the velocity is deliberately throttled to stay under per-minute thresholds. Velocity rules alone will not see it, because the whole design is to stay beneath them. What does surface it is correlation across attempts that look unrelated at the address level: one device environment behind many card numbers, or many addresses behind one device. Pair that with protocol-layer consistency checks — a residential address running a non-browser TLS stack is a contradiction worth acting on — and the pattern becomes visible again. [The residential-network guide](https://maskbreak.com/blog/residential-proxy-detection-guide-2026) and [TLS fingerprinting](https://maskbreak.com/blog/ja4-tls-fingerprinting) cover both halves. ## Questions people ask **What's the difference between card testing and carding?** Card testing (also called a BIN attack or card verification) is the process of making small charges to verify whether stolen card numbers are still active. Carding is the broader term for using verified stolen cards to make fraudulent purchases. Card testing is the first step in the carding workflow — it sorts live cards from dead ones before they're used or sold on fraud markets. **Why do fraudsters target small merchants instead of large retailers?** Large retailers have dedicated fraud teams, sophisticated ML models, velocity rules, and often 3DS2 enforcement. Small merchants frequently have none of these — just default Stripe Radar settings. They're also less likely to notice a card testing event until Stripe flags them. Donation pages, nonprofit checkouts, and small SaaS payment flows are particularly targeted because they accept arbitrary small amounts with minimal friction. **Will blocking residential proxies hurt legitimate international customers?** A detected proxy, residential or not, makes the decision block by default, because it hides the connection a payment really comes from; a commercial VPN on its own comes back as review. If some of your genuine customers do reach you through a proxy, such as a corporate gateway, set the Proxy rule to Review in the console's Rules tab and step those payments up instead of declining them. Run in watch mode first, so you can see how often that happens before anything is refused. **How quickly can a card testing attack escalate?** Fast. Once a script finds a low-friction checkout it can send attempts as quickly as your checkout answers, so a run can trip a payment provider's decline or dispute thresholds before anyone responds by hand. That is why the check belongs before the charge and runs automatically, rather than in a manual review after the fact. --- # Headless Browser Detection in 2026 URL: https://maskbreak.com/blog/headless-browser-detection-2026 Published: 2026-05-07 · Updated: 2026-07-30 > navigator.webdriver was solved years ago and stealth plugins kill the next 20 checks. What actually catches headless Chrome and CDP-driven browsers in 2026. If your headless-detection still pivots on `navigator.webdriver`, you're catching the bots that didn't read the StackOverflow answer. Modern Puppeteer, Playwright, and Selenium ship with stealth plugins that patch every classical detection vector before the page even loads. The signals that still work in 2026 are not on `navigator`. They're in the input physics, the GPU rendering pipeline, the timing of synthesized events, and the entropy of the keystroke stream. Here's what to instrument. If you would rather not build and maintain these checks yourself, Maskbreak's [bot detection API](https://maskbreak.com/bot-detection) flags headless and automated browsers on a live visit. Headless browsers are the workhorse of automation: scrapers, credential stuffers, scalper bots, click farms, ad-fraud rings, content harvesters. Every one of those threats begins with a Chromium process driven via the Chrome DevTools Protocol (CDP). If you can detect the CDP-driven session, you can stop the threat before it executes. If you can't, every other defense is downstream of an attacker who can already script your interface. ## The detection arms race, briefly The classical headless signals — and what defeated each: - navigator.webdriver === true — solved 2018 by puppeteer-extra-plugin-stealth. - window.chrome.runtime missing — solved 2019 by stealth plugins, undetected-chromedriver, browser-launchers. - Plugin array empty — solved 2019. - Permissions API inconsistencies (Notification.permission) — solved 2020. - Languages mismatch — solved 2020. - Iframe contentWindow.chrome === undefined — solved 2021. - WebGL VENDOR / RENDERER spoofing — defeated by stealth plugins that override the WebGLRenderingContext.getParameter return values. - User-Agent CDP property exposure — defeated by Chromium build flags and runtime patching. Every static-property check has a stealth-plugin counter. The detection axis has to move off static properties entirely. ## What still works in 2026 ### 1. Input-event entropy This is the most reliable single signal we have. Real human input — even very fast input — produces continuous streams of events with predictable physical characteristics: - Mouse: mousemove events arrive at sub-millisecond intervals between meaningful position changes, with sub-pixel coordinates and acceleration profiles that follow Fitts's-law-like curves toward targets. - Touch: multiple touchmove events with pressure variation between events, tilt angle data when supported, and finger-area variation. - Keyboard: keydown and keyup separated by 30–120 ms typically; modifier-key combinations show physical-impossibility patterns when faked (Shift+x with Shift release before x release is normal; the inverse is suspicious). CDP-driven mouse movement, even via `page.mouse.move()` with stealth plugins, produces synthesized events with characteristic anomalies: integer-pixel coordinates only, perfectly straight or perfectly curved trajectories with no jitter, identical inter-event timings on every move regardless of distance. Real users' mouse movements are noisy in a particular way that's very hard to fake without explicitly modeling it. Detection rule: a session that performs a meaningful action (login, signup, checkout) without a single mouse-move event preceding it is bot-by-default. Add the entropy check on top — the `mousemove` stream should have a Shannon entropy above a threshold. CDP-injected events fail it almost universally. ### 2. CDP runtime detection The Chrome DevTools Protocol leaves a small but persistent runtime signature regardless of stealth patching. Calling `console.debug` with a `%c`-formatted argument inside a getter that's accessed during devtools attachment produces a measurable timing delta. Multiple frameworks have published similar techniques (Hero's CDP-detection, ADTrustLab's research). The gap is small (~0.3 ms) but stable, and combined with input-entropy it's a strong joint signal. This signal does need to be re-checked every few months — Chromium's CDP team patches the most-public detections — but as of May 2026 several variants still work reliably and the underlying gap is fundamental enough that it's unlikely to fully close. ### 3. GPU / canvas rendering signature Headless Chrome's GPU pipeline differs from headful Chrome's in measurable ways even when running with `--use-gl=swiftshader` or with hardware acceleration emulation. Specific differences: - Subpixel positioning of text in canvas rendering deviates from headful by stable, machine-predictable values. - Bezier curve aliasing patterns in canvas paths show characteristic differences. - WebGL readPixels() output for a controlled scene differs from headful by stable byte-level deltas. Maintaining a hash table of "canvas rendering of a known calibration scene → CDP-driven Chromium" matches is one of the cleanest detection surfaces. Stealth plugins don't touch the GPU pipeline because doing so would require swapping in a fake renderer, which itself produces detectable inconsistencies. ### 4. Timing of high-precision APIs The Performance API and `requestAnimationFrame` behave differently when the browser is being driven via CDP, especially when the page is "headless" without a real compositor: - requestAnimationFrame callbacks fire on a precise vsync-aligned cadence in headful (60 Hz typically). In headless, the cadence is software-generated and exhibits a different jitter profile. - performance.now() resolution varies by browser mode and security context. Headless mode can show non-default resolution patterns. Useful as supporting signals, less reliable as primaries — modern stealth tooling does try to spoof the rAF cadence, with mixed success. ### 5. Behavioral baselines vs the population Per-session and per-action baselines that real users vary on but bots don't: - Typing dwell time variance. Real users vary their key dwell-time wildly across keys. Bot scripts don't, even when randomized. - Form-fill order entropy. Real users tab around, click around, edit fields out of order. Bots tend to fill in source-order. - Scroll-event distribution. Real users produce trackpad/mouse-wheel scrolls in characteristic bursty patterns; programmatic scroll is essentially absent or perfectly uniform. - Page-dwell time distribution. Bots exhibit bimodal dwell distributions — either nanoseconds (script raced ahead) or exactly the configured wait time. Real users are continuous. ## What to log per session The minimum useful client-side telemetry, captured before the action you care about (login, signup, checkout): ``` { "input": { "mouseMoveCount": 42, "mouseMoveEntropy": 4.13, "mouseTrajectorySmoothness": 0.78, "touchEventCount": 0, "keyDwellMeanMs": 84, "keyDwellStdDev": 33, "scrollEventCount": 7, "scrollEventEntropy": 2.6 }, "render": { "canvasFingerprint": "f3a9...", "webglRendererHash": "b21c...", "rafJitterMs": 0.42 }, "timing": { "performanceNowResolutionMs": 0.005, "loadTimeMs": 1842 }, "navigator": { "webdriver": false, "languages": ["en-US", "en"], "platform": "Win32", "hardwareConcurrency": 8 } } ``` The first block (input) is by itself a strong-enough signal to power the detection in most cases. The render block is the high-confidence supporting signal. The timing block is a tie-breaker. The navigator block is for the bots who don't bother with stealth plugins — it catches them cheaply and lets you allocate resources to the harder cases. ## Patterns to deploy carefully ### Don't block on a single signal Every individual signal has false positives. Real users on touch-only devices have zero `mousemove` events. Real users with bursty trackpads have low scroll entropy. Real users on integrated GPUs have non-standard canvas signatures. Block on a vector, not a scalar — the joint distribution is what catches automation reliably while keeping false-positive rates under 0.1%. ### Score, then gate Return a 0–1 confidence that this session is automation, then route to actions: - 0.0–0.3: allow. - 0.3–0.6: step-up (CAPTCHA, email confirm, 2FA challenge). - 0.6–0.9: hard challenge or honeypot route. - 0.9–1.0: block, log, blacklist visitorId. ### Beware of headless-Chromium-as-a-service BrowserBase, Browserless, ScrapingBee, and similar providers run hardened headless instances with stealth-grade configurations and rotating residential proxies. They're harder to detect than self-hosted Puppeteer because the operators have invested in fingerprint normalization. The behavioral signals (input entropy, action timing) still catch them; the static-property signals do not. ## How Maskbreak handles this The `device.automation` flag in the evaluate response is a composite that runs the signals above (and ~15 others) in a single client-side SDK with no measurable performance impact. The `device.tampering_score` float catches the harder cases where the automation framework is well-stealthed but the underlying engine is still patched. Combined with `device.antidetect` and the network-level proxy and VPN flags, the joint signal is what the composite scores on; measure the rate on your own traffic rather than trusting a vendor figure. The Free plan (10,000 visitor checks a month, no card) is enough to instrument the highest-value paths — login, signup, checkout, password-reset — and watch the automation signal in production. Most teams find their existing CAPTCHA-only defense was missing 30–60% of real headless traffic. Headless detection isn't a single check anymore. It's a behavioral and rendering-level analysis that has to assume the attacker patched everything cosmetic. The signals that still work in 2026 are the ones the attacker can't patch without rewriting the underlying browser engine — and that's a much harder lift than installing a stealth plugin. ## Update: the layer this post does not cover Everything here operates inside the browser — JavaScript surfaces, automation traces, interaction entropy. There is a second layer that stealth-patching cannot reach, and it has become the more durable signal. A client asserts its identity at several layers at once, and the TLS ClientHello and HTTP/2 settings frame are produced by the build itself, not by anything a patch script sets. So a session claiming a current Chrome version while presenting the cipher ordering of a three-year-old build, or a Go HTTP client's fingerprint, has contradicted itself in a way no amount of JavaScript patching resolves. Note that JA3 specifically stopped being reliable in 2023, when Chrome began randomising ClientHello extension order — plenty of stacks still carry JA3 rules that have not matched since. [JA3, JA4, and TLS fingerprinting](https://maskbreak.com/blog/ja4-tls-fingerprinting) covers what replaced it. ## Questions people ask **Does navigator.webdriver still work for headless detection?** It works for the absolute baseline of automation that doesn't bother to hide. puppeteer-extra-plugin-stealth, undetected-chromedriver, playwright-stealth, and every commercial scraping framework set navigator.webdriver to false at startup. As a single signal it catches less than 5% of real-world automation traffic in 2026. Use it as one bit in a vector, never as a standalone check. **What's the difference between headless and headful Chrome for detection?** Modern Chrome's --headless=new mode renders close enough to headful that surface differences are nearly gone. The remaining gaps are GPU-rendering deltas, missing input device entropy, and some narrow font/audio-context fingerprints. Behavior, not browser-mode probing, is the better axis. **How do I detect Puppeteer with stealth plugin?** Stealth plugins patch the obvious detection surface (navigator.webdriver, window.chrome.runtime, plugin and language inconsistencies) but don't change the underlying behavior of the engine. Detection in 2026 relies on signals stealth doesn't reach: input-event physics, mouse-trajectory entropy, scroll dynamics, and the specific GPU rendering signature of Chromium when controlled via CDP. **Will headless detection block legitimate accessibility tools?** Screen readers (NVDA, JAWS, VoiceOver) and other accessibility tools run inside a real headful browser, not in headless mode, and produce normal input-event streams. Their fingerprint signature is distinct from Puppeteer/Playwright/Selenium and they won't trigger an automation-detected flag in any well-built detector. **Can I detect headless Firefox the same way?** The same signal families can apply to Firefox, but browser-specific baselines differ. Test each supported engine separately and measure false positives rather than applying Chromium thresholds unchanged. **What about headless mode in CI for legitimate testing?** Your own CI never hits the production fraud-detection surface unless someone misconfigured. If it does, the right answer is allow-listing the CI's IP or a dedicated CI header — not weakening production detection. The simplest pattern is to skip the Maskbreak call for allow-listed CI traffic in your own middleware, so test runs never touch the underlying detection. --- # iGaming Bonus Abuse Detection in 2026 URL: https://maskbreak.com/blog/igaming-bonus-abuse-detection Published: 2026-05-06 · Updated: 2026-07-30 > Bonus abuse and free-bet farming cost iGaming operators 4–7% of GGR. The device, ASN, and behavioral signals that catch professional bonus hunters in 2026. Bonus abuse and multi-accounting cost iGaming operators 4–7% of GGR — and the professional bonus-hunter class has fully adopted residential proxies and antidetect browsers. Same operator, same household, 200 unique "customers" each claiming the welcome bonus, each on a different IP, each with a different fingerprint. KYC alone never catches them. The operators who stop the bleed are the ones treating bonus abuse as a device-cluster problem, not an identity problem. This piece is for sportsbook and online-casino fraud, payments, and platform teams. It covers the actual bonus-hunter workflow as we observe it, the regulatory dimension (UKGC, MGA, ARJEL), the signals that work in 2026, and a deployable detection plan that doesn't kill conversion on legitimate first-time depositors. ## What "bonus abuse" actually means in 2026 Three distinct behaviors get bundled under the term, and they need different responses: - Welcome-bonus farming (multi-account). One person, many accounts, each claiming the new-customer bonus. Pure economic loss. Often part of an organized ring with shared payout infrastructure. - Matched betting / bonus-arbitrage. One person, one account, but the user's lifetime value is engineered to be the bonus value minus wagering EV. Legal in most jurisdictions; commercially negative for the operator. - Self-excluded re-registration. A previously self-excluded player creates a new account under a different identity. Regulatory exposure on top of commercial loss — UKGC and MGA both treat failure-to-detect as a licensing concern. The first two are economic problems. The third is a compliance problem with regulator-imposed deadlines for remediation when caught. ## The professional multi-accounting workflow An operationally typical bonus-farming setup, observed in instrumented data: - Identity supply. Synthetic identities (real-but-rented IDs from underground markets) or aged accounts on adjacent KYC-passing platforms. Cost: $15–$60 per identity for tier-1 jurisdictions. - Payment supply. Prepaid cards, cashback debit cards, and increasingly crypto on-ramps that sidestep card-issuer KYC. Some rings use the same card across accounts via aliasing techniques specific to certain prepaid programs. - Browser supply. Multilogin or Kameleo. One unique fingerprint per account: distinct canvas, distinct WebGL renderer, distinct timezone, distinct language preference, distinct font set. - Network supply. Residential proxy pool. Each account assigned a "sticky" residential exit (commercial and peer-to-peer residential networks) for the duration of its lifecycle — sometimes weeks, to make the IP-and-device pair age into looking organic. - Play supply. Either manual (a small team executing wagering) or scripted (Selenium/Playwright with stealth plugins) running the minimum-wagering bet pattern. Slots: minimum bets on low-volatility games. Sportsbook: matched bets against an exchange. - Withdrawal aggregation. The 200 individual withdrawals collapse into a few payout endpoints — bank accounts, crypto wallets, e-wallets — that the ring controls. Step 6 is the single most reliable retroactive signal. Even with perfect device-and-IP separation per account, the bonuses aggregate at the cashout layer. If your fraud team isn't running cashout-clustering retrospectively, you're missing the cleanest disambiguation in the entire stack. ## Why traditional KYC alone fails KYC verifies identity-document-to-real-person. It does not verify this person has not previously played here under a different identity. The gap is structural: - A real ID can be rented for $30–$80 per claim cycle. KYC passes. - Family members, flatmates, and paid identity-rental networks supply real, legally-distinct identities that all live in one household and play through one device. - A self-excluded player using their cousin's ID is invisible to KYC by definition. The cousin is a real, eligible person. Identity-layer defenses must be paired with device-layer defenses. Neither alone is sufficient. ## The signals that catch professional bonus abuse ### 1. Device fingerprint clustering at registration The single highest-yield signal in the entire stack. At signup, capture a stable `visitorId` derived from canvas, audio, WebGL, hardware concurrency, and 100+ other low-entropy signals. Index every account by visitorId. When registration N+1 arrives at a visitorId that already has N accounts, you don't need to know who the user is — you know there are N+1 accounts on one device and only one of them gets the bonus. Threshold heuristics that work: - visitorId with 1 account → allow, normal first-time depositor. - visitorId with 2 accounts, different KYC, different timezone-of-play → allow but flag for monitoring (likely household). - visitorId with 3+ accounts → bonus-eligibility is for the first account only. Subsequent accounts allowed to play with own money but not eligible for promotional offers. - visitorId with 5+ accounts in any 90-day window → operationally an abuse ring. Block bonus claims, freeze pending bonus withdrawals, queue for fraud-team review. ### 2. Antidetect browser detection Multilogin, Kameleo, GoLogin, AdsPower, and Dolphin{anty} are not used by legitimate iGaming customers. Detection of any of these at the registration or deposit surface is extremely strong evidence of bonus-farming intent. [How to detect antidetect browsers in 2026](https://maskbreak.com/blog/detect-antidetect-browsers-2026) covers the technical signals; for iGaming specifically, the false-positive rate of antidetect detection on legitimate first-time depositors is essentially zero. ### 3. Residential proxy detection Legitimate iGaming customers in regulated jurisdictions almost never connect through residential proxies. Geolocation-restriction-bypass via VPN does happen for casino/sportsbook customers in restrictive jurisdictions, but a residential-proxy signal can be relevant but should not be treated as proof of fraud without device, account, payment, and safer-gambling context. [The complete guide to residential proxy detection](https://maskbreak.com/blog/residential-proxy-detection-guide-2026) covers the ASN and device signals. ### 4. Payment-instrument clustering Hash payment instruments (BIN + last4 + expiry tuple, hashed-and-truncated cardholder name) and cluster across accounts. Distinct accounts depositing from the same hashed instrument are a multi-account ring with high specificity. The corresponding signal at withdrawal — distinct account payouts to the same IBAN, same crypto wallet, same e-wallet email — is the cleanest cashout-cluster signal. ### 5. Behavioral play-pattern matching Self-excluded re-registration specifically: the original excluded account has a behavioral baseline (game preferences, average bet size, session duration distribution, pattern of wagering vs. cashout). When a new account from a different identity but the same device starts producing the same baseline, that's the same player. This is the regulatory-defensible signal: a UK/Malta regulator inquiry will accept "device match + behavioral match" as actionable evidence; "device match alone" is sometimes contested. ## The detection stack, deployed A working production order: - Registration: capture visitorId, run POST /v1/evaluate to get residential-proxy, antidetect, automation, and risk-score signals. Block clear-fraud (antidetect + residential proxy combination, automation detected) at registration. Flag medium-risk for downstream gating. - Deposit: re-evaluate. New device since registration → step-up. Antidetect now appearing → freeze deposit, manual review. - Bonus claim: check visitorId against the index of prior bonus-claiming accounts. If the device has previously claimed a welcome bonus on any account, block the claim with a "bonus already claimed on this device" message. Hash-clustered payment instrument matches against prior bonus claims also block. - Wagering and play: behavioral-baseline collection. Establish per-user norms within the first 30 sessions. Used downstream for re-registration detection and for matched-betting flagging. - Withdrawal: cashout cluster lookup. Three accounts paying out to the same crypto wallet in 60 days → pause all three pending review. - Self-exclusion event: hash and persist the visitorId, the device profile, the payment-instrument cluster, and the behavioral baseline. On every future registration, cross-check. ## Bonus-claim policy that actually works The bonus-claim block is the highest-value lever. Policies we've seen work in production: - Bonus eligibility is per-device, not per-account. One welcome bonus per device (visitorId). One reload bonus per device per offer cycle. Legitimate household sharing collapses cleanly into this — most households have one primary gambler, and the secondary gambler can play without a bonus or claim a smaller "second-account bonus" with stricter wagering. Most bonus-farming rings break completely. - Bonus eligibility is per-payment-instrument cluster. One welcome bonus per BIN+last4+holder-name cluster. Catches the common "rented prepaid card pool" pattern. - Step-up before bonus credit. Identity confirmation (selfie + ID, or banking ID where available) before the bonus is credited, not before the account is created. This shifts friction to the moment-of-claim, not registration — better signup conversion, better fraud filtering. - Bonus-cap by risk score. The full welcome bonus available to risk-score < 30. Reduced offer for 30–60. No promotional offer for > 60 (account allowed to play with own funds only). ## Regulatory dimension UK Gambling Commission, Malta Gaming Authority, and ARJEL (France) all impose specific requirements on detecting self-excluded re-registration. The required posture is "reasonable steps", not perfection — but "reasonable" has been interpreted in recent enforcement actions to include device-fingerprinting where it's commercially available. Operators relying solely on identity-document checks have been fined; operators with documented device-and-behavioral controls have generally not been. The defensible audit trail when an inquiry lands: a re-registered self-excluded player flagged at signup by visitorId match, escalated to manual review, and either blocked at signup or blocked at first deposit. Showing the regulator the exact event log with the device-match signal and the timestamp of intervention is the cleanest possible defense. ## How Maskbreak fits The `POST /v1/evaluate` endpoint returns the relevant signals in one server-side call: - visitorId — stable device identity for cluster indexing. - residentialProxy, vpn, tor, dch — network-layer flags. - antidetectBrowser + antidetectProduct — Multilogin/Kameleo/GoLogin/Dolphin{anty}/AdsPower flags. - browserTampering — float 0–1 catching the cookie-import / fingerprint-spoof case. - automationDetected — Selenium/Puppeteer/Playwright detection at the registration or wagering surface. - riskScore — 0–100 composite for the simplest possible "block / step-up / allow" gate on bonus claims. The Free plan (10,000 visitor checks a month) is enough to start instrumenting an iGaming registration and deposit surface; paid plans raise the allowance from €29 a month. The typical instrumented finding in the first 30 days is 3–5× more bonus-abuse rings than the operator's existing internal heuristics were catching. Bonus abuse is solvable. The operators who solve it are the ones who stop treating it as a one-account-at-a-time identity problem and start treating it as a device-cluster + cashout-cluster problem. The signals exist. The integration is one API call. The economic return on the first month of deployment is, for most mid-tier operators, larger than the entire annual fraud budget. ## Update: make promotions the strictest gate you have One recommendation is worth sharpening in light of agent traffic. Across every vertical, promotion and bonus redemption is where losses concentrate, and it is also the action with essentially no legitimate automated use case. That combination makes it the right place for your hardest rule — harder than signup, harder than login. Reads should stay open and queries should be rate-limited, because an assistant reading your offers page may be carrying a real customer. An assistant redeeming a bonus from a device that has redeemed four already is not a customer at all. [The decision guide](https://maskbreak.com/blog/should-you-block-ai-agents) sets out the action-by-action mapping, and the device-linking argument above is what makes the fourth redemption visible. ## Questions people ask **What is bonus abuse in iGaming?** Bonus abuse is the systematic exploitation of operator promotions — sign-up bonuses, free spins, free bets, deposit-match offers, cashback — by users who have no intent to play organically. The professional version is multi-account: the same person creates 50–500 accounts, claims the welcome bonus on each, runs the minimum wagering requirement, and withdraws. Each individual account looks valid. The cluster is the fraud. **How much does bonus abuse cost iGaming operators?** Industry data converges on 4–7% of gross gaming revenue (GGR) lost to bonus abuse and multi-accounting at typical operators. For a casino doing $50M GGR/year, that's $2–3.5M of effectively zero-margin marketing spend. At sportsbooks running larger acquisition bonuses, the loss percentage runs higher during major events. **Can I use IP address to detect multi-accounts?** No. Professional bonus hunters route every account through a separate residential proxy exit. Same household, same building, but every account claims a different IP, often a different country. IP-based duplicate detection catches the absolute beginners and nothing else. The reliable signal is device fingerprinting, not IP. **How do I detect self-excluded players re-registering?** A self-excluded player creating a fresh account with a different name and a different email is invisible to KYC alone (the new identity may be a real person — a family member, a flatmate, a paid identity-rental). Device fingerprinting plus behavioral baselining catches this: the device, browser, mouse-movement patterns, and play-style cluster all match the excluded account. **What are matched-betting operators, and should I block them?** Matched betting is a form of bonus abuse where the user covers all outcomes on an event using a sportsbook's free bet plus an exchange lay bet, locking in the bonus value as profit. It's legal but operators consistently lose money on these users. Most operators allow first-bonus arbitrage but flag the device cluster afterward to suppress further promotional offers, rather than blocking outright. **Will device detection block legitimate shared-device cases?** Two real customers from one household using the same iPad to play occasionally is common and should not be blocked. The right model is risk-tiered: shared device with shared payout method and shared play patterns is a multi-account ring; shared device with distinct payout methods, distinct timezones of play, and distinct game preferences is a household. Use the cluster signal to gate bonuses, not core gameplay. --- # Tor Exit Node Detection in Real Time URL: https://maskbreak.com/blog/tor-exit-node-detection Published: 2026-04-29 · Updated: 2026-08-30 > Match the address your edge saw against the Tor Project's observed exit list, refreshed hourly, and step up on account routes instead of blocking reads. - Match observed exit addresses, not relay counts: 3,312 ExitNode records resolved to 1,427 addresses in our 2026-08-29 snapshot. - A daily copy is stale by design: the file's observation timestamps spanned 40 hours; refresh hourly and never replace with an empty fetch. - Route on decision and reasons: a Tor-only hit returns decision: block with tor_exit_node and anonymous_network; its risk_score of 75 only sorts a queue. - network.residential reads true on a Tor exit; it describes the route, never a clearance. - A missing Sec-CH-UA, an ESR TLS hash and a 200 by 100 window bucket are Firefox tells, not Tor tells. Tor is the one anonymizing network that publishes its own address list. The Tor Project's [bulk exit list](https://check.torproject.org/torbulkexitlist) is a plain text file, one IPv4 address per line, so the check looks like a set lookup, and most teams ship that: a cron job, a daily copy, a firewall rule. That version misses exits that came up after the fetch, keeps ones that went away, counts relays where it should count addresses, and blocks the readers the Tor Project's own abuse FAQ says to sort at the application layer. This playbook is the check we run instead: the published list plus our own network intelligence, refreshed on a clock, read at the route where the decision is made. ## How Tor traffic reaches your stack Tor is not a fraud tool, but it is a free way to make every request arrive from an address that is not yours; each step is in the [tor manual](https://manpages.debian.org/testing/tor/tor.1.en.html) (checked 2026-08-29). - Run a client. Tor Browser for manual account work; the tor daemon for scripts, a SOCKS proxy on port 9050 by default that curl --socks5-hostname, Python requests and Playwright's proxy option all speak. - Pin the exit country. ExitNodes {us} in torrc restricts exits to one country; StrictNodes 1 stops Tor falling back to others, so stolen US credentials arrive from a US exit and trip no geography rule. - Rotate. A circuit is reused for ten minutes by default (MaxCircuitDirtiness); the controller signal NEWNYM switches to clean circuits on demand, and the [control spec](https://spec.torproject.org/control-spec/commands.html) says Tor may rate-limit it. Every rotation is a new exit address for the same operator. - Enter through the routes that matter. The request reaches your edge from the exit relay's address, on the same routes as any [account takeover run](https://maskbreak.com/blog/account-takeover-prevention-that-holds-up): login, password reset, signup, payout. ``` # torrc: US exits only, fresh circuit after 60 s ExitNodes {us} StrictNodes 1 MaxCircuitDirtiness 60 SocksPort 9050 # the request your login route receives curl --socks5-hostname 127.0.0.1:9050 https://example.com/login \ -d 'email=victim@example.com&password=Summer2026!' ``` The destination sees the exit relay, never the client, and abuse complaints go to the relay operator ([types of relays](https://community.torproject.org/relay/types-of-relays/), checked 2026-08-29). You cannot push the cost upstream, only decide what an exit address may do on your site. ## Why a daily copy of the exit list misses it The Tor Project also publishes [exit-addresses](https://check.torproject.org/exit-addresses), the file the bulk list is built from: one record per exit relay, each with timestamped `ExitAddress` lines naming the address its scanner saw traffic leave from. We fetched both files at 18:59 UTC on 2026-08-29 and counted them with `wc` and `awk`. The observation timestamps ran from 02:34 UTC the previous day to five minutes before the fetch: a copy taken yesterday morning misses every address confirmed since and still carries some the scanner has not seen for a day. Relays are not addresses. The same fetch held 3,312 `ExitNode` records but 1,427 distinct addresses, and the bulk list was those 1,427 exactly. Tor Metrics counted 3,272 relays with the Exit flag on 2026-08-27 ([relay flags](https://metrics.torproject.org/relayflags.html), CSV checked 2026-08-29). More than two exit relays share an address on average, so a relay count overstates what you have to match. One fingerprint had three `ExitAddress` lines, three distinct addresses; the format allows it, so match the observed-address file. Not every listed exit can reach you. Each relay carries an exit policy, and `reject *:*` relays only inside the network ([exit policies](https://support.torproject.org/relays/legal-and-abuse/exit-relay-abuse/), checked 2026-08-30); since March 2020 the list no longer filters by policy ([exit list service change](https://blog.torproject.org/changes-tor-exit-list-service/)), so the raw count overstates your exposure. And check the address your edge saw, never a forwarded header, or anyone can write a Tor verdict for someone else's address. Bridges do not change this. A bridge is a "non-public Tor relay" kept out of the directory so ISPs and governments cannot block them all ([what is a bridge](https://support.torproject.org/relays/getting-started/what-is-a-bridge/)), and obfs4 is "a pluggable transport that makes Tor traffic look random" ([Tor glossary](https://support.torproject.org/glossary/); both checked 2026-08-30). Both hide the first hop from the client's own network; the traffic still leaves through a listed exit relay. An earlier version of this post said bridge users bypass exit lists. They do not: what is undetectable by design is the bridge's address, which never reaches you. Two last gaps. The list we fetched held no IPv6 addresses, so a v6 exit is a miss for the list alone. And a firewall rule blocks reading as well as writing, which the Tor Project's abuse FAQ argues against, recommending "application-level decisions to separate the legitimate users from the jerks" and noting that hundreds of thousands of people use Tor every day for ordinary data hygiene ([banning Tor](https://support.torproject.org/abuse/ban-tor/), checked 2026-08-30). ## The tells Our verdict resolves Tor from two inputs: the Tor Project's published exit list, refreshed every four hours and never replaced with an empty fetch, and our own network intelligence, which classifies the connection independently of the list's IPv4-only format. Either sets `network.tor` and adds `tor_exit_node` to `reasons`. TellVerdict field / reason codeWeight Address on the current exit list, or classified as Tor by our network layer`network.tor: true`, `network.service: "TOR"`, `tor_exit_node`Step-up on account routes; block on cash-out Anonymizing layer with no named VPN or proxy`network.anonymous: true`, `anonymous_network`Evidence Tor exit plus a device seen for the first time`tor_exit_node` with `device.times_seen: 1`Step-up Tor exit plus a device already linked to other accounts`device.linked_accounts`, `multi_account_device`Block on signup, referral and bonus routes Tor exit plus a spoofed or automated browser`antidetect_browser`, `automation_detected`Block on any route Resist-fingerprinting settings in the browser`device.privacy_mode: true`Evidence only; we have not run Tor Browser on our bench Browser clock disagrees with the exit country`timezone.checked: false`None; expected on Tor and not raised Exit reads as a home line`network.residential: true`None; means neither datacenter nor proxy, so a Tor exit reads residential The last row is the trap: `network.residential` describes the route, not the risk, and a rule that treats residential as safe waves Tor through (the [residential proxy guide](https://maskbreak.com/blog/residential-proxy-detection-guide-2026) says the same of proxy exits on consumer lines). ### Three things that are not Tor tells An earlier version of this post listed browser-side tells that do not hold. Its header-ordering and session-shape tells are gone, unsourced and unmeasured; these three are corrected. A request without `Sec-CH-UA` is a Firefox or Safari request, not a Tor request. Client hints are a Chromium feature: MDN's compatibility data lists Chrome 89 and marks Firefox and Safari as not supported ([Sec-CH-UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA), checked 2026-08-30). Tor Browser inherits the absence from Firefox. Tor Browser's TLS handshake is Firefox ESR's. Tor Browser 15.0 is "our first stable release based on Firefox ESR 140" ([release notes](https://blog.torproject.org/new-release-tor-browser-150/), 2025-10-28). A JA4 hash that matches Firefox ESR tells you the engine; we have not measured a difference between Tor Browser and ESR on our bench and do not treat an ESR hash as a Tor signal (see the [JA4 explainer](https://maskbreak.com/blog/ja4-tls-fingerprinting)). The window is rounded to multiples of 200 by 100 pixels, not 1000 by 1000. Tor Browser "starts with a content window rounded to a multiple of 200px x 100px" and buckets the operating system to Windows 10, OS X 10.15 or "Linux running X11" ([fingerprinting protections](https://support.torproject.org/tor-browser/features/fingerprinting-protections/), checked 2026-08-30). That fits Tor Browser and Firefox with resist-fingerprinting on; on its own it is evidence for `device.privacy_mode`, nothing more. ## Where the check goes Server side, on the address your edge attributes to the client, in the route handler, before the side effect. `GET /v1/lookup/{ip}`, the [IP reputation API](https://maskbreak.com/ip-reputation-api), covers log enrichment and allowlist screening on a bare address; `POST /v1/evaluate` with the SDK token covers live visits, plus the device layer when you forward `fingerprintEventId`; both request shapes are in the [API reference](https://maskbreak.com/api). In the browser, `Sentinel.collect()` returns that token and event id — the SDK keeps Sentinel, the product's original name, as its global. The decision point is one branch on `reasons`, per route class. ``` // Express: one evaluation, three route classes. // Read-only routes never call this; cash-out routes always do. const CASH_OUT = new Set(['/payout', '/withdraw', '/cards/add', '/kyc']); async function screen(req, res, next) { const r = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { 'Authorization': 'Bearer sk_test_YOUR_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ token: req.body.token, // from Sentinel.collect() fingerprintEventId: req.body.fingerprintEventId, accountId: req.user ? req.user.id : undefined }) }).then(r => r.json()); const tor = r.reasons.includes('tor_exit_node'); const device = r.reasons.some(x => x === 'antidetect_browser' || x === 'automation_detected' || x === 'multi_account_device'); if (tor && (CASH_OUT.has(req.path) || device)) { return res.status(403).json({ error: 'action_unavailable' }); // block } if (tor || r.decision !== 'allow') { req.stepUp = true; // review } req.verdict = r; // log decision + reasons next(); } ``` The response this branches on, from the public sandbox on 2026-09-25 with `sk_test_sandbox` and the `test_tor` token (the legacy `status`, `isSuspicious` and `details` fields trimmed): Verdict ``` {"test":true,"sandbox":true,"decision":"block","risk_score":75,"ip":"203.0.113.99","country":null,"network":{"vpn":false,"proxy":false,"datacenter":false,"anonymous":true,"tor":true,"residential":true,"service":"TOR"},"reasons":["tor_exit_node","anonymous_network"],"evaluated_in_ms":1} ``` `decision` is `block`: Tor is a hard signal by default. Route on `decision` and `reasons`, not on `risk_score`: the 75 is the Tor weight (60) plus the anonymous-network weight (15), and as the [thresholds reference](https://maskbreak.com/blog/risk-score-thresholds) puts it, the decision is the verdict and the score sorts a review queue. For `review` on a bare Tor hit, set the `tor` rule to review in the dashboard Rules tab. The rule changes `decision` for Tor alone: a proxy, automation or a fake browser on the same visit still blocks, and `reasons` still lists `tor_exit_node`. ### Keep your own copy of the list Fetch the list yourself to audit any vendor's Tor verdict, ours included, and to stay covered when a provider is unreachable. This script keeps the previous snapshot and prints what changed, so churn is a number you log. ``` #!/usr/bin/env bash # Fetch the Tor exit list, diff it against the last snapshot, keep both. set -euo pipefail dir=${TOR_LIST_DIR:-/var/lib/tor-exits} mkdir -p "$dir" new="$dir/exits.$(date -u +%Y%m%dT%H%MZ).txt" curl -fsS --max-time 30 -A 'exit-list-sync/1.0 (ops@example.com)' \ https://check.torproject.org/torbulkexitlist | sort -u > "$new" # Never replace data with nothing: an empty fetch is a failed fetch. [ -s "$new" ] || { rm -f "$new"; echo "empty list, keeping previous" >&2; exit 1; } if [ -e "$dir/current.txt" ]; then added=$(comm -13 "$dir/current.txt" "$new" | wc -l) removed=$(comm -23 "$dir/current.txt" "$new" | wc -l) echo "$(date -u +%FT%TZ) total=$(wc -l < "$new") added=$added removed=$removed" fi ln -sf "$new" "$dir/current.txt" # Lookup: grep -qxF "$ip" /var/lib/tor-exits/current.txt ``` Run it hourly, one fetch per fleet, served from your own store. Our feed refreshes every four hours with a random offset of up to ten minutes so a fleet does not hit the Tor Project on the same minute. ### Test it ``` # 1. The deterministic Tor shape, no account needed curl -s -X POST https://maskbreak.com/v1/evaluate \ -H 'Authorization: Bearer sk_test_sandbox' \ -H 'Content-Type: application/json' \ -d '{"token":"test_tor"}' # expect: "decision":"block" and "tor_exit_node" in reasons # 2. A real exit, with your own test key: the first ExitAddress # in https://check.torproject.org/exit-addresses right now ip=$(curl -s https://check.torproject.org/exit-addresses | awk '/^ExitAddress/{print $2; exit}') curl -s "https://maskbreak.com/v1/lookup/$ip" \ -H 'Authorization: Bearer sk_test_YOUR_KEY' # expect: "verdict":"block", "risk_score":90, "signals":{...,"tor":true,...} ``` On 2026-08-30 the free [IP lookup](https://maskbreak.com/ip-lookup) on `171.25.193.25`, then the first address in the file, returned `verdict: block`, `risk_score: 90`, `signals.tor: true`. It will have rotated by the time you read this, which is why the script reads the live file. ## Response ladder This is the part most teams get wrong. Tor is used legitimately by journalists, activists, security researchers, abuse-survivors looking for help, and people in countries with surveillance that makes plain-text browsing unsafe. Blanket-blocking Tor at the network layer punishes them. It also visibly signals to attackers that you're a soft target who responded to a single signal. Better policy patterns: - Allow read-only access from Tor. Browsing your marketing site, blog, and docs from Tor should work. There's no fraud risk. - Step up auth, don't block, on signup and login. A Tor visitor signing up should clear an extra friction layer (email + phone, or device-bound passkey) rather than be rejected outright. This filters spam without locking out legitimate privacy users. - Block Tor on payment, withdrawal, KYC. Tor for cash-out is almost always fraud. Tor for browsing is usually fine. - Use Tor as one signal of N, never on its own. Tor + new account + datacenter card BIN + tampered browser fingerprint is a clear block. Tor alone, on a 12-month-old account in good standing, is not. Mapped onto the verdict: RungRoutesEvidence requiredWhat the user sees AllowPages, docs, search, public profilesNone. Do not call the API on read-only routesNothing ReviewSignup, login, password reset, profile changes`tor_exit_node` alone, or with `device.times_seen: 1`; no device reason codeA second factor; the same response shape as the clean path BlockPayout, withdrawal, card add, KYC, referral payout`tor_exit_node` on a cash-out route; or `tor_exit_node` with `antidetect_browser`, `automation_detected` or `multi_account_device` on any routeA generic unavailable message, never a Tor-specific one Keep the review response byte-identical to the clean one until the second factor is issued, so an operator cannot tell the exit was recognized (the [credential stuffing playbook](https://maskbreak.com/blog/credential-stuffing-detection) shows the constant-shape response). Keep the reason codes with the event: a reviewer a week later needs `tor_exit_node` next to the timestamp, and [ExoneraTor](https://metrics.torproject.org/exonerator.html) "answers the question whether there was a Tor relay running on a given IP address on a given date". ## What it costs you The cost of over-blocking is the population you turn away. Tor Metrics estimated about 3.3 million daily users on 2026-08-27 ([users by country](https://metrics.torproject.org/userstats-relay-country.html), CSV checked 2026-08-29; Tor Metrics revises the estimate as more relays report, so the exact figure moves between fetches); a firewall rule removes all of them from your reading traffic to stop the fraction that would reach a cash-out route. The cost of stepping up is the challenge. Twilio Verify lists $0.05 per successful verification plus $0.0083 per SMS in the United States ([Verify pricing](https://www.twilio.com/en-us/verify/pricing), checked 2026-08-30; other countries differ). Worked model, inputs stated: one hundred Tor-exit signups a day, each stepped up by one successful US SMS, cost about $5.83 a day at list price, the price of not turning away a signup that might be a journalist. The cost of abuse lands on you: complaints go to the relay operator ([types of relays](https://community.torproject.org/relay/types-of-relays/)), so there is no upstream to charge back to, and whatever leaves through a payout from a Tor exit is gone. That is why the rung is a block, and why the [account takeover](https://maskbreak.com/blog/account-takeover-prevention-that-holds-up) flow puts the evaluation before the password compare, not after the withdrawal. ## Checklist - Check the address your edge attributes to the client, never a forwarded header. - Match against observed exit addresses; keep a dated snapshot so churn is a logged number. - Refresh hourly from your own store, keep the previous list on an empty fetch, and pair it with network intelligence for IPv6. - Route on decision and reasons, not on the legacy isSuspicious flag; risk_score is a sort key. - Never read network.residential: true as a clearance; it is true on a Tor exit. - Skip the API on read-only routes, step up on account routes, block on cash-out routes. - Keep Firefox tells (a missing Sec-CH-UA, an ESR TLS hash, a 200 by 100 window) out of Tor rules. - Log reason codes with the event under the retention you declare (IP addresses are [personal data under GDPR](https://maskbreak.com/blog/is-an-ip-address-personal-data)), and keep Tor policy separate from [VPN detection](https://maskbreak.com/blog/free-vpn-detection-api); the other [playbooks](https://maskbreak.com/blog/playbooks) cover the attacks Tor is used to run. ## Questions people ask **Is it legal to detect Tor exit nodes?** The Tor Project publishes the exit list and the exit-addresses file for this use, and identifying that a request came from a listed exit is a lookup on public data. What you do with it is the policy question. An IP address is still personal data under GDPR, so log the reason code under the retention you already declare. **Should I block all Tor traffic?** No. Allow reads, step up on signup, login and password reset, and block on payout, withdrawal and KYC. The Tor Project's own abuse FAQ recommends application-level decisions and multi-tiered access over a network block, and a firewall rule turns away every reader to stop the fraction that would ever reach a cash-out route. **How often does the Tor exit node list change?** Continuously. In our 2026-08-29 snapshot the ExitAddress observation timestamps spanned about 40 hours, from 02:34 UTC the previous day to five minutes before the fetch. A copy from yesterday morning misses every exit confirmed since. Refresh hourly, keep the previous snapshot, and treat an empty fetch as a failure. **Can Tor bridges be detected by IP address?** The bridge cannot: bridges are non-public relays kept out of the directory, and obfs4 disguises the client's connection to them. But a bridge is only the first hop. The traffic still leaves the network through an exit relay, and the exit address is what your server sees and what the published list carries. **What does the Maskbreak API return for a Tor exit?** On a network-only evaluation the sandbox returns decision: block, network.tor: true, network.service: "TOR" and reasons ["tor_exit_node", "anonymous_network"], with risk_score 75 (Tor 60 plus anonymous network 15). network.residential also reads true, because it means neither datacenter nor proxy. Route on decision and reasons, not on the score. --- # Ticketing Bot Detection: Stop Scalpers in 2026 URL: https://maskbreak.com/blog/ticketing-bot-detection Published: 2026-04-22 · Updated: 2026-10-29 > Sneaker drops, concert tickets, and limited releases vanish in seconds because bots beat humans to checkout. Here's how to actually stop them. Every Taylor Swift drop, every Yeezy release, every PS5 restock turns into the same scene: thousands of items gone in 90 seconds, immediately listed on StockX or eBay at 4×. The buyers are not your fans. They're 12 GPUs in a Romanian data center renting residential proxies and antidetect browsers. If you sell anything that's both scarce and resold for profit — concert tickets, limited sneakers, console restocks, designer drops, NFT mints, presale slots — you have a bot problem. And if your defense is "we have reCAPTCHA on the cart page," you don't have a defense. The [reCAPTCHA alternatives](https://maskbreak.com/alternatives/recaptcha) worth testing are compared here. ## How modern ticketing & drop bots actually work The "drop bot" software market is professional. Tools like AIO Bot, Cybersole, Wrath, Stellar AIO, and Soleslayer cost $200–$1,200/year and ship with active Discord support. They're optimized for exactly two things: speed of checkout, and evading exactly the kind of defenses you've been told to install. A typical drop run looks like this: - Pre-positioned tasks — the operator queues 200–2,000 "tasks" pointing at your specific product URL. Each task is a separate session with a unique fingerprint. - Residential proxy assignment — each task pulls a fresh US residential IP from BrightData, Smartproxy, IPRoyal, or NetNut. From your access logs, every request looks like a different home Comcast user. - Antidetect browser session — Kameleo or GoLogin gives each task a unique canvas hash, WebGL renderer, audio fingerprint, timezone, and screen resolution. Browser-fingerprint matching gives you nothing. - Captcha solver pre-warmed — 2Captcha and CapSolver hold a queue of solved tokens. The bot does not "solve" your captcha; it pastes one in 0.4 seconds. - Coordinated burst at T-0 — at the second the drop opens, all 2,000 tasks attempt checkout simultaneously. From your servers' point of view, you got a flash flood of legitimate-looking US residential users. The brutal math. If you list 1,000 units and a single operator has 2,000 tasks running, that operator's expected take is 30–60% of your inventory. Add five other operators competing and your real fans get nothing. They go on Twitter and blame you. ## Why traditional defenses don't work here ### reCAPTCHA / hCaptcha Cost to solve a reCAPTCHA v2 in 2026: $0.0006 in 9 seconds via 2Captcha. For a $400 ticket marked up to $1,200, an operator can spend $0.06 on captcha solving per attempt and still net $799.94. CAPTCHAs are a tax on real users at this point. (Long version: [bot detection without CAPTCHA](https://maskbreak.com/blog/bot-detection-without-captcha).) ### IP rate-limiting Every single request comes from a different residential IP. A blanket per-IP limit blocks zero bots and blocks plenty of real users behind shared NAT (university campuses, mobile carriers, corporate VPNs). Negative signal-to-noise. ### Account-age requirements Bot operators farm aged accounts months in advance. There's a whole subculture on the BlackHatWorld and Nulled forums dedicated to it. A drop bot's account pool is older than yours. ### Browser fingerprinting (canvas / WebGL / audio) This was the answer in 2020. In 2026, antidetect browsers rotate every fingerprint surface per session. The Kameleo "profile" you're trying to identify is gone after one purchase. ## What actually works in 2026 Stopping drop bots requires signals that survive residential-proxy rotation and per-session fingerprint rotation. Three categories: ### 1. Behavioral signature of automation No human can fill a 6-field checkout form in 280ms. No human moves the cursor in a perfectly straight line from product card to "Add to Cart". No human's scroll velocity has zero jitter. Drop bots overwhelmingly do all three. Behavioral analysis costs nothing for real users (it's passive) and is extremely expensive for bots to fake convincingly. ### 2. Network reputation beyond IP Even when residential proxies hide the data-center origin of a request, the proxy provider is identifiable. The exit IP belongs to a known BrightData range, or shows up in 47 different account signups in the last hour, or has a TLS JA3 fingerprint inconsistent with the User-Agent it's claiming. Per-IP reputation fails. Per-network-pattern reputation works. ### 3. Persistent visitor identity The single most useful signal is: "is this the same browser session that already attempted checkout 14 times in the last 60 seconds, despite each attempt coming from a different IP?" A persistent visitor ID survives incognito mode, IP changes, and most fingerprint rotation. With it, you stop counting requests and start counting sessions. The bot operator's 2,000 tasks become 2,000 visitor IDs, and you can rate-limit those. ## How Maskbreak handles ticketing & drops Maskbreak is built for exactly this case. Every check returns the network flags, and the device fields whenever the browser check ran: - Bot / automation flag — Puppeteer, Playwright, Selenium, headless Chrome. - Antidetect browser flag — Kameleo, GoLogin, AdsPower, Multilogin, Dolphin, Octo. The "real Chrome with fake fingerprint" tier. - Proxy flag — separate from the VPN flag, residential pools included: an exit already tied to a known commercial or peer-to-peer proxy pool returns network.proxy: true and a block. - Persistent visitor ID — single stable identifier across IP rotation and incognito windows. - Device history — device.times_seen (lifetime sightings of the visitor ID) and device.linked_accounts; key your own short-window attempt counter on device.visitor_id for drop-day velocity. The full evaluation is one server-side call, and each response reports its own processing time. You can call it from your edge worker before the cart endpoint even fires. ## Integration: a checkout-protected drop Add the script to the page with the Buy form, and put `class="monocle-enriched"` on the `` itself. The script then adds three hidden fields to the form in the background: `monocle` (the network token), `sentinel_fp` (the browser check) and `sentinel_tz` (the time zone). They arrive a second or two after the page loads, so a checkout posted sooner carries only what has arrived. In watch mode the server below still sends the check, and the answer says which half was missing; in enforce mode such a checkout is held for verification. ```
``` A cart your JavaScript submits (React, Vue, a custom drop page) sends what `Sentinel.collect()` returns instead, already under the API’s names. A blocked or missing script never holds the button: ``` const evidence = window.Sentinel ? await window.Sentinel.collect() : {}; // evidence = { token, fingerprintEventId, tz }: send it with the cart request. ``` On your backend, the gate runs in front of `POST /api/cart/checkout`. It starts in watch mode: every checkout is checked and logged, and nothing is refused. Set `MASKBREAK_MODE=enforce` once the log lines match what you see in the console’s Events, well before the drop rather than during it. `countRecentAttempts` and `existingCheckoutHandler` are yours: ``` // Server-side only. Node.js 18+ (fetch and AbortSignal.timeout). // 'watch' (default): check every checkout, log what enforce would do, always continue. // 'enforce': stop block; hold review, missing evidence and errors. const MASKBREAK_MODE = process.env.MASKBREAK_MODE || 'watch'; app.use(express.json({ limit: '16kb' })); app.use(express.urlencoded({ extended: false, limit: '16kb' })); app.post('/api/cart/checkout', async (req, res, next) => { const body = req.body || {}; // Form fields -> API fields: monocle -> token, sentinel_fp -> fingerprintEventId, // sentinel_tz -> tz. Sentinel.collect() already returns the API names. const token = body.token || body.monocle; const fingerprintEventId = body.fingerprintEventId || body.sentinel_fp; const tz = body.tz || body.sentinel_tz; const missing = typeof token !== 'string' || !token || typeof fingerprintEventId !== 'string' || !fingerprintEventId; let result = null, hold = null, monthUsedUp = false; // Watch mode sends the check even with a field missing, so the dashboard // can say which half did not arrive. Enforce mode holds it without a call. if (!missing || MASKBREAK_MODE !== 'enforce') { try { const response = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', signal: AbortSignal.timeout(5000), headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ token, fingerprintEventId, tz }) }); if (!response.ok) { const refusal = await response.json().catch(() => null); // The month's checks are used up: let the checkout through unchecked // until the 1st (00:00 UTC) and log it, as watch mode does. if (response.status === 429 && refusal?.code === 'monthly_quota_exceeded') monthUsedUp = true; else throw new Error('Evaluation unavailable'); } else { result = await response.json(); if (!result || !['allow', 'review', 'block'].includes(result.decision) || result.test || result.sample || result.sandbox) { throw new Error('No production verdict'); } if (result.decision === 'block') { hold = [403, 'Request declined.']; } else if (result.decision === 'review' || result.degraded || !result.device) { hold = [409, 'Verification required.']; } } } catch { hold = [503, 'Verification unavailable. Try again later.']; } } if (missing) hold = [409, 'Verification required.']; // enforce never trusts half a check // Drop-day velocity: your own short-window counter (a Redis INCR with a // 60 s expiry), keyed on the visitor ID, and only when the browser check // returned one: without it, every buyer would share a single key. const visitorId = result?.device?.visitor_id; let attempts = 0; if (typeof visitorId === 'string' && visitorId) { try { attempts = await countRecentAttempts(visitorId); } catch { /* counter down: no limit */ } } if (!hold && attempts > 8) hold = [429, 'Too many attempts. Try again in a minute.']; // One line per check. Never log the key, browser tokens or form data. console.log('[maskbreak]', JSON.stringify({ mode: MASKBREAK_MODE, decision: result?.decision ?? null, reasons: result?.reasons ?? null, month_used_up: monthUsedUp, attempts, enforce_would: hold ? 'return ' + hold[0] : 'continue' })); if (MASKBREAK_MODE === 'enforce' && hold) { // Nothing is reserved for a refused or held checkout. return res.status(hold[0]).json({ error: hold[1] }); } return next(); // Watch, or a passed gate: your existing handler reserves the inventory. }, existingCheckoutHandler); ``` Note the layered policy. The decision already blocks a proxy, automation, an emulator and a fake or tampered browser, and asks for review on a VPN alone: plenty of real fans use NordVPN, so a review sends them to your verification step, never to a refusal. A checkout that arrived without the browser check is held the same way, and that is where a bot posting straight to the cart endpoint ends up. The attempt counter is yours — key it on `device.visitor_id`, which stays stable across the IP rotation and incognito windows drop bots rely on. An allowed visitor past eight attempts in a minute is told to try again. ## What changes after deployment After deployment, track these outcomes against a comparable event or holdout cohort: - Suspected automation share of inventory — compare completed purchases, challenged sessions, and later cancellations. - Real-user complaints and challenge abandonment — verify that stricter controls do not punish legitimate fans. - Purchase concentration — measure how many units cluster by device, payment instrument, address, and account group. - Server load at T-0 — reject high-confidence automation before inventory reservation while preserving a safe retry path. ## Get started Free key at [maskbreak.com/signup](https://maskbreak.com/signup). The Free plan’s 10,000 visitor checks a month are enough to test against a real drop, and no plan has an hourly cap. Paid plans raise the allowance to 1,000,000 a month on Scale; bigger on-sale peaks are on Enterprise, with custom volume. The Node SDK is [@sentinelsup/sdk](https://www.npmjs.com/package/@sentinelsup/sdk). ## Update: when the buyer is an agent Ticketing now has to answer a question this post did not anticipate: what to do when the automation is a fan's own assistant, instructed to buy the moment a sale opens. That traffic is automated, arrives from cloud infrastructure, and is behaviourally indistinguishable from scalping automation — but it carries a real customer's intent. The distinction cannot be drawn from "is this a bot", so it has to come from what the request is doing and how much of it one origin is doing. Per-origin purchase limits, device-level correlation across accounts, and the strictest gate on the checkout step itself all survive this shift, because they constrain volume rather than automation as such. [The agent-traffic piece](https://maskbreak.com/blog/ai-agent-traffic-detection) covers verification; [the decision guide](https://maskbreak.com/blog/should-you-block-ai-agents) covers where to enforce. ## Questions people ask **Will Maskbreak work for sneaker drops, ticket releases, and console restocks all the same?** Yes. The underlying signals — automation, antidetect browser, proxy (residential pools included), persistent visitor ID — are universal. The policy you apply on top is what differs (e.g. ticket releases often need a queue, sneaker drops need first-second cart-grab protection). **Won't a strict policy block legitimate fans on VPNs?** No. A VPN on its own returns review, not block, so in enforce mode a fan on NordVPN gets your verification step, never a refusal. A proxy, automation or a fake or tampered browser is what makes the decision block, and your own attempt counter, keyed on the visitor ID, covers one browser trying checkout again and again within a minute. **How does Maskbreak hold up at peak traffic — 100,000 visitors hitting at T-0?** Each check is one server-side call, and each response reports its own processing time. The frontend SDK is asynchronous and adds nothing to your page's interactive time. No plan has an hourly cap, so a drop that size only draws on the month: Growth (250,000 checks a month) and Scale (1,000,000) hold it, and bigger or more frequent peaks are on Enterprise, agreed with us before the event. **Can drop-bot operators reverse-engineer Maskbreak?** The detection logic runs server-side after the SDK collects data, so the actual scoring isn't reachable from the client. The SDK itself ships with active obfuscation that rotates frequently. Operators that try to fake a clean signal usually create new tells in the process — antidetect browsers leave their own fingerprint. **What does it cost?** The Free plan includes 10,000 visitor checks a month with no card. Paid plans start at €29 a month (Starter: 50,000 checks a month) and go to €299 a month on Scale (1,000,000 checks); bigger drops are on Enterprise, from €990 a month. No plan has an hourly cap, and there are no automatic overage charges. --- # Free VPN API: 10 VPN Detection APIs Compared URL: https://maskbreak.com/blog/free-vpn-detection-api Published: 2026-04-11 · Updated: 2026-10-19 > Ten free VPN detection APIs compared on free allowance, what you send (IP address or live visit), whether they name the VPN, and commercial-use terms. - Decide on the input first: nine of the ten free plans take an IP address, while Maskbreak checks a live visit to your page. - Free allowances are counted per hour, per day, per month or per minute, so size them against both your busiest hour and your monthly total. - The free tiers of vpnapi.io and ip-api are licensed for non-commercial use only; read each vendor’s terms before production. - Only some responses name the VPN service: proxycheck.io documents an operator field on its free plan, and Maskbreak returns network.service when known on live visits. Free VPN detection APIs come in two kinds: ones you send an IP address, and ones that check a live visit to your website. This page compares ten of them on four things: the free allowance, what you send, whether the response names the VPN service, and whether the free plan allows commercial use. Every other vendor’s figure was checked on its own pricing, documentation or terms page on 23 September 2026; Maskbreak’s row reflects its plans as of 30 September 2026. Maskbreak publishes this page and is one of the ten, so read it as a vendor’s comparison. Every other row links to that vendor’s own page, and free allowances change, so confirm the current offer before you integrate. This is about APIs that detect VPN use, not services that provide a VPN connection; for residential and mobile proxies, see [our proxy detection API comparison](https://maskbreak.com/blog/proxy-detection-api-comparison). If you already know you need a live-visit check, the [VPN detection API](https://maskbreak.com/vpn-detection) page covers Maskbreak on its own. ## Free VPN detection APIs compared Free plans as published on 23 September 2026 (Maskbreak: 30 September 2026); “commercial use” means on the free plan ServiceFree planInputNames the VPNCommercial use [Maskbreak](https://maskbreak.com/pricing)10,000 visitor checks a month, no hourly limit; paid plans from €29/monthLive visit; a bare IP gets Tor and cloud checks onlyYes, in `network.service` when known (live visits)Yes, on every plan, the Free plan included [proxycheck.io](https://proxycheck.io/pricing/)1,000 queries a day, same features as paidIP addressYes: an `operator` object when the operator is knownNo non-commercial clause; one free account each [IPHub](https://iphub.info/pricing)1,000 requests a day (Basic tier)IP addressNot in the documented responseNot stated on the pricing page [FindIP](https://www.findip.net/vpn-detection-api)No limit statedIP addressNot in the documented exampleNo restriction in the terms we read [GetIPIntel](https://getipintel.net/free-proxy-vpn-tor-detection-api/)500 a day, 15 a minute; contact email requiredIP address (returns a probability)NoNo reselling without consent; credit the source [vpnapi.io](https://vpnapi.io/pricing)1,000 requests a dayIP addressNot in the documented fieldsNo: the free version is licensed for personal, non-commercial use [ipinfo](https://ipinfo.io/pricing)Lite: country and ASN only; VPN data from the paid Core planIP addressOn the paid Max planLite: commercial licence with attribution [ipgeolocation.io](https://ipgeolocation.io/pricing.html)1,000 credits a day, geolocation only; VPN data is paidIP address; paid plans add a client-side scriptOn paid plans (`vpn_provider_names`)Not applicable (no VPN data free) [IPQualityScore](https://www.ipqualityscore.com/plans)1,000 lookups a month, 35 a dayIP addressNot in the response fields we readNot stated on the plans page [ip-api](https://ip-api.com/docs/api:json)45 requests a minute; HTTP onlyIP address (one combined proxy flag)NoNo: [non-commercial use only](https://ip-api.com/docs/legal) “Not in the documented response” means we did not find the field in the vendor’s public documentation, not that the vendor cannot tell you. The table says nothing about detection quality: none of these vendors, Maskbreak included, publishes an independent accuracy benchmark that we could cite, so test on your own traffic. ## IP address or live visit: which input do you have? The first question is not which vendor, but what you can send. On their free plans, nine of the ten services above take an IP address. That suits server logs, batch jobs, API-to-API traffic and anything without a browser. The answer comes from what the vendor knows about that address: VPN exit lists, proxy observations, hosting ranges and similar data. Maskbreak works differently. A small script on your page collects a token during the visitor’s real visit, your server forwards that token to `POST /v1/evaluate`, and the response carries VPN and [residential-proxy signals](https://maskbreak.com/proxy-detection), the service name when known, and an `allow`, `review` or `block` decision. Optional device evidence adds browser-tampering and automation signals. The honest limit: without a live visit, Maskbreak can do much less. Its bare-IP lookup (`GET /v1/lookup/{ip}`) checks [Tor exits](https://maskbreak.com/blog/tor-exit-node-detection) and [cloud-server ranges](https://maskbreak.com/blog/datacenter-ip-detection) only. It does not return a VPN or proxy verdict. If you only have addresses from logs and need VPN flags for them, one of the IP-based services above is the better fit. Many teams run both: an IP API for logs and back-office jobs, and a live-visit check on the signup, login or checkout form. ## Notes on each free VPN detection API ### Maskbreak Free plan: 10,000 visitor checks a month, no credit card; paid plans start at €29 a month ([pricing](https://maskbreak.com/pricing)). Bare IP lookups have their own allowance, ten times the plan’s visitor checks. A VPN on its own produces `review`, not `block`, under the default policy. [Inspect a sample response](https://maskbreak.com/api#playground) without an account. ### proxycheck.io The [pricing page](https://proxycheck.io/pricing/) lists a free plan of 1,000 daily queries and says it has the same features as the paid plans. The [API documentation](https://proxycheck.io/api/) shows an `operator` object that names the VPN or proxy operator when it is known (and is `null` otherwise), which makes it the free IP-based option here that documents a service name. The [terms](https://proxycheck.io/terms/) allow one free account per customer. See the [proxycheck.io alternatives](https://maskbreak.com/alternatives/proxycheck) page for a longer comparison. ### IPHub IPHub’s [pricing page](https://iphub.info/pricing) offers a free plan of 1,000 requests per day on the Basic tier, which covers open proxies, Tor exits, datacenter addresses and commercial VPNs. Its home page says residential proxy detection is on the commercial plans. The response carries a `block` value plus ISP and ASN. ### FindIP FindIP’s [VPN detection page](https://www.findip.net/vpn-detection-api) says the API has no daily or monthly caps and needs no credit card. Its terms say the service is currently free, reserve the right to add limits later, and ask you not to use the data as the sole basis for consequential decisions. That is good advice for any vendor in this table. ### GetIPIntel GetIPIntel returns a probability that an address is a proxy, VPN or bad IP rather than a yes/no flag. The [documentation](https://getipintel.net/free-proxy-vpn-tor-detection-api/) asks free users to stay under 500 queries a day and 15 a minute, and requires a contact email that is checked often. Its terms forbid reselling the results without consent and ask for credit when results are reused. Residential proxy detection is an optional flag. See [GetIPIntel alternatives](https://maskbreak.com/alternatives/getipintel). ### vpnapi.io vpnapi.io documents separate `security.vpn`, `security.proxy`, `security.tor` and `security.relay` flags plus ASN details ([API documentation](https://vpnapi.io/api-documentation)). Free accounts get 1,000 requests a day ([pricing](https://vpnapi.io/pricing)). Its [terms of use](https://vpnapi.io/terms-of-use) limit the free version to personal, non-commercial use; commercial use needs a paid plan. See [vpnapi.io alternatives](https://maskbreak.com/alternatives/vpnapi). ### ipinfo ipinfo’s free Lite plan ([pricing](https://ipinfo.io/pricing)) covers country-level location and ASN name. VPN, Tor, proxy and relay detection starts on the paid Core plan, and the Max plan adds residential proxy detection and service names. If you already use ipinfo for geolocation, VPN detection is an upgrade rather than a new vendor. See [ipinfo alternatives](https://maskbreak.com/alternatives/ipinfo), and for geolocation itself the [IP geolocation comparison](https://maskbreak.com/blog/ip-geolocation-api-comparison) of ipinfo, MaxMind, IP2Location and three others. ### ipgeolocation.io The [pricing page](https://ipgeolocation.io/pricing.html) gives 1,000 credits a day on the free plan and marks security data (VPN, proxy and Tor) as not available on it. On paid plans, the [IP Security API](https://ipgeolocation.io/ip-security-api.html) documents `vpn_provider_names` and `proxy_provider_names` fields, and the paid plans also list a client-side real-time VPN and proxy detection script. ### IPQualityScore The IPQS [plans page](https://www.ipqualityscore.com/plans) lists a free plan of 1,000 lookups a month and 35 a day, shared with its email, phone and URL checks. The [Proxy & VPN Detection API](https://www.ipqualityscore.com/documentation/proxy-detection-api/overview) returns a fraud score with VPN, proxy and Tor flags from an IP address. See [IPQS alternatives](https://maskbreak.com/alternatives/ipqs). ### ip-api The free JSON endpoint returns geolocation, a combined proxy/VPN/Tor flag and a hosting flag, over HTTP only, at up to 45 requests a minute per IP address ([documentation](https://ip-api.com/docs/api:json)). Its [terms](https://ip-api.com/docs/legal) restrict free use to non-commercial purposes, so it suits hobby projects, not a business’s fraud checks. ## Maskbreak: live check vs IP lookup Your taskUseWhat it tells you Check a visitor at signup, login or checkoutBrowser SDK + `POST /v1/evaluate`Live VPN/proxy signals; service name when known; optional device evidence Screen an arbitrary IP address`GET /v1/lookup/{ip}`Current production coverage: Tor exits and cloud-server ranges Test response handling without real traffic`sk_test_sandbox` + a documented test tokenDeterministic fixtures, not a live detection measurement Read the [IP lookup reference](https://maskbreak.com/api#lookup) for its separate response shape. A false VPN flag from that endpoint does not prove an address is outside a VPN. To see the live check’s answer for your own connection, open the [free VPN checker](https://maskbreak.com/ip-lookup). For the full distinction, see [proxy detection API vs IP lookup](https://maskbreak.com/blog/proxy-detection-api-vs-ip-lookup). ## Set up a live VPN and proxy check Create a [free account](https://maskbreak.com/signup), copy your live key from the dashboard, and store it as `MASKBREAK_API_KEY` in your server’s environment. The browser loads the collector without a secret. Keep the live API key out of HTML, browser JavaScript and public source repositories. ### 1. Collect evidence in the visitor’s browser Add this script to the page containing your existing signup form: ``` ``` After the SDK loads, collect evidence in your form’s submit handler and include these fields with the form data you already send to your own backend: ``` // Inside your existing async submit handler, after event.preventDefault(). const { token, fingerprintEventId, tz } = await window.Sentinel.collect(); const response = await fetch('/your-signup-endpoint', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ...formData, // your existing signup fields token, fingerprintEventId, tz }) }); // Handle response.status in your existing signup UI. ``` The network token is required for the live VPN/proxy assessment. `fingerprintEventId` adds device evidence when available. Handle collector errors in your form UI; missing evidence must not silently authorize the signup. ### 2. Evaluate on your server before completing the action This Node 22 / Express example plugs into an existing application. `app`, `express` and `existingSignupHandler` belong to your app. Keep its normal validation, authentication, rate limiting and abuse controls. ``` app.use(express.json({ limit: '16kb' })); app.post('/your-signup-endpoint', async (req, res, next) => { try { const { token, fingerprintEventId, tz } = req.body; const response = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', signal: AbortSignal.timeout(2000), // example budget; measure yours headers: { 'Authorization': 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ token, fingerprintEventId, tz }) }); if (!response.ok) { const refusal = await response.json().catch(() => null); // The month's checks are used up: continue unchecked until the 1st // (00:00 UTC), logged. Every other error holds the signup. if (response.status === 429 && refusal?.code === 'monthly_quota_exceeded') { console.warn('[maskbreak] monthly_quota_exceeded: continuing unchecked'); return next(); } throw new Error('Visitor check unavailable'); } const result = await response.json(); if (result.test || result.sandbox || result.sample) { throw new Error('Synthetic result in production'); } if (!['allow', 'review', 'block'].includes(result.decision)) { throw new Error('Unexpected verdict'); } if (result.decision === 'block') { return res.status(403).json({ error: 'Action refused by policy' }); } if (result.decision === 'review' || result.degraded) { // Your app must complete a real step-up or manual review here. return res.status(409).json({ next: 'step_up' }); } req.fraudCheck = result; return next(); // continue normal signup validation } catch { // Example temporary hold; choose a fallback for your business action. return res.status(503).json({ error: 'Check unavailable; try again shortly' }); } }, existingSignupHandler); ``` The example holds a signup when the check fails, except when the month’s checks are used up (HTTP 429 with the code `monthly_quota_exceeded`): then it lets the signup through unchecked and logs it until the 1st, so running out never takes your signup form offline. A `409` response only requests your application’s review flow; it does not implement a challenge. If your action needs a different timeout or fallback, define it explicitly. The [integration guide](https://maskbreak.com/integrate.md) and [timeout guide](https://maskbreak.com/blog/fraud-api-timeouts) cover the rest, and [JavaScript VPN detection](https://maskbreak.com/blog/javascript-vpn-detection) explains what the browser side can and cannot see. ## How to use VPN detection without rejecting every VPN user A VPN signal describes a connection, not a person’s intent. Under Maskbreak’s default evaluation policy, a VPN alone produces `review`, not `block`. Customer rules and exceptions can change the final decision. Read `decision` and `reasons`; do not turn `isSuspicious` or `network.vpn` into an automatic rejection. The same applies to any vendor’s VPN flag in the table above. For explanations, use `network.vpn`, `network.proxy` and `network.tor`. `network.service` names the VPN or proxy service when known and can be `null`. If `degraded: true` is present, false network flags mean evidence was unavailable. Optional device fields may also be absent. See the [response reference](https://maskbreak.com/api#response-obj) and [how to avoid rejecting legitimate VPN users](https://maskbreak.com/blog/vpn-detection-false-positives). ## What to test before relying on a free tier - Response handling: use test_clean, test_vpn, test_proxy and test_tor with the public sandbox key in a separate test environment. Fixtures check your code paths; they do not measure detection coverage. - Controlled live visits: compare a direct connection, your own VPN and [an authorized residential proxy](https://maskbreak.com/blog/residential-proxy-detection-guide-2026) ([our mobile proxy test](https://maskbreak.com/blog/mobile-proxy-detection) is one such visit). Record which evidence was available and whether the resulting action fits your policy. Run the same visits through any IP-based API you are considering. - Missing evidence: test a blocked collector, a missing token, a timeout and an unavailable device layer. None should become a successful check by accident. - Quota handling: free plans count differently (per hour, per day, per month, per minute). Test 429 responses, respect Retry-After, and size for your busiest hour and your monthly total, not your average day. Use the [sandbox documentation](https://maskbreak.com/api#sandbox) and [VPN API test cases](https://maskbreak.com/blog/vpn-detection-api-test-cases) to make these checks repeatable. Before you commit beyond a free tier, work through [our VPN detection API evaluation guide](https://maskbreak.com/blog/vpn-detection-api-what-actually-matters). ## Which free VPN detection API should you choose? - You only have IP addresses and run a business: start with proxycheck.io, IPHub or FindIP, and read each one’s terms for your use. GetIPIntel fits low volumes if you can credit it. - You want the VPN’s name from an IP, on a free plan: proxycheck.io documents an operator field on every plan. ipinfo and ipgeolocation.io name services on paid plans. - It is a personal, non-commercial project: vpnapi.io and ip-api license their free tiers for exactly that. - You already pay for geolocation: check whether your current vendor’s next plan adds VPN detection before adding another one. - You protect a signup, login or checkout in a browser: a live-visit check sees the visit itself and returns a decision. That is what Maskbreak is built for. [Start on the Free plan](https://maskbreak.com/signup): 10,000 visitor checks a month, with no card. Or [inspect the response first](https://maskbreak.com/api#playground). Review [the plans and their limits](https://maskbreak.com/pricing) before choosing. ## Questions people ask **What is the best free VPN detection API in 2026?** It depends on what you can send and how you will use it. For IP addresses in a commercial product, proxycheck.io (1,000 queries a day), IPHub (1,000 a day) and FindIP (no stated limit) are the free plans to compare first. For a signup, login or checkout in a browser, Maskbreak checks the live visit, and its Free plan includes 10,000 visitor checks a month. The other vendors’ figures were checked on 23 September 2026; confirm current terms and test on your own traffic. **Which free VPN detection API names the VPN provider?** proxycheck.io documents an operator object that names the VPN or proxy operator when it is known, on every plan including the free one. Maskbreak returns network.service when known on live visits. ipinfo and ipgeolocation.io name services on paid plans only. **Can I use a free VPN detection API commercially?** Not always. The free versions of vpnapi.io and ip-api are licensed for non-commercial use only. GetIPIntel forbids reselling results and asks for credit, and ipinfo Lite allows commercial use with attribution. Maskbreak’s terms cover production use on every plan, the Free plan included. Read each vendor’s current terms before you ship. **How does VPN detection work via API?** Most free APIs take an IP address and answer from what they know about it, such as VPN exit lists and hosting ranges. Maskbreak uses a browser-collected token for a live network evaluation. Its bare-IP lookup checks Tor exits and cloud ranges only; it does not replace the live VPN/proxy check. **Can I detect residential proxies for free?** Maskbreak includes live residential proxy detection in its Free plan’s visitor-check allowance, with the service name when known. Among the IP-based services, IPHub puts residential proxy detection on its commercial plans and ipinfo on its Max plan; check each vendor’s current plan pages. **Is there a free API to detect Tor exit nodes?** Yes. Most services in this comparison flag Tor exits. Maskbreak evaluation returns network.tor, and its IP lookup endpoint, which works from a bare address, returns signals.tor. Handle unavailable evidence separately from a negative result. --- # Prevent Multi-Accounting and Fake Signups URL: https://maskbreak.com/blog/prevent-multi-accounting-fake-signups Published: 2026-04-11 · Updated: 2026-07-30 > One person, hundreds of accounts. Why IP blocking and CAPTCHAs fail against multi-accounting — and what actually stops fake signup abuse. Multi-accounting is a common and expensive abuse pattern for SaaS platforms, marketplaces, and gaming sites. One person creates dozens or hundreds of accounts to exploit free trials, [promotions](https://maskbreak.com/blog/promo-code-abuse-detection), referral programs, or voting systems. ## Why It's Hard to Stop Traditional approaches fail because fraudsters have evolved: - Email aliases: Gmail's dot trick (j.ohn vs john) and + aliases create unlimited email addresses - Residential proxies: Each account appears to come from a different home IP — clean, no flags - Antidetect browsers: Tools like Kameleo and GoLogin create unique device fingerprints for each account - VPNs: Cheap VPN subscriptions provide thousands of IP addresses Each control has blind spots on its own: residential proxies weaken IP rules, aliases weaken email deduplication, challenge solvers weaken CAPTCHAs, and antidetect tools target basic fingerprints. ## What Actually Works The solution is layered detection — combining multiple signals that are hard to fake simultaneously: - Device fingerprinting + tampering detection: Detect if the browser fingerprint is spoofed (antidetect browsers leave detectable traces even when spoofing) - Network intelligence: Flag VPNs, proxies, and residential proxy networks - Account velocity: Compare signup timing and reuse patterns in your own application. - Pseudonymous account linking: Pass your own non-identifying accountId to measure distinct accounts associated with a device. ## Implementation with Maskbreak Maskbreak returns network and device signals in one API call; your application can combine them with its own account and behavioural context. When a user signs up: - The Maskbreak SDK collects a security token (invisible to the user) - Your backend sends the token to POST /v1/evaluate - Maskbreak returns whether the connection is suspicious + a persistent visitor ID - You check if that visitor ID has already created an account Use `isSuspicious`, reason codes, and linked-account counts to choose between allow, review, or step-up verification. Avoid blocking on one signal without measuring false positives. Before you pick a vendor, the [comparison of fake account prevention software](https://maskbreak.com/blog/best-fake-account-detection-software) sets eight tools side by side. ## Results Measure the result against a labelled holdout: duplicate-account rate, review rate, false positives, and promotion loss. Layered signals make evasion more expensive, but no detector is perfect and thresholds should be tuned on your own traffic. Try it free at [maskbreak.com](https://maskbreak.com/signup) — the Free plan includes 10,000 visitor checks a month, no credit card required. ## Update: linking is still the counter, and the tool list still does not matter The main argument here has held up, and the antidetect market since publication makes it stronger. New products keep appearing — Octo Browser, MoreLogin, VMLogin, Hidemyacc — and each arrives with the same claim of undetectability. Chasing per-tool signatures does not pay off: the category has low barriers to entry, vendors rebrand constantly, and a signature keyed to one build breaks at the next release. What does not break is correlation. An operator's goal is not to look like one convincing user but like two hundred separate ones, so the decisive question is whether forty accounts across forty residential exits trace back to one environment. [The second-tier write-up](https://maskbreak.com/blog/octo-browser-detection) covers the structural weakness the whole category shares. One constraint worth restating: linking of this kind belongs strictly inside a single business's own data. Correlating device identity across unrelated companies is a privacy boundary, not a feature. ## Questions people ask **How do you prevent multi-accounting?** Multi-accounting is best prevented at the device layer. IP blocking is ineffective since users share IPs (NAT, offices) and fraudsters use proxies. Device fingerprinting links multiple accounts to the same device even when different emails, IPs, and browsers are used. Maskbreak provides persistent device identity. **Can someone create multiple accounts using a VPN?** Yes, if only IP-based detection is used. Maskbreak detects VPN and proxy usage directly, and also links accounts by device fingerprint — so even if a user switches IPs, their device identity remains consistent. **What is the best API to detect fake signups?** Maskbreak detects the signals that indicate fake signups: antidetect browsers (used to spoof device identity), residential proxies (used to bypass IP blocks), and bot automation (used for bulk account creation). It catches multi-accounting attempts that bypass email verification. **Does Maskbreak detect the same device across different browsers?** Maskbreak's device fingerprinting uses hardware-level signals that persist across browser sessions. Even when a user switches browsers, clears cookies, or uses incognito mode, consistent hardware signals allow device linking. --- # Shopify Bot Detection: Sneaker Bots & Scalpers URL: https://maskbreak.com/blog/shopify-bot-detection Published: 2026-04-11 · Updated: 2026-10-08 > Sneaker bots and scalpers buy through Shopify's own checkout. What a storefront script can and cannot do, and how to hold bot orders before they ship. If your Shopify store drops limited inventory (sneakers, hype apparel, tickets, console restocks), plan for automated buyers on every drop. This guide is about what Maskbreak can and cannot do about them on Shopify, and the setup that works today. Some drop bots run full browser automation, often through residential proxies, and rotate fake-browser profiles between attempts. Those are the signals Maskbreak reads: the visitor's own connection (VPN, proxy, Tor) and the browser itself (automation, emulators, tampered or fake browsers). Others never open a page of your store and call Shopify's cart and checkout directly, which no script on your storefront can see. Where Maskbreak can read anything on Shopify is the part that needs care. ## What is possible on Shopify, and what is not Shopify runs your cart and checkout. That sets the limits, on every plan: - Maskbreak's script runs on your storefront pages (product, collection, cart), because you control the theme. - It does not run inside Shopify's checkout. Third-party scripts cannot add evidence to Shopify's checkout pages, and checkout.liquid is no longer an option. - Maskbreak cannot refuse a cart or an order by itself. Shopify's cart and checkout answer without asking your server, so a bot that calls them directly never meets a check of yours. - Every check needs a server of yours. The API key is a secret, so the call to Maskbreak comes from a backend you run: a custom app, or a small server that receives Shopify's order webhook. A theme alone cannot call Maskbreak. What that leaves is a real, useful setup: check each shopper who reaches checkout from your cart, attach the evidence to the order, evaluate it from your backend when the order arrives, and hold suspicious orders before you fulfil them. That stops the goods from leaving, not the order from being placed. Shopify's own bot protections stay on; this does not replace them. ## Step 1: Add the script to the page with your form (the cart) In your theme (Online Store, Themes, Edit code), open `layout/theme.liquid` and add this just before ``. The first line loads the script. The second part runs when a shopper presses Checkout on a cart form: it asks the script for the evidence with `Sentinel.collect()`, writes it into three cart attributes, and then lets the checkout continue. Shopify copies cart attributes onto the order. ``` {%- comment -%} layout/theme.liquid, just before {%- endcomment -%} ``` `collect()` waits at most five seconds for the browser check, then the checkout continues with whatever evidence there is; a shopper whose blocker stopped the script goes straight through. Accelerated checkout buttons (Shop Pay, Apple Pay and the like), a cart drawer whose Checkout button is not a submit button named `checkout`, and anything that calls Shopify's cart directly skip this step, so those orders arrive without the attributes. Your theme may need the selector adjusted; check that a test order carries the three attributes before relying on it. ## Step 2: Send the check from your server Subscribe a small backend to the `orders/create` webhook: from a custom app, or under Settings, Notifications, Webhooks in the Shopify admin, which also shows the secret the webhooks are signed with. The handler verifies the signature, answers Shopify at once, then sends the check. It sends whatever evidence the order carries, including none: a check without a token or a browser check id is how the console tells you which half is missing. In watch mode, the default, it only logs. ``` // server.js: Node 18+ with Express const crypto = require('crypto'); const express = require('express'); const MODE = process.env.MASKBREAK_MODE || 'watch'; // 'watch' or 'enforce' const seen = new Set(); // webhook ids already handled; use your database in production const app = express(); app.post('/webhooks/orders-create', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => { const given = req.get('X-Shopify-Hmac-Sha256') || ''; const expected = crypto.createHmac('sha256', process.env.SHOPIFY_WEBHOOK_SECRET) .update(req.body).digest('base64'); if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) { return res.sendStatus(401); } res.sendStatus(200); // answer Shopify first; the check runs after const id = req.get('X-Shopify-Webhook-Id'); if (id && seen.has(id)) return; // Shopify can deliver a webhook twice if (id) seen.add(id); checkOrder(JSON.parse(req.body.toString('utf8'))) .catch(err => console.warn('[maskbreak] order check failed:', err.name)); }); async function checkOrder(order) { const attrs = Object.fromEntries((order.note_attributes || []).map(a => [a.name, a.value])); let result = null; try { const res = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ token: attrs.maskbreak_token || '', fingerprintEventId: attrs.maskbreak_fp || undefined, tz: attrs.maskbreak_tz || undefined, email: order.email || undefined, accountId: order.customer ? String(order.customer.id) : undefined, }), signal: AbortSignal.timeout(3000), }); if (res.ok) result = await res.json(); else console.warn('[maskbreak] HTTP', res.status); // 401: the key, 400: the token } catch (err) { console.warn('[maskbreak] unavailable:', err.name); } // One line per order. Never log the key, the token or customer data. console.log('[maskbreak]', JSON.stringify({ mode: MODE, order: order.id, decision: result ? result.decision : null, reasons: result ? result.reasons : null, device_evidence: result ? result.device_evidence : null, degraded: result ? !!result.degraded : null, })); if (MODE === 'enforce') { // review or block: hold it. No network token, or no answer at all: the // order was never checked (an accelerated checkout button, a blocked // script, or a bot that skipped your cart), which is not a verdict. const tag = result && result.decision !== 'allow' ? 'maskbreak-' + result.decision : !result || result.degraded ? 'maskbreak-unchecked' : null; if (tag) await tagOrder(order.admin_graphql_api_id, tag); } } // Enforce mode: tag the order (maskbreak-review, maskbreak-block or // maskbreak-unchecked) for the people who fulfil it. Needs an Admin API token // with the write_orders scope. async function tagOrder(orderId, tag) { const res = await fetch(`https://${process.env.SHOPIFY_SHOP}.myshopify.com/admin/api/2026-07/graphql.json`, { method: 'POST', headers: { 'X-Shopify-Access-Token': process.env.SHOPIFY_ADMIN_TOKEN, 'Content-Type': 'application/json', }, body: JSON.stringify({ query: 'mutation ($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { userErrors { message } } }', variables: { id: orderId, tags: [tag] }, }), signal: AbortSignal.timeout(5000), }); // A missing scope or a bad id still answers 200, with the reason in the body. const out = res.ok ? await res.json() : null; if (!out || out.errors || (out.data && out.data.tagsAdd && out.data.tagsAdd.userErrors.length)) { console.warn('[shopify] tagging failed:', res.status, JSON.stringify(out && (out.errors || out.data))); } } app.listen(process.env.PORT || 3000); ``` Set `MASKBREAK_API_KEY` (your live key), `SHOPIFY_WEBHOOK_SECRET` and, for enforce mode, `SHOPIFY_SHOP` and `SHOPIFY_ADMIN_TOKEN` in the server's environment. None of them goes in the theme: anything in theme code is readable by every visitor. Use an Admin API version that Shopify still supports in the URL. ## Step 3: Submit your form once (place one order) Put a product in the cart in an ordinary browser, wait a moment, press Checkout and complete one test order (with Shopify's test payment mode, or a discount code that makes it free). The first check then appears in the Maskbreak console (if half of it did not arrive, the console says which half), and your server logs one `[maskbreak]` line for the order. `degraded: true` means the order carried no network token: it skipped the cart form, or the script was blocked. `device_evidence: "not_sent"` means no browser check id arrived; `"ok"` with `degraded: false` is a complete check. The answer's `evidence` block says how old each reading was by the time the order arrived. ## Holding orders in enforce mode After a few days of comparing the log lines with the console's Events, set `MASKBREAK_MODE=enforce`. The handler then tags every order Maskbreak answered with `review` or `block`, and the people who fulfil orders hold those until someone has looked: an order that has not shipped can still be cancelled and refunded. For limited drops, that is the difference that matters: the stock stays on your shelf for the next real customer. It also tags `maskbreak-unchecked` on every order that arrived with no network token or got no answer. That is not a verdict: a blocked script and a bot that skipped your cart land there, and so does every real customer who used an accelerated checkout button. Outside a drop, leave those alone. During a drop, look at the unchecked orders for the limited products too, because a bot that calls Shopify's cart directly only ever shows up there. Route on `decision`, never on a single signal. A plain commercial VPN comes back as `review`, not `block`: plenty of real customers use one out of privacy habit, and a VPN alone is a weak signal. A proxy, automation, an emulator or a fake or tampered browser is what turns an answer into `block`. ## Getting started The Free plan at [maskbreak.com/signup](https://maskbreak.com/signup) includes 10,000 visitor checks a month, enough to pilot on your next drop, and no plan has an hourly cap. Paid plans raise the allowance, from €29 a month for 50,000 checks; larger volumes are on Enterprise. ## 2026 update: shopping agents are not sneaker bots The most significant change for merchants since this was first published is that some automated checkout traffic is a customer's assistant acting on their instruction. It arrives headless, it often egresses from cloud infrastructure, and it looks identical to inventory-hoarding automation under any rule that asks only "is this a bot?" Blocking it is a revenue decision, and usually the wrong one. The pattern that works is to stop deciding at the edge of the store and start deciding at the edge of the action: browsing and search stay open, and the scrutiny goes on the orders for limited-release inventory and discount codes, where the loss actually concentrates. [Telling assistants from attackers](https://maskbreak.com/blog/ai-agent-traffic-detection) covers verifying declared agents against published ranges, and [the decision guide](https://maskbreak.com/blog/should-you-block-ai-agents) maps each action to a response. Running WordPress instead? The [WooCommerce guide](https://maskbreak.com/blog/woocommerce-fraud-detection) puts the same check on registration and checkout with two hooks. ## Questions people ask **Does Maskbreak work with Shopify's built-in Bot Protection?** They are separate layers. Shopify's protections run inside Shopify's storefront and checkout, and you should keep them on. Maskbreak runs where you add it: a script on your storefront pages and a check sent from your own backend when an order arrives. It does not replace Shopify's protections and cannot change them. **Do I need Shopify Plus to use Maskbreak?** No. The setup in this guide works on every plan: theme code, cart attributes and an orders/create webhook, plus a backend of your own (a custom app or a small server) that holds the API key and calls Maskbreak. On no plan does Maskbreak's script run inside Shopify's checkout; a gate before the order would need a checkout extension or validation design of your own, and Shopify restricts what those may call. **Can Maskbreak block a bot at Shopify's checkout?** Not with this setup. Shopify's cart and checkout answer without asking your server, so a bot that calls them directly never meets your check. What you can do is check each shopper who reaches checkout from your cart, evaluate the evidence when the order arrives, hold review and block orders before fulfilment, which keeps the goods from leaving, and look at the orders that arrived without any evidence. **Will this slow down my checkout?** Only by the browser check: when a shopper presses Checkout, the cart waits for the evidence, at most five seconds, before moving on. The call to Maskbreak happens later, from your server, when Shopify sends the order webhook, so it adds nothing to the shopper's checkout. **Can I use this for a single drop and then turn it off?** Yes. There's no commitment. Sign up free, deploy before your drop, and move to a monthly paid plan for the drop month if you need more volume, then cancel afterwards (the plan runs to the end of the paid period). --- # OAuth Signup Fraud: Fake Google & Apple Sign-Ins URL: https://maskbreak.com/blog/oauth-signup-fraud Published: 2026-04-08 · Updated: 2026-10-08 > Google and Apple Sign-In feel safe — but fraudsters exploit them daily. How fake OAuth signups actually work and why verified email isn't enough. Most product teams treat "Sign in with Google" as a trust signal. The reasoning: Google verified the email, so the user is real. In 2026, that reasoning is broken. Here's how much it costs to buy a batch of aged, phone-verified Google accounts: about $0.40 each, bulk-purchased from Telegram sellers. Microsoft accounts are $0.20. Apple IDs (which require paid device attestation) run $2–$5. For a fraudster running a bonus-abuse farm or a SaaS trial scraper, this is an operating cost, not a barrier. ## How OAuth signup fraud works in practice Fraudsters target OAuth signups specifically because most platforms skip their usual fraud checks when the user authenticates with Google or Apple. The typical flow: - Buy 500 aged Google accounts ($200 total). Aged = created 6+ months ago, with login history and a verified phone. - Spin up a Kameleo profile per account — unique canvas, WebGL, timezone, user agent. - Route each session through a different residential proxy endpoint. - Hit the target signup flow, complete OAuth, redeem the signup bonus / trial / free credits. - Repeat 500 times. Cash out. Because the user hit Google's consent screen and logged in successfully, every signal your application sees looks legitimate: verified email, established account history, no password to crack. Your fraud model never gets invoked. The fraud isn't in the OAuth flow itself — it's in your downstream assumption. Google verified the email. They did not verify that this session is legitimate, that this device hasn't already signed up 400 times, or that the user agent isn't a tampered browser. ## What signals are actually reliable Email verification tells you almost nothing about fraud intent. The high-signal checks for OAuth signups are all device- and network-layer: - Residential proxy flag — fraudsters need proxies to rotate IPs across 500 signups. Every signup that comes through a detected proxy gets a block decision by default. - Antidetect-browser tampering — aged Google accounts are worthless unless the fraudster can rotate browser fingerprints per session. That rotation is what tampering detection catches. - Visitor ID persistence — a single device completing 12 OAuth signups in a day is diagnostic. Verified email, verified device, 12 accounts — that's the fraud pattern in one line. - Session age vs account age — a fresh session on a fresh device claiming an aged Google account is suspicious. Real users' session devices usually correlate with their account history. ## The integration, in watch mode first Load `` on the sign-in page. When Google hands your page the ID token, call `await window.Sentinel.collect()` (check that `window.Sentinel` exists, and sign in anyway when it does not) and post its `token`, `fingerprintEventId` and `tz` to your server with the ID token: ``` // POST /auth/google: your callback handler. The sign-in page sends the // Google ID token plus the values from window.Sentinel.collect(). const MODE = process.env.MASKBREAK_MODE || 'watch'; // 'watch' or 'enforce' app.post('/auth/google', express.json(), async (req, res, next) => { const { idToken, token, fingerprintEventId, tz } = req.body || {}; // 1. Verify the Google ID token as usual let email; try { const ticket = await googleClient.verifyIdToken({ idToken, audience: process.env.GOOGLE_CLIENT_ID }); email = ticket.getPayload().email; } catch (_) { return res.status(401).json({ error: 'invalid_id_token' }); } // 2. Ask Maskbreak what this session looks like, even without a token let verdict = null; try { const r = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ token: token || '', fingerprintEventId: fingerprintEventId || undefined, tz: tz || undefined, email, }), signal: AbortSignal.timeout(3000), }); if (r.ok) verdict = await r.json(); } catch (_) { /* outage: no verdict, sign-in continues */ } console.log('[maskbreak]', JSON.stringify({ mode: MODE, decision: verdict ? verdict.decision : null, reasons: verdict ? verdict.reasons : null, device_evidence: verdict ? verdict.device_evidence : null, degraded: verdict ? !!verdict.degraded : null, })); try { // 3. Count prior accounts made from the same browser const visitorId = verdict && verdict.device ? verdict.device.visitor_id : null; const prior = visitorId ? await countUsersByVisitor(visitorId) : 0; if (MODE === 'enforce' && ((verdict && verdict.decision === 'block') || prior > 3)) { return res.status(403).json({ error: 'signup_blocked' }); } // Create the account, keeping the visitor ID for the weekly query below await createUser(email, visitorId); res.json({ ok: true }); } catch (err) { next(err); // Express 4 does not catch a rejected promise: an uncaught one ends the process } }); ``` In watch mode, the default, every sign-in is checked and logged and nothing is refused. Compare the log lines with the console's Events for a few days before you set `MASKBREAK_MODE=enforce`; the account threshold is yours to tune against your own traffic. ## Apple Sign-In: same problem, slightly rarer Apple IDs are harder (and more expensive) to farm because of the $99 developer entry for reliable bulk generation. But they're not immune — particularly because Apple's "hide my email" feature generates unique relay addresses, making email-based deduplication useless. The same device-layer checks apply. ## What about magic-link / passwordless? Same problem, same solution. Magic link flows let you verify "someone controls this email," but they give you zero information about whether the device / network context is legitimate. Maskbreak runs on the client page regardless of the auth method, so you can gate any email-verification flow the same way. For the wider set of tools that stop fake signups, see the [fake account detection software compared](https://maskbreak.com/blog/best-fake-account-detection-software). ## Dashboard insight: catching the farm The operational signal you want in your dashboard: accounts per visitor ID. Run this weekly: ``` SELECT visitor_id, COUNT(*) as accounts FROM users WHERE created_at >= NOW() - INTERVAL '7 days' GROUP BY visitor_id HAVING COUNT(*) > 3 ORDER BY accounts DESC; ``` A visitor ID behind more than a few accounts in a week deserves a look, and the threshold is yours to set against your own traffic. To act on one, open one of its checks in the console's Events and pin that visitor to Block under Rules, Always allow or block: its later checks then come back as `block`, whichever Google account it uses next, for as long as the browser keeps that identity. ## Getting started The Free plan at [maskbreak.com/signup](https://maskbreak.com/signup) includes the visitor ID. Add the check next to your OAuth callback in watch mode, and read the log lines and the console's Events before you enforce anything. ## Update: agent-driven signups A pattern worth adding: signups completed by a browser-driven agent on a real person's behalf. The OAuth handshake is genuine, the Google or Apple account is genuine, and the human did ask for the outcome — but the flow is automated end to end, so every behavioural signal reads like a bot. Blanket-blocking automation at this step therefore rejects real customers. The workable pattern is the one this post already recommends for other cases: treat the provider assertion as evidence of identity, then scale scrutiny to what the new account can immediately do. An account that can only read is cheap to grant; one that can immediately claim a referral credit is not. [The decision guide](https://maskbreak.com/blog/should-you-block-ai-agents) sets out where to put the gate. ## Questions people ask **Isn't Google Sign-In already secure?** Google verifies the email, not the session. Fraudsters buy aged Google accounts in bulk and complete real OAuth flows with them. Your application sees a legitimate sign-in; Google does not know it is one of many signups from the same farm. **How do I know if I have OAuth signup fraud?** Symptoms can include signup-bonus redemptions from new accounts that never return, unusually low trial-to-paid conversion, early churn, or referral-payout exploitation. Compare accounts per pseudonymous device identifier with your own legitimate-user baseline before setting a review threshold. **Can I block this without breaking real users?** Use multiple signals and a graduated response. Validate thresholds against holdout data, monitor false positives, and send uncertain cases to step-up verification or review instead of promising a perfect block rule. **Does this work for Apple Sign-In?** Yes. Maskbreak runs on the browser/webview regardless of OAuth provider. Apple's hide-my-email feature makes email-dedupe useless, but device-level visitor ID is unaffected. **What does Maskbreak cost for signup protection?** The Free plan includes 10,000 visitor checks a month with no card. Paid plans raise the allowance, from €29 a month for 50,000 checks; larger volumes are on Enterprise. --- # How to Detect Residential Proxies in 2026 URL: https://maskbreak.com/blog/residential-proxy-detection-guide-2026 Published: 2026-04-04 · Updated: 2026-08-29 > A rotating pool gives every attempt a fresh address, never a fresh machine: detect residential proxies on device continuity, clock and velocity, not the IP. - A residential exit is a route, not a clearance: network.residential: true means nothing fired, not that nothing is wrong. - The pool rotates the address every attempt and never the machine; key counters and history on device.visitor_id, not the IP. - An exit already tied to a pool returns network.proxy: true and blocks by default; on the rest, the device and the clock carry the signal. - Read timezone.matches_ip only when timezone.checked is true, or every VPN customer becomes a false positive. - Route on device.antidetect and antidetect_browser; the tampering score read 0.0029 on spoofed and unspoofed profiles alike on our bench. A residential proxy defeats an IP check by construction. The address belongs to a real household, the ISP is one your customers use, and no reputation database has an opinion on it because the pool rotates the address before complaints accumulate. Behind that address the operator runs the same machine, the same browser profile and the same script for every attempt. This playbook is about detecting the machine once the address has stopped identifying anyone: how the attack is assembled, why reputation returns green, which fields in a `/v1/evaluate` verdict still move, and what each rung of the response needs before it fires. It is the hub for the residential-proxy posts in our [fraud playbooks](https://maskbreak.com/blog/playbooks). ## How a residential proxy attack is run The stack has four parts, none hard to buy; we name tools and list prices because a team that has never priced them overestimates the effort on the other side. - Rent a pool. Residential bandwidth is sold by the gigabyte with geographic targeting included. On 2026-08-29 [Oxylabs](https://oxylabs.io/pricing/residential-proxy-pool) listed $6/GB on a 5 GB starter plan down to $2.50/GB at 1 TB; [Decodo](https://decodo.com/proxies/residential-proxies) listed $4/GB pay as you go and a 3-day trial of 100 MB; [IPRoyal](https://iproyal.com/residential-proxies/) listed $7.00/GB falling to $1.75/GB in bulk, with traffic that does not expire. - Pin the exit for as long as the action takes. Sticky sessions hold one address across a multi-page checkout or a signup with email verification: up to 24 hours at [Oxylabs](https://oxylabs.io/products/residential-proxy-pool), up to 7 days at [IPRoyal](https://iproyal.com/residential-proxies/) (both checked 2026-08-29). Per-request rotation is the other mode, for spreading attempts thin. - Put a browser profile in front of it. One antidetect profile per account (Kameleo, GoLogin, Multilogin, AdsPower, Dolphin Anty) with its own cookie jar and spoofed fingerprint, or an automation framework with stealth patches; which still trips a verdict is the subject of [our antidetect browser hub](https://maskbreak.com/blog/detect-antidetect-browsers-2026). - Run the action and rotate. Signup, checkout, bonus claim, login attempt; any CAPTCHA goes to a solver farm at the prices in [our CAPTCHA farm economics post](https://maskbreak.com/blog/captcha-farms); then the exit changes and the next attempt begins. It enters your stack at the endpoint your customers use, from a consumer ASN, with a current Chrome user agent and a normal TLS handshake. Nothing in the request says proxy. ### Where the pools come from, by class Sourcing decides how an exit behaves under observation; the supply chain, paid and involuntary, is traced in our post on [residential proxy botnets](https://maskbreak.com/blog/residential-proxy-botnets), and the basics are in [what a residential proxy is](https://maskbreak.com/blog/what-is-a-residential-proxy). ClassHow it is sourcedWhat it looks like on the wire SDK-monetized peer pool[An SDK inside a free app routes traffic through the device](https://maskbreak.com/blog/proxyware-sdks). [Pawns](https://business.pawns.app/sdk/) pays the app developer a fixed $0.20 per GB shared through users' unused IPs; [PacketStream](https://packetstream.io/) pays the person sharing $0.10 per GB; [Honeygain](https://www.honeygain.com/) describes it as sharing "unused internet bandwidth" (all checked 2026-08-29).Consumer ASN, a household or phone line, the household's own traffic beside it. Exits come and go with the app; per-request rotation is cheap. ISP / static residential"An IP address hosted on a data center but registered under ISPs", as [Oxylabs describes its ISP proxies](https://oxylabs.io/products/isp-proxies), naming British Telecom, Comcast, Lumen and Frontier, at $1.20 to $1.60 per IP per month (checked 2026-08-29).Residential in every registry, datacenter stability: the same exit for weeks, no household traffic. Defeats "residential means human" and "stable means human" at once. Botnet-derived[Malware bundled with free VPN installers](https://maskbreak.com/blog/residential-proxy-botnets). The 911 S5 network held "over 19 million compromised IP addresses in over 190 countries" and spread through MaskVPN, DewVPN, PaladinVPN, ProxyGate, ShieldVPN and ShineVPN, per the [FBI's 2024-05-29 alert](https://www.ic3.gov/PSA/2024/PSA240529).Indistinguishable from a peer pool at the network layer. The owner never consented; the exit vanishes when the machine sleeps. Mobile / CGNATCarrier egress, sold by the gigabyte; [IPRoyal](https://iproyal.com/mobile-proxies/) listed rotating mobile at $6.80/GB on 2 GB, falling to $5.20/GB at 100 GB (checked 2026-09-01). Carriers put many subscribers behind one public address, which is what [RFC 6598](https://www.rfc-editor.org/info/rfc6598/) reserved 100.64.0.0/10 for in 2012.One address is thousands of real phones. A rule keyed on the IP is a rule against a city, and rotation follows the carrier's schedule. One such exit, tested live: [a 4G/5G mobile proxy, blocked on its first visit](https://maskbreak.com/blog/mobile-proxy-detection). ## Why IP reputation misses residential proxies Reputation data is real and useful, and structurally behind. Addresses are cycled to dilute complaints and spread velocity thin; by the time a database has enough reports to flag one, it has been rested and another household carries the traffic. Our own classification ties exits to named pools when it can; the operator's business is making sure most exits are not there yet. The second failure is a misreading: `network.residential: true` means neither `network.datacenter` nor `network.proxy` fired — the exit looks like consumer access, which is what the pool pays for. It describes the route, not the person. The third is the reflex fix: blocking residential ASNs blocks consumer internet, and a stale denylist entry blocks a household that left the pool weeks ago; why datacenter ranges can be handled decisively and residential ones cannot is in [residential versus datacenter proxies](https://maskbreak.com/blog/residential-proxy-vs-datacenter-proxy). Connection`network.*` in the verdictWhat the IP layer can and cannot do Commercial VPN exit`vpn: true`, often `datacenter: true`, `service` names the provider when known (`PROTON_VPN` in the [reference sample](https://maskbreak.com/api#evaluate))Shared, stable exits; classification works. The question is policy, not detection. Cloud / datacenter`datacenter: true`, `service` names the cloud when knownASN classification is decisive. The false positives are corporate egress and self-hosted VPNs. Residential proxy exit, classified`proxy: true`, `residential: false`, `service` names the pool when known (`BRIGHT_DATA` in the sandbox)Caught at the network layer. Only holds for exits already tied to a pool. Residential proxy exit, unclassified`proxy: false`, `residential: true`, `service` is the ISPNothing fires. The device, the browser's clock and your own counters carry the signal. ISP / static residentialEither of the two rows above, depending on whether the address has been tied to a poolReads as a home line with unusual stability; stability heuristics point the wrong way. Mobile / CGNAT`residential: true`, `service` is the carrierPer-IP counters measure a city. Only device-keyed counters mean anything. Home line`residential: true`, `service` is the ISP (`DEUTSCHE_TELEKOM` in the reference sample)The case every row above is imitating. ### Test whether your stack sees it An afternoon, nothing beyond a trial, against your own site and accounts; read the trial's terms first. - Take a trial from any pool above; [Decodo](https://decodo.com/proxies/residential-proxies) offered 3 days and 100 MB on 2026-08-29, more than a signup flow needs. - Route an ordinary browser through an exit in your main market and complete the action that matters: signup, checkout, bonus claim. - Open whatever records the session on your side; no signal means the IP layer was your only control, and it just failed. - Repeat with the same browser and a different exit. Does anything on your side link the two sessions? That link is the rest of this post. ## The tells that survive rotation One operator machine behind a rotating pool: five exit addresses, one visitor id one machine profile + script visitor_id nifHIy4C… - pool gateway rotates per request exit 1 · household, DE exit 2 · phone, DE exit 3 · household, DE exit 4 · ISP static, DE exit 5 · household, DE your endpoint 5 addresses 1 visitor_id The pool gives every attempt a fresh address, never a fresh machine — and the machine is what the verdict's device block identifies. Three things do not rotate with the address: the machine, the story the browser tells about itself, and the operator's rate. Each row is one measurement, the field it appears in, and the weight the evidence justifies on its own; the [ladder](https://maskbreak.com/blog/residential-proxy-detection-guide-2026#response-ladder) below is how they combine. The first row is the network layer's whole contribution — exits already tied to a pool, named in network.service when known — and the rest is what still moves when that row is silent. TellVerdict field / reason codeWeight Exit already tied to a poolnetwork.proxy: true, network.service, reason proxy_detectedBlock (the engine's default) Browser misrepresents its environmentdevice.antidetect: true, reason antidetect_browserBlock Automated browserdevice.automation: true, reason automation_detectedBlock One device, many accountsdevice.linked_accounts, device.multi_account: true, reason multi_account_deviceStep-up; block with any row above Browser clock disagrees with the exit country on an ordinary connectiontimezone.matches_ip: false while timezone.checked: true, reason timezone_mismatchStep-up Home-line exit, first-seen device, high-value actionnetwork.residential: true with device.times_seen: 1 or a recent device.first_seenStep-up Attempts per device per hourYour own counter keyed on device.visitor_idStep-up at your threshold; block with a row above Device identified unusually oftendevice.high_activity: true, reason high_activity_deviceEvidence Same exit, a different device each timeYour counters keyed on IP versus on visitor_idEvidence only; CGNAT produces the same shape ### Device continuity: the test and the limit device.visitor_id is derived from the browser and machine, not the connection, and holds across cookie clears and private windows. In our harness run of 2026-08-12 (WKWebView profiles against the homepage scanner's keyless /api/device-intel path, which reports the same identity as visitorId) a profile kept one id across three runs with the storage jar wiped each time, timesSeen counting 1, 2, 3; two profiles with different screen sizes collapsed into one id; patching canvas and WebGL readback inside the engine did not move it. One stack behind a thousand exits is still a handful of devices; device.linked_accounts — the distinct accounts a device has touched under your key — is the multi-accounting signal, and the SQL is in [our multi-accounting playbook](https://maskbreak.com/blog/prevent-multi-accounting-fake-signups). The limit, from the same run: early on, each spoofed profile minted its own stable id; after some thirty sightings from one machine, no JS-level change minted a new one at all. What fired on every spoofed profile and never on the baseline was the tampering flag one layer up: continuity catches the operator who rotates exits, integrity the one who also rotates profiles — the argument in [device fingerprinting versus IP intelligence](https://maskbreak.com/blog/device-fingerprinting-vs-ip-intelligence). ### The browser's clock against the exit: the test and the trap Send the visitor's IANA timezone as tz (the client SDK sends it as sentinel_tz; on your own, Intl.DateTimeFormat().resolvedOptions().timeZone, no permission prompt) and the verdict adds a timezone block: reported, country, matches_ip, checked. A home-line exit whose browser clock belongs to another country is the shape of a residential proxy the network layer missed; the engine adds timezone_mismatch and escalates allow to review, never to block. Watch out timezone.checked is false on a VPN, proxy, Tor or datacenter exit, because disagreeing with the clock is what those do. When checked is false, read matches_ip as information about the tunnel, not a judgment about the person. The limit: an operator who sets the profile's timezone to the exit country passes by construction; our harness grew a --tz= flag for that after a third-party checker caught a profile claiming America/New_York behind an Estonian exit our device layer had passed. It catches the careless profile; travelers land here legitimately, so it is a step-up, never a block. ### Velocity on the device: the test and the limit Count signups, checkouts and login attempts per visitor_id and per account, never per IP; the address is the measurement the pool exists to defeat. The test: run the self-test twice through different exits and confirm the counter reads 2. The limit: once a device is counted, the operator's next move is a different machine, a virtual machine or an emulator, which carry their own reason codes (virtual_machine, emulator_detected). ### Browser integrity: route on the flag, not the score In the same run the scanner's browserTampering flag, which device.antidetect and the antidetect_browser reason are built from, fired on all three spoofed profiles and never on the baseline. tamperingScore (device.tampering_score in a verdict) read 0.0029 on every profile, spoofed and unspoofed alike. Route on the boolean and its reason code; do not build a threshold on the score until it discriminates. The same pattern on a commercial tool is in [our Kameleo and Undetectable live test](https://maskbreak.com/blog/kameleo-undetectable-live-detection-test). The limit, also measured: canvas noise alone passed the flag, so it is a plausibility check on values it can contradict, not hook detection. ## Where the check goes Server-side, after the form and its client token arrive, before the action commits. Three optional fields separate a network-only verdict from the one this post is about: fingerprintEventId (no device block without it), accountId (no linked_accounts without it) and tz. Ship it in shadow mode: log the verdict, change nothing, read the reasons for a week, then wire the decision. Placement per framework, timeouts and the fail-open path are in [our Express middleware guide](https://maskbreak.com/blog/express-fraud-detection-middleware). // POST /signup — after the form arrives, before the account exists. const SIGNUPS_PER_DEVICE_PER_HOUR = 3; // your number, from your own logs app.post('/signup', async (req, res) => { const pendingId = newUserId(); // the id you are about to create const r = await fetch('https://maskbreak.com/v1/evaluate', { method: 'POST', headers: { Authorization: 'Bearer sk_test_YOUR_KEY', // sk_test_ while you shadow 'Content-Type': 'application/json' }, body: JSON.stringify({ token: req.body.monocle, // hidden input the client SDK fills fingerprintEventId: req.body.sentinel_fp, // no device block without it accountId: pendingId, // hashed server-side; unlocks linked_accounts email: req.body.email, // adds email.disposable tz: req.body.sentinel_tz // adds the timezone block }) }); const v = await r.json(); // The address is the one field the operator controls cheaply. // Everything worth counting hangs off the device instead. const id = v.device?.visitor_id; if (id) { await db.query( `INSERT INTO device_events (visitor_id, account_id, action, decision, risk_score, reasons, seen_at) VALUES ($1, $2, $3, $4, $5, $6, now())`, [id, pendingId, 'signup', v.decision, v.risk_score, v.reasons] ); } const perHour = id ? await db.countEvents(id, 'signup', '1 hour') : 0; if (v.decision === 'block' || perHour > SIGNUPS_PER_DEVICE_PER_HOUR) { return res.status(403).json({ error: 'Signup unavailable.' }); } const clockDisagrees = v.timezone?.checked && v.timezone.matches_ip === false; if (v.decision === 'review' || clockDisagrees || v.device?.times_seen === 1) { return res.status(202).json({ next: 'verify_email' }); // step-up, not a wall } // allow: create the account }); With that table in place the questions are ordinary SQL: accounts per device today, devices per account, how many of either in the last hour. Persist reasons and risk_score on every row; weeks later they tell you which combination predicted fraud and which predicted a family. To exercise the block path without a browser, send the deterministic token through the public sandbox key; nothing is billed or stored and the response carries "test": true. curl -s -X POST https://maskbreak.com/v1/evaluate \ -H "Authorization: Bearer sk_test_sandbox" \ -H "Content-Type: application/json" \ -d '{"token": "test_proxy"}' Verdict { "test": true, "sandbox": true, "status": "success", "decision": "block", "risk_score": 80, "ip": "203.0.113.9", "country": "DE", "network": { "vpn": false, "proxy": true, "datacenter": true, "anonymous": true, "tor": false, "residential": false, "service": "BRIGHT_DATA" }, "reasons": ["proxy_detected", "datacenter_asn"], "evaluated_in_ms": 1, "details": { "ip": "203.0.113.9", "cc": "DE", "vpn": false, "proxied": true, "anon": true, "dch": true, "tor": false, "service": "BRIGHT_DATA" } } That is abridged from the sandbox response of 2026-08-29 — every value shown is as returned. test_clean returns the opposite shape: decision: allow, residential: true, empty reasons. Neither carries a device block, because a test token has no browser behind it. ## Response ladder Residential proxy detection is a correlation problem, and correlation produces confidence, not certainty. The response carries that shape: three rungs, each with the evidence it needs, and nothing jumping a rung on a single soft signal. RungEvidence it needsWhat you do Allowdecision: allow and nothing in your own counters. A residential exit on its own is here, and so is times_seen: 1 on a low-value action: every new customer is a first-seen device.Proceed. Log the verdict and the device id anyway. Review / step-upMixed evidence: decision: review (the engine escalates on timezone_mismatch and disposable_email), a multi_account_device reason (the engine adds the code without escalating; stepping up on it is our call), a home-line exit plus a first-seen device plus a high-value action, or your device counter over its threshold.Verify something the pool cannot supply: email confirmation, a payment-method check, a hold on the payout, a manual queue for the bonus. BlockIndependent measurements agreeing: decision: block (an exit tied to a pool, an antidetect or automated browser, Tor), or two step-up rows from different layers, such as a device linked to a dozen accounts and a counter tripping in the same hour.Refuse, with the same response the rest of your failures use, so the operator learns nothing about which tell fired. An exit tied to a pool is a hard block by default; if corporate egress in your traffic is named as a proxy, a dashboard rule can move that signal to review for your key — the response then reports decision_source: "rules" with the engine's call kept in engine_decision. Route on decision, sort on risk_score: the score orders a review queue, not a second decision ([our post on risk score thresholds](https://maskbreak.com/blog/risk-score-thresholds)). ## What it costs you The operator pays per attempt, by the gigabyte, at the list prices above; you pay per miss with the bonus, trial, chargeback or referral reward, and per false positive with a customer. That asymmetry is why the attack exists. Worked model. Inputs stated, nothing measured: assume a signup flow moves 300 KB through the proxy, page, assets and API calls included. At Decodo's pay-as-you-go $4/GB ([checked 2026-08-29](https://decodo.com/proxies/residential-proxies)) that is $0.0012 of bandwidth per attempt; at PacketStream's $1.00/GB ([checked 2026-08-29](https://packetstream.io/)) it is $0.0003, so a thousand attempts cost between thirty cents and $1.20 in bandwidth, plus the solver fee for any CAPTCHA, usually the larger line. A sticky ISP address for a month is $1.20 to $1.60 at [Oxylabs](https://oxylabs.io/products/isp-proxies) (checked 2026-08-29). While the reward per fake account exceeds the cost per attempt, the attack pays — until the device is counted, the one cost the operator cannot rent by the gigabyte. The product-side view is on [our multi-accounting page](https://maskbreak.com/blog/prevent-multi-accounting-fake-signups); the network-side capability is on the [residential proxy detection API](https://maskbreak.com/proxy-detection) page, and how it compares with other vendors' APIs is in [our proxy detection API comparison](https://maskbreak.com/blog/proxy-detection-api-comparison). ## Checklist Counters and history keyed on device.visitor_id, not the IP; a per-IP rule is a rule against a CGNAT city. - fingerprintEventId, accountId and tz on every evaluate, or the device block, linked_accounts and the timezone block never appear. - network.residential read as a route, never a clearance; timezone.matches_ip read only when timezone.checked is true. - Routing on device.antidetect and antidetect_browser; no threshold on tampering_score. - Step-up on mixed evidence; block when independent layers agree or the engine already says block. - reasons, risk_score and decision persisted on every event, shadow mode before enforcement. - No blanket rule on residential ASNs, no denylist you cannot expire; the self-test once a quarter through a different pool. ## Questions people ask **Can you detect a residential proxy from the IP address alone?** Only when the exit has already been tied to a pool, in which case the verdict returns network.proxy: true and names the provider in network.service. The pool's business is rotating addresses faster than that classification catches up, so most exits arrive as network.residential: true. Detection then rests on the device (visitor_id, linked_accounts), the browser's clock against the exit country, and your own counters keyed on the device. **Does network.residential: true mean the visitor is safe?** No. It means neither network.datacenter nor network.proxy fired, so the exit looks like consumer access. That is what a residential proxy pays for. Read it as a description of the route and let the device block, the timezone block and your velocity counters decide; the response ladder in this post starts a home-line exit at allow and moves it up only on independent evidence. **How do I detect rotating residential proxies?** Stop keying anything on the IP. Send fingerprintEventId, accountId and tz with every /v1/evaluate call, store visitor_id, decision, risk_score and reasons in a device_events table, and count attempts per device per hour. A pool gives each attempt a fresh address; it does not give each attempt a fresh machine, and device.linked_accounts shows how many accounts that machine has touched under your key. **Should I block residential proxies?** Block what the engine already blocks: an exit tied to a pool, an antidetect or automated browser, Tor. Everything else is graduated. A residential exit alone is allow; a home-line exit plus a first-seen device plus a high-value action is a step-up; two step-up tells from different layers in the same hour is a block. Blocking residential ASNs blocks your own customers, and a per-IP rule on a CGNAT address blocks a city. **What is the difference between a residential proxy and an ISP proxy?** A residential (peer) proxy exits through a real household or phone whose bandwidth is shared via an SDK, so exits appear and vanish and rotate cheaply. An ISP or static residential proxy uses an address registered to an ISP but hosted on a datacenter server, rented per IP per month, so it holds the same exit for weeks with no household traffic beside it. The first defeats reputation; the second defeats stability heuristics as well. --- # Detecting Antidetect Browsers in 2026 URL: https://maskbreak.com/blog/detect-antidetect-browsers-2026 Published: 2026-02-08 · Updated: 2026-10-27 > Two live scans and an eleven-spoof ablation: the antidetect flag fired on both commercial profiles we ran, and the tampering score never moved. - Kameleo 4.5.0 and Undetectable both scanned risk 100 on the first attempt; the device flag fired independently of the VPN exit. - Only two single spoofs trip browserTampering on our bench: a UA that contradicts the engine, and a GPU string the machine cannot back. - tamperingScore read 0.0029 on the baseline and on every spoof; the boolean discriminates, the score does not, so do not threshold it. - On a fresh machine a switcher minted distinct ids that linked_accounts did not join; after ~30 sightings the matcher re-joined new ones. - TLS and HTTP/2 come from the kernel the vendor shipped, not from the profile; Kameleo, Linken Sphere and Multilogin say so themselves. A profile switcher turns one laptop into hundreds of different-looking devices and pairs each with a clean residential exit. Every value a page can read is set per profile: user agent, GPU strings, canvas hash, font list, timezone. A fingerprint library that hashes those values sees a new visitor each time; an IP-only stack sees a home connection (the category itself is explained in [what an antidetect browser is](https://maskbreak.com/antidetect)). This post is the index for our lab series on those tools. It rests on two runs: the Kameleo 4.5.0 and Undetectable live scans from June, and the August harness run that took our tampering flag apart one spoof at a time. Every number below is a measurement with its method or a vendor's own documentation, and each table row says which. ## Setup Two runs, two paths into one pipeline. The live scans went through the homepage scanner, which posts to the public `/api/verify` route — not `/v1/evaluate`, but the same signal pipeline behind it — so the signals it displays are the ones the [API](https://maskbreak.com/api#evaluate) returns. The harness run went through the keyless `/api/device-intel` path, which returns the scanner's device block without spending a key. Its field names are the scanner's camelCase (`browserTampering`, `tamperingScore`, `visitorId`), labeled as scanner output wherever they appear. RunTool and versionProfileTarget pathDateKey type Live scan AKameleo 4.5.0 on a Windows 11 desktop"test": Chrome 149 on Windows 10, en-US, no proxy on the profile, Proton VPN running system-wideHomepage scanner → `/api/verify`2026-06-12None (scanner) Live scan BUndetectable, Chromium-based profile (version not recorded)Windows 11, Chrome 149; WebGL metadata spoofed, WebGPU masked, fonts and window size emulated, canvas and audio left realHomepage scanner → `/api/verify`2026-06-12None (scanner) HarnessOur WKWebView shim (`scripts/antidetect`) on a macOS host`none` (baseline), `macos-safari`, `win11-nvidia`, `noisy-canvas`, plus eleven single-spoof ablations; fresh storage jar every run`/api/device-intel` (keyless)2026-08-12None (public path) Both live results are the first scan each browser produced, not the best of several, as recorded in [the Kameleo and Undetectable live test](https://maskbreak.com/blog/kameleo-undetectable-live-detection-test). A later live test, of [the Aurorium antidetect browser](https://maskbreak.com/blog/aurorium-antidetect-browser-detection) on 30 September 2026, came back review, not block: the VPN was named and the browser read as a virtual machine, but the antidetect flag (`device.antidetect`) stayed false. The harness is a JavaScript shim injected at document start: it changes what a page can read and nothing underneath, the ceiling we return to in the limits. ### The tools: engine, what a profile changes, what it cannot The engine column is the vendor's own description, linked; the middle column is what the vendor documents, or what the profile editor showed where marked. The transport column is the one a profile editor never reaches: the TLS ClientHello and the HTTP/2 SETTINGS frame come from the shipped build. We did not measure that layer; "not documented" means the vendor says nothing. Vendor pages and free-profile counts were checked on 2026-08-30. ToolEngine (vendor's words)What a profile changesTLS / HTTP/2On our bench [Kameleo](https://maskbreak.com/antidetect/kameleo)Chroma (Chrome, Edge) and Junglefox (Firefox) kernels ([Kameleo docs](https://developer.kameleo.io/concepts/kernels/))In our run: WebGL and WebGPU metadata, "Intelligent" canvas noise, a 466-font list, cores, device memory, WebRTC, timezone, geolocationKernel-bound; Chroma tracks Stable Chrome "within 5 days", Junglefox "about every two months"2026-06, v4.5.0: antidetect fired ([live test](https://maskbreak.com/blog/kameleo-undetectable-live-detection-test)) UndetectableChromium-based (profile panel, in our run)WebGL metadata spoofed, WebGPU masked, fonts, window size and speech emulated; canvas, audio, WebGL image and ClientRects left realNot checked2026-06: antidetect and automation fired ([live test](https://maskbreak.com/blog/kameleo-undetectable-live-detection-test)) [GoLogin](https://maskbreak.com/antidetect/gologin)Orbita, "based on the Chromium platform" ([GoLogin](https://gologin.com/blog/meet-the-new-antidetect-browser-orbita/), updated 2023-08-29)"Browser, operating system, platform, geolocation and 15 more parameters"; WebGL; fontsNot documentedQueued (series #2) [Multilogin](https://maskbreak.com/antidetect/multilogin)Mimic, Chromium-based; the Firefox-based Stealthfox is retired ([Multilogin](https://multilogin.com/blog/what-is-stealthfox-browser/), updated 2026-06-01)User agent, canvas, WebGL, fonts (vendor, on Stealthfox)Stealthfox: no TLS control, per the vendor (quoted below); Mimic not documentedQueued (series #3) [Dolphin{anty}](https://maskbreak.com/antidetect/dolphin)"Runs on the Chromium engine" ([Dolphin docs](https://dolphin-anty.com/blog/en/how-anti-detect-browsers-work/), updated 2026-08-08)User agent, canvas, WebGL, WebRTC, language, timezone, screen resolution, OS and device information; "more than 50 available characteristics"Not documentedNot yet run; [5 free profiles](https://dolphin-anty.com/) [AdsPower](https://maskbreak.com/antidetect/adspower)SunBrowser (Chrome-based) and FlowerBrowser (Firefox-based) ([AdsPower](https://www.adspower.com/))Canvas, WebGL, audio, WebRTC, language, resolution, timezone, geolocation, fonts; "50+ customizable parameters"Not documentedQueued (series #4); [2 free profiles](https://www.adspower.com/) [Incogniton](https://maskbreak.com/antidetect/incogniton)Chromium, exposed over WebSocket, debugger port or WebDriver ([Incogniton](https://incogniton.com/blog/playwright-vs-puppeteer-vs-selenium/))Device model, OS, browser version, timezone, language, plugins, screen resolution, audio and video capabilitiesNot documentedNot scheduled; [10 free profiles](https://incogniton.com/) [Octo Browser](https://maskbreak.com/blog/octo-browser-detection)"Octium browser kernel", a Chromium build ([Octo](https://octobrowser.net/))Not itemized on the vendor siteNot documentedQueued in the Octo post [Linken Sphere](https://maskbreak.com/blog/linken-sphere-detection)"The current Chromium engine" ([Linken Sphere](https://ls.app/blog/dns-webrtc-and-tls-leaks), 2026-03-06)Per-profile fingerprints; not itemized on the page we checkedChrome-equivalent ciphers and extensions, per the vendor (quoted below)Researched profile queued MoreLoginChrome and Firefox kernels ([MoreLogin](https://www.morelogin.com/antidetect-browser))User agent, canvas, fonts, resolution; language, timezone and geolocation matched to the proxy regionNot documentedSecond tier in the Octo post VMLoginA modified "Chrome kernel" ([VMLogin](https://www.vmlogin.cc/en/detection.html))"Dozens of browser fingerprint parameters"; WebRTC, public and internal IP, languageNot documentedNot scheduled Four layers of a browser session, who sets each one, and which check reads it LayerSet byRead by Page-visible valuesnavigator, screen, canvas, WebGL strings, fonts, timezone the profile tampering flag, visitor_id Enginehow pixels render, how APIs behave the shipped kernel tampering flag, visitor_id TransportTLS ClientHello (JA4), HTTP/2 SETTINGS the shipped kernel your edge, not /v1/evaluate Networkexit IP, ASN, service attribution the proxy or VPN network block The profile editor reaches the top band only. The other three are decided by the kernel the vendor shipped and by the exit the operator bought. ## What fired Both live scans came back at risk 100 on the first attempt. Kameleo was flagged at the device layer as antidetect and at the network layer as a Proton VPN exit on datacenter infrastructure; Undetectable was flagged as antidetect and as automation, on the same exit. Both scans also read Tor exit: yes on the same address they attributed to Proton VPN; nothing we captured explains that read, so the table reports it as displayed, unexplained. The layers fired independently: the device verdict is computed from what the browser presented, not from the address it arrived on, so switching the VPN off or swapping it for a residential exit does not change it. Live scan A, first scan. Kameleo 4.5.0, profile "test" claiming Chrome 149 on Windows 10. Device layer: antidetect. Network layer: Proton VPN exit, with a Tor-exit read on the same address. Signal (scanner label)Live scan A: Kameleo 4.5.0Live scan B: Undetectable Antidetect (device layer)✓ yes✓ yes Bot (device layer)– no✓ yes VPN exit (network layer)✓ Proton VPN✓ same Proton exit Datacenter (network layer)✓ yes✓ same exit Tor exit (network layer)✓ yes✓ yes, same exit Risk score100100 The harness run is the finer instrument because it has a baseline: the `none` profile loads the shim and applies nothing, so any signal that differs from it is attributable to the spoofing, not to the web view. Fields are scanner output from `/api/device-intel`. Scanner fieldnonemacos-safariwin11-nvidianoisy-canvas `browserTampering`falsetruetruetrue `tamperingScore`0.00290.00290.00290.0029 `antidetectBrowser`falsefalsefalsefalse `botDetected`falsefalsefalsefalse `osName` (follows the UA)Mac OS XMac OS XWindowsMac OS X `visitorId`, fresh jar every runSNRP5DSC… returned again by eight ablation runsnifHIy4C… stable ×32uyWPokd… one run recordedHLEWtoo0… stable ×3 Three things to read off that table. `browserTampering` is the field the API surfaces as `device.antidetect` and the reason code `antidetect_browser`; it moved on all three composite profiles, including `noisy-canvas`, whose platform story is truthful and which only perturbs canvas and audio; the ablation below shows which single spoofs move it on their own. The scanner's separate `antidetectBrowser` field stayed false throughout, so the tampering flag is the one carrying the verdict. And `tamperingScore` read 0.0029 on all four, baseline included: the boolean discriminates, the score does not, so nothing here recommends a threshold on `device.tampering_score`. ### The response shape (worked model) No `/v1/evaluate` payload was captured for either live scan; the next scan's raw JSON is queued for the live-test post. This is a worked model, not a capture. Its inputs are the [documented](https://maskbreak.com/api#evaluate) response fields, the values the scanner displayed for live scan A, the reason codes they imply, and the pipeline's hard-block set. Unobserved values are marked. Verdict (worked model) ``` { "decision": "block", // antidetect_browser and Tor each hard-block "risk_score": 100, // as the scanner showed "network": { "vpn": true, // shown by the scanner "proxy": false, // not flagged "datacenter": true, // shown by the scanner "tor": true, // shown, same address; unexplained (see above) "anonymous": true, // follows from vpn (reference definition) "residential": false, // follows from datacenter "service": "PROTON_VPN" // the operator the scanner named }, "device": { "antidetect": true, // Chrome 149 on Windows 10 over a non-Chrome kernel "automation": false, // true on live scan B "visitor_id": "...", // not captured "tampering_score": "..." // not captured; 0.0029 on every harness profile }, "reasons": ["vpn_detected", "datacenter_asn", "antidetect_browser"] // the Tor signal adds a code too; the reference does not spell it, so we do not guess // evaluated_in_ms: not captured } ``` ### Review or block The pipeline puts `antidetect_browser` in the same hard-block set as proxy, Tor, automation and emulator, so a session like live scan A returns `decision: block` before the network layer is counted; a commercial VPN alone returns `review`. We keep block for signup, bonus claims and checkout, the actions a profile farm exists for; the [multi-accounting page](https://maskbreak.com/blog/prevent-multi-accounting-fake-signups) covers the per-action policy. Where you want `review`, set an antidetect rule to review in the dashboard: a rule decides for the signal it names, but every other signal on the visit that has no rule keeps its weight (a proxy on the same visit still blocks), and the engine's verdict is kept in `engine_decision`. Do not build the softening on `device.tampering_score`; on our bench it does not move. ## Ablation: one spoof at a time Eleven profiles, each changing one category with everything else untouched, plus the unspoofed `none` baseline, through the same scanner path on 2026-08-12. ProfileWhat it changes`browserTampering``visitorId` vs baseline `none`nothingfalsebaseline `ab-uasafari`UA to Safari on macOS (consistent with the engine)falsenew id `ab-ua`UA to Chrome 131 on Windowstruenew id `ab-webgl`WebGL renderer to "Apple M1 Max"truesame `ab-webgl-identity`WebGL hook installed, returns the machine's real stringsfalsesame `ab-screen`screen size, availWidth and availHeight, DPRfalsenew id `ab-tz`timezone (Intl and getTimezoneOffset)falsesame `ab-langs`navigator.languagesfalsesame `ab-cores`hardwareConcurrencyfalsesame `ab-canvas`canvas pixel noisefalsesame `ab-audio`audio noisefalsesame `ab-plugins`empty plugins and mimeTypesfalsesame ### Engine consistency: the user agent is checked against the engine Swapping the user agent is not itself suspicious. `ab-uasafari` changes it and passes; `ab-ua` claims Chrome 131 on Windows while running WebKit and fails. The scanner's `browserName` and `osName` labels follow the user agent either way, so on `win11-nvidia` the label says Windows and the flag says tampered, and the flag is the one telling the truth. Live scan A is the same contradiction at commercial quality: Chrome 149 on Windows 10, on a Windows 11 host, through a kernel that is not Chrome 149. ### Render versus claim: the WebGL check is on the value, not the hook `ab-webgl` reports a GPU the machine does not have and fails. `ab-webgl-identity` installs the same `getParameter` override, returns the real strings, and passes. The interception is invisible; what fails is a renderer string that something measurable contradicts. That cuts both ways: the check holds for values it can contradict and for nothing else. The live scans are the commercial version: Kameleo presented Intel HD Graphics 520 on hardware that is not that, and Undetectable presented NVIDIA WebGL metadata over the host's real canvas and audio output. ### Noise passes the flag and never moves the identity Canvas noise, audio noise, timezone, languages, core count and plugin emptying are each invisible to the flag, and eight of the eleven ablations returned the baseline's `visitorId`; only the user agent and the screen ever moved it. We then went below JavaScript: a patched WebKit build with perturbed `readPixels` and `getImageData`, verified to change the canvas and WebGL hashes, produced two profiles with the same visitor id as before and consecutive sighting counts, 17 and 18. Identification here does not rest on canvas or WebGL rendering. The [device identifier](https://maskbreak.com/device-fingerprinting) is a server-side match that absorbs small divergences: two generated profiles with different resolutions collapsed into one id while a third split off. ### Identity across profiles: what device linking survives `macos-safari` and `noisy-canvas` each returned a distinct id that stayed stable across three runs with a wiped storage jar, `timesSeen` counting 1, 2, 3. Early in the session, then, a switcher minted stable, distinct identities from one laptop, and `device.linked_accounts`, the signal behind [multi-accounting detection](https://maskbreak.com/blog/prevent-multi-accounting-fake-signups), did not join them. On a fresh machine, device linking alone does not survive a profile switcher; the tampering flag one layer up is what catches the switch. Later in the session the trick stopped working: a resolution and Safari version no earlier profile had used came back "seen 12 times", after roughly thirty visits from the machine. The matcher appears to gain confidence with history, which makes a different machine, not a better disguise, the operator's next move. ### Network: the second layer, independent of the first Both live scans flagged the Proton exit as VPN, datacenter and Tor, and neither device verdict depended on it. The variant we have not run is a paid residential exit. Classifying that exit, and naming the pool when known, is the network layer's job ([proxy detection](https://maskbreak.com/proxy-detection)); the layered claim is that if an exit does get past it, the device flag still stands. Until that run ships, the claim is argued, not measured. One check we lacked at the time, a third-party checker had: the harness profile claimed `America/New_York` while leaving through an Estonian exit. The API now takes the browser's zone as `tz` and raises `timezone_mismatch`, but not on a VPN, proxy, Tor or datacenter exit, where `timezone.checked` is false; on that profile it would be information, not a verdict. [Residential proxy detection](https://maskbreak.com/blog/residential-proxy-detection-guide-2026) is where the check earns its keep. ### Transport: what we did not measure, and what the vendors say Nothing in either run touched TLS or HTTP/2, and `/v1/evaluate` returns no field at that layer; the transport contradiction is read at your own edge, as [the JA4 post](https://maskbreak.com/blog/ja4-tls-fingerprinting) describes. It matters because a profile editor cannot reach it. The [JA4 specification](https://github.com/FoxIO-LLC/ja4/blob/main/technical_details/JA4.md) hashes the cipher and extension lists "sorted in hex order", ignoring GREASE, and [Cloudflare's JA4 write-up](https://blog.cloudflare.com/ja4-signals/) explains why: in early 2023 Chromium began shuffling TLS extension order per connection, which broke JA3, so JA4 keys on the set rather than the order (2024-08-12; both checked 2026-08-30). On HTTP/2, [RFC 9113](https://www.rfc-editor.org/rfc/rfc9113.html) requires a SETTINGS frame from both endpoints at the start of a connection, and Akamai's [Passive Fingerprinting of HTTP/2 Clients](https://blackhat.com/docs/eu-17/materials/eu-17-Shuster-Passive-Fingerprinting-Of-HTTP2-Clients-wp.pdf) found clients differ in which parameters they send, in what order, and with what values: Chrome 58 on macOS and on Windows 10 sent an identical `1:65536;3:1000;4:6291456`, while Firefox 53 added five PRIORITY frames for streams it had not opened (2017). Those values come from the kernel, and the vendors say so. [Kameleo's kernel documentation](https://developer.kameleo.io/concepts/kernels/) lists "cipher suite ordering or ALPN set belongs to an older release than the claimed version" as a risk you fix by picking the matching kernel. [Linken Sphere](https://ls.app/blog/dns-webrtc-and-tls-leaks) says its profiles send "the same set of ciphers and extensions as a regular Chrome of the corresponding version" because the browser runs current Chromium. [Multilogin's retrospective](https://multilogin.com/blog/what-is-stealthfox-browser/) says its retired Firefox engine "lacked control over subtle identifiers like TLS fingerprinting". A profile claiming Chrome 149 over a kernel that emits an older ClientHello is `ab-ua` one layer down. ## What this does not show - One machine, one connection per run. Every network signal reflects the connection the run used, not the profile. The residential-exit run for Kameleo is queued, not done. - The harness stops at JavaScript. A shim injected at document start, not a rebuilt engine; it is not Kameleo or Multilogin. Its results say what the tampering flag keys on, not how a commercial kernel fares. - First scans only, and no raw JSON. The live results are scanner screenshots; Undetectable's version was not recorded and no /v1/evaluate payload was captured. Both are queued for the next revision of the live test, as is the unexplained Tor read on the Proton address. - The tampering score does not discriminate. 0.0029 on the baseline and on every spoof. There is no threshold to recommend, and the reference's 0.6 line predates this run. - No product identification. device.antidetect is a class flag; the API does not return which tool was used. The tool table is ours, built from vendor documentation. - Nine of the eleven tools have not been on the bench. Their rows are what the vendors publish. A row is not a result. - Combinations and screen plausibility are unmeasured. Whether two profiles built only from the passing categories stay unflagged and still separate into distinct ids is unknown, and the impossible resolutions a third-party checker flagged are not a check we make. ## Reproduce it Two paths. The short one needs no key: install a free tier (AdsPower, Dolphin and Incogniton list 2, 5 and 10 free profiles, linked in the table), open maskbreak.com inside a profile and read the scanner; it is the pipeline the live scans went through. The longer one runs the profile against your own key. Put the collector on a page; it fills two hidden inputs, `monocle` for the network layer and `sentinel_fp` for the device layer (Sentinel was the product's earlier name; the SDK keeps it). ```
``` Submit the form from inside the profile, take the two values off the request, and post them with your personal `sk_test_` key: full pipeline, event badged as test, no webhooks; the check counts toward your monthly allowance. The public `sk_test_sandbox` key answers only the fixed `test_*` tokens, so it cannot evaluate a real profile. ``` curl -s -X POST https://maskbreak.com/v1/evaluate \ -H "Authorization: Bearer sk_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "token": "eyJ...", # the monocle input "fingerprintEventId": "a1b2...", # the sentinel_fp input "accountId": "lab-profile-01" # optional: makes linked_accounts appear }' | jq '{decision, risk_score, reasons, device}' ``` Run it three times from one profile and `device.times_seen` should count up while `device.visitor_id` stays put; run it from a second profile on the same machine and, early on, you should get a second id, the gap the tampering flag covers. Our bench is the WKWebView harness in the repository; these commands produced the ablation table. A local server without vendor keys returns an empty `allow` for every profile, so the run has to reach an environment where the device layer is live. ``` scripts/antidetect/build.sh # parses spoof.js with jsc, builds both binaries scripts/antidetect/antidetect selftest macos-safari # what the page sees about itself scripts/antidetect/antidetect run win11-nvidia https://maskbreak.com --wait=8 SENTINEL_LAB_KEY=sk_test_YOUR_KEY \ scripts/antidetect/antidetect verdict noisy-canvas https://maskbreak.com # posts to /v1/evaluate ``` Next in this series are GoLogin and Multilogin in the live-test format, then the residential-exit run for Kameleo, then AdsPower. Each ships with its setup table, first-scan result and raw response, and each gets a row update here. The rest of the [detection research](https://maskbreak.com/blog/research) section follows the same rule: no run, no report. ## Questions people ask **Can antidetect browsers be detected?** At the device layer, in every run we have published: Kameleo 4.5.0 and Undetectable were both flagged as antidetect on their first scan. On our own bench the three composite profiles (macos-safari, win11-nvidia, noisy-canvas) tripped browserTampering and the unspoofed baseline did not; of eleven single spoofs, only a user agent that contradicts the engine and a GPU string the machine cannot back fired on their own. Nine of the eleven tools in the table have not been run. **Which antidetect browser is undetectable?** None that we have run scanned clean, and we do not rank the ones we have not run. The API returns device.antidetect as a class flag; it does not name the product, and this post does not claim it can. The two tools with results are Kameleo (antidetect fired) and Undetectable (antidetect and automation fired). GoLogin, Multilogin and AdsPower are queued in that order. **Does a residential proxy hide an antidetect browser?** It can hide the network layer, not the device layer. Both live scans flagged the Proton exit as VPN, datacenter and Tor, and neither device verdict depended on it: the antidetect flag is computed from what the browser presented. Classifying a residential exit is the network layer's job; if one gets past it, the device flag still stands. That run is queued for the Kameleo post; until it ships, treat the layered claim as argued, not measured. **What does the tampering score mean in the API?** device.tampering_score is documented as 0 to 1. On our bench the scanner's tamperingScore read 0.0029 on the unspoofed baseline and on every spoofed profile, while the boolean browserTampering moved on the three composite profiles and on two of the eleven single spoofs. So the boolean carries the verdict and the score does not discriminate. Do not build a rule on the score until a run shows it moving; route on decision and the antidetect_browser reason code instead. **How do I test an antidetect browser against my own API key?** Put the collector script on a page with a monocle-enriched form, submit it from inside the profile, take the monocle and sentinel_fp values off the request, and POST them to /v1/evaluate with your personal sk_test_ key. That key runs the device and network checks and badges the event as test; its checks count toward your monthly allowance. Run it three times: visitor_id should stay put. Test-key answers leave times_seen out (since 27 October 2026, so testing never inflates a real device's count); to watch it climb, send the same profile through your live key from your own page. --- # Bot Detection Without CAPTCHAs: A 2026 Guide URL: https://maskbreak.com/blog/bot-detection-without-captcha Published: 2026-01-15 · Updated: 2026-10-10 > A solved CAPTCHA proves a token was bought, not a person: run the bot check on the server, on the POST, reading automation, network and device signals. - A passed challenge proves a token was bought for your sitekey; 2Captcha lists Turnstile solves at €1.40 per thousand. - Five families survive stealth patches: automation surfaces, environment coherence, TLS vs user agent, network origin, device history. - The check sits on the server between the form POST and the side effect; the browser never sees the verdict. - Block on automation_detected, antidetect_browser, tor_exit_node and proxy_detected; hold, never block, on a VPN or datacenter alone. - Log decision, reasons[], network.service and device.times_seen for a full cycle before enforcing; no rule reads tampering_score. A passed challenge proves one thing: somebody obtained a token for your sitekey within the last few minutes. On [2Captcha's price list](https://2captcha.com/pricing) (checked 2026-08-29) that token costs €1.40 per thousand for Cloudflare Turnstile and for a reCAPTCHA v3 score of 0.3 or under, and the request carrying it arrives from a real Chrome build on a home IP. The challenge never saw the automation; it saw a browser that could wait for a solver. If you are replacing a challenge, the [reCAPTCHA alternatives](https://maskbreak.com/alternatives/recaptcha) and [Turnstile alternatives](https://maskbreak.com/alternatives/turnstile) guides compare the options, and [bot detection APIs compared](https://maskbreak.com/blog/bot-detection-api-comparison) puts twelve tools side by side with their prices. This playbook covers the bot run as the operator sets it up, the five signal families that survive stealth patches, where the verdict goes, and a ladder that shows nobody a puzzle. ## How a bot run is set up in 2026 Like every entry in the [fraud playbooks](https://maskbreak.com/blog/playbooks), this one starts with the operator's setup. Four parts, each a product with a price list. - A browser runtime. Puppeteer or Playwright driving Chrome's new headless mode, "the real Chrome browser" rather than the old stripped shell ([Chrome for Developers](https://developer.chrome.com/docs/automation-and-testing/headless-chrome-shell), checked 2026-08-29). On top, [puppeteer-extra-plugin-stealth](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-stealth), which patches navigator.webdriver, chrome.runtime, webgl.vendor and the rest of its evasion list, or [rebrowser-patches](https://github.com/rebrowser/rebrowser-patches), which works on the DevTools protocol itself. For account farming, an antidetect browser (Kameleo, Multilogin, GoLogin, AdsPower) swaps profiles instead. - An exit per identity. A residential pool sold by the gigabyte (Bright Data, Oxylabs, IPRoyal, Decodo), one home line per session. [How residential proxies are sourced and detected](https://maskbreak.com/blog/residential-proxy-detection-guide-2026) covers the supply side. - A solver. The bot posts your challenge to 2Captcha or Anti-Captcha and waits for the token. [Anti-Captcha](https://anti-captcha.com/) quotes Turnstile at $2 per thousand and reCAPTCHA Enterprise at $5 (checked 2026-08-29). - A script, or a model. A hand-written flow for one target, or an LLM agent that reads the page and fills the form. They look different in the DOM and identical in your access log. The run enters your stack as the same POST your own form sends: signup, login, coupon redemption, add-to-cart. None of it is a page view, so a rule written for crawlers never fires on it. Forms with nothing to steal are targets too: in [email bombing](https://maskbreak.com/blog/email-bombing), bots submit one person's address to newsletter, signup and contact forms across many sites, and every confirmation lands in that inbox. ### LLM-driven bots and agent runtimes The scripted bot needed a developer per target; an agent runtime removes that cost. [Browser Use](https://github.com/browser-use/browser-use) drives Playwright from a model prompt, showed 111.7k GitHub stars when we checked on 2026-08-29, and its hosted tier advertises "best stealth with proxy rotation and captcha solving." The same runtime carries a shopper who asked an assistant to buy a ticket and a crew opening two hundred accounts, so the automation signal alone no longer says which. Operators who want to be recognized can be. OpenAI publishes IP ranges for GPTBot, OAI-SearchBot and ChatGPT-User, and notes that for ChatGPT-User "robots.txt rules may not apply" because the fetch is user-initiated ([OpenAI bot docs](https://developers.openai.com/api/docs/bots), checked 2026-08-29). The IETF draft [HTTP Message Signatures for automated traffic](https://datatracker.ietf.org/doc/draft-meunier-webbotauth-httpsig-protocol/) (draft-02, dated 2026-08-18) defines a `Signature-Agent` header that verifies against a published key; a request that verifies is a population you can name and give its own policy. Verifying declared agents is covered in [telling AI assistants from attackers](https://maskbreak.com/blog/ai-agent-traffic-detection), the policy question in [whether to block AI agents at all](https://maskbreak.com/blog/should-you-block-ai-agents). A user-agent string that merely says "agent" goes through the five families like everything else. ## Why a CAPTCHA misses it A challenge tests whether the client can produce a token, and every product now sells a mode that produces one without a puzzle: reCAPTCHA v3 "will never interrupt your users" and returns a score from 0.0 to 1.0 with 0.5 as the default threshold ([Google docs](https://developers.google.com/recaptcha/docs/v3), checked 2026-08-29); Turnstile's non-interactive and invisible widgets run "proof-of-work (computational puzzles), proof-of-space, probing for web APIs" ([Cloudflare docs](https://developers.cloudflare.com/turnstile/)); hCaptcha's Pro plan lists a "99.9% Passive Mode" ([hCaptcha pricing](https://www.hcaptcha.com/pricing)). Two things follow. - The token is the product. A Turnstile token "is valid for 300 seconds (5 minutes) after generation" and "can only be validated once" ([siteverify docs](https://developers.cloudflare.com/turnstile/get-started/server-side-validation/), checked 2026-08-29). That stops replay, not a solver returning a fresh token per request; the widget sees the tab the bot controls, not the machine. - The score is priced. [2Captcha](https://2captcha.com/pricing) charges €1.40 per thousand for a v3 score of 0.3 or lower and €2.80 above it. The bypass market quotes your threshold back at you. [Why solver prices below a cent broke the CAPTCHA model](https://maskbreak.com/blog/captcha-farms) works through the economics; a passed challenge is evidence of a budget, not of a person. We make the last row of the table. Control Friction Solver price per 1,000 (checked 2026-08-29) What it sees reCAPTCHA v3 None; a badge [€1.40 at score ≤ 0.3, €2.80 above](https://2captcha.com/pricing) Page interactions; it "learns by seeing real traffic on your site" hCaptcha Puzzle on Basic; passive on Pro and Enterprise Not on either list we checked Its own challenge in the widget Turnstile Managed shows a checkbox on risk; non-interactive and invisible show nothing [€1.40](https://2captcha.com/pricing) (2Captcha), [$2](https://anti-captcha.com/) (Anti-Captcha) Browser quirks and proof-of-work inside the bot's tab; a cross-session `ephemeral_id` only on Enterprise, expiring "within a few days" ([Cloudflare docs](https://developers.cloudflare.com/turnstile/additional-configuration/ephemeral-id/)) Server-side verdict (Maskbreak `/v1/evaluate`) None; nothing rendered No token to buy; the bot needs a new machine and a new exit Automation surfaces, environment coherence, network origin, device history across sessions ## The tells: five signal families and what defeats each Grouped by what the operator has to replace to beat them; the sections after the table say where each family breaks. Tell Verdict field / reason code Weight `navigator.webdriver` true, `Runtime.Enable` artifacts, `sourceURL=pptr:` stamps`device.automation` / `automation_detected`block User agent claims an engine the runtime is not`device.antidetect` / `antidetect_browser`block WebGL renderer the hardware cannot produce`device.antidetect` / `antidetect_browser`block Tor exit`network.tor` / `tor_exit_node`block Residential or SOCKS proxy, provider attributed`network.proxy` (legacy `details.proxied`), `network.service` / `proxy_detected`block Datacenter ASN on a consumer flow`network.datacenter` (legacy `details.dch`) / `datacenter_asn`step-up Commercial VPN`network.vpn`, `network.service` / `vpn_detected`step-up Browser clock in a country the exit is not, on an ordinary connection`timezone.matches_ip` false with `timezone.checked` true / `timezone_mismatch`step-up One device across many accounts`device.linked_accounts`, `device.multi_account` / `multi_account_device`step-up Device never seen before, on a high-value action`device.times_seen` 1, `device.first_seen`evidence Device evaluated unusually often`device.high_activity` / `high_activity_device`evidence Virtual machine`device.virtual_machine` / `virtual_machine`step-up TLS handshake (JA4) contradicts the user agentNot in the verdict; read at the edgeevidence ### 1. Automation surfaces: WebDriver and the DevTools protocol The WebDriver specification defines `navigator.webdriver` as "a standard way for co-operating user agents to inform the document that it is controlled by WebDriver" ([W3C](https://w3c.github.io/webdriver/#interface), checked 2026-08-29). The stealth plugin removes that flag first, but not the protocol it runs on. The [rebrowser-patches](https://github.com/rebrowser/rebrowser-patches) README says "popular automation libraries rely on the CDP command `Runtime.Enable`," that Puppeteer "adds `//# sourceURL=pptr:...` to every script in `page.evaluate()`," and that patched `console` and `navigator` objects can be detected too: "it's always a cat-and-mouse game." What defeats it: a patched driver plus the discipline of touching nothing on the JavaScript surface, which holds for one target and gets expensive across many; the stealth maintainers themselves aim to make detection "cost-prohibitive or triggers too many false-positives," not impossible. In the verdict this family is `device.automation` with reason `automation_detected`, and it needs the device token: send `fingerprintEventId` or you get a network-only verdict. [Which headless probes still fire on Chrome's new headless mode](https://maskbreak.com/blog/headless-browser-detection-2026) and [the framework-by-probe view for Puppeteer and Playwright](https://maskbreak.com/blog/puppeteer-playwright-detection) go deeper. ### 2. Environment coherence: does the story hold together? On 2026-08-12 we ran spoofed profiles through the homepage scanner's device path (`/api/device-intel`; the camelCase fields are scanner output, mapping to `device.antidetect` in the API). An unspoofed WKWebView came back `browserTampering: false`. A profile claiming Chrome 131 on Windows while running WebKit came back `true`; a user agent changed to a Safari string consistent with the engine passed. A WebGL hook returning the machine's real renderer passed; one returning "Apple M1 Max" fired. Every other single change, from screen size to canvas noise, passed alone. Two lessons. It is a consistency check, not a change detector: lying is fine as long as every layer tells the same lie, and the tell is the layer the tool forgot. And the score is not the signal: `tamperingScore` read 0.0029 on every profile, spoofed or not, so we build no rule on `device.tampering_score` and route on the boolean and the reason code `antidetect_browser`. What defeats it: a profile whose every surface agrees with the real engine, which is what commercial antidetect browsers sell; a second machine is not for sale, which is family five. [How antidetect browsers are detected, tool by tool](https://maskbreak.com/blog/detect-antidetect-browsers-2026) and [the Kameleo and Undetectable live run](https://maskbreak.com/blog/kameleo-undetectable-live-detection-test) show it on shipping products. ### 3. TLS and HTTP/2 versus the user agent A Python `requests` client with a Chrome user agent still opens TLS like Python. JA3 and JA4 "identify TLS clients based on how they initiate connections" and are "a stable identifier across different destination IPs, ports, and certificates" ([Cloudflare docs](https://developers.cloudflare.com/bots/additional-configurations/ja3-ja4-fingerprint/), checked 2026-08-29). A user agent claiming Chrome on a Go or Python ClientHello is a contradiction no JavaScript patch reaches; the same page notes that similar clients share a fingerprint, so it identifies the stack, not the person. What defeats it: a real browser; Playwright driving real Chrome presents Chrome's TLS. This family does not live in our verdict, since `/v1/evaluate` returns no TLS field, so read it at your edge and log it beside the verdict; see [what a JA4 string decodes to and where to read it](https://maskbreak.com/blog/ja4-tls-fingerprinting) and [what a Cloudflare Worker can and cannot see](https://maskbreak.com/blog/cloudflare-workers-bot-detection). ### 4. Network origin Datacenter ranges, Tor exits and attributed proxy and VPN services are the oldest family and still the one the cheapest bots fail. The verdict carries `network.datacenter`, `network.tor`, `network.proxy`, `network.vpn` and `network.service`, the last naming the provider when known. The engine blocks on an attributed proxy and on Tor by itself; a VPN alone moves the decision to review, and so does Apple's iCloud Private Relay, the one attributed proxy it does not block (`network.privacy_relay`). What defeats it: a residential exit, which is why the operator buys one. Read `network.residential: true` as the absence of a datacenter or proxy hit, not a clearance. The `timezone` block adds a cheap contradiction: when the browser's clock belongs to a different country than an ordinary-looking exit, `timezone.matches_ip` is `false`, `timezone_mismatch` fires and allow becomes review. On a VPN, proxy, Tor or datacenter exit `timezone.checked` is `false` and the mismatch raises nothing; it never blocks on its own, because travelers land there too. ### 5. Cross-session device velocity Everything above scores one request. A bot is a pattern across requests, and the pattern lives on the device, not on the IP the operator swaps per session. `device.visitor_id` is stable across sessions and cookie clears; `device.times_seen` and `device.first_seen` give the history under your key; with your own `accountId` in the request, `device.linked_accounts` and `device.multi_account` count the accounts this device has touched; `device.high_activity` flags a device evaluated unusually often. All of it is stored as one-way hashes under your key. What defeats it: a new machine per identity, and the lab says so, with one caveat. In the same 2026-08-12 run a profile switch on one laptop did mint a distinct, stable id per profile early on, and `linked_accounts` did not join them; the tampering flag is what caught those. Once the matcher had about thirty sightings from the machine, nothing moved the id: every JavaScript-reachable value was changed, canvas and WebGL readback were perturbed inside a rebuilt WebKit, and it still came back as the same device. The run's limits: one machine, one IP, nothing below JavaScript except the two readback patches. [Linking one person to hundreds of accounts](https://maskbreak.com/blog/prevent-multi-accounting-fake-signups) is the multi-accounting side of this family. ## Where the check goes After the POST reaches your server and before the side effect: the account row, the session cookie, the payment intent. Not on page views, where nothing is at stake. Not in the browser, where the bot can read the answer. The verdict is fetched by your server between the form POST and the side effect Browser SDK fills monocle + sentinel_fp - Your server POST /signup Maskbreak POST /v1/evaluate decision · reasons[] · risk_score allow create the account review create, hold the reward block generic error, same shape The verdict is read on the server. The browser never sees it. Same POST the form sends; no page views, no crawlers. The call sits between the POST and the side effect. The dashed return carries decision, reasons[] and risk_score to your server only. The client half is one script and one class on the form. The SDK fills two hidden inputs, monocle for the network token and sentinel_fp for the device event id, and Sentinel.collect() returns both (sentinel is the SDK's object name, kept from the product's original name so integrations did not break). It waits at most 5 seconds for the device layer; a device id that has not arrived by then is null.
The server half is the decision point, with two rules built in. The call has a timeout and fails open with a counter, because an outage that blocks every signup is a worse incident than an hour of unscored traffic. The block response has the shape and status of a validation failure, so the operator cannot tell a verdict from a typo. The documented sample responses show evaluated_in_ms of 118 and 126; we give the client 1,500 ms and fall through past it. // npm install @sentinelsup/sdk (MASKBREAK_API_KEY=sk_test_... until ENFORCE goes on) const Sentinel = require('@sentinelsup/sdk'); const sentinel = new Sentinel({ apiKey: process.env.MASKBREAK_API_KEY, timeoutMs: 1500 }); app.post('/signup', async (req, res) => { const { email, token, fingerprintEventId } = req.body; let verdict; try { verdict = await sentinel.evaluate({ token, fingerprintEventId, email }); } catch (err) { metrics.increment('evaluate.unavailable'); // alert on the rate, not the event verdict = { decision: 'allow', risk_score: null, reasons: [], fallback: true }; } log.info({ decision: verdict.decision, risk_score: verdict.risk_score, reasons: verdict.reasons, service: verdict.network && verdict.network.service, times_seen: verdict.device && verdict.device.times_seen, ms: verdict.evaluated_in_ms, fallback: verdict.fallback === true }, 'signup.evaluate'); if (ENFORCE && verdict.decision === 'block') { // same shape and status as a validation error; never echo reasons[] return res.status(400).json({ error: 'We could not create your account.' }); } const user = await users.create({ email }); if (verdict.decision === 'review') await holds.queue(user.id, verdict.reasons); return res.status(201).json({ ok: true }); }); VERDICT // shape of a blocked automation session (fields per /api; values illustrative) { "decision": "block", "reasons": ["automation_detected", "datacenter_asn"], "network": { "vpn": false, "proxy": false, "datacenter": true, "tor": false, "residential": false }, "device": { "automation": true, "antidetect": false, "virtual_machine": true, "times_seen": 1 }, "evaluated_in_ms": 126 } ### Observe-only first: what to log Ship with ENFORCE off and log for at least one full cycle of your traffic. The log line above is the minimum; add device.linked_accounts once you pass accountId, and join each line to outcomes: refunds, chargebacks, later bans. Read the three bands against those outcomes before enforcing, hard reasons first. The sandbox key exercises the routing without an account; it answers only the test tokens and the response carries "test": true. curl -s -X POST https://maskbreak.com/v1/evaluate \ -H "Authorization: Bearer sk_test_sandbox" \ -H "Content-Type: application/json" \ -d '{"token":"test_proxy"}' # decision: block -> your 400 path # test_vpn -> decision: review -> account created, hold queued # test_clean -> decision: allow -> 201 # Your own sk_test_ key (Settings -> API keys) runs the full pipeline with real tokens, # badged as test in the console and kept out of your stats (it counts toward the month). ## Response ladder decision is advisory: our reading of the signals, which your dashboard rules can override while risk_score stays what the engine computed. [Route on the decision, sort your queue on the score](https://maskbreak.com/blog/risk-score-thresholds) is the rule we use ourselves. In every tier the user sees nothing extra. Tier Evidence it needs Response Allow reasons[] empty, or only high_activity_device on a low-value action Proceed. Keep the log line; the history is what scores the next visit. Review One of vpn_detected, virtual_machine, datacenter_asn, timezone_mismatch, multi_account_device, disposable_email; or times_seen 1 on a payout, coupon or referral Proceed with a silent hold: verify the email before the reward, delay the payout, queue anything with money attached for a person. Block automation_detected, antidetect_browser, emulator_detected, tor_exit_node, proxy_detected, or a rule of your own Refuse with the shape and timing of a validation failure. Never name the reason. Log reasons[] and device.visitor_id. The block tier is the engine's own hard set, the one the [bot detection API](https://maskbreak.com/bot-detection) page documents: proxy, Tor, automation, emulator and antidetect come back as block from the pipeline itself; a VPN alone, or a browser inside a virtual machine, comes back as review. The ladder never blocks on vpn_detected or datacenter_asn alone (a VPN on a login is a commuter), and it never reads device.tampering_score. The signup hold flow is drawn out on [stopping fake signups](https://maskbreak.com/blog/best-fake-account-detection-software). ## What it costs you Two bills: the control and the friction. The control prices are published. reCAPTCHA's Essentials tier is "free up to 10,000 assessments per calendar month"; Premium charges an "$8.00 flat fee" for 10,001–100,000 assessments a month and "$1.00 per 1,000 assessments" above that; Enterprise is "$1 per 1,000 assessments" on a twelve-month minimum ([Google Cloud tiers](https://docs.cloud.google.com/recaptcha/docs/compare-tiers), checked 2026-08-29). hCaptcha's Basic plan is free; Pro is $99 a month billed yearly or $139 monthly, with "100K monthly evals included, then $0.99/1K"; risk scores are Enterprise ([hCaptcha pricing](https://www.hcaptcha.com/pricing)). Turnstile is free for up to 20 widgets with 10 hostnames each; Ephemeral IDs and unlimited widgets are Enterprise ([Cloudflare plans](https://developers.cloudflare.com/turnstile/plans/)). Maskbreak's Free plan includes 10,000 visitor checks a month; paid plans start at €29 a month ([pricing](https://maskbreak.com/pricing)). If you are swapping one challenge for another, the round-ups compare the alternatives to [reCAPTCHA](https://maskbreak.com/alternatives/recaptcha), [hCaptcha](https://maskbreak.com/alternatives/hcaptcha), [Cloudflare Turnstile](https://maskbreak.com/alternatives/turnstile) and [Friendly Captcha](https://maskbreak.com/alternatives/friendlycaptcha), with their published prices. The friction bill has no published number we would repeat. Measure it in your funnel: challenge shown, challenge passed, form submitted, before and after. The server-side verdict renders nothing, so its friction line is zero by construction; its cost is the review queue. What a misfire looks like from the other side, and how people get past it, is in the visitor’s guide to [the “unusual traffic” message and endless CAPTCHAs](https://maskbreak.com/blog/unusual-traffic-from-your-computer-network). ## Checklist The check runs on the POST that creates the side effect, never on page views and never from the browser. - fingerprintEventId is forwarded with the token, or the automation and antidetect checks never run; accountId is sent so device.linked_accounts exists. - The client timeout is explicit, the failure path returns allow, and the failure rate has an alert. - The block response is byte-for-byte a validation error; reasons[] goes to the log, never to the client. - Enforcement started with the hard reasons after an observe-only cycle; the review band is a hold, not a refusal. - No rule reads device.tampering_score; no rule blocks on vpn_detected or datacenter_asn alone. - JA4 is logged at the edge beside the verdict; declared agents are verified by published ranges or a Signature-Agent signature, not a user-agent string. ## Questions people ask **How do you detect bots without a CAPTCHA?** Score the request on the server, after the form POST and before the side effect. Read automation surfaces (device.automation), environment coherence (device.antidetect), network origin (network.proxy, network.tor, network.datacenter, network.vpn) and device history (device.times_seen, device.linked_accounts) in one verdict, log reasons[] for a full cycle, then enforce the hard reasons first. The visitor sees nothing; a block is shaped like a validation error. **Can bots bypass reCAPTCHA v3 and Turnstile?** Yes, at a published price. On 2026-08-29 2Captcha listed Turnstile and a reCAPTCHA v3 score of 0.3 or under at €1.40 per thousand, and Anti-Captcha listed Turnstile at $2. A solved token proves that someone bought a token for your sitekey in a real browser the widget could not see past. That is why the check has to read the machine and its history, not the tab. **Does Maskbreak detect Puppeteer and Playwright with stealth plugins?** Automation comes back as device.automation with the automation_detected reason code, and the bot detection page documents that patched Puppeteer, Playwright and Selenium sessions still return it. No detector stays ahead of every framework forever, which is why the verdict also carries network origin and device history, and why we publish no detection rate. The check needs fingerprintEventId; without it you get a network-only verdict. **How do I detect AI agents like Browser Use on my site?** An undeclared agent is automation on a residential exit and goes through the same five signal families as a scripted bot. A declared one can be verified: OpenAI publishes IP ranges for GPTBot, OAI-SearchBot and ChatGPT-User, and the IETF Web Bot Auth draft defines a Signature-Agent header you can check against a published key. Verify, then give that population its own per-action policy.