🛡️ BRShield

Advanced security middleware for Node.js — WAF, rate limiting, bot detection, and IP reputation.

Features

| Protection | Details | |---|---| | 🔥 WAF | Blocks XSS, SQLi, path traversal, command injection — case-insensitive, URL-decoded | | ⏱️ Rate Limiting | Sliding-window per-IP with automatic banning | | 🤖 Bot Detection | User-agent fingerprinting, header heuristics, known attack tools | | 🌐 IP Resolution | Hardened against X-Forwarded-For spoofing — trusted proxy whitelist | | 📋 Structured Logging | JSON logs compatible with Datadog, Loki, CloudWatch | | 🔌 Custom Hooks | onBlocked callback for custom responses |

Install

npm install brshield

Quick Start

import express from 'express';
import { shield } from 'brshield';

const app = express();
app.use(express.json());
app.use(shield());

app.get('/', (req, res) => res.json({ ok: true }));
app.listen(3000);

Configuration

app.use(shield({
  rateLimit: {
    windowMs: 10_000,   // sliding window in ms (default: 10s)
    max: 20,            // max requests per window (default: 20)
    banTime: 60_000,    // ban duration in ms (default: 60s)
  },

  risk: {
    blockScore: 50,     // score threshold to block (0–100, default: 50)
  },

  // IPs that are allowed to set X-Forwarded-For
  // (your Nginx, load balancer, Cloudflare egress IPs, etc.)
  // Leave empty [] to always use the direct socket IP (safest default).
  trustedProxies: ['10.0.0.1', '10.0.0.2'],

  logging: true,        // structured JSON logs (default: true)

  // Custom blocked response handler
  onBlocked: (req, res, err) => {
    res.status(err.statusCode).json({
      message: 'Access denied',
      code: err.code,
    });
  },
}));

Risk Score

Each request receives a risk score (0–100). If the score reaches blockScore, the request is blocked.

| Flag | Score | Trigger | |---|---|---| | Rate limited | +20 | Exceeds req/window | | Bot detected | +30 | Suspicious headers / bad UA | | WAF hit | +50 | Malicious payload found |

A WAF hit alone (50 pts) immediately triggers a block at the default threshold.

Response Codes

| Situation | HTTP Status | |---|---| | WAF / Bot block | 403 Forbidden | | Rate limited / Banned | 429 Too Many Requests |

Trusted Proxies & IP Spoofing

By default, X-Forwarded-For is completely ignored.

This prevents attackers from faking their IP to bypass rate limiting:

X-Forwarded-For: 127.0.0.1   ← ignored unless your proxy IP is trusted

Only add IPs to trustedProxies that you control (your Nginx, Cloudflare edge IPs, etc.).

WAF Coverage

• XSS: <script>, javascript:, event handlers (onerror=, onclick=), <iframe>, <svg>
• SQLi: OR 1=1, UNION SELECT, DROP TABLE, -- comments, inline /* */ comments
• Path Traversal: ../, %2e%2e%2f
• Command Injection: shell metacharacters + common commands
• Encoding bypasses: URL-decoded before scanning

All patterns are case-insensitive and applied to: URL, request body, User-Agent, Referer, Cookie, X-Forwarded-For.

Exports

import { shield, createShield, SecurityError, Codes } from 'brshield';

| Export | Description | |---|---| | shield(opts) | Alias for createShield — drop-in middleware factory | | createShield(opts) | Middleware factory with full options | | SecurityError | Typed error class (err.code, err.statusCode) | | Codes | { RATE_LIMITED, BANNED, WAF_BLOCKED, BOT_DETECTED } |

Requirements

• Node.js >= 18
• Works with Express, Fastify (with adapter), or any framework that uses Node's IncomingMessage

License

MIT