DEV Community: webdecoy

WebDecoy is now on Shopify: from bot signals to order review

webdecoy — Sat, 03 Oct 2026 03:45:04 +0000

WebDecoy is now approved and publicly listed on the Shopify App Store. We built the app to connect suspicious storefront activity with the work merchants already do: inspect traffic, investigate repeat activity, and review orders before fulfillment.

Disclosure: I’m the founder of WebDecoy. This post was prepared with AI assistance and checked against our published Shopify implementation and capability documentation.

From a visit to an order review

An IP address alone is a poor reason to reject an order. A VPN is context, not proof of fraud. We combine browser behavior, server-derived request signals, IP enrichment, and interactions with hidden honeypot links and fields to make suspicious activity reviewable.

The integration has three distinct paths:

Storefront: a Theme App Extension supplies the app embed. Enable WebDecoy Bot Detection in the theme editor and save; there is no script to paste into theme files.
Checkout: a separate Web Pixel reports supported checkout-funnel events. The theme embed does not run inside Shopify-hosted checkout.
Orders: the storefront writes a session reference into the cart. When an order is created, matching detections and available actor context can contribute to its risk evidence.

Keeping those paths separate matters. A successful storefront test does not prove that checkout-pixel events arrive, and an order without the relevant session data cannot acquire a reliable browsing history just because the app is installed.

What merchants can inspect

Detection details show scores and supporting signals. Actor profiles group related activity using available fingerprint and session evidence, helping investigate repeat visits across IPs. These are investigative groupings, not guarantees of one unique person.

Flagged Orders provides a review queue with status and notes. Supported plans add order tagging, native Shopify risk assessments with facts, and Shopify Flow triggers. The app also supplies order-risk metafields and an order-details extension.

AI Crawlers and AI Referrals are separate reports: catalog retrieval and a shopper arriving from an AI assistant are different events. Referrals depend on identifiable source information; missing referrers cannot be reconstructed.

Verify collection before enabling a response

After installation:

Choose a plan through Shopify and enable the theme app embed.
Open Setup & health, create a labeled storefront test, visit its link, and confirm that the detection arrived.
Check checkout-pixel delivery separately, accounting for consent and browser conditions.
Review detections and correlated orders before adding automation.

Test detections are excluded from traffic metrics, order review, and enforcement. Setup checks should not become fake threats in production reports.

Pro and Agency include Shopify Flow triggers. Our downloadable review and staff-notification templates start inactive when imported. Review the settings and enable them for new events when ready.

The order-created handler does not independently cancel orders or block checkout. Cancellation is a separate Flow action that a merchant must deliberately configure and enable.

What this can observe

A scraper that neither executes JavaScript nor touches a decoy can fetch public pages without appearing in storefront reports. This app does not deploy a WAF in front of Shopify-hosted checkout. We report the evidence our collection surfaces actually observe.

Try the Shopify app

The Free plan includes 500 detections per month. Starter is $59 USD/month, Pro $149, and Agency $449. Starter and Pro currently list 14-day trials; Shopify shows current pricing and trial availability before plan approval.

Watch the short demo and see the full setup guide. The demo uses a test store and seeded data, not customer results.

Install WebDecoy from the Shopify App Store.

What evidence would your team need before escalating an order for review?

What's calling your Fastify API?

webdecoy — Wed, 30 Sep 2026 18:49:00 +0000

A product endpoint can serve your frontend, a customer integration, and a scraper through the same URL. Your page analytics may only show the first of those.

Let's add request detection to a small Fastify API, watch a decoy request produce a verdict, and connect the results to a dashboard. We'll start in monitor mode so detection does not change the API's responses.

We build WebDecoy. This example uses its Fastify plugin and was prepared with AI assistance. It is request monitoring, separate from our FCaptcha project.

Build a small API

Use Node.js 22.12 or later. Create a folder and install the versions used here:

mkdir fastify-crawler-monitor
cd fastify-crawler-monitor
npm init -y
npm install --save-exact fastify@5.12.5 @webdecoy/fastify@0.18.3 @webdecoy/node@0.18.3

Create server.mjs:

import Fastify from 'fastify';
import webdecoy from '@webdecoy/fastify';
import { tripwire } from '@webdecoy/node';

const app = Fastify({ logger: false, trustProxy: false });
const apiKey = process.env.WEBDECOY_API_KEY || undefined;

await app.register(webdecoy, {
  apiKey,
  mode: 'monitor',
  honeytoken: false,
  skipPaths: ['/health'],
  rules: [tripwire({ paths: ['/.env'] })],
});

app.addHook('preHandler', async (request) => {
  const decision = request.webdecoyDecision;
  if (!decision) return;
  console.log({
    route: request.routeOptions.url,
    conclusion: decision.conclusion,
    tripwire: decision.deniedBy('tripwire'),
    dashboardConfigured: Boolean(apiKey),
  });
});

app.get('/health', async () => ({ ok: true }));
app.get('/api/products', async () => ({
  products: [{ id: 1, name: 'Field notebook' }],
}));
app.get('/.env', async (_request, reply) =>
  reply.code(404).send({ error: 'Not found' })
);

await app.listen({ host: '127.0.0.1', port: 4310 });

Register WebDecoy before your routes and the hook that reads its decision. Fastify's hook documentation explains the lifecycle and scope.

The /.env handler returns a fixed 404. It never opens an environment file. We use a path that should not contain public application content to demonstrate a concrete rule.

Automatic HTML trap injection is disabled here with honeytoken: false. The sample is a JSON API, and we only need request observation for this walkthrough.

See a verdict while the API keeps responding

Start the server:

node server.mjs

From another terminal:

curl -i http://127.0.0.1:4310/api/products
curl -i http://127.0.0.1:4310/.env

The product request returns HTTP 200 and a small catalog. The decoy path returns HTTP 404, while the terminal records:

route: '/.env'
conclusion: 'DENY'
tripwire: true
dashboardConfigured: false

DENY is the rule verdict. Monitor mode lets the application continue, so the response is still the 404 defined by the handler. Seeing a refusal in the log does not mean the request was blocked.

The example only logs a route template and a few decision fields. It does not print request headers, query strings, bodies, IP addresses, or API keys.

Put the detections in a dashboard

The local tripwire works without an account. To collect cloud detections, create a WebDecoy account and create an API key for the site you want to observe.

Put the key in a local .env file:

WEBDECOY_API_KEY=your_api_key

Add .env to .gitignore. Keep the key on the server, including when you deploy. It does not belong in the frontend that calls this API.

Stop and restart the server with the file loaded:

node --env-file=.env server.mjs

Then send the reserved test request:

curl -i -A 'WebDecoy-Test/1.0' http://127.0.0.1:4310/api/products

Open Detections in WebDecoy and look for the labeled Test record. The endpoint should still return its catalog. The record verifies reporting; it does not represent an actual AI agent visiting your API.

dashboardConfigured: true only means the process received a key. It does not prove the key is valid or the report arrived. If the record is missing, check the selected site, the key, outbound connectivity, and reporting errors.

Move it into your application

Keep your existing authentication, validation, authorization, and handlers. Add the plugin before the routes you want covered rather than replacing your server with this demo.

The demo binds to loopback and trusts no proxy headers. For deployment, configure trusted proxies for your actual network using the SDK's proxy settings. Do not trust arbitrary forwarded IP headers. Otherwise the traffic you are reviewing can be attributed to the wrong client.

This plugin uses preHandler. Requests rejected earlier in Fastify's lifecycle may never reach it. Likewise, requests served entirely by an upstream CDN do not reach this Node process. Use edge collection or access logs for those parts of the traffic.

Work out which activity matters

After deploying, look at the paths, repeated requests, classification, and supporting signals. A client using a familiar AI crawler name is not automatically that company's crawler. A legitimate customer integration is automated too, which is one reason to observe before enforcing a policy.

Detections are not a complete request counter. Some requests can be allowed locally without cloud reporting, and caching can affect reporting frequency. Keep access logs for overall volume.

Start with one useful question: which automated clients are repeatedly requesting the content this API exposes? Once you can answer that, you have a better basis for deciding what to allow, limit, or investigate.

What we checked

The example was tested locally on Node.js 26.5.0 with Fastify 5.12.5 and WebDecoy packages 0.18.3. Checks covered the catalog response, the tripwire verdict with its unchanged 404, the skipped health route, and the reserved test request in monitor mode.

No API key was used in those checks. Cloud delivery and real-crawler identification are not claimed as local test results.

Who's crawling your Astro site?

