Erste Schritte

Dhal ist eine anwendungsnative Web Application Firewall und Sicherheitsschicht für Node.js-Anfragen. Version 1.1 unterstützt Express, Fastify, NestJS, Koa, Hono auf Node.js und rohe node:http-Server.

Dhal ergänzt CDN-, Edge-, Netzwerk-, Authentifizierungs-, Autorisierungs- und Validierungskontrollen. Es ersetzt weder volumetrischen DDoS-Schutz noch Infrastruktursicherheit.

Voraussetzungen

• Node.js 20 oder neuer
• Ein moderner npm-kompatibler Paketmanager
• Redis oder Valkey für gemeinsame Zähler, wenn mehrere Instanzen dieselben Routen schützen

Installation

npm install @rokadhq/dhal

Das npm-Paket heißt @rokadhq/dhal, der CLI-Befehl lautet dhal und die Standardkonfiguration ist dhal.json.

Empfohlen: geführte Einrichtung

Führen Sie dhal add im Anwendungsstamm aus:

npx dhal add

Der Standardaufruf ist schreibgeschützt. Er erkennt Framework und Paketmanager, zeigt eine Monitor-Konfiguration zur Prüfung, erzeugt ein nachvollziehbares Integrationsmodul und gibt genaue Registrierungsschritte aus.

Nach der Prüfung können Sie die vorgeschlagenen Dateien erstellen:

npx dhal add --write

Dhal verändert vorhandenen Anwendungscode nicht automatisch. Bestehende Ausgabedateien werden nur mit --force überschrieben.

Für rohe node:http-Anwendungen wählen Sie das Framework explizit:

npx dhal add --framework node-http --write

Manuelle Konfiguration

Die allgemeine Startkonfiguration kann weiterhin direkt erstellt werden:

npx dhal init

Die Konfiguration startet im Modus monitor und protokolliert potenzielle Blockierungen, ohne Datenverkehr abzulehnen.

Framework-Einstiegspunkte

Express

import { dhal } from "@rokadhq/dhal/express";
app.use(express.json({ limit: "1mb" }));
app.use(dhal({ configPath: "dhal.json" }));

Fastify

import { dhalFastify } from "@rokadhq/dhal/fastify";
await app.register(dhalFastify({ configPath: "dhal.json" }));

NestJS

import { installDhalNest } from "@rokadhq/dhal/nest";
const app = await NestFactory.create(AppModule);
await installDhalNest(app, { configPath: "dhal.json" });
await app.listen(3000);

Installieren Sie Dhal nach dem Erstellen der Nest-Anwendung und vor app.listen(). Der Adapter erkennt Express oder Fastify.

Koa

import { dhalKoa } from "@rokadhq/dhal/koa";
app.use(dhalKoa({ configPath: "dhal.json" }));

Registrieren Sie Dhal vor Routen und Middleware, die erst nach der Prüfung ausgeführt werden sollen.

Hono auf Node.js

import { dhalHono } from "@rokadhq/dhal/hono";
app.use("*", dhalHono({ configPath: "dhal.json" }));

Der Hono-Adapter verwendet standardisierte Web-Request- und Response-Objekte und wird auf der Node.js-Laufzeit unterstützt.

node:http

import { createNodeHttpDhal } from "@rokadhq/dhal/node-http";
const protection = createNodeHttpDhal({ configPath: "dhal.json" });

Vollständige Beispiele zu Lebenszyklus und Identität finden Sie im Kapitel Framework-Integrationen.

Vor der Durchsetzung validieren und reparieren

npx dhal test-config
npx dhal migrate --check
npx dhal doctor
npx dhal doctor --fix --dry-run
npx dhal readiness --production

doctor --fix führt nur vorsichtige mechanische Reparaturen aus. Es kann eine fehlende Monitor-Konfiguration erstellen oder eine kompatible Konfiguration mit Sicherung migrieren. Blockierung, Proxy-Vertrauen, Redis, Telemetrie oder externe Reputation werden nicht automatisch aktiviert.

Eine sichere Einführung:

1. Global im Modus monitor bereitstellen.
2. Bekannten Datenverkehr wiedergeben und wouldBlock-Ereignisse prüfen.
3. block nur auf ausgewählten Hochrisikorouten aktivieren.
4. Latenz, Fehlalarme und Verfügbarkeit der Abhängigkeiten prüfen.
5. Die Durchsetzung schrittweise erweitern.

Betriebsmodi

Routenprofile können den globalen Modus überschreiben und so eine schrittweise Durchsetzung ermöglichen.