rokadhq/dhal
GitHub: rokadhq/dhal
Dhal是Node.js应用的本地WAF，用于保护API安全。
Stars: 0 | Forks: 0
# Dhal
Dhal 是一个针对 Node.js 应用程序的本地应用 WAF、机器人防御、策略控制和请求安全中间件。
它位于应用程序请求路径内部，提供确定性控制，例如 IP 允许/阻止列表、CIDR 匹配、速率限制、路由感知策略、攻击签名、IP 声誉检查、机器人检测、凭证填充信号、诱饵金丝雀、webhooks、OpenTelemetry 钩子、CI 检查、误报重放和 AI 辅助自动设置。
Dhal 补充 CDN/边缘/网络 WAF。它不会替换上游 DDoS 或带宽耗尽保护。
## v0.12 测试版 / v1 准备重点
Dhal v0.12 将项目从 alpha-public 增强转向 v1 发布轨道。它添加了兼容性矩阵、v1 准备度评分、公共准备度 API 和工作流程更新，这些更新可以自动解决 alpha、beta、rc、next 和最新版本的预发布 dist-tags。
明确使用 beta 标签：
```
npm install @rokadhq/dhal@beta
npx dhal readiness --production
npx dhal compat
```
公共 API、配置形状和 CLI 现在被视为 beta 稳定。在 v1 之前应提供迁移说明和明确的发布指南。
## v0.11 alpha-public 重点
Dhal v0.11 alpha-public 增强了包的真实公共使用。它添加了运行时故障策略控制、健康检查/预检绕过、隐私优先的可观察性编辑、支持报告生成和针对生产安装的更强诊断。
该包仍然是 pre-1.0。将公共 API 视为可用的但未冻结。生产用户应固定版本，从 `monitor` 开始，使用 `dhal replay` 进行误报回归测试，并在审查后仅将特定路由移动到 `block`。
## v0.10 重点
Dhal v0.10 是生产上线版本。它通过 `dhal presets` 添加可审查的配置预设、公共预设 API 和从监控模式到路由级别阻止的更安全的升级路径。目标是帮助团队从“已安装”过渡到“生产型策略”，而不隐藏默认值背后的行为。
## v0.9 重点
Dhal v0.9 标准化了作用域包标识 `@rokadhq/dhal`，添加了 `dhal doctor` 用于生产就绪诊断，通过 `dhal rules` 暴露了内置规则目录，并添加了规则/目录和 doctor 工具的公共 API 导出。
Dhal 仍然以产品名称 **Dhal**。npm 包是 `@rokadhq/dhal`，CLI 命令是 `dhal`，配置文件是 `dhal.json`。
## v0.7 功能基线
Dhal v0.7 添加了规则质量和设置自动化：
- 规则包：`generic-web`、`api`、`auth`、`wordpress`、`strict-api`
- 签名/标题/API 决策上的置信度元数据
- SSRF、RCE、GraphQL 反射、SSTI 和 WordPress 探测签名
- JSON API 的积极安全模型
- 标头异常检测
- JSON Content-Type/body 不匹配检查
- IPv4 和 IPv6 CIDR 允许/阻止支持
- 通过 `dhal replay` 的误报重放 harness
- 通过可选的 Vercel AI SDK `ai` 包驱动的 AI 辅助自动设置
## 发布就绪
此包包括发布清单和发布脚本：
```
npm run verify:publish
npm run pack:dry
npm publish --tag beta --access public
```
GitHub Actions 发布工作流程自动解决 dist-tags：预发布 alpha 版本在 `alpha` 下发布，beta 在 `beta` 下发布，候选版本在 `rc` 下发布，pre-1.0 非预发布版本在 `next` 下发布，v1+ 版本在 `latest` 下发布。发布前请参阅 `PUBLISHING.md`。
## 安装
```
npm install @rokadhq/dhal
```
可选的 AI 自动设置依赖项：
```
npm install ai @ai-sdk/openai
```
或者仅使用带有 `ai` 包的 Vercel AI Gateway，具体取决于您的 AI SDK 设置。
## Express
```
import express from "express";
import { dhal } from "@rokadhq/dhal/express";
const app = express();
app.use(express.json({ limit: "1mb" }));
app.use(dhal());
app.post("/api/login", (req, res) => {
res.status(401).json({ error: "bad credentials" });
});
app.listen(3000);
```
Express 适配器在请求完成后记录响应状态码。这允许凭证填充保护从重复的 401/403 登录失败中学习，并阻止后续尝试。
## Fastify
```
import Fastify from "fastify";
import { dhalFastify } from "@rokadhq/dhal/fastify";
const app = Fastify();
await app.register(dhalFastify());
app.get("/", async () => ({ ok: true }));
await app.listen({ port: 3000 });
```
## 原始节点：http
```
import http from "node:http";
import { createNodeHttpDhal } from "@rokadhq/dhal/node-http";
const dhal = createNodeHttpDhal();
const server = http.createServer(async (req, res) => {
const decision = await dhal.inspect(req, res);
if (decision.action === "block") return;
res.end("ok");
});
server.listen(3000);
```
## 命令行界面
创建一个启动配置：
```
npx dhal init
```
验证配置：
```
npx dhal test-config
```
运行生产就绪诊断：
```
npx dhal doctor
```
为生产目标评分 v1 准备度：
```
npx dhal readiness --production
```
打印支持的运行时、框架适配器、集成和稳定性状态：
```
npx dhal compat
```
列出有效的规则目录：
```
npx dhal rules
```
生成用于调试安装的编辑后的支持报告：
```
npx dhal report --output dhal.report.json
```
列出生产就绪配置预设：
```
npx dhal presets
```
在应用之前检查预设：
```
npx dhal presets show api-production
```
将预设合并的配置写入审查文件：
```
npx dhal presets apply api-production --output dhal.production.json
```
直接将预设应用到 `dhal.json`：
```
npx dhal presets apply auth-hardened --write
```
## 运行时安全控制
Dhal 默认对 alpha/public 使用优先考虑可用性：
```
{
"runtime": {
"onInternalError": "allow",
"internalErrorStatusCode": 500,
"maxInspectionMs": 25,
"bypass": {
"enabled": true,
"paths": ["/health", "/healthz", "/ready", "/readyz", "/live", "/livez"],
"methods": ["OPTIONS"]
}
}
}
```
对于加固的内部 API，您可以设置 `runtime.onInternalError` 为 `block`，但在推广之前请使用 `dhal simulate`、`dhal replay` 和 `dhal doctor` 进行测试。
## 隐私优先的可观察性
安全日志和事件很有用，但它们可能包含敏感的操作数据。Dhal 现在默认编辑可观察性有效载荷：
```
{
"observability": {
"redaction": {
"enabled": true,
"ip": "mask",
"identity": "hash",
"userAgent": "full"
}
}
}
```
这会影响 Dhal 安全事件、日志、遥测有效载荷和支持报告。请求路径和路由保留用于调试；IP 和身份键根据配置进行屏蔽或哈希。
## 配置预设
预设是有名、可审查的配置覆盖。它们不会替换 `dhal.json`；它们有助于为常见的部署形状创建更安全的起始策略。
可用预设：
- `starter` — 首次安装的监控模式基线
- `api-production` — 带有 Redis/Valkey、受信任代理假设、OTel 就绪设置和强制执行路由配置文件的 JSON API 基线
- `auth-hardened` — 登录/auth 路由加固和凭证填充控制
- `strict-json-api` — 应仅接受 JSON 请求体的 API 的积极安全模型
- `behind-proxy` — CDN/反向代理/入口设置的部署基线
- `observability` — OpenTelemetry 和已签名-webhook 就绪的遥测设置
程序性使用：
```
import { applyDhalPreset, getDhalPreset, listDhalPresets } from "@rokadhq/dhal";
const presets = listDhalPresets();
const apiPreset = getDhalPreset("api-production");
const config = applyDhalPreset({}, apiPreset.name);
```
## AI 辅助自动设置
自动设置扫描您的 Node 项目，检测框架提示和路由，构建确定性安全建议，并可选择请求 AI SDK 模型来细化配置。
Dry-run，仅确定性：
```
npx dhal autosetup . --no-ai --json
```
使用 AI Gateway/global 提供模型字符串的 AI 辅助建议：
```
AI_GATEWAY_API_KEY=... npx dhal autosetup . \
--provider gateway \
--model openai/gpt-4.1-mini \
--json
```
OpenAI 提供器包：
```
OPENAI_API_KEY=... npx dhal autosetup . \
--provider openai \
--model gpt-4.1-mini \
--json
```
写入合并的配置：
```
npx dhal autosetup . --no-ai --write
```
写入单独的审查文件：
```
npx dhal autosetup . --no-ai --write --output dhal.proposed.json
```
自定义提供器模块：
```
npx dhal autosetup . \
--provider custom \
--provider-module ./security-ai-provider.js \
--provider-export createModel \
--model company/security-model-v1
```
自动设置不会内联机密。API 密钥应保留在特定于提供器的环境变量中。
## 规则包
```
{
"rules": {
"packs": ["generic-web", "api", "auth"],
"api": {
"enabled": true,
"requireJsonContentType": true,
"allowedContentTypes": ["application/json", "application/problem+json"],
"methodsWithBody": ["POST", "PUT", "PATCH"],
"maxJsonDepth": 20,
"maxJsonKeys": 500
},
"headers": {
"enabled": true,
"requireHostHeader": true,
"maxHeaderCount": 96,
"maxHeaderBytes": 16384,
"suspiciousHeaders": ["x-original-url", "x-rewrite-url"],
"blockConflictingForwardingHeaders": false
},
"contentType": {
"enabled": true,
"blockMissingOnBodyMethods": false,
"blockJsonMismatch": true,
"allowedJsonMimeTypes": ["application/json", "application/problem+json"]
}
}
}
```
每个匹配决策都可以包括 `meta.confidence`，为下游 SIEM/agent 工作流程提供更多上下文以进行分类。
## 模式
```
off disables inspection
monitor logs what Dhal would block, but allows the request
block actively blocks matching requests
strict blocks on internal evaluation errors
```
路由配置文件可以覆盖全局模式。常见的生产设置是全局 `monitor`，将选定的高风险路由设置为 `block`。
## 路由感知配置文件
```
{
"mode": "monitor",
"routes": {
"/api/login": {
"mode": "block",
"tags": ["auth", "credential-stuffing"],
"rateLimit": {
"enabled": true,
"windowSeconds": 60,
"max": 20,
"keyBy": ["ip", "route"]
},
"rules": {
"credentialStuffing": {
"enabled": true,
"windowSeconds": 300,
"maxFailures": 4,
"keyBy": ["ip", "route", "userAgent"]
}
}
},
"/api/private/*": {
"mode": "block",
"rateLimit": {
"enabled": true,
"windowSeconds": 60,
"max": 30,
"keyBy": ["tenantId", "apiKeyId", "route"]
}
}
}
}
```
## 策略控制
### 严重性映射
```
{
"policy": {
"severity": {
"default": "low",
"categories": {
"honeypot": "critical",
"credential_stuffing": "high",
"signature": "high",
"rate_limit": "medium"
},
"rules": {
"signature.path_traversal": "critical",
"honeypot.triggered": "critical"
}
}
}
}
```
### 规则抑制
抑制是明确的、可审计的例外。优先考虑窄匹配器和 `expiresAt`。
```
{
"policy": {
"suppressions": [
{
"id": "known-validation-scanner",
"enabled": true,
"ruleId": "honeypot.triggered",
"path": "/.well-known/test-canary",
"reason": "temporary validation scanner",
"expiresAt": "2999-01-01T00:00:00.000Z"
}
]
}
}
```
被抑制的阻止变为 `action: "allow"`，带有 `wouldBlock: true`、`meta.suppressed: true` 和审计元数据。
标签：AI 辅助安全, API 保护, Bot 防御, CI 检查, GET参数, GNU通用公共许可证, IP 信誉检查, IP 黑白名单, MITM代理, Node.js, OpenTelemetry, Webhooks, Web 应用防火墙, 员工枚举, 安全可观测性, 攻击签名, 版本控制, 生产就绪, 生产监控, 用户代理, 策略控制, 网络安全, 自动化攻击, 蜜罐, 证书利用, 请求安全, 迁移指南, 配置预设, 隐私保护