webdecoy — Wed, 30 Sep 2026 18:48:23 +0000

Your Astro blog can serve a lot of readers without running much JavaScript. A crawler can read those same pages without running any at all.

That makes browser analytics an incomplete place to look for automated visitors. A request for an article can reach your hosting provider even if the client never loads your analytics script.

Let's put observation at the edge and check that it works with one request. This walkthrough is for a static Astro site on a custom domain already proxied through Cloudflare. You can keep your existing build and hosting setup.

We build WebDecoy. This guide uses its Cloudflare edge sensor and dashboard, and was prepared with AI assistance.

Start with where your pages are served

Astro prerenders pages by default. Your hosting provider can serve the resulting HTML without starting an Astro server for each visit. Adding code to an Astro component does not make that code run whenever a crawler downloads the built file. Astro's rendering documentation explains the distinction.

For this setup, requests take this path:

Visitor → Cloudflare route → WebDecoy edge sensor → cached page or origin

The sensor observes requests that reach its matching Worker route, including clients that do not execute page scripts. It does not require an Astro adapter or a change to server rendering.

If you use a provider's default hostname rather than a Cloudflare-proxied custom domain, this particular setup will not cover it. Also check for existing Workers on the intended route. Do not replace a Worker that serves your application to make room for a sensor.

Connect the site you want to observe

Create a WebDecoy account, then select the site you want to monitor.

Open Integrations → Cloudflare.
Choose Connect with Cloudflare and review the requested permissions.
Open Edge Sensor and select the zone and route for your site.
Check which WebDecoy site will receive the detections before deploying.

In Cloudflare's DNS → Records, confirm that your site's hostname is proxied, shown by the orange cloud. A DNS-only record can leave you with an installed Worker that never receives the requests you expect.

