@bottoll/express

Official Bottoll WAF middleware for Express.

Bottoll protects Express applications against AI crawlers, AI agents, scrapers and automated bot traffic before requests reach your application.

Express Only

This package is designed for Express-based applications.

Supported environments:

• Express.js
• NestJS (Express adapter)
• Express-compatible middleware stacks

Prerequisites

A Bottoll account is required.

Create an account and generate an API key from:

https://app.bottoll.com

If no valid API key is configured, Bottoll filtering is automatically disabled and requests continue normally.

Installation

npm install @bottoll/express

Configuration

Register the Bottoll middleware before your application routes.

import express from "express";
import { bottoll } from "@bottoll/express";

const app = express();

app.use(
    bottoll({
        apiKey: process.env.BOTTOLL_API_KEY,
    })
);

app.listen(3000);

Add your API key to your environment variables:

BOTTOLL_API_KEY=your_api_key

Start your application.

How It Works

For every incoming request:

1. The Bottoll middleware intercepts the request.
2. Request metadata is securely sent to Bottoll.
3. Bottoll analyzes the request using its WAF engine.
4. Bottoll returns an allow or block decision.
5. Allowed requests continue normally.
6. Blocked requests receive a 403 Forbidden response.

Request Data

Bottoll processes only the metadata required for request evaluation and bot detection.

This may include:

• IP address
• User-Agent
• Request path
• Request method
• Standard HTTP headers

The following sensitive headers are automatically excluded before transmission:

• Authorization
• Cookie
• Set-Cookie
• Proxy-Authorization
• X-CSRF-Token
• X-XSRF-Token

Complete Example

import express from "express";
import { bottoll } from "@bottoll/express";

const app = express();

app.use(
    bottoll({
        apiKey: process.env.BOTTOLL_API_KEY,
    })
);

app.get("/", (req, res) => {
    res.send("Hello World");
});

app.listen(3000);

Fail-Open Behavior

If Bottoll is temporarily unavailable or an unexpected error occurs, requests are allowed to continue.

This prevents Bottoll from causing downtime for your application.

Response Codes

200

The request is allowed.

403

The request is blocked by Bottoll.

Requirements

• Node.js 18 or later
• Express 4+

Documentation

https://bottoll.com/docs

Dashboard

https://app.bottoll.com

Website

https://bottoll.com

License

MIT