## 什么是 HodorGuard？ HodorGuard 是一个专为 Express API 打造的即插即用安全中间件。它默默监控每一个传入的请求，为每个 IP 构建**风险评分**，并自动拦截可疑行为，且不会对合法用户造成任何影响。 它专为内存和 CPU 资源有限的 VPS 环境设计，仅依赖 Redis 作为其唯一的依赖项。 ## 功能特性 - **速率限制** — 可配置的时间窗口内每个 IP 的请求限制 - **蜜罐路由** — 伪造的端点，会对任何访问它们的 IP 进行惩罚 - **风险评分** — 每个 IP 根据其行为获得动态评分 - **自动拦截** — 超过风险阈值的 IP 会通过 Redis TTL 被拦截 - **扫描器检测** — 检测访问了过多不同路由的 IP - **暴力破解检测** — 检测大批量的突发请求模式 - **洪水攻击检测** — 检测持续的高频请求 - **请求日志** — 存储在 Redis 中的轻量级 24 小时日志 - **监控端点** — 内置 HTTP 端点，用于检查运行时数据 - **双模式包** — 同时支持 CommonJS 和 ES Modules 消费者 ## 系统要求 - **Node.js** >= 18.0.0 - 可从您的应用程序访问的 **Redis** 服务器 - **Express** >= 4.0.0（完全支持 Express 5） ## 测试兼容性 | 配置环境 | 状态 | | ---------------------------------- | ------------------------------------------------- | | Express 4 + CommonJS | ✅ 已测试 | | Express 5 + ESM (tsx, ts-node ESM) | ✅ 已测试 | | NestJS | ⚠️ 尚未测试 | | Fastify | ❌ 不支持（中间件系统不同） | | Koa | ❌ 不支持（中间件签名不同） | ## 安装说明 ``` npm install hodor-guard ``` ## 快速开始 (Express + ESM) ``` import express from 'express'; import { hodorGuard } from 'hodor-guard'; import { statsRouter } from 'hodor-guard/router'; const app = express(); app.use( hodorGuard({ rateLimit: true, honeypot: true, autoBlock: true, }), ); // optional mount monitoring endpoints app.use('/hodor', statsRouter); app.listen(3000); ``` ## 快速开始 (Express + CommonJS) ``` const express = require('express'); const { hodorGuard } = require('hodor-guard'); const { statsRouter } = require('hodor-guard/router'); const app = express(); app.use( hodorGuard({ rateLimit: true, honeypot: true, autoBlock: true, }), ); app.use('/hodor', statsRouter); app.listen(3000); ``` ## 配置说明 所有选项都是可选的。HodorGuard 开箱即用，采用了合理的默认设置。 | 选项 | 类型 | 默认值 | 描述 | | -------------------- | ---------- | --------- | ----------------------------------------- | | `rateLimit` | `boolean` | `true` | 启用速率限制 | | `honeypot` | `boolean` | `true` | 启用蜜罐路由 | | `autoBlock` | `boolean` | `true` | 启用自动 IP 拦截 | | `rateLimitMax` | `number` | `100` | 每个时间窗口内每个 IP 的最大请求数 | | `rateLimitWindowMs` | `number` | `60000` | 时间窗口（毫秒） | | `riskScoreThreshold` | `number` | `70` | 导致 IP 被拦截的分数阈值 (0–100) | | `blockTtlSeconds` | `number` | `900` | 被拦截 IP 的持续拦截时长 | | `scannerThreshold` | `number` | `10` | 被标记为扫描器前的唯一路由数 | | `honeypotRoutes` | `string[]` | 见下文 | 触发蜜罐惩罚的路由 | | `logRequests` | `boolean` | `true` | 将请求日志存储在 Redis 中 | ### 默认蜜罐路由 ``` /admin /admin/login /wp-admin /wp-login.php /phpmyadmin /config /.env /backup /shell /console ``` ## 配置最佳实践 ### ⚠️ 蜜罐路由不得与真实路由冲突 蜜罐路由旨在捕捉攻击者，任何访问它们的 IP 都将受到严厉惩罚。**如果您有一个与默认蜜罐路径匹配的真实路由，该路由将误捕您的合法用户。** 例如：如果您的应用程序有一个真实的 `/admin` 面板，默认的蜜罐列表将在几次合法访问后拦截您的管理员。 **两种安全的模式：** **1. 为敏感路由使用难以猜测的路径（推荐）** ``` // instead of /admin, use a non-obvious path app.get('/secret-panel-x9k2', adminHandler); ``` 保持默认蜜罐启用，任何访问 `/admin` 的人都将被视为攻击者。 **2. 覆盖蜜罐列表以移除冲突的路径** ``` app.use( hodorGuard({ honeypotRoutes: ['/wp-admin', '/.env', '/phpmyadmin', '/shell'], // /admin removed your app uses it legitimately }), ); ``` ### 位于反向代理之后 如果您的应用运行在反向代理（Nginx、Caddy、Cloudflare）之后，请启用 Express 的 trust proxy，以便 HodorGuard 能够从 `x-forwarded-for` 中读取真实的客户端 IP： ``` app.set('trust proxy', 1); ``` ## 风险评分 每项可疑行为都会增加该 IP 的风险评分。当评分达到阈值时，该 IP 将被拦截。 | 行为 | 惩罚分数 | | ----------------------- | ------- | | 访问了蜜罐路由 | +40 | | 检测到暴力破解 | +25 | | 超出速率限制 | +20 | | 检测到扫描器 | +15 | | 检测到洪水攻击 | +10 | ## 监控端点 挂载 `statsRouter` 以暴露运行时数据： ``` app.use('/hodor', statsRouter); ``` | 端点 | 描述 | | --------------------------- | --------------------------------- | | `GET /hodor/stats` | 全局请求和拦截计数器 | | `GET /hodor/blocked` | 当前所有被拦截的 IP | | `GET /hodor/top-attackers` | 按风险评分排序的被拦截 IP | | `GET /hodor/logs/:ip` | 特定 IP 的请求日志 | | `GET /hodor/ip/:ip` | 特定 IP 的完整风险数据 | | `DELETE /hodor/blocked/:ip` | 手动解封 IP | ## 环境变量 ``` REDIS_HOST=127.0.0.1 REDIS_PORT=6379 REDIS_PASSWORD= ``` ## 运行示例 克隆仓库并启动演示服务器： ``` git clone https://github.com/pecinallib/hodor-guard.git cd hodor-guard npm install cp .env.example .env npm run example ``` 在第二个终端中，运行攻击模拟器： ``` npm run simulator ``` 观看 HodorGuard 实时检测并拦截暴力破解、扫描器、蜜罐和洪水攻击。 ## 运行测试 ``` npm test npm run test:coverage ``` ## IP 风险数据结构 ``` { "ip": "192.168.0.1", "riskScore": 87, "flags": ["honeypot_access", "brute_force"], "blocked": true, "firstSeen": 1713000000000, "lastSeen": 1713000120000, "requestCount": 342 } ``` ## 局限性 - **IP 伪造** — 依赖于 `x-forwarded-for` 请求头。请配置您的反向代理以覆盖此请求头，防止客户端伪造。 - **分布式攻击** — 使用大量 IP 且每个 IP 仅发送少量请求的僵尸网络无法在单 IP 层面被检测到。 - **Redis 依赖** — 如果 Redis 不可用，HodorGuard 将会允许请求通过（开放模式）。这是有意为之，以确保在发生内部错误时不会拦截合法流量，但也意味着如果 Redis 宕机，您的防护将处于离线状态。 - **共享 IP** — 企业代理或 CDN 可能会在多个用户之间共享同一个 IP。请相应地调整 `rateLimitMax` 和 `riskScoreThreshold`。 - **Redis 重启后无持久化** — 如果未配置 Redis 持久化，当 Redis 重启时，评分和拦截记录将会丢失。 ## 许可证 MIT © [Matheus Bastos Pecinalli](https://github.com/pecinallib)

标签：API安全, AppImage, CC攻击防护, CISA项目, CommonJS, ES Modules, Express, GNU通用公共许可证, JSON输出, MITM代理, Node.js, Node.js安全, NPM包, OSV-Scalibr, Redis, WAF, Web应用防火墙, 中间件, 安全中间件, 恶意请求拦截, 扫描检测, 插件系统, 搜索引擎查询, 暗色界面, 红队行动, 网络安全, 自动化攻击, 自动封锁, 蜜罐, 证书利用, 防御洪水攻击, 防爆破, 隐私保护, 风险评分