Secure Rate Limiter 🛡️

Advanced rate-limiting middleware for Node.js with comprehensive bot detection, behavioral analysis, and DDoS protection.

Features

• Multi-layered Protection: Rate limiting, burst detection, behavioral analysis
• Advanced Bot Detection: Pattern-based detection beyond simple user-agent checks
• IP Spoofing Detection: Identifies suspicious header manipulation
• Temporary Banning: Progressive punishment system for repeat offenders
• Connection Limiting: Prevents connection flooding attacks
• Behavioral Analysis: Detects script-like timing patterns and fingerprint rotation
• Comprehensive Logging: Security event logging with detailed analytics
• Memory Efficient: Automatic cleanup of old tracking data

Installation

1npm install secure-rate-limiter

Quick Start

1const express = require('express');
2const SecureRateLimiter = require('secure-rate-limiter');
3
4const app = express();
5
6// Initialize with default settings
7const limiter = new SecureRateLimiter();
8
9// Apply to all routes
10app.use(limiter.middleware());
11
12// Or apply to specific routes
13app.get('/api/*', limiter.middleware(), (req, res) => {
14  res.json({ message: 'API endpoint protected' });
15});
16
17app.listen(3000);

Configuration

1const limiter = new SecureRateLimiter({
2  windowMs: 60 * 1000,           // Time window (1 minute)
3  maxRequests: 50,               // Max requests per window
4  burstThreshold: 10,            // Max requests in burst window
5  burstWindowMs: 5 * 1000,       // Burst detection window (5 seconds)
6  delayThresholdMs: 500,         // Min delay between requests (ms)
7  suspiciousThreshold: 3,        // Strikes before temp ban
8  tempBanDurationMs: 10 * 60 * 1000, // Temp ban duration (10 minutes)
9  maxConnectionsPerIP: 20,       // Max concurrent connections per IP
10  botKeywords: [                 // Additional bot detection keywords
11    'mybot', 'scraper'
12  ]
13});

Advanced Usage

Manual IP Management

1// Ban an IP manually
2limiter.banIP('192.168.1.100', 'Suspicious activity');
3
4// Unban an IP
5limiter.unbanIP('192.168.1.100');
6
7// Get current statistics
8const stats = limiter.getStats();
9console.log(stats);
10// {
11//   totalFingerprints: 150,
12//   tempBannedIPs: 5,
13//   suspiciousIPs: 12,
14//   activeConnections: 45
15// }

Custom Bot Detection

1const limiter = new SecureRateLimiter({
2  botKeywords: [
3    'Googlebot', 'Bingbot', 'curl', 'wget',
4    'python-requests', 'scrapy', 'selenium'
5  ]
6});

Environment-Specific Configuration

1// Development - More lenient
2const devLimiter = new SecureRateLimiter({
3  maxRequests: 1000,
4  burstThreshold: 50,
5  tempBanDurationMs: 60 * 1000 // 1 minute
6});
7
8// Production - Strict security
9const prodLimiter = new SecureRateLimiter({
10  maxRequests: 30,
11  burstThreshold: 5,
12  delayThresholdMs: 1000,
13  tempBanDurationMs: 30 * 60 * 1000 // 30 minutes
14});

Protection Mechanisms

1. Rate Limiting

• Tracks requests per IP/fingerprint combination
• Configurable time windows and request limits
• Progressive enforcement with temporary bans

2. Burst Detection

• Monitors rapid-fire requests in short time windows
• Separate threshold for burst vs sustained traffic
• Immediate blocking of burst attacks

3. Bot Detection

• User-Agent analysis with keyword matching
• Header pattern analysis (missing standard headers)
• Behavioral fingerprinting

4. Behavioral Analysis

• Request timing analysis to detect scripts
• User-Agent rotation detection
• Multiple fingerprint tracking per IP

5. Connection Limiting

• Prevents connection flooding
• Per-IP concurrent connection limits
• Automatic cleanup on connection close

6. IP Spoofing Detection

• Analyzes conflicting IP headers
• Detects header manipulation attempts
• Blocks requests with suspicious header combinations

Logging

The middleware creates detailed logs in the logs/ directory:

• requests.log - All requests with classifications
• security.log - Security events only (blocks, bans, suspicious activity)

Log format:

2024-01-15T10:30:45.123Z | IP: 192.168.1.100 | UA: Mozilla/5.0... | Status: blocked | Burst limit exceeded

Performance Considerations

• Memory Usage: Automatic cleanup prevents memory leaks
• CPU Impact: Minimal overhead with efficient algorithms
• Scalability: Designed for high-traffic applications
• Cleanup: Automatic cleanup every 5 minutes removes stale data

Integration Examples

Express.js

1const express = require('express');
2const SecureRateLimiter = require('secure-rate-limiter');
3
4const app = express();
5const limiter = new SecureRateLimiter();
6
7app.use(limiter.middleware());

Koa.js

1const Koa = require('koa');
2const SecureRateLimiter = require('secure-rate-limiter');
3
4const app = new Koa();
5const limiter = new SecureRateLimiter();
6
7app.use(async (ctx, next) => {
8  return new Promise((resolve, reject) => {
9    limiter.middleware()(ctx.req, ctx.res, (err) => {
10      if (err) reject(err);
11      else resolve(next());
12    });
13  });
14});

Testing Against Attacks

The middleware has been tested against various attack patterns:

• High-volume request floods
• Rotating User-Agent attacks
• IP header spoofing
• Distributed attacks with multiple IPs
• Timing-based evasion attempts

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: Report a bug
• Documentation: See examples above
• Version: 2.0.0