Use the hostname people actually visit. A route for example.com/* does not cover www.example.com/*. Cloudflare's route documentation explains how patterns are matched.

The managed installer can exclude asset paths such as /_astro/* to reduce Worker invocations. Check these exclusions if you already have Workers serving assets: a route assigned to no Worker can affect more than the sensor. Worker usage is billed through your Cloudflare account under its current plan.

The current managed setup supports one edge-sensor site per WebDecoy organization. The installation guide covers this and the permissions in detail.

Deploy, then prove a request arrives

Select Deploy edge sensor, then open Sensors in WebDecoy. Look for the Edge Worker entry and confirm reporting is enabled.

Sensing reports activity. Existing deny policies can still be enforced by the same Worker, so review any rules you already have if your goal is observation only.

Now send a request to your own site's real hostname. Replace the example URL with yours:

curl -i -A 'WebDecoy-Test/1.0' https://your-site.example/

This request does not execute JavaScript. It uses a reserved user agent that asks the sensor to report a labeled test detection.

Open Detections for the same site and find the Test record. That is your evidence that the request reached the sensor and the report reached WebDecoy. A successful page response or a successful deployment message alone does not establish both.

The test label is intentional. It is not a claim that an AI crawler visited your site, and you should not include it in a screenshot as real crawler activity.

If the record is missing

Check these before changing your Astro project:

Is the hostname proxied in Cloudflare DNS?
Does the Worker route match the hostname and path used by curl?
Is Reporting on, and is the sensor build current?
Are you looking at the WebDecoy site selected during deployment?

A request redirected from the bare domain to www may take a different route. Check the response headers and test the final hostname directly. An upstream security rule can also stop traffic before your sensor sees it.

Read the first real detections

After the test, let ordinary traffic arrive. Start with the requested URLs. Are clients reading articles, following pagination, or probing paths such as /.env?

Then look at the crawler classification and the evidence supporting it. A user agent claiming to be GPTBot is a claim made by the client. Keep that separate from any verified identity shown in a record.

Timing helps too. Several article requests spread across a day tell a different story from repeated probes within a few seconds. Neither pattern, on its own, tells you whether your content ended up in model training.

The detections view is not a complete access log. The sensor selects automated-looking traffic for reporting, and sampling or limits can affect real-traffic counts. Keep hosting or CDN logs if you need a total request count.

Once your labeled test appears, you can leave collection running and return to the dashboard to see what actually visits. You do not need to start blocking crawlers to make that useful.

See which bots and AI crawlers are visiting your Angular site

webdecoy — Tue, 29 Sep 2026 19:07:56 +0000

If a crawler downloads a page without running JavaScript, an Angular service or HTTP interceptor will never see it. The request still reaches the server that delivers your site.

This walkthrough puts WebDecoy in front of Angular's server-side rendering handler. You can observe requests in monitor mode, inspect the results, and keep serving the application while you decide what needs a response.

We build WebDecoy. This tutorial was prepared with AI assistance and uses a runnable example from our public SDK repository. It covers WebDecoy request detection, not FCaptcha.

Start with the server that serves your pages

The example uses Angular SSR with an Express server:

Crawler or browser → Express → WebDecoy → Angular SSR

The same middleware also sees requests to the application's public catalog API. It runs before both the API route and Angular's rendering handler.

A separate API server cannot observe crawlers that only request HTML from another host. If your Angular app is deployed as static files, put collection at that hosting or CDN layer. Likewise, a CDN cache hit that never reaches Node is outside this middleware's coverage.

Run the example

Use Node.js 26.5, which was used for these checks, or another version supported by your Angular release.

git clone https://github.com/WebDecoy/node.git
cd node
# Revision used for this walkthrough:
git checkout 1a6b0700d45f4437311e359d3ab1ea91927fc0bf
cd examples/angular-monitor/app
npm ci --workspaces=false
npm run build
npm test
npm run serve

The example installs the published SDK packages independently of the repository's workspaces. Open http://127.0.0.1:4300 and select Load public catalog.

Use the built Node server for this check. ng serve is not the production server whose middleware order we are testing.

The complete source includes the Angular component, server, lockfile, and integration tests. The example uses Angular 22.2 and WebDecoy's Express and Node packages at 0.18.0.

Place detection before Angular's request handler

In src/server.ts, WebDecoy runs before the call to angularApp.handle(req):

import { webdecoy } from '@webdecoy/express';
import { tripwire, rateLimit } from '@webdecoy/node';

app.use(webdecoy({
  apiKey: process.env['WEBDECOY_API_KEY'] || undefined,
  mode: 'monitor',
  honeytoken: false,
  rules: [
    tripwire({ paths: ['/.env', '/wp-config.php'] }),
    rateLimit({ max: 60, window: 60 }),
  ],
}));

This is the middleware block to integrate into your existing Express server, not a complete replacement for server.ts. Keep your existing routes and rendering handler.

mode: 'monitor' records a refusal without enforcing it. The tripwire paths let us test a concrete rule without needing a real crawler. The sample does not expose a real environment file or WordPress configuration file at either path.

The rate limit is intentionally low for the demonstration. It is per process, not a shared limit across a fleet. Adjust or remove it for your workload, or use a shared store if you need one limit across replicas.

honeytoken: false turns off automatic HTML trap injection in this example. That keeps the initial setup focused on request observation without adding DOM changes during hydration.

The server serves real static assets before the middleware and excludes its health endpoint. Other requests pass through detection. The Angular server routes use:

import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  { path: '**', renderMode: RenderMode.Server },
];

Angular distinguishes server rendering, prerendering, and client rendering. Its hybrid-rendering documentation explains those choices. Check how your host serves each route before assuming every page request reaches this Node process.

Inspect a decision without blocking the page

With the server running, send these requests from another terminal:

curl -i http://127.0.0.1:4300/api/products
curl -i http://127.0.0.1:4300/.env

The catalog should return HTTP 200 with two demo items. The tripwire request should produce a terminal record with conclusion: "DENY", tripwire: true, and wouldBlock: true.

Its HTTP response stays 404 because the application defines that response and monitor mode lets the request continue. A refusal in the decision log is not the same thing as a blocked request.

The example logs limited structured decisions. It does not log visitor IPs, full headers, request bodies, or credentials.

Connect the dashboard

For cloud reporting, set your own WEBDECOY_API_KEY in the server environment and restart the server. Create the key in your WebDecoy account.

Keep the key out of Angular configuration, components, and HTTP interceptors. Those can ship to the browser.

Then send the reserved test request:

curl -i -A 'WebDecoy-Test/1.0' http://127.0.0.1:4300/api/products

Look for the labeled Test record in Detections. This checks the reporting pipeline; it does not represent a real AI crawler visit.

Without a key, the example explicitly logs dashboardConfigured: false and reportingError: true for this test. A configured key alone is not proof of delivery either. Check the dashboard record and any reporting errors.

What was verified

The production build and five integration tests passed locally. Those checks cover server-rendered HTML, catalog availability, the tripwire decision, the reserved test trigger, and rate-limit observation while responses continue.

No API key was used in those tests, so they do not verify cloud delivery or detection accuracy against real AI crawlers.

Read the real traffic after deployment

Start with the requested paths, supporting signals, timing, and crawler classification. Keep a client's claimed user-agent identity separate from any verified identity. A familiar crawler name can be copied by another client.

Before deploying behind a proxy, configure trusted proxies for your actual network path. The local example trusts no forwarding headers and binds only to loopback. Incorrect proxy settings can attribute many visitors to the same address.

Finally, detections are not a complete access log. Requests may be allowed locally without being reported, and caching can affect reporting frequency. Keep access logs for total request counts. Monitor mode gives you a way to investigate before changing how the site responds.

See which bots and AI crawlers are visiting your React site

webdecoy — Tue, 29 Sep 2026 18:20:35 +0000

A crawler can request your React site's HTML without ever running React. If you only look at browser analytics, you can miss those requests entirely.

This tutorial uses WebDecoy to observe requests to a React application served by Express. It starts in monitor mode, so you can inspect detections before choosing whether to block anything. We build WebDecoy; this example uses its Express SDK and cloud dashboard.

Start with where your React site is hosted

React renders your interface. The server or CDN in front of it receives the initial request. That is where this tutorial puts detection.

The example has a simple request path:

Visitor or crawler → Express → WebDecoy → built React site

If your React files live on a static host and your API runs elsewhere, installing this middleware on the API only covers requests to that API. It does not reveal crawlers fetching the separately hosted pages. Use a sensor at the hosting or CDN layer for that traffic.

For Next.js, use the Next.js setup guide, which places detection in its server request hook.

Run the example

Download the React + Express example and extract it. With Node.js 22.12 or later installed, run these commands from the extracted directory:

npm ci
cp .env.example .env.local

Create an API key in your WebDecoy dashboard and add it to .env.local:

WEBDECOY_API_KEY=your_api_key

This is a server credential. Keep it out of React components and do not give it a VITE_ prefix, which is intended for variables exposed to client code.

Then build and start the application:

npm run build
npm start

Open http://127.0.0.1:3110. You are visiting Express serving Vite's production output. Running the Vite development server separately would bypass this Express middleware.

Put WebDecoy before the page routes

The important part of server.mjs is the middleware order:

import express from 'express';
import { webdecoy } from '@webdecoy/express';
import { fileURLToPath } from 'node:url';
import path from 'node:path';

const app = express();
const dist = fileURLToPath(new URL('./dist/', import.meta.url));

app.use(webdecoy({
  apiKey: process.env.WEBDECOY_API_KEY || undefined,
  mode: 'monitor',
  honeytoken: false,
  skipPaths: ['/assets/'],
}));

app.use('/assets', express.static(path.join(dist, 'assets')));
app.get(['/', '/guide'], (req, res) => {
  res.sendFile(path.join(dist, 'index.html'));
});
app.use((req, res) => res.status(404).send('Not found'));

app.listen(3110, '127.0.0.1');

Both page routes pass through WebDecoy before Express serves the HTML. Built assets bypass analysis. Unknown routes still return 404; the middleware does not turn a request for a nonexistent file into a successful page response.

Monitor mode lets requests continue when WebDecoy would otherwise deny them. honeytoken: false disables automatic HTML trap injection for this walkthrough, keeping the example focused on observing incoming requests.

The local server accepts direct connections. Before deploying behind a proxy, configure Express's trust proxy setting for your actual hosting topology so client IP attribution is correct. Do not blindly trust forwarding headers supplied by clients.

The downloadable project also logs the request path and decision locally. It avoids logging visitor addresses, full headers, or credentials. Local decisions and cloud reporting are separate: without an API key, those terminal messages do not mean a record reached your dashboard.

Verify reporting with a labeled test request

Send the reserved test user agent to the guide route:

curl -i -A 'WebDecoy-Test/1.0' http://127.0.0.1:3110/guide

The page should return HTTP 200. In WebDecoy, open Detections and look for the Test record. This is an installation check, not a visit from a real AI crawler. The Express integration documentation describes the reserved test request.

If the record is missing, confirm that your key is loaded, restart the server after editing .env.local, and check the server output for errors. Also check the port: a request to a separate Vite server will not run through Express.

The example was tested locally with React 19.3.0, Vite 8.3.1, Express 5.2.1, and @webdecoy/express 0.18.0. Its production build passed. A normal page request and the test request returned 200, an unknown route returned 404, and the built JavaScript asset loaded successfully. Those checks used no API key; verify dashboard delivery with your own key using the steps above.

Read the crawler detections

Once the integration is deployed, inspect the real traffic that arrives. Look at the requested paths, crawler classifications, supporting signals, and request timing.

A name in a user-agent string tells you what the client claims to be. Check any available identity verification before attributing that request to a particular operator. A familiar crawler name alone is not proof.

Also distinguish requesting a page from rendering it. A crawler requesting the HTML of this client-rendered example has not necessarily executed React or read the content React renders. Server request detection cannot establish that by itself.

WebDecoy's detection list is not a complete access log. Some requests are allowed locally without being reported, and SDK caching can affect reporting frequency. Requests answered by an upstream CDN without reaching Express are outside this setup's coverage. Use access logs for complete request counts and collection at the CDN for requests served there.

Leave monitor mode enabled while you learn what is visiting. From there, you can decide which crawlers are useful and which behaviors need a response. The AI detection guide explains the categories available for investigating that traffic.

Originally published on WebDecoy. This tutorial was prepared with AI assistance. The local checks performed and their limits are described above.

See which bots and AI crawlers visit your Next.js site

webdecoy — Tue, 29 Sep 2026 18:17:10 +0000

If you publish a blog, documentation, or a product catalog, it helps to know which automated clients are requesting those pages. Are they identifying themselves as AI crawlers? Which URLs do they visit? Are they fetching content or probing for files that should not be public?

This guide adds WebDecoy to a Next.js application in monitor mode. Requests continue to your site while you collect detections. You can review the traffic before deciding whether any of it needs blocking.

We build WebDecoy. The example below uses its Next.js SDK and cloud dashboard.

Put detection where crawler requests arrive

A browser script can only run when the client executes it. An HTTP crawler can download your HTML without running your React components or analytics script.

For this walkthrough, detection runs on the server, before the page response. That gives it access to requests from clients that do not execute JavaScript. It does not reveal the internal purpose of every visitor, and it does not prove who operates a client merely because its user agent contains a familiar name.

You need a Next.js application with a running server and a WebDecoy API key for dashboard reporting. A static export hosted as files needs collection at its hosting or CDN layer instead.

Try the complete example

Download the runnable Next.js example. Extract it, run npm ci, copy .env.example to .env.local, add your API key, and run npm run dev. It listens on http://127.0.0.1:3107.

The example was built and checked locally with Next.js 16.3.7 and @webdecoy/nextjs 0.18.0. Normal and reserved test requests both returned HTTP 200 in monitor mode. These local checks used no API key; dashboard delivery is a separate check you will perform below.

Install the adapter

The companion example pins the adapter to version 0.18.0:

npm install @webdecoy/nextjs@0.18.0

Create an API key in your WebDecoy dashboard and put it in .env.local:

WEBDECOY_API_KEY=your_api_key

Keep this variable server-side. Do not prefix it with NEXT_PUBLIC_ or place it in a React component. When you deploy, add it to your hosting environment as well.

Without a key, the SDK can run local checks, but those checks will not appear in your cloud dashboard.

Monitor page requests

Next.js 16 uses proxy.ts for this request hook. Place it beside app, or beside src/app when your application uses a src directory:

import { withWebDecoy } from '@webdecoy/nextjs';

export default withWebDecoy({
  apiKey: process.env.WEBDECOY_API_KEY,
  mode: 'monitor',
  // Assumes one trusted proxy in front of the application.
  trustProxy: 1,
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

The matcher includes your homepage, articles, documentation, and other page routes. It excludes Next.js static assets, image optimization requests, and the favicon. Add exclusions for other assets if your site needs them, but keep the content pages you want to observe.

mode: 'monitor' lets the request continue even when WebDecoy would otherwise deny it. It does not disable protection implemented elsewhere in your application or hosting provider.

The proxy setting matters for attribution. This example assumes one trusted proxy that sanitizes forwarding headers. Configure it for your actual hosting chain; copying an arbitrary header into the client IP field can produce misleading results.

If you already have a proxy for authentication or redirects, integrate detection into that request flow rather than replacing the existing file. For an older Next.js application using the middleware convention, the adapter can be exported from middleware.ts; do not install both files.

Check that the installation reports a detection

Start your application, then send the reserved test request to a page covered by the matcher:

curl -i -A 'WebDecoy-Test/1.0' http://localhost:3000/

Use port 3107 if you are running the companion example.

Your page should still load. Open Detections in WebDecoy and look for the record labeled Test. The reserved test user agent checks the reporting pipeline; it is not evidence that a real AI crawler visited your site. The installation documentation describes this test and its dashboard label.

If nothing appears, check the API key, restart the development server after changing environment variables, and confirm that the request path matches your configuration. A successful page response alone does not establish that reporting worked. Check server errors as well.

Look at actual crawler activity

After deploying, return to Detections and the AI traffic views as real requests arrive. Start with a few records and inspect:

The requested path. An article request and a request for /.env mean different things.
The user agent and crawler classification. A recognizable name is useful context, but it is also a string a client can copy.
The supporting signals and any identity verification shown. Keep a claimed identity separate from one supported by verification.
The timing and repeated requests. A pattern across several paths can be more useful than a single score.

The SDK's detections are not a complete page-view log. Some requests can be allowed locally without being reported, and SDK caching can affect how often a decision reaches the service. Use access logs when you need a complete request count.

If an upstream CDN serves a cached response without reaching your Next.js application, this sensor will not see that request. To understand that traffic, collect at the CDN layer or use its access logs.

Decide what to do with what you find

You can leave the application in monitor mode while you learn which traffic is useful. A search crawler fetching public pages may be welcome. Repeated probes for secrets deserve a different response.

Start with the evidence in the records, then choose a policy for the specific behavior you want to change. You do not need to block every AI crawler to get value from knowing which ones are visiting.

The AI detection guide explains the available categories. Browser automation and browser-side AI signals require different evidence from a server request; this setup is not a claim that every kind of AI activity is identifiable.

Originally published on WebDecoy. This tutorial was prepared with AI assistance. The local checks performed and their limits are described above.

Your Next.js API route is public—even if your UI isn’t.

webdecoy — Mon, 28 Sep 2026 18:00:32 +0000

Hiding a form behind a client-side condition doesn't make its API route private. Unless the route enforces its own checks, another client can call it directly.

For a public contact form, you may not want to require an account. You still want the server to validate the request before it triggers an email or database write.

This example uses a Next.js App Router route handler and self-hosted FCaptcha. The browser collects a token. The server verifies it before accepting the submission.

Disclosure: I build WebDecoy and maintain FCaptcha, the free open-source project used here.

Run it locally

Complete example and README. Use the docs/angular-nextjs-tutorials branch shown below; these instructions work before it is merged into main.

The example pins Next.js 16.3.6 and uses FCaptcha 1.42. It was built and tested with Node 26.5.

git clone --branch docs/angular-nextjs-tutorials https://github.com/WebDecoy/FCaptcha.git
cd FCaptcha
npm --prefix server-node install --ignore-scripts --package-lock=false
cd examples/framework-forms
npm ci
npm --prefix nextjs ci
npm run next

Open http://127.0.0.1:3000. The launcher starts both Next.js and FCaptcha (port 8788), creates separate temporary signing and verification secrets, and passes server configuration through the environment. Use 127.0.0.1 consistently because hostname validation is exact.

The server-node install command works around an existing upstream lockfile mismatch. The example dependencies have their own lockfiles.

Separate the browser and server responsibilities

The source layout is small:

nextjs/app/page.js                 client form
nextjs/app/api/contact/route.js    server entry point
shared/browser.js                 widget loading and submission
shared/contact.mjs                validation and verification

page.js is a client component. It imports only the browser helper. A useRef guard prevents two submissions before React has rendered the pending state; useState supplies the visible status and disabled button.

On each attempt, the helper loads the widget, requests a token for action: 'contact', then sends { message, token } to /api/contact. It never receives the verification secret.

const result = await window.FCaptcha.execute('framework-contact', {
  action: 'contact', lang: 'en'
});
if (!result.success || !result.token) {
  throw new Error('Verification did not pass. Please try again.');
}

const response = await fetch('/api/contact', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message, token: result.token }),
  signal: AbortSignal.timeout(8000)
});

This excerpt runs after the loader configures FCaptcha. The full helper checks the HTTP response and accepted field before displaying success.

Keep verification in the route handler

Here is the complete route entry point:

import { contactHandler } from '../../../../shared/contact.mjs';
export const runtime = 'nodejs';
export async function POST(request) {
  try {
    return await contactHandler({ origin: process.env.APP_ORIGIN,
      captchaOrigin: process.env.FCAPTCHA_ORIGIN, verifySecret: process.env.FCAPTCHA_VERIFY_SECRET })(request);
  } catch { return Response.json({ error: 'server_configuration_error' }, { status: 503 }); }
}

The shared handler uses Node APIs, so the runtime is explicit. The verification secret is read only on the server. Do not rename it to a NEXT_PUBLIC_* variable or pass it to the page as a prop.

Before contacting FCaptcha, the handler requires the expected Origin, JSON content type, a body no larger than 16 KiB, a nonempty message of at most 2,000 characters and a token. It then performs this server-to-server request:

const verification = await fetch(new URL('/siteverify', captchaOrigin), {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({ secret: verifySecret, response: body.token }),
  signal: AbortSignal.timeout(5000),
  cache: 'no-store'
});
if (!verification.ok) throw new Error('Verification unavailable');
const result = await verification.json();

if (result?.success !== true ||
    result.hostname !== hostname ||
    result.action !== 'contact') {
  return Response.json({ error: 'captcha_rejected' }, { status: 403 });
}
// Only now perform the protected action.

A token for another hostname or another action is rejected even if its signature is valid. A successful verification consumes the token, so replay is rejected too.

Treat verification failure as failure

The handler catches network errors and malformed verifier responses and returns 503. A rejected token returns 403; invalid input returns 400. The protected action never runs in those branches.

Don't turn a timeout into success: true to keep the form moving. Show an error and let the visitor retry with a new token. The client keeps the message in the textarea and clears its pending state in finally.

You can check that a direct request cannot skip verification:

curl -i http://127.0.0.1:3000/api/contact \
  -H 'Origin: http://127.0.0.1:3000' \
  -H 'Content-Type: application/json' \
  --data '{"message":"hello","token":"forged"}'

The running example returns 403 with captcha_rejected.

What this example tests

npm test runs 17 integration checks across the Express adapter and the Next.js route handler against the real FCaptcha verification endpoint. They cover valid tokens, replay, forged and expired tokens, hostname/action mismatches, input limits, origin checks and verification outages. Both framework production builds also passed.

The tests sign fixtures with a temporary test key. They test the integration contract—not the browser's ability to distinguish humans from bots. No human pass-rate claim follows from these tests.

Before you deploy

The launcher is deliberately local: it creates fresh, separate signing and verification secrets for every run and binds FCaptcha to loopback. The browser helper also uses a hardcoded loopback URL. Replace those with your own HTTPS origins, public site key and stable server-side secrets for deployment.

Keep rate limits, request-size limits and authentication/authorization where needed. An Origin check helps with unwanted browser requests, but a script can forge that header. CAPTCHA is another check, not a replacement for authorization or a complete spam defense.

When you add email or database writes, handle duplicate business actions separately. Verification consumes the token; if the later action fails, the retry needs a new token. Multiple FCaptcha replicas also need shared state for replay protection. Give legitimate visitors a recovery path if verification fails.

This demo only returns { accepted: true, demoOnly: true }. It does not store a message or send an email.

FCaptcha is free and open source. If you try the example, useful feedback is a reproducible integration issue—including framework version and the failing step—with tokens and secrets removed.

Framework reference: Next.js Route Handlers.

Your Angular form has validation. Bots don’t care.

webdecoy — Mon, 28 Sep 2026 18:00:12 +0000

A disabled submit button is useful feedback. It does not protect the endpoint behind it.

Someone can skip your Angular application and send an HTTP request directly. Validators.required never runs in that request. Neither does your submit handler.

Let's build a small contact form where the backend decides whether the request is accepted. It uses Angular reactive forms, Express and self-hosted FCaptcha.

Disclosure: I build WebDecoy and maintain FCaptcha. This is a runnable integration tutorial for our open-source project.

Run the example

Complete example and README. This tutorial's source is on the docs/angular-nextjs-tutorials branch; it does not depend on a future merge to main.

Use a current Node version compatible with Angular 22 (tested with Node 26.5). The example pins Angular 22.2 and uses FCaptcha 1.42.

git clone --branch docs/angular-nextjs-tutorials https://github.com/WebDecoy/FCaptcha.git
cd FCaptcha
npm --prefix server-node install --ignore-scripts --package-lock=false
cd examples/framework-forms
npm ci
npm --prefix angular ci
npm run angular

Open http://127.0.0.1:4200, not localhost. The allowed hostname is intentionally exact. The launcher starts Angular, an Express API on port 4201 and FCaptcha on port 8788. Angular proxies /api to Express so the form submits to its own origin.

The server dependency command works around an existing server-node lockfile mismatch. The example itself includes dependency lockfiles.

Keep Angular validation for the user experience

The standalone component imports ReactiveFormsModule and uses a typed form control:

form = new FormGroup({
  message: new FormControl('', {
    nonNullable: true,
    validators: [Validators.required, Validators.maxLength(2000)]
  })
});
busy = signal(false);
status = signal('');

The template binds the form and displays a live status message:

<form [formGroup]="form" (ngSubmit)="submit()">
  <label for="message">Test message</label>
  <textarea id="message" formControlName="message"
            maxlength="2000" required></textarea>
  <button type="submit" [disabled]="form.invalid || busy()">
    {{ busy() ? 'Verifying…' : 'Verify and submit' }}
  </button>
</form>
<p role="status" aria-live="polite">{{ status() }}</p>

The submit method checks validity, sets busy before awaiting anything, and clears it in finally. That prevents accidental double clicks and leaves the form usable after errors. The full component is in angular/src/main.ts.

These controls improve the browser experience. The server repeats the checks because it cannot trust the browser.

Get a token, then submit it to your API

The shared browser helper lazily loads /fcaptcha.js from the local FCaptcha server and configures that server URL. After loading, the important sequence is:

const result = await window.FCaptcha.execute('framework-contact', {
  action: 'contact', lang: 'en'
});
if (!result.success || !result.token) {
  throw new Error('Verification did not pass. Please try again.');
}
const response = await fetch('/api/contact', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message, token: result.token }),
  signal: AbortSignal.timeout(8000)
});

The helper checks the API response too. A successful client result alone never means the message was accepted. Each attempt gets a fresh token; a successfully verified token cannot be reused.

Express makes the decision

angular/api.mjs limits the request body to 16 KiB and passes a Web Request to shared/contact.mjs. The shared handler validates JSON, limits messages to 2,000 characters and requires a token before contacting FCaptcha.

This is the core server-side verification step, excerpted from that handler:

const verification = await fetch(new URL('/siteverify', captchaOrigin), {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({ secret: verifySecret, response: body.token }),
  signal: AbortSignal.timeout(5000),
  cache: 'no-store'
});
if (!verification.ok) throw new Error('Verification unavailable');
const result = await verification.json();

if (result?.success !== true ||
    result.hostname !== hostname ||
    result.action !== 'contact') {
  return Response.json({ error: 'captcha_rejected' }, { status: 403 });
}
// Only now perform the protected action.

verifySecret exists only in the server process. The public site key is not a secret. The application checks both the expected hostname and the contact action, rather than accepting any successful token from any workflow.

Network errors, non-2xx verification responses and malformed verification JSON produce a 503 response. Rejected tokens produce 403. Neither path sends a message.

What this example tests

The tests sign fixtures with a temporary test key. They test the integration contract—not the browser's ability to distinguish humans from bots. No human pass-rate claim follows from these tests.

Before you deploy

This demo only returns { accepted: true, demoOnly: true }. It does not store a message or send an email.

FCaptcha is free and open source. If you try the example, useful feedback is a reproducible integration issue—including framework version and the failing step—with tokens and secrets removed.

Framework reference: Angular reactive forms.

Who's hitting your WordPress site while you sleep?

webdecoy — Mon, 28 Sep 2026 17:40:12 +0000

Fake registrations. Repeated login attempts. Strange requests for files you never published. If you run WooCommerce, checkout abuse can add another problem to the list.

Before enabling another blocking rule, I want to answer a smaller question: can I see what triggered it?

I'm Chris, the developer behind WebDecoy. This walkthrough uses our free, open-source WordPress plugin to record a controlled request in monitor mode. Local functionality doesn't require an account or API key; connecting the cloud service is optional.

The useful part is the workflow: generate one known event, find its record, and separate detection from enforcement.

Start on one staging site

From the WordPress root, with WP-CLI available:

wp plugin install webdecoy --activate
wp webdecoy config set mode monitor
wp webdecoy config get mode
wp webdecoy status

You can also install WebDecoy Bot Detection through Plugins → Add New. Check the mode before testing. If the plugin is already installed, skip the installation command.

Monitor mode lets you inspect detections before applying blocking. It still executes code and writes records, so use staging to check compatibility and overhead.

If WEBDECOY_DEFAULT_MODE forces a mode in wp-config.php, the CLI won't override it. Read the command result rather than assuming the change worked.

In the status output, note:

Field	What to check
`version`	Which build you're evaluating
`mode`	Confirm `monitor`
`cloud`	Whether a cloud account is connected
`detections_total`	Your starting detection count
`active_blocks`	Your starting active IP-block count

Give the logger one known event

I ran this on an isolated local WordPress site, bound to loopback at port 18079. There was no real .env file at the target path. The request exercises a default tripwire path.

TEST_BASE='http://localhost:18079'
curl -sS -A 'python-requests/2.31' \
  -o /dev/null -w 'HTTP %{http_code}\n' \
  "$TEST_BASE/.env"

Use your own isolated test environment, not another person's site or a path containing actual secrets. A CDN, cache, authentication layer, or WAF may stop a request before WordPress sees it.

Then check again:

wp webdecoy status

The request returned 301. The detection still happened.

Here's what the September 28 test actually produced:

Signal	Before	After
Mode	monitor	monitor
Total detections	0	1
Active IP blocks	0	0

The HTTP response was 301. The saved detection contained the tripwire_rule flag and /.env path metadata.

That is why I don't use HTTP status as my detection test. A redirect can come from another part of the request path. A recorded detection also doesn't prove that the request was blocked.

This test established that a matching record was created and the active IP-block count didn't increase. It did not measure detection accuracy, false-positive rates, checkout compatibility, or performance.

The exact environment was WordPress 7.1, PHP 8.3.33, and WebDecoy 2.10.1 at commit d386344, with no cloud connection. For this run I mounted that source checkout and activated it with wp plugin activate webdecoy; the WordPress.org installation command above is the normal distribution route. Record your version because the repository and directory package can update at different times.

Match the record, then test real workflows

In WebDecoy's detection log, correlate the timestamp, User-Agent, and detection flags with your request. On a busy site, an increased total alone won't tell you which request caused it.

Next, stay in monitor mode and exercise the workflows your visitors need:

Log in as an administrator and an ordinary user.
Register, reset a password, and submit a comment where those features are enabled.
Browse through the same cache/CDN path your visitors use.
For WooCommerce, test the journey from cart to order confirmation using a test payment environment.

Watch for detections that overlap legitimate actions. Understand those before changing enforcement. Shared IPs and reverse proxies also affect how you should interpret an address in a log.

For agencies, one representative staging site is a useful starting point. It isn't evidence that every client site, theme, checkout, and plugin combination behaves the same way.

To stop the trial:

wp plugin deactivate webdecoy

Deactivation is not uninstallation or a promise that stored logs have been erased.

Try it on a site you control

What's the most persistent unwanted traffic on your WordPress sites: login attempts, fake registrations, comment spam, or checkout abuse? If you try the workflow, I'd be interested in what was hard to interpret in the logs. Please redact IP addresses and customer information before sharing examples.

How to Block Bots on WordPress Without a CAPTCHA or a WAF

webdecoy — Sun, 13 Sep 2026 18:32:08 +0000

Most WordPress bot protection works by estimating. It looks at a User-Agent, a request rate, a header set, and produces a guess. Good scoring gets you a long way — but every guess carries a false-positive tail, and on a checkout page that tail has a price.

There's a second approach that doesn't guess at all: set things that only a bot can touch.

This is a practical guide to doing that on WordPress. I'll use the WebDecoy plugin for the concrete examples because it's the one I work on and it's free and local, but the technique is the point — you could build most of it yourself in an afternoon.

Why deception is different from detection

A detector says "this request is 80% likely to be automated." A trap says "this request fetched a URL that appears nowhere in your sitemap, nowhere in your HTML, and is disallowed in robots.txt."

The second statement isn't a probability. A human browsing your site cannot accidentally do it.

That property is worth a lot, because the expensive failure in bot blocking isn't the bot you miss — it's the customer you block. A signal with no false-positive tail can drive a hard action (block, ban, refuse checkout) that you'd never dare trigger from a score alone.

So a sane architecture uses both: scoring for breadth, deception for certainty.

The four traps worth setting

1. Tripwire paths

Hidden URLs that only crawlers and scanners request. Nothing links to them, they're disallowed in robots.txt, and they don't appear in your sitemap. Anything that requests one has either ignored robots.txt or is enumerating paths.

WordPress has an unusually rich set of these available, because attackers probe the same handful of things on every WP site:

Fake vulnerable-plugin paths (/wp-content/plugins/<known-CVE-plugin>/…)
An XML-RPC trap
An author-enumeration canary (/?author=1 style probing)

These are the "public scanner" tier. They fire constantly on any site with a public IP, so treat them as a steady background signal rather than something to alert on.

2. Honeytoken links

An invisible decoy link injected into your pages. A human never sees it; a link-following scraper follows it.

The distinction from a tripwire path matters: a tripwire catches something guessing at URLs, a honeytoken catches something parsing your HTML and following every href. Different populations, and the second one is usually the scraper you actually care about.

Because nothing legitimate ever touches it, this is the one trap worth an alert.

A small war story on that: an earlier version of the plugin emailed the admin when the canary tripped. Sensible idea, terrible in practice — the canary link is on every public page, so busy sites got an email every hour, forever. It got removed one release later. Detections belong on a detections page, not in your inbox. If you build this yourself, learn from that: alert on the first trip per source, not every trip.

3. Deceptive files with canary credentials

This is the sharpest one. Serve plausible-looking responses for the files attackers always probe:

/.env
/wp-config.php.bak
/backup.sql
/phpinfo.php

Instead of a 404, return a realistic file — seeded with per-site canary credentials that are valid nowhere.

Now you have a second-stage signal. Requesting /.env tells you someone is probing. Using the database password from that fake .env tells you someone read it and is trying it. That's not reconnaissance any more, that's an attempted intrusion, and it earns an immediate critical classification.

The per-site part matters: the canary has to be unique per install, or a single leaked credential list makes every site's canary identical and useless.

4. A decoy WooCommerce coupon

If you run a store: a hidden coupon code that appears nowhere a customer could find it. Coupon-scraping bots harvest and try codes in bulk. Applying that code at checkout is proof of automation — there is no innocent path to it.

This one is my favourite because it sits exactly where the money is. Card-testing and coupon-abuse bots both hit checkout, and checkout is where a false positive costs you an actual order. A deterministic signal there is worth more than anywhere else on the site.

Start in monitor mode. Actually do it.

The plugin ships in monitor mode by default — it records what it would have done without doing it. That default is correct and you should respect it rather than flipping to blocking on day one.

I wrote a whole piece on why bot detection false positives are a business event, and the short version applies here: you cannot know your false-positive rate until you've watched real traffic, including the weird tail of it — corporate proxies, carrier-grade NAT, accessibility tooling, your own uptime monitors.

Run it in monitor mode across at least one full weekly cycle. Then look specifically at what would have been blocked and ask whether you recognise anyone in there.

# check current mode and counts
wp webdecoy status

# watch first
wp webdecoy config set mode monitor

# ...then, once the would-block list looks clean
wp webdecoy config set mode block

If you manage client sites, you can lock the mode in wp-config.php so a settings save can't silently drift it:

define( 'WEBDECOY_DEFAULT_MODE', 'monitor' );  // or 'block'
define( 'WEBDECOY_MAX_LOG_RETENTION', 90 );    // days, default 30

One design detail I think is worth stealing: an unrecognised value for that constant is ignored rather than guessed. Forcing 'block' on a typo would start enforcing on a site that asked to watch; defaulting to 'monitor' would disarm one that asked to enforce. Neither is a safe guess, so it refuses to make one.

Verify the pipeline actually works

The failure mode nobody talks about with security plugins: it's installed, the dashboard is green, and it isn't actually inspecting anything — because a page cache sits in front of it, or the real client IP never arrives, or the scanner script is being stripped by an optimizer.

Two ways to prove it end to end:

Trip your own canary. The honeytoken's secret path is shown in the settings with a "trip it now" link. Open it and watch the detection land. That exercises the full path: request → trap → scoring → storage → UI.

Hit it with the reserved test User-Agent:

curl -A "WebDecoy-Test/1.0" https://your-site.example/

The plugin records a detection and answers with a 403 JSON receipt, so the curl output itself shows it acted. The test never blocks your IP, never trips enforcement rules, and never fires alerts.

That second one is the check I'd want in a deploy script. A green admin page proves the plugin is installed; a 403 receipt proves it's in the request path.

Don't break your SEO on the way

The single most common way to hurt yourself here is blocking a crawler you needed.

Never allowlist by User-Agent string. Matching Googlebot and letting it through is a bypass, not an allowlist — anyone can send that string, and attackers do precisely because so many plugins trust it. Use forward-confirmed reverse DNS:

Reverse-DNS the requesting IP to a hostname
Check the hostname ends in a verified domain (.googlebot.com)
Forward-resolve that hostname back to an IP
Confirm it matches the original IP

Any decent plugin does this for you — WebDecoy ships a list of 60+ verified crawlers — but check that yours does, because "recognises Googlebot" and "verifies Googlebot" are very different claims.

AI crawlers are a separate decision from search crawlers. GPTBot, ClaudeBot, PerplexityBot and friends can be blocked independently of Googlebot and Bingbot, and you want that as its own switch rather than robots.txt surgery. Worth deciding deliberately: some AI search engines send referral traffic worth having, while pure training scrapers return nothing.

What this doesn't solve

Being honest about the limits, because "deception" can sound like a silver bullet:

Traps catch bots that explore. A scraper that only fetches linked, allowed pages at a human pace will never touch one. That population needs the scoring layer, not the trap layer.
A trap is one signal, not a policy. You still need to decide what a trip does — block, ban, challenge, refuse checkout — and for how long.
Application-layer blocking still costs you the request. The bot reached PHP. If you're being flooded rather than probed, you want blocking at the edge; application-layer detection is where you identify who to push there, not where you absorb volume.
Local means local. No third-party IP reputation, no cross-site intelligence, unless you opt into a cloud tier. That's a genuine tradeoff, not just a privacy talking point.

Install

wp plugin install webdecoy --activate

Or Plugins → Add New → search "WebDecoy". Requires WordPress 6.1+ and PHP 7.4+ (tested to 7.0.x). GPL, free, and with no API key it makes zero external connections — front end or back end. Detection data lives in your own database and cleans itself up after 30 days.

The mental model I'd leave you with: scoring tells you who's probably a bot, deception tells you who definitely is. Most setups have plenty of the first and none of the second, and the second is the cheaper half to build.

If you've deployed honeypot paths or canary tokens on a production site — what actually tripped them first? On ours it's almost always a plugin-vulnerability scanner, long before anything interesting shows up.

Originally published at webdecoy.com.

Bot Protection for WordPress Without CAPTCHAs or API Keys

webdecoy — Sun, 13 Sep 2026 18:29:59 +0000

Most WordPress security plugins ask you to configure rules, connect APIs, tune thresholds, and then hope you got it right. We went the other way: install, activate, done. Every protection layer works immediately with zero configuration and no API key.

This post is about why that design, and what it actually stops.

The two camps, and why neither worked

WordPress powers a large share of the web and is the most targeted CMS for automated attacks. Comment spam, brute force logins, fake registrations, credential stuffing, and WooCommerce carding are daily realities for site owners.

Existing solutions fall into two camps:

CAPTCHA-based plugins force every visitor to prove they're human. Conversion rates drop. Accessibility suffers. And vision models can now solve image challenges programmatically — so you're paying a UX tax for a test the attacker passes and your customer resents.

API-dependent plugins require accounts, keys, and external services. They charge per request, which means costs spike during attacks — exactly when you need protection most. If the API goes down, your protection disappears with it.

So: all detection runs locally, on your server and in the visitor's browser. No external dependencies. No per-request billing. No CAPTCHAs. Humans never see a challenge.

Zero-config, and what that actually means

Earlier versions required an API key before protection hooks would activate. That requirement is gone. Every detection layer — server-side analysis, client-side fingerprinting, proof-of-work challenges, rate limiting — runs locally without any external connection.

An optional Cloud integration adds threat intelligence feeds, VPN detection, and cross-site threat sharing for teams managing multiple installs. The core protection needs none of it. That's the part worth stressing: the free path isn't a crippled trial, it's the whole detection engine.

SHA-256 proof-of-work instead of a CAPTCHA

Rather than showing a challenge, the plugin issues invisible SHA-256 proof-of-work. The browser computes a valid hash before a form submission is accepted. For humans on modern hardware this takes milliseconds and is completely invisible. For bots running thousands of concurrent sessions, the compute cost makes attacks economically unviable.

Same principle as FCaptcha, our open-source CAPTCHA replacement, adapted for WordPress's form handling.

4-factor behavioral scoring

Every form submission is evaluated across four weighted signal categories:

Behavioral (40%) — interaction timing, keystroke patterns, mouse movement characteristics
Environmental (35%) — browser consistency checks, headless detection, automation framework markers
Temporal (15%) — time-on-page, submission velocity, session duration anomalies
Form (10%) — honeypot triggers, field completion order, paste detection

Each category contributes a weighted score; the combined result decides allow, flag, or block. No single signal is decisive — the system looks at the full picture. That's deliberate: binary checks are how you end up blocking a real customer on a Tuesday because they had one unusual header.

What it protects

Comment and form spam. Invisible detection is injected into comment, login, and registration forms. Honeypot fields catch simple bots, proof-of-work stops headless browsers, behavioral scoring catches everything in between. Hooks activate automatically for standard WordPress forms.

Login and registration attacks. Brute force and fake registrations are blocked through rate limiting and behavioral analysis. The plugin tracks failed-login velocity per IP and blocks sources that exceed thresholds.

WooCommerce carding. Fraudsters test stolen cards against your checkout. Every declined transaction generates processor fees — enough declines and your payment provider drops you. The plugin detects the pattern: multiple small transactions from one IP, rapid checkout velocity, different card numbers in quick succession, headless signatures on the checkout page. Detected carders are blocked before reaching your payment processor.

Content scraping and AI crawlers. Identifies and blocks unauthorized scrapers including GPTBot, ClaudeBot, and others. Legitimate crawlers — Googlebot, Bingbot, and 60+ more — are verified through forward-confirmed reverse DNS, not by trusting the User-Agent string, and always allowed through. Your SEO stays intact.

MITRE ATT&CK path analysis. Requests probing for wp-config.php, admin endpoints, backup files, and other sensitive paths are flagged as reconnaissance — not just logged, but fed into the scoring model as signals.

Under the hood: two layers that cross-reference

Server-side analysis examines every request before WordPress processes it: user-agent patterns, header consistency, request rates, IP reputation, path analysis. Known good bots are verified via reverse DNS and exempted immediately.

Client-side fingerprinting runs in the visitor's browser checking for headless markers, automation framework signatures (Playwright, Puppeteer, Selenium), browser API consistency, and environmental anomalies. The fingerprint is submitted alongside form data and validated server-side.

When the two layers disagree — a request claims to be Chrome but client-side checks detect Playwright markers — the threat score increases significantly. The disagreement is the signal.

IP management

Individual addresses and CIDR ranges
IPv4 and IPv6
Optional expiration (temporary blocks that auto-release)
Bulk operations for large block lists

Expiring blocks matter more than they look. A permanent block list is a growing pile of decisions nobody revisits, and shared IPs rotate — today's abusive address is next month's office NAT.

Local dashboard

A statistics page with trend visualization: detection volume over 30 days, threat type distribution (spam bots, scrapers, credential stuffing, carding), top blocked IPs and their attack patterns, and source analysis. The detections interface supports date filtering, CSV export, and bulk operations.

All of it renders from your own database. Detection data cleans itself up after 30 days, and the charting library is bundled into the plugin rather than loaded from a CDN — so the dashboard makes no third-party requests either.

Install

wp plugin install webdecoy --activate

Or Plugins → Add New → search "WebDecoy". Protection starts immediately; there is no step three.

Requirements: WordPress 6.1+, PHP 7.4+. GPL v2, open source at github.com/WebDecoy/wordpress-plugin.

If you want the detection internals — the scoring table, the MITRE mapping, the HMAC-signed proof-of-work design — I wrote those up separately in Inside a WordPress Bot Detection Engine.

If you run WooCommerce: have you actually measured your decline rate from card testing? It's the one bot cost that shows up directly on a processor invoice, and most stores never look.

Originally published at webdecoy.com.

Related reading:

Inside a WordPress Bot Detection Engine

webdecoy — Sun, 13 Sep 2026 16:54:36 +0000

The WebDecoy WordPress plugin ships with zero configuration required. But underneath the "install, activate, done" experience is a multi-layer detection engine that scores every request across server-side signals, client-side fingerprints, behavioral analysis, and proof-of-work verification.

This post walks through how each layer works, how they combine into a single threat score, and why this architecture catches bots that simpler approaches miss. It's a WordPress plugin, but the scoring design applies to any request pipeline.

The Detection Pipeline

Every request flows through a pipeline that evaluates it before WordPress processes it:

Incoming Request
  │
  ├─ Is this IP blocked? → Yes → Block page
  │
  ├─ Is this a known good bot? → Verify via reverse DNS → Allow
  │
  ├─ Server-side analysis
  │    ├─ User-Agent patterns
  │    ├─ HTTP header consistency
  │    ├─ MITRE ATT&CK path matching
  │    └─ Rate limit check
  │
  ├─ Client-side signals (on form submission)
  │    ├─ WebDriver / headless detection
  │    ├─ Automation framework markers
  │    ├─ Canvas / WebGL fingerprint
  │    └─ Behavioral scoring
  │
  ├─ Proof-of-Work verification (on form submission)
  │    └─ SHA-256 challenge validation
  │
  └─ Score aggregation → Allow / Challenge / Block

The first two checks are fast exits. Blocked IPs get rejected immediately. Verified good bots skip detection entirely. Everything else gets scored.

Threat Scoring: 0 to 100

Every detection signal adds points to a threat score. The score determines what happens to the request:

Score Range	Severity	Action
0–19	Minimal	Allow (likely human)
20–39	Low	Log only
40–59	Medium	Optional challenge
60–74	High	Challenge or block
75–100	Critical	Automatic block

The default blocking threshold is 75, configurable in settings. Scores at 40 and above are logged for review.

The scoring is additive. A request doesn't need to fail one dramatic test — it accumulates evidence across multiple signals. A slightly suspicious user agent (+25) combined with missing cookies (+15) and an unusual request path (+20) adds up to 60, enough to trigger a challenge. No single signal is conclusive, but the combination tells a clear story.

Base scores for common signals:

Missing standard headers:      10-30
No cookies on non-first visit:    15
Suspicious user agent:            25
Known bot user agent:             50
curl / wget / python-requests:    35
Automation tool detected:         40
Headless browser markers:         25
Rate limit exceeded:              25
Honeypot field triggered:         60
Fake bot (failed DNS verify):     80

A real Chrome browser hitting a normal page scores near zero. A Python script with a spoofed user agent, no cookies, and missing standard headers quickly crosses the blocking threshold.

Server-Side Analysis

User-Agent and header consistency

The plugin checks the User-Agent against known bot patterns (curl, wget, python-requests, Go-http-client, scrapy, and dozens more) and evaluates header consistency. Real browsers send a predictable set of headers — Accept, Accept-Language, Accept-Encoding, Connection — in a consistent order. Automated tools frequently omit headers or send them in unusual combinations.

Missing Accept-Language is a strong signal. Every real browser sends it. Most HTTP libraries don't unless explicitly configured.

MITRE ATT&CK path matching

This is one of the more distinctive pieces. Rather than maintaining an arbitrary blocklist of "bad" URLs, detection is organized by attacker tactic:

Credential Access (TA0006):
  .env, wp-config.php, .git/, *.sql         → +30 points

Collection (TA0009):
  Backup files, database dumps              → +25 points

Reconnaissance (TA0043):
  Admin probes, user enumeration            → +20 points

Discovery (TA0007):
  Debug endpoints, phpinfo, server-status   → +20 points

When an IP requests /wp-config.php.bak, then /.env, then /.git/config, each request scores individually while the rate limiter tracks velocity. The combined effect is rapid escalation to the blocking threshold.

The mapping isn't only for scoring. It surfaces in the detections table, so you can see a blocked IP was performing credential access reconnaissance rather than just "requesting bad URLs." The categorization tells you what attackers are actually looking for.

Rate limiting

Tracks requests per IP with a configurable window (default: 60 requests per 60 seconds). Exceeding it adds 25 points and can trigger automatic blocking.

The limiter uses the WordPress database for tracking, so it works behind load balancers and CDNs as long as the real client IP is forwarded in a standard header (X-Forwarded-For, X-Real-IP, or CF-Connecting-IP).

Client-Side Detection

The server-side layer catches unsophisticated bots. The client-side layer targets headless browsers, automation frameworks, and tools that spoof headers but can't perfectly replicate a real browser environment.

A scanner script loads with defer so it never blocks rendering, runs environment checks, and submits results alongside form data.

WebDriver detection — the simplest check. Selenium, Puppeteer, and Playwright all set navigator.webdriver = true by default. Stealth plugins override this, but it still catches unmodified tooling.

Headless markers — HeadlessChrome in the UA string, missing chrome.runtime and chrome.app objects (present in real Chrome, absent in headless), PhantomJS signatures on window.

Chrome consistency — a request claiming Chrome should have the chrome global with chrome.runtime, chrome.app, chrome.csi. If the UA says Chrome but these are missing or structurally wrong, the environment has been tampered with.

Behavioral scoring

For form submissions, the plugin evaluates how the user interacted with the page. This is where most sophisticated bots fail, because generating convincing human behavior at scale is genuinely hard.

Behavioral signals (40% weight):
  - Mouse velocity variance
  - Straight-line movement ratio
  - Micro-tremor score (natural hand movement)

Environmental signals (35% weight):
  - Headless browser markers
  - Automation framework detection
  - Browser API consistency

Temporal signals (15% weight):
  - Time on page before submission
  - Form completion velocity
  - Session duration

Form signals (10% weight):
  - Honeypot field triggers
  - Field completion order
  - Paste detection

Mouse velocity variance is particularly effective. Humans move with variable speed — accelerating, decelerating, overshooting, correcting. Bots that simulate movement typically use linear interpolation or simple easing functions, producing unnaturally smooth velocity profiles.

Straight-line movement ratio measures what percentage of movements travel in perfectly straight lines. Humans almost never do, because of micro-tremors and natural imprecision.

Micro-tremor score looks for the tiny involuntary oscillations present in all human hand movement. These have characteristic frequency patterns that are difficult to simulate; their absence suggests input generated by code.

Honeypot fields, rotated daily

Invisible form fields real users never see. If a field receives a value, the submission came from a bot that filled every input on the page.

What makes the implementation interesting is the obfuscation. Instead of obvious names like honeypot or trap, the plugin generates legitimate-looking field names that change daily:

// Field names rotate using a daily seed
// Examples of generated names:
//   contact_name, user_email, address_field, phone_number
// CSS class prefixes mimic common form frameworks:
//   form-, input-, wp-, cf-, gform-, ninja-

Daily rotation stops bot operators hardcoding a skip-list of honeypot names. The realistic naming defeats bots that filter for obvious trap patterns.

Proof-of-Work Challenges

The layer that makes automated attacks economically painful even when bots pass everything else.

When a form loads, the server generates a challenge: a random hex prefix and a difficulty parameter. The client must find a nonce where SHA-256(prefix + nonce) starts with N zero hex characters. There's no shortcut — it's brute force.

Server generates:
  prefix:      "a7f3c8e91b04d265"   (16 hex chars from 8 random bytes)
  difficulty:  4                     (requires 4 leading zero hex chars)
  expires:     current_time + 5 minutes
  signature:   HMAC-SHA256(challenge_data, wordpress_auth_key)

Client computes:
  nonce = 0:  SHA-256("a7f3c8e91b04d265" + "0") = "7f2a..."   (fail)
  nonce = 1:  SHA-256("a7f3c8e91b04d265" + "1") = "b391..."   (fail)
  ...
  nonce = N:  SHA-256("a7f3c8e91b04d265" + "N") = "0000a..."  (pass)

Client submits:  { challengeId, nonce, signature }

At difficulty 4, the client tries roughly 65,536 hashes on average — milliseconds on modern hardware, entirely in the background while the user fills out the form. They never see it.

Why it stops bots: a single challenge is trivial, but the economics change at scale. A bot submitting 10,000 spam comments needs 10,000 challenges — about 655 million hash operations. Achievable, but it costs real compute.

Difficulty also scales with threat signals. An IP already flagged by server-side analysis gets harder challenges. Default difficulty 4 is intentionally low for normal users; suspicious traffic might face difficulty 6, roughly 16 million hashes per challenge.

Replay prevention

Each challenge carries an HMAC signature generated with WordPress's AUTH_KEY salt. The server verifies the signature before checking the hash, which prevents:

Challenge reuse — each challenge ID is single-use
Challenge tampering — difficulty and prefix are signed, so they can't be modified
Challenge forging — without AUTH_KEY, valid signatures can't be generated
Stockpiling — a 5-minute TTL kills pre-solved challenges

Signing rather than storing means the server never writes issued challenges to the database. That keeps the table clean and removes a DoS vector where an attacker floods the challenge endpoint to fill storage.

Good Bot Verification

Not all bots are bad. Googlebot, Bingbot, and 60+ other legitimate crawlers need unimpeded access for indexing, previews, uptime monitoring, and SEO tooling.

Search engines:   Googlebot, Bingbot, YandexBot, Baiduspider,
                  DuckDuckBot, Applebot
Social:           Facebook, LinkedIn, Twitter, Pinterest
Monitoring:       Pingdom, UptimeRobot, StatusCake, Datadog
SEO tools:        Ahrefs, SEMrush, Moz, Majestic
Feed readers:     Feedly, NewsBlur
AI crawlers:      GPTBot, ClaudeBot, PerplexityBot (optional blocking)

For verifiable bots, the plugin does forward-confirmed reverse DNS:

Look up the requesting IP's hostname via reverse DNS
Check the hostname ends with a verified domain (.googlebot.com, .google.com)
Forward-resolve that hostname back to an IP
Confirm it matches the original requesting IP

A fake Googlebot scores +80 — an instant block — because spoofing a search crawler is a strong signal of intent. Results cache in WordPress transients with a 1-hour TTL to avoid repeated lookups.

This matters more than it sounds: matching Googlebot in a User-Agent string and allowing it is a bypass, not an allowlist. Anyone can send that string.

WooCommerce: carding defense

Attackers test stolen card numbers against real checkout flows. Every failed transaction generates processor fees, and a high decline rate can get your payment processing suspended.

Checkout velocity limiting — configurable max checkout attempts per IP per window (default: 5 per hour). Legitimate shoppers rarely attempt checkout more than once or twice. An IP submitting 20 attempts in an hour is testing cards.

Card testing pattern detection — multiple different card numbers from one IP, rapid sequential attempts, and headless signatures on the checkout page all trigger detection, blocking before further transactions reach the processor.

Compatible with classic checkout and WooCommerce Blocks, and declares HPOS (High-Performance Order Storage) compatibility.

Architecture decisions worth calling out

No external dependencies for core protection. The entire detection engine runs on your server. No API calls during request processing, no third-party JavaScript on the frontend. Protection works during API outages, on airgapped installs, and at any traffic volume without per-request costs. Even the admin dashboard's charting library is bundled into the plugin rather than pulled from a CDN, so the plugin makes zero external connections unless you explicitly add a Cloud API key.

Additive scoring over binary decisions. Every signal adds to a score rather than making a pass/fail call. This dramatically reduces false positives: a single suspicious signal might be coincidence, five together are a pattern. No single check that misfires can block a legitimate user on its own.

Daily rotating honeypot names. Static names get learned and skip-listed. Seeded rotation changes them daily while staying deterministic, so the server can verify which fields are honeypots without storing state.

HMAC-signed challenges instead of stored ones. The signature itself proves the challenge is legitimate and unmodified — no database writes, no storage-exhaustion vector.

Getting started

wp plugin install webdecoy --activate

Or: Plugins → Add New → search "WebDecoy" → Install → Activate.

Defaults (sensitivity medium, block threshold 75, rate limit 60/min, PoW difficulty 4) work for most sites. Requires WordPress 6.1+ and PHP 7.4+. GPL-licensed.

If you're building request scoring in any stack, the transferable idea here is the additive model: resist the urge to make any single signal decisive, and let evidence accumulate instead. It's the difference between a detector that's occasionally spectacularly wrong and one that's boringly right.

How do you handle bot scoring — hard rules or weighted signals? Curious what thresholds other people have landed on.

Originally published at webdecoy.com.

Related reading: