bot-detect

A simple bot detection library for Node.js.

Installation

npm install bot-detect

Usage

This library can be used in different contexts. The following sections illustrate common use cases.

Express.js Middleware

This is the typical way to use bot-detect in a web application. You integrate it as middleware in your Express.js app.

const BotDetector = require('bot-detect');
const express = require('express');
const app = express();

const detector = new BotDetector({
  suspiciousRequestThreshold: 5,  // Number of suspicious actions before flagging IP
  suspiciousIpThreshold: 20,       // Number of suspicious IPs before flagging bot activity
  suspiciousIpWindowMs: 60000,    // Time window for suspicious IP tracking (1 minute)
  rateLimit: 10,                   // Maximum requests per second per IP
  rateLimitWindowMs: 1000,         // Time window for rate limiting (1 second)
  // ... other options (see Options section below)
});

app.use((req, res, next) => {
  if (detector.isBot(req)) {
    console.log("Bot detected by middleware!");
    return res.status(403).send("Forbidden"); // Or other appropriate action
  }
  next(); // Continue to the next middleware/route handler
});

// ... rest of your Express.js server code ...

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

app.listen(3000, () => {
    console.log("Server is listening on port 3000");
})

Testing or CLI Scripts (Mock Requests)

You can use bot-detect outside of a web server context by creating mock request objects. This is helpful for testing your bot detection logic or using it in command-line scripts.

const BotDetector = require('bot-detect');
const detector = new BotDetector({ /* ... options ... */ });

const mockRequest = {
  ip: '192.168.1.100', // Replace with a real IP or test IP.
  headers: {
    'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...', // Or a known bot UA for testing
    'x-request-time': 150, // Example of rapid request time (if your detector uses it)
  },
};

if (detector.isBot(mockRequest)) {
  console.log("Bot detected (mock request)!");
} else {
  console.log("Not a bot (mock request)");
}

// Example with a different mock request
const mockRequest2 = {
    ip: '192.168.1.101',
    headers: {
        'user-agent': 'Mozilla/5.0',
        'x-custom-header': 'suspicious-value'
    }
}

if (detector.isBot(mockRequest2)) {
    console.log("Bot detected using custom check!");
}

Custom Checks (Extending Functionality)

You can extend the bot detection logic by adding custom checks to the checkForSuspiciousActions function.

const BotDetector = require('bot-detect');
const detector = new BotDetector({ /* ... options ... */ });

detector.checkForSuspiciousActions = function(req) {
    let suspicious = false;
    const customHeader = req.headers['x-custom-header'];

    if (customHeader === 'suspicious-value') {
        suspicious = true;
        console.log("Custom suspicious header detected!");
    }
    return suspicious;
}

// ... then use the detector as usual

Options

The BotDetector constructor accepts an options object with the following properties:

suspiciousRequestThreshold (Number, default: 3):  The number of suspicious actions an IP can take within the suspiciousIpWindowMs before it is considered suspicious.

suspiciousIpThreshold (Number, default: 10): The number of suspicious IPs within the suspiciousIpWindowMs before bot activity is suspected.

suspiciousIpWindowMs (Number, default: 60000): The time window (in milliseconds) for tracking suspicious IPs (e.g., 60000 for 1 minute).

rateLimit (Number, default: 5): The maximum number of requests allowed per IP within the rateLimitWindowMs.

rateLimitWindowMs (Number, default: 1000): The time window (in milliseconds) for rate limiting (e.g., 1000 for 1 second).