Bot detection for Node.js
The core package. Use it directly for a framework we do not ship middleware for, or to compose rules yourself. It runs entirely in your process, in memory, with no outbound call and no account.
Install
npm install @webdecoy/nodeQuick start
The whole integration. Local rules run in your process, so a blocked request never leaves your infrastructure.
import { WebDecoy, tripwire, honeytoken } from '@webdecoy/node';
// A hidden decoy link, plus the secret path it points at.
const trap = honeytoken();
const wd = new WebDecoy({
rules: [
// Blocks the honeytoken path plus built-in scanner bait
// (/.env, /.git/config, /wp-config.php, ...).
tripwire({ paths: [trap.path] }),
],
});
// Inject the invisible, rel=nofollow decoy link into your HTML.
// Real users never see it; a link-following scraper requests it.
body = body.replace('</body>', trap.linkHtml + '</body>');Monitor before you enforce. Detection defaults to monitor mode, so nothing is turned away until you opt in. Watch what the rules would have done against your real traffic first, then switch to enforce. Installing a blocking rule blind is how a bot filter takes down a site on day one.
What it catches
Tripwires detect intent rather than appearance, so a stealthier browser does not help the scraper.
- Any client that requests the honeytoken path, deterministically
- Scanner bait: /.env, /.git/config, /wp-config.php and friends
- Stealth scrapers that defeat fingerprinting but still follow links
- Automation that presents a genuine browser fingerprint
Questions
Why tripwires instead of fingerprinting?
Purpose-built stealth scrapers run a real Chrome, strip navigator.webdriver, and spoof canvas and WebGL, so they present a genuine browser fingerprint. A tripwire does not ask whether a client looks like a bot. It exploits the one thing automation does that people do not: requesting a path a human can never see. That detects intent, which a better fingerprint cannot spoof away.
What counts as a false positive?
The decoy link is invisible and rel=nofollow, and the default bait paths are never requested by real traffic, so a hit is a request for a path that exists only to trap automation. The honest edge cases are documented in the package README rather than glossed over.
Do I need an account?
No. The package is MIT licensed and the local rules need no account, no API key, and no outbound request. Cloud features such as IP reputation and cross-IP actor identity are optional and additive.
Other runtimes
For the full picture, including the browser client and the server-side detection loop, see the SDK overview. Full API reference lives in the Node.js documentation Opens in a new tab .
Add bot detection to your Node.js app
Start with the local rules, no account required. Add cloud features when you need actor identity that survives IP rotation.
Contact Sales