is-antibot 0.1.1

is-antibot detects antibot and CAPTCHA challenges from 30+ providers using signals.

Why?

microlink.io handles +700M requests every month.

When you're building infrastructure that needs an URL as input for getting data, you’re constantly interacting with defenses designed to stop you.

Modern antibot systems operate at multiple layers, often before your request even reaches the application code.

Our library is-antibot does something fundamental: it tells you when a non-success resolution happens and who triggered it, so you can make a better decision about what to do next.

Common signals include:

• IP reputation: Data-center IPs are flagged by default. Residential traffic behaves differently.
• HTTP consistency: Headers must match a real browser profile—not just User-Agent, but the full set.
• TLS fingerprints (JA3): The way a client negotiates TLS leaks whether it’s a browser or a script.
• Behavioral heuristics: Timing, navigation order, and interaction patterns matter.
• JavaScript fingerprinting: Canvas, WebGL, fonts, screen size—small inconsistencies are enough.

Based on these signals, a request is either:

• Allowed: If the heuristics indicate a legitimate human visitor, the request is passed through to the target website.
• Blocked: If the request is highly suspicious (e.g., coming from a known malicious IP or with a broken TLS fingerprint), it is blocked immediately with a 403 Forbidden or 429 Too Many Requests error.
• Challenged: If the system is unsure, it serves a “challenge”—such as a CAPTCHA or a JavaScript-based interstitial—that must be resolved before the actual content is released.

Quick start

Install it as dependency is the first thing to do:

npm install is-antibot

is-antibot is designed to have a minimal footprint. It works with static HTTP response analysis.

No headless browser is required. Just pass it the response information:

import isAntibot from 'is-antibot'

const response = await fetch('https://example.com')

const { detected, provider, detection } = isAntibot({
  headers: response.headers,
  statusCode: response.status,
  html: await response.text(),
  url: response.url
})

if (detected) {
  console.log(`Blocked by ${provider} (via ${detection})`)
  // => "Blocked by CloudFlare (via headers)"
}

The result is deterministic and fast—designed to run on every request without becoming the bottleneck.

It works with any HTTP client, including got, axios, undici or just the vanilla fetch.

How it works

At a high level, is-antibot classifies challenge responses using:

• HTTP status patterns: Certain platforms use unusual status codes when blocking automation; for example, LinkedIn can return 999 and Reddit can return 403 on challenge flows.
• Known challenge signatures: Challenge pages often include recognizable artifacts like CAPTCHA widgets, interstitial templates, or verification scripts.
• Response headers and body markers: Blocking responses usually expose hints in headers and HTML, such as mitigation headers, challenge tokens, or provider-specific script references.
• Provider-specific fingerprints: Each provider leaves a distinct combination of signals; for example, Cloudflare commonly surfaces cf-mitigated: challenge, while other providers rely more on cookie, URL, or HTML fingerprints.

Each provider has unique fingerprints across one or more of these signals. The library checks them in priority order and returns the first match.

Providers

is-antibot currently detects challenges across antibot systems, CAPTCHA vendors, and platform-specific protection flows.

Use this table as a quick coverage map when building retry logic, escalation rules, or provider-specific analytics in your scraping pipeline.

In case you are missing a provider or signal detection, please report to us, and we will continue evolving the library.