Node.js WAF•Config-first•OTel-ready

App-native WAF for modern Node.js APIs

Dhal runs inside your app, inspects every request, applies route-aware security rules, emits security telemetry, and stays configurable through one reviewable dhal.json file.

Install

$ npm install @rokadhq/dhal

$ npx dhal init

Published as @rokadhq/dhal. CLI remains dhal. Config remains dhal.json.

Add middleware

app.ts

import express from "express";
import { dhal } from "@rokadhq/dhal/express";

const app = express();

app.use(express.json({ limit: "1mb" }));
app.use(dhal());

app.get("/", (_req, res) => {
  res.json({ ok: true });
});

app.listen(3000);

Most Node apps have a security gap between the edge and the route handler

Edge WAFs and reverse proxies are essential, but they often lack visibility into application-level context: route semantics, tenant identity, API keys, login failure patterns, per-route policies, JSON body expectations, and framework-specific behaviors.

Edge tools see traffic

CDNs and proxies filter requests before your app, but they lack context about your routes, users, and business logic.

Your app knows context

Your Node.js app understands route semantics, user identity, API keys, tenant boundaries, and per-route policies.

Dhal connects the two

Dhal bridges the gap—applying app-aware security decisions at the request layer while integrating with your existing infrastructure.

How Dhal works

Every incoming request flows through a unified pipeline that normalizes, inspects, decides, and reports—all within your application process.

Adapter

Express, Fastify, node:http, future Fetch-style adapters

Normalized Request

method, path, headers, IP, route, identity keys

Rule Engine

signatures, IP reputation, rate limits, bot signals, honeypots

Policy Layer

mode, severity, suppressions, sampling, route overrides

Decision

allow, monitor, block

Telemetry

logs, metrics, spans, webhooks

Adapter

Express, Fastify, node:http, future Fetch-style adapters

Normalized Request

method, path, headers, IP, route, identity keys

Rule Engine

signatures, IP reputation, rate limits, bot signals, honeypots

Policy Layer

mode, severity, suppressions, sampling, route overrides

Decision

allow, monitor, block

Telemetry

logs, metrics, spans, webhooks

Incoming RequestProtected Response

Features built for production security

Dhal provides comprehensive request-layer protection without requiring external services or complex infrastructure changes.

Config-first WAF

Define security behavior in dhal.json. Keep rules reviewable, portable, and version-controlled.

Route-aware protection

