zsecurity/README.md

A lightweight, production-minded, rule-based Web Application Firewall (WAF) for Node.js applications.

# 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
```bash
npm install zsecurity
```

## Quick Start — Express
```js
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
```js
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.

```js
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:
```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:

```js
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  
support@bithost.in

## License
MIT