auto-smart-security

🔐 Production-ready security middleware for Express / NestJS
Protect your API from bots, abuse, and attacks with rate limiting, auto blacklist, and Redis support.

✨ Features

• ✅ Path whitelist (block API scanning)
• ✅ Rate limiting (express-rate-limit)
• ✅ Automatic IP blacklist with TTL
• ✅ Bot detection (score-based)
• ✅ Memory or Redis blacklist store
• ✅ Multi-instance / Docker / Kubernetes safe
• ✅ Framework-agnostic (Express & NestJS)
• ✅ onBlock hook for logging & notifications (Slack / Telegram / Sentry…)

📦 Installation

npm install smart-security

⚠️ Peer dependency Your application must have express installed

npm install express

🚀 Quick Start (Express / NestJS)

import { applySecurity } from 'smart-security';
import { SEND_NOTIFICATION_ERR } from './notify';

applySecurity(app, {
  mode: 'prod',
  pathWhitelist: ['admin/', 'media', 'oauth2'],
  rateLimit: { max: 120, windowMs: 60_000 },
  bot: { enabled: true },
  blacklistTTL: 10 * 60 * 1000,

  onBlock: (info) => {
    SEND_NOTIFICATION_ERR(
      `[SECURITY]
Reason: ${info.reason}
IP: ${info.ip}
URL: ${info.url}
UA: ${info.ua ?? 'N/A'}`,
    );
  },
});

⚙️ SecurityOptions

interface SecurityOptions {
  /** Skip all security when in dev mode */
  mode?: 'prod' | 'dev';

  /** Allowed API paths */
  pathWhitelist: string[];

  /** Hard-coded blacklist */
  staticBlacklist?: string[];

  /** Dynamic blacklist TTL (milliseconds) */
  blacklistTTL?: number;

  /** Custom blacklist store (Redis / Memory) */
  blacklist?: {
    store?: BlacklistStore;
  };

  /** Rate limiting */
  rateLimit?: {
    windowMs: number;
    max: number;
  };

  /** Bot detection */
  bot?: {
    enabled: boolean;
    scoreLimit?: number;
  };

  /** Callback when a request is blocked */
  onBlock?: (info: BlockInfo) => void;
}

🚫 Block Reasons

The onBlock callback receives one of the following reasons:

| reason | Description | | ------------------ | ------------------------ | | rate-limit | Too many requests | | bot-detected | Bot behavior detected | | path-not-allowed | Path not in whitelist | | error-spam | Repeated error responses | | blacklist | IP is blacklisted |

🤖 Bot Detection

Bots are detected using a score-based system, including:

• Suspicious User-Agent (curl, python, scrapy)
• Missing browser headers
• No cookies
• Scanning sensitive paths (.env, wp-admin)
• Unusual HTTP methods

➡ When the score exceeds the threshold → block + blacklist

🧱 Blacklist Store

🧠 Memory (default)

• No configuration required
• Suitable for single-instance deployments

☁️ Redis (recommended for production)

Using ioredis

import Redis from 'ioredis';
import { RedisBlacklistStore } from 'smart-security';

const redis = new Redis({
  host: process.env.REDIS_HOST,
  port: Number(process.env.REDIS_PORT ?? 6379),
  password: process.env.REDIS_PASSWORD || undefined,
});

applySecurity(app, {
  mode: process.env.NODE_ENV === 'development' ? 'dev' : 'prod',
  rateLimit: { max: 120, windowMs: 60_000 },
  bot: { enabled: true },
  blacklistTTL: 10 * 60 * 1000,
  pathWhitelist: ['api', '/media'],
  blacklist: {
    store: new RedisBlacklistStore(
      redis,
      ['1.2.3.4'], // static blacklist
      600, // TTL in seconds
    ),
  },
  onBlock: (info) => {
    SEND_NOTIFICATION_ERR(
      `[SECURITY]
Reason: ${info.reason}
IP: ${info.ip}
URL: ${info.url}
UA: ${info.ua ?? 'N/A'}`,
    );
  },
});

Development Mode

Disable all security logic (local development):

applySecurity(app, {
  mode: 'dev',
  pathWhitelist: [],
});

🧠 Best Practices

• ✔ Whitelist only valid API paths
• ✔ Avoid permanent blacklisting
• ✔ Use Redis for multi-instance environments
• ✔ Handle logging & notifications via onBlock

🧩 Works With

• Express
• NestJS (Express adapter)
• Docker / Kubernetes
• Cloudflare / Nginx / reverse proxies

📬 Contact

If you have questions, suggestions, or want to report security issues, feel free to contact:

• Email: [email protected]

I usually respond within 24–48 hours.