zsecurity

zsecurity is a lightweight, production-minded rule-based Web Application Firewall (WAF) for Node.js applications. Framework-friendly (Express, Koa), easy to operate for teams of all levels, and designed for straightforward deployment in both single-instance and horizontally-scaled environments.

Features

• Framework Friendly — Works as middleware for both Express and Koa.
• Sensible Defaults — Ships with default rules for common threats: XSS, SQLi, LFI/RFI, Command Injection, and blocks known bad bots/scanners.
• Programmatic Control — Manage and modify rules directly from your application runtime.
• Load Balancer Aware — Correctly identifies client IPs behind proxies (configure trust proxy / X-Forwarded-For as needed).

Installation

npm install zsecurity

Quick Start — Express

const express = require('express');
const zsecurity = require('zsecurity');

const app = express();

// Define custom rules
const customRules = [
  {
    id: 'block-specific-ip',
    type: 'IP_BLACKLIST',
    description: 'Block a known bad actor.',
    enabled: true,
    ips: ['192.168.1.100']
  },
  {
    id: 'rate-limit-basic',
    type: 'RATE_LIMIT',
    description: 'Stricter rate limiting.',
    enabled: true,
    windowMs: 60 * 1000,
    maxRequests: 50 // reduced from default 100
  }
];

// Initialize zsecurity with custom rules
const waf = zsecurity({ rules: customRules });

// Use the WAF middleware for all routes
app.use(waf);

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Quick Start — Koa

const Koa = require('koa');
const zsecurity = require('zsecurity');

const app = new Koa();

// Initialize zsecurity, disabling default rules and using only your own.
const waf = zsecurity({
  disableDefaults: true,
  rules: [
    {
      id: 'my-rate-limit',
      type: 'RATE_LIMIT',
      description: 'Custom rate limit.',
      enabled: true,
      windowMs: 30 * 1000,
      maxRequests: 20
    }
  ]
});

// Use the WAF middleware for Koa apps
app.use(waf.koa());

app.use(async ctx => {
  ctx.body = 'Hello World';
});

app.listen(3000);

Programmatic Rule Management

You can manipulate rules at runtime via the ruleManager attached to the WAF instance.

const waf = zsecurity();
app.use(waf);

// Get all current rules
const allRules = waf.ruleManager.getAllRules();
console.log(allRules);

// Add a new rule on the fly
waf.ruleManager.addRule({
  id: 'block-another-ip',
  type: 'IP_BLACKLIST',
  description: 'Block another bad actor.',
  enabled: true,
  ips: ['10.0.0.5']
});

// Disable a rule by its ID
waf.ruleManager.updateRule('xss-basic', { enabled: false });

// Delete a rule
waf.ruleManager.deleteRule('sqli-basic');

Note: method names may vary slightly between releases (e.g., addSimple vs addRule). Check the waf.ruleManager API in your installed version.

Rule Types (examples)

• IP_BLACKLIST — block traffic from specific IPs.
• RATE_LIMIT — throttle requests by IP/window.
• HEADER — match and act on header values (eg. suspicious user-agent).
• URL / ANY — regex match against URL, query, or body.
• CUSTOM — provide a custom matching function.

Example rule JSON:

{
  "id": "rule-id",
  "type": "RATE_LIMIT",
  "description": "Human readable description",
  "enabled": true,
  "windowMs": 60000,
  "maxRequests": 100
}

Load Balancer / Proxy Awareness

If your app runs behind a load balancer or reverse proxy, ensure your Node app trusts the proxy headers so the WAF can determine client IPs correctly:

app.set('trust proxy', true); // Express example

Versioning

Security & Production Notes

• Secure admin endpoints — always protect admin routes (API keys, OAuth, internal network only).
• Persist rules & metrics for multi-instance — use Redis or another shared store to synchronize across instances.
• Observability — export Prometheus metrics and build dashboards for blocked events and anomalies.
• Rotating secrets — never commit private keys or secrets into the repo. Add them to .gitignore and rotate if leaked.

Author

ZHOST Consulting Private Limited
[email protected]

License

MIT