Apply different security profiles to /api/login, /api/upload, /api/private/*, admin routes, and public APIs.

Rate limiting

Memory, Redis, and Valkey-ready token-bucket controls with IP, route, user, tenant, and API-key based identities.

IP intelligence

Allow/block lists, CIDR support, and AbuseIPDB-style reputation checks with caching.

Signature rules

Detect common SQLi, XSS, path traversal, SSRF, RCE, SSTI, GraphQL probes, WordPress probes, and malformed requests.

Bot scoring

Score suspicious clients using headers, user agents, automation hints, request anomalies, and configurable false-positive controls.

Credential-stuffing defense

Learn from repeated failed login outcomes and block abusive IP/user/API-key combinations.

Honeypot canaries

Detect scanners and malicious automation through trap paths, headers, and query parameters.

OpenTelemetry

Emit Dhal-specific security spans, metrics, and structured events to your observability stack.

Webhook alerts

Send signed security alerts to your backend, SIEM, Slack bridge, or incident pipeline.

CLI workflow

Initialize, validate, simulate, replay, migrate, export schema, and run CI checks from the command line.

AI autosetup

Scan your project and generate a proposed Dhal config using the AI SDK or deterministic fallback heuristics.

Works where Node developers already are

Drop Dhal into your existing stack. Native adapters for popular frameworks, distributed stores, and telemetry systems.

Express(Framework)

Fastify(Framework)

node:http(Framework)

NestJS(Framework)

Next.js(Framework)

Redis(Store)

Valkey(Store)

OpenTelemetry(Telemetry)

AbuseIPDB(Intelligence)

AI SDK(Autosetup)

import express from "express";
import { dhal } from "@rokadhq/dhal/express";

const app = express();

app.use(express.json({ limit: "1mb" }));
app.use(dhal());

app.listen(3000);

One `dhal.json`. Full request policy.

All security behavior lives in a single, reviewable configuration file. Version control it, diff it, audit it.

dhal.json

{
  "mode": "monitor",
  "trustProxy": true,
  "ip": {
    "allow": ["127.0.0.1", "::1"],
    "block": ["203.0.113.0/24"],
    "reputation": {
      "enabled": true,
      "provider": "abuseipdb",
      "apiKeyEnv": "ABUSEIPDB_API_KEY",
      "minScore": 75,
      "cacheTtlSeconds": 86400
    }
  },
  "rateLimit": {
    "enabled": true,
    "store": "redis",
    "default": {
      "windowSeconds": 60,
      "max": 120,
      "keyBy": ["ip", "route"]
    }
  },
  "routes": {
    "/api/login": {
      "mode": "block",
      "rateLimit": {
        "windowSeconds": 60,
        "max": 5,
        "keyBy": ["ip", "route"]
      },
      "rules": {
        "credentialStuffing": true,
        "bot": true
      }
    },
    "/api/upload": {
      "mode": "block",
      "rules": {
        "largePayload": {
          "enabled": true,
          "maxBytes": 5242880
        }
      }
    }
  },
  "observability": {
    "otel": {
      "enabled": true,
      "serviceName": "api"
    },
    "webhooks": {
      "enabled": true,
      "urlEnv": "DHAL_SECURITY_WEBHOOK_URL",
      "secretEnv": "DHAL_WEBHOOK_SECRET"
    }
  }
}

Route-specific policies

Different rules for login, upload, admin, and public routes

Environment-aware secrets

API keys and webhook secrets read from env vars, not config

Observable by default

Built-in OpenTelemetry and webhook integrations

AI-assisted setup without hiding the policy

Dhal can scan your project, detect framework and route patterns, and generate a proposed dhal.json policy using the optional AI SDK integration or deterministic fallback heuristics. Generated rules are reviewable before enforcement.

Note: AI autosetup proposes configuration—it does not silently enforce rules. Your team reviews and commits the generated config before production use.

$ npx dhal autosetup . --no-ai --json

$ npx dhal autosetup . --provider openai --model gpt-4.1-mini --json

$ npx dhal autosetup . --provider gateway --model openai/gpt-4.1-mini --write

Scans routes

Analyzes your project structure, detects frameworks, and discovers API routes automatically.

Suggests policies

Proposes rate limits, security rules, and detection settings based on route patterns and semantics.

Outputs reviewable config

Generates a dhal.json you can review, edit, and commit—no hidden enforcement.

Supports configurable AI providers

OpenAIAnthropicGoogleMistralxAIAI GatewayCustom

Rule packs for real application surfaces

Pre-configured rule sets targeting specific application types and attack surfaces. Enable what you need, tune as you go.

generic-web

General web application protection with broad coverage for common attack patterns.

api

Optimized for JSON APIs with Content-Type validation, header checks, and body expectations.

auth

Enhanced protection for authentication endpoints with credential-stuffing and brute-force detection.

wordpress

Specialized rules for WordPress admin, plugin, and upload path attacks.

strict-api

Positive security model enforcing strict JSON body validation and header requirements.

Additional capabilities

Positive security model for JSON APIs
Header anomaly checks
Content-Type/body mismatch detection
Confidence scoring
False-positive replay harness

Security telemetry your infra stack can understand

Dhal turns request security decisions into traces, metrics, structured logs, and webhook events—ready for your existing observability tools.

Metrics

dhal_requests_totalTotal requests processed

dhal_blocked_requests_totalRequests blocked by policy

dhal_rule_matches_totalRule match count by rule ID

dhal_rate_limited_totalRate-limited requests

dhal_inspection_duration_msRequest inspection latency

Span Attributes

dhal.actionDecision: allow, monitor, block

dhal.rule_idMatched rule identifier

dhal.severityRule severity level

dhal.routeMatched route pattern

dhal.client_ip_hashHashed client IP

dhal.risk_scoreComputed risk score

Compatible with

DatadogGrafanaHoneycombJaegerPrometheus

Start safe. Tighten gradually.

Dhal supports multiple enforcement modes so you can observe before acting, then enable blocking with confidence.

off

Disabled

Dhal is loaded but performs no inspection. Useful for gradual rollouts or feature-flagged deployments.

Recommended start

monitor

Monitor

Detects and logs security events without blocking requests. Perfect for initial deployment and rule tuning.

block

Block

Actively blocks requests matching security rules. Enable per-route after validating monitor-mode behavior.

strict

Strict

Aggressive enforcement with tighter thresholds. Designed for hardened APIs requiring maximum protection.

Recommended approach

1.Start in monitor mode across all routes
2.Review logged security events and identify false positives
3.Use the replay harness to validate rule adjustments
4.Enable block mode per-route as confidence grows

CLI-first workflow

Manage your security configuration from the command line. Initialize, validate, test, and integrate with CI/CD pipelines.

terminal

$ npx dhal init

Initialize dhal.json in your project

$ npx dhal test-config

Validate configuration syntax

$ npx dhal explain-config

Human-readable config explanation

$ npx dhal simulate fixtures.simulation.json

Test rules against sample requests

$ npx dhal replay fixtures.replay.json

Replay recorded traffic for testing

$ npx dhal schema dhal.schema.json

Export JSON schema for IDE support

$ npx dhal migrate dhal.json

Migrate config to latest schema

$ npx dhal ci --json

CI-friendly validation with JSON output

Where Dhal fits

Dhal operates at the application layer, complementing your existing infrastructure security without replacing it.

Layer	Tool examples	What they do	Where Dhal helps
CDN / Edge WAF	Cloudflare, AWS WAF	Filters traffic before your app sees it	Dhal complements, does not replace edge protection
Reverse Proxy	nginx, Envoy, Caddy	Routing, TLS termination, basic proxy controls	Dhal adds route-aware application policy
Node Middleware	Helmet, express-rate-limit	Focused security modules	Dhal unifies WAF-style policy in one config
App Code	Auth, business logic	Knows users, tenants, routes, context	Dhal uses this context for enforcement

CDN / Edge WAF

Tools: Cloudflare, AWS WAF

Role: Filters traffic before your app sees it

Dhal: Dhal complements, does not replace edge protection

Reverse Proxy

Tools: nginx, Envoy, Caddy

Role: Routing, TLS termination, basic proxy controls

Dhal: Dhal adds route-aware application policy

Node Middleware

Tools: Helmet, express-rate-limit

Role: Focused security modules

Dhal: Dhal unifies WAF-style policy in one config

App Code

Tools: Auth, business logic

Role: Knows users, tenants, routes, context

Dhal: Dhal uses this context for enforcement

Built for teams that need reviewable security

Dhal is designed for engineering teams that want security controls they can understand, audit, and maintain.

Version-controlled config

dhal.json lives in your repo. Review changes in PRs, audit history via git log.

CI posture checks

Validate configuration syntax and policy consistency in your CI pipeline.

Signed webhooks

Webhook payloads include HMAC signatures for tamper-proof event verification.

Redis/Valkey distributed state

Share rate limit counters and IP reputation cache across instances.

JSON schema export

Generate schema files for IDE autocompletion and validation.

Suppressions and sampling

Temporarily suppress rules or sample enforcement during tuning.

Audit explanations

Human-readable explanations for why requests were blocked or flagged.

False-positive replay

Replay recorded requests against updated rules to validate changes.

Published and released through GitHub

Dhal is published on npm as @rokadhq/dhal and maintained from the rokadhq/dhal GitHub repository. Releases are built and published through GitHub Actions, with package verification before publish.

npm

Install from npm with npm install @rokadhq/dhal.

GitHub

Source, issues, releases, and workflows live on GitHub.

CLI

After installation, use npx dhal to initialize, validate, simulate, replay, migrate, and run CI checks.

Add an application-layer WAF to your Node API

Start in monitor mode, inspect what Dhal catches, and turn on route-level blocking when you are ready.

$npm install @rokadhq/dhal