JSRAB (JavaScript Regex Anti-Bot)

JSRAB is a highly advanced, enterprise-grade filtration service and anti-cheat engine designed specifically for Node.js real-time applications, WebSockets, and multiplayer games.

By combining mathematical entropy analysis, leaky-bucket rate limiting, physics-based movement tracking, and comprehensive regex validation, JSRAB protects your server from spam joins, packet flooding, SQLi/XSS injection, speed-hacking, and automated macro bots.

Features

• Reputation-Based Penalties: Clients are assigned a reputation score. Minor infractions (like spamming actions) lower the score. Severe infractions (injection attempts) result in immediate bans. Scores naturally recover over time for legitimate players.
• Physics Anomaly Detection: Calculates vector velocity (Distance over Time) to detect speed-hacking and teleportation in game environments.
• Mathematical Entropy Analysis: Calculates the Shannon Entropy of string payloads to detect "keyboard mashing" bots (e.g., asdfqwer or aaaaaa).
• Connection Mitigation: Protects against DDoS/Botnet connection flooding using token-bucket rate limits per IP.
• Deep Regex Filtration: Configurable regex matrices to catch XSS, SQL Injection, Command Injection, and chat spam.
• Professional Telemetry: Clean, non-intrusive, enterprise-standard logging. No AI-generated conversational logs. Just raw, actionable data.

Installation

npm install jsrab

Usage & Integration

JSRAB is designed to be injected at the middleware or socket interception layer of your application.

Example 1: Integrating with WebSockets (ws)

const WebSocket = require('ws');
const JSRab = require('jsrab');

const wss = new WebSocket.Server({ port: 8080 });

// Initialize JSRAB with custom thresholds
const antiBot = new JSRab({
    reputation: { banThreshold: 0, startingScore: 100 },
    inputs: { maxActionsPerSecond: 20 },
    movement: { maxVelocityPerSecond: 60.5 }
});

// Event Listeners for telemetry & logging
antiBot.on('ban', (data) => {
    // data: { identifier, reason, expiration }
    console.log(`[SEC-OPS] Target locked out: ${data.identifier}`);
});

wss.on('connection', (ws, req) => {
    const ip = req.socket.remoteAddress;
    const clientId = generateUniqueId(); 
    
    // 1. Connection Filtration
    if (!antiBot.evaluateConnection(ip, clientId)) {
        return ws.close(4000, 'Connection rejected by security policy.');
    }

    ws.on('message', (message) => {
        const payload = message.toString();

        // 2. Payload & Regex Filtration
        if (!antiBot.evaluatePayload(clientId, payload)) {
            // Malicious payload detected. JSRAB handles reputation drops automatically.
            return; 
        }

        // 3. Action / Spam Limiting
        if (!antiBot.evaluateAction(clientId)) {
            ws.send(JSON.stringify({ error: 'Rate limit exceeded. Slow down.' }));
            return;
        }

        // 4. Movement Validation (If payload is a movement packet)
        const parsed = JSON.parse(payload);
        if (parsed.type === 'MOVE') {
            const isValid = antiBot.evaluateMovement(clientId, parsed.x, parsed.y, parsed.z);
            if (!isValid) {
                // Client is speed-hacking or lagging heavily. Rubber-band them.
                ws.send(JSON.stringify({ type: 'RUBBER_BAND', msg: 'Movement anomalous' }));
                return;
            }
        }
        
        // Process legitimate game logic here...
    });
});

Advanced Configuration Options

JSRAB is completely customizable. You can pass an options object to the constructor to override any default limit.

const customOptions = {
    reputation: {
        startingScore: 100,
        banThreshold: 0,      // Score at which a ban is triggered
        warnThreshold: 40,    // Score at which 'warn' event is emitted
        decayRate: 5,         // Points passively recovered per minute
    },
    connections: {
        maxPerIpPerMinute: 10,
        blockDurationMs: 900000, // 15 minutes
    },
    inputs: {
        maxPayloadSizeBytes: 2048,
        maxActionsPerSecond: 15,
        gibberishDetection: true,
        minEntropy: 1.2, // Below this = repetitive spam (aaaaa)
        maxEntropy: 4.8, // Above this = high-randomness bots (a%1g#9v)
    },
    movement: {
        enabled: true,
        maxVelocityPerSecond: 50.0,
        toleranceBuffer: 1.1, // 10% leniency for network latency
    },
    regex: {
        enabled: true,
        patterns: [
            // Add custom patterns. 'penalty' is how much reputation is lost.
            { name: 'PROFANITY', regex: /\b(badword1|badword2)\b/i, penalty: 15 }
        ]
    },
    logging: {
        enabled: true,
        level: 'WARN' // Options: DEBUG, INFO, WARN, ERROR
    }
};

const antiBot = new JSRab(customOptions);

Events API

JSRAB extends the standard Node EventEmitter. You can listen to the following events to bridge JSRAB with your database or UI:

| Event | Description | Payload Data | |-------|-------------|--------------| | flag | Fired when a client loses reputation points. | { clientId, reason, penalty, remainingReputation } | | warn | Fired when a client's reputation drops below the warning threshold. | { clientId, reputation } | | ban | Fired when a client hits 0 reputation or is IP-blocked. | { identifier, reason, expiration } |

Built for scale.