KuraPiee/fauxhuman

# 🥷 Fauxhuman ``` ███████╗█████╗ ██╗ ██╗██╗ ██╗██╗ ██╗██╗ ██╗███╗ ███╗█████╗ ██╗ ██╗ ██╔════╝██╔══██╗██║ ██║██║ ██║██║ ██║██║ ██║████╗ ████║██╔══██╗██║ ██║ █████╗ ███████║██║ ██║███████║██║ ██║██║ ██║██╔████╔██║███████║███████║ ██╔══╝ ██╔══██║██║ ██║██╔══██║██║ ██║██║ ██║██║╚██╔╝██║██╔══██║██╔══██║ ██║ ██║ ██║╚██████╔╝██║ ██║╚█████╔╝╚██████╔╝██║ ╚═╝ ██║██║ ██║██║ ██║ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ``` [](LICENSE) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://www.fastify.io/) [](https://expressjs.com/) [](https://playwright.dev/) ## 🌐 快速链接 - [🇬🇧 英文文档](#-english-documentation) - [概述](#-overview) - [功能](#-key-features) - [安装与快速入门](#-installation--quickstart) - [自定义规则与 HMAC 安全性](#-extensibility--hmac-security) - [CLI 攻击测试框架](#-cli-attack-harness) - [🇹🇷 Türkçe Dokümantasyon](#-türkçe-dokümantasyon) # 🇬🇧 英文文档 ## 📌 概述 **Fauxhuman**（源自 *"faux human"* —— 人工访客）是一个开源的全栈机器人检测框架，也是用于 Node.js 应用程序的自动化安全攻击测试框架。 当攻击者使用轮换代理或隐蔽的无头浏览器时，传统的 IP 速率限制器通常会失效。Fauxhuman 使用基于客户端环境指纹、header 异常、鼠标轨迹曲率、不可见的 DOM 蜜罐和 Redis 滑动窗口速度分析的加权 **0–100 机器人可能性评分**来评估传入的流量。 它还具有一个 **由 Playwright 提供支持的自动化 CLI 攻击测试框架**，可针对您的应用程序（或任何目标网站）运行 6 种真实的机器人场景，以审核检测的有效性。 ## ✨ 核心功能 - 🛡️ **加权检测引擎（0–100 分数）**：通过 header、客户端信号和微行为进行快速评估。 - ⚡ **Express 和 Fastify 原生中间件**：即插即用的安全包装器，提供诊断响应 header（`X-Fauxhuman-Score`、`X-Fauxhuman-Action`）。 - 🔬 **客户端遥测收集器（`fauxhuman.js`）**： - `navigator.webdriver` 状态验证 - Canvas 2D 渲染签名检查 - WebGL 软件渲染识别（SwiftShader、Mesa、LLVMpipe） - 插件与 MimeType 数组异常检测 - 🖱️ **行为微遥测**： - 曲率方差计算，用于捕获合成的直线鼠标路径 - 亚人类反射交互检测（<180ms） - 动态不可见 DOM 蜜罐陷阱生成 - 🔐 **HMAC SHA-256 Payload 验证**：可选的密钥签名，防止遥测 token 被篡改。 - 🧩 **可扩展的自定义规则 API**：通过 `engine.addRule()` 注册自定义异步评估函数。 - 🚀 **Redis 速率存储 + 内存回退**：具有自动零配置内存回退功能的滑动窗口速率限制器。 - 🧪 **Playwright 攻击测试框架 CLI**：针对 cURL 脚本、标准无头 Chromium、隐蔽浏览器、蜜罐爬虫、泛洪攻击和人类模拟器对任何 endpoint 进行基准测试。 - 📄 **HTML 审计报告生成器**：通过 `--report` 生成独立、可共享的离线 HTML 安全审计报告。 ## 📦 安装 ``` npm install fauxhuman ``` ## 🚀 安装与快速入门 ### 1. Express 中间件集成 ``` import express from 'express'; import { fauxhumanExpress } from 'fauxhuman'; const app = express(); // Protect /api routes app.use('/api', fauxhumanExpress({ flagThreshold: 45, // Flag requests with score >= 45 blockThreshold: 75, // Block requests with score >= 75 (HTTP 403) useRedis: true, // Uses Redis if available, falls back to memory automatically })); app.get('/api/resource', (req, res) => { res.json({ success: true, botScore: req.fauxhuman?.score }); }); app.listen(3000, () => console.log('Server running on port 3000')); ``` ### 2. Fastify 插件集成 ``` import Fastify from 'fastify'; import { fauxhumanFastify } from 'fauxhuman'; const fastify = Fastify(); fastify.register(fauxhumanFastify, { flagThreshold: 45, blockThreshold: 75, }); fastify.get('/api/protected', async (request, reply) => { return { status: 'OK', score: request.fauxhuman?.score }; }); fastify.listen({ port: 3000 }); ``` ### 3. 嵌入客户端收集脚本（`fauxhuman.js`） 在前端 HTML 模板中引入此轻量级脚本，以收集浏览器硬件信号和鼠标遥测数据： ``` ``` ## 🧩 可扩展性与 HMAC 安全性 ### 注册自定义规则 使用您自己的自定义安全检查扩展引擎（例如 GeoIP 黑名单、header 规则）： ``` import { FauxhumanEngine } from 'fauxhuman'; const engine = new FauxhumanEngine({ secretKey: 'super-secret-key' }); // Add custom rule evaluator engine.addRule((ip, headers, signals) => { if (headers['x-custom-bot-header']) { return { ruleId: 'CUSTOM_BOT_HEADER', ruleName: 'Custom Bot Signature', category: 'header', scoreDelta: 50, reason: 'Request contained custom bot signature header.' }; } return null; }); ``` ## 🧪 CLI 攻击测试框架：审核目标 Endpoint 针对 6 种真实的机器人场景审核您的应用程序或任何目标 URL： ``` # 对目标 endpoint 运行安全基准测试 npx fauxhuman test --url http://localhost:3000/api/verify # 生成独立的 HTML 审计报告文件 npx fauxhuman test --url https://your-domain.com/api --report audit-report.html ``` ### CLI 终端输出预览 ``` ┌────────┬──────────────────────────────┬────────────────────┬──────────┬──────────┬────────┬──────────┬──────────┐ │ ID │ Scenario Name │ Category │ Expected │ Detected │ Score │ Result │ Time │ ├────────┼──────────────────────────────┼────────────────────┼──────────┼──────────┼────────┼──────────┼──────────┤ │ SCN-01 │ cURL / Scripted HTTP Request │ Raw HTTP Client │ BLOCK │ BLOCK │ 75 │ PASS │ 30ms │ │ SCN-02 │ Standard Headless Chromium │ Automated Browser │ BLOCK │ BLOCK │ 100 │ PASS │ 643ms │ │ SCN-03 │ Stealth Headless Attempt │ Evasive Bot │ FLAG │ FLAG │ 50 │ PASS │ 565ms │ │ SCN-04 │ Honeypot Link Crawler │ Behavior Trap │ BLOCK │ BLOCK │ 90 │ PASS │ 630ms │ │ SCN-05 │ High-Velocity Request Flood │ Rate Limit / DoS │ BLOCK │ BLOCK │ 100 │ PASS │ 43ms │ │ SCN-06 │ Human Visitor Simulator │ Legitimate User │ ALLOW │ ALLOW │ 0 │ PASS │ 2831ms │ └────────┴──────────────────────────────┴────────────────────┴──────────┴──────────┴────────┴──────────┴──────────┘ Detection Efficacy: 100% (6/6 Scenarios Caught) ``` # 🇹🇷 Türkçe Dokümantasyon ## 📌 是什么？ **Fauxhuman**（名字来源于 *"faux human"* —— 人造人/机器人访客的概念），是为 Node.js 应用程序开发的开源 **机器人检测中间件和攻击模拟 CLI 工具**。 Fauxhuman 通过分析浏览器硬件指纹（Canvas 2D、WebGL 软件渲染器）、header 异常、鼠标移动曲率、不可见的 Honeypot 陷阱以及 Redis 速率限制，为请求计算出 **0 到 100 之间的实时机器人可能性分数**。 同时，通过拥有 Playwright 基础架构的 **CLI 测试框架**命令，您可以对自己的网站（或目标地址）运行机器人场景，并报告您网站的机器人保护成功率。 ## 🚀 核心功能 - 🛡️ **0–100 高级评分引擎**：多层规则评估。 - ⚡ **支持 Express 和 Fastify**：只需一行代码即可添加到您的项目中，自动使用 403 Forbidden 拦截恶意请求。 - 🔬 **客户端指纹脚本（`fauxhuman.js`）**： - `navigator.webdriver` 存在性 - Canvas 2D 签名验证 - WebGL 软件渲染检测（SwiftShader、Mesa、LLVMpipe） - 缺失的浏览器插件/ MimeType 异常 - 🖱️ **行为鼠标分析**： - 检测人工直线的鼠标移动（零曲率方差） - 捕获点击不可见 Honeypot 陷阱链接的机器人 - 🔐 **HMAC SHA-256 客户端 Token 验证**：防止 token 被篡改。 - 🧩 **自定义规则添加 API（`engine.addRule()`）**：您可以轻松添加自己的自定义检查规则。 - 🚀 **Redis + 内存回退速率限制器**：在没有 Redis 的情况下，也会在内存中执行滑动窗口速率限制。 - 🧪 **CLI 测试模拟器（`npx fauxhuman test`）**：运行 cURL、无头 Chrome、隐蔽机器人、Honeypot 猎手、请求泛洪攻击和真实人类模拟。 - 📄 **HTML 报告生成器（`--report audit.html`）**：将攻击模拟输出保存为离线 HTML 安全报告。 ## 📜 许可证 基于 **MIT License** 分发。详情请参阅 [`LICENSE`](LICENSE)。 怀着 ❤️ 为开源与网络安全社区开发。

标签：Express, Fastify, GNU通用公共许可证, MITM代理, Node.js, TypeScript, Web中间件, 安全插件, 搜索引擎查询, 机器人检测, 特征检测, 自动化攻击, 行为分析引擎