request-risk-score

A privacy-respecting, lightweight Node.js package to analyze HTTP requests and calculate a risk score (0-100) indicating the likelihood of the request being a bot or automated script.

Features:

🚀 Lightweight: Zero runtime dependencies (mostly).
🔒 Privacy Needed: No external APIs, no browser fingerprinting, no PII logging.
🧠 Probabilistic: Returns a score, not a binary "block/allow".
⚡ Performance: In-memory caching and efficient heuristics.

Installation

npm install request-risk-score

Usage

const { analyzeRequest } = require('request-risk-score');

// In your request handler (Express, HTTP, etc.)
app.use((req, res, next) => {
  const risk = analyzeRequest(req);
  
  if (risk.bucket === 'high') {
    console.log(`Blocked suspicious request from ${risk.ip}. Score: ${risk.score}`);
    console.log('Signals:', risk.signals);
    return res.status(403).send('Request verification failed.');
  }

  // Add risk info to request for downstream logic
  req.risk = risk;
  next();
});

Response Object

{
  "score": 78,
  "bucket": "high",
  "signals": [
    "no_user_agent",
    "rate_limit_exceeded",
    "regular_request_timing"
  ],
  "ip": "203.0.113.10"
}

Decision Buckets

Score	Bucket	Recommendation
0-39	`likely_human`	Likely Human. Allow.
40-69	`suspicious`	Suspicious. Monitor or CAPTCHA?
70-100	`likely_automated`	Likely Bot. Block or Challenge.

Configuration

You can pass an options object to analyzeRequest:

const options = {
  enableTorCheck: false, // Default: false (requires external list)
  rateLimitWindowMs: 60000, 
  rateLimitMaxRequestPerWindow: 100,
  ip: req.ip // Manually pass IP if using proxy
};
const result = analyzeRequest(req, options);

Signals Analyzed

Network: Bogus IPs, IPs that look local (in production context).
Headers: Missing standard headers, bad User-Agent patterns (curl, wget), presence of browser-specific headers.
Behavior:
- Rate Limiting: Sliding window counter.
- Path Entropy: Detects random scanning paths (e.g. /admin/w8x7e9...).
- Sensitive Paths: Flags access to known protected paths (e.g. /admin, /login).
- Timing Variance: Detects perfectly regular intervals (bot-like) vs irregular human timing.
Session: Cookie presence (weak signal).

⚠️ Limitations & Disclaimers

Probability != Certainty: A score of 0 does not guarantee a human, and 100 does not guarantee a malicious bot.
In-Memory State: Rate limiting and timing analysis are stored in memory. This package is not stateful across cluster/serverless instances unless sticky sessions are used.
Privacy: This package does not track users across sites. It only analyzes the current request context.
Tor: Tor exit node detection is disabled by default to avoid stale bundled lists.

License

MIT

FilesExpand file tree

README.md

Latest commit

History