FrannnnDev/RiskEngine-JS
GitHub: FrannnnDev/RiskEngine-JS
基于行为分析的JavaScript反滥用与反作弊引擎，通过统计异常检测和多层风险评分为Web应用和API提供实时自适应安全防护。
Stars: 27 | Forks: 0
# RiskEngine-JS
**面向 JavaScript 应用的高级基于行为的反滥用与反作弊引擎**
[](https://github.com/yourusername/RiskEngine-JS/blob/main/LICENSE)
[](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
[](https://nodejs.org/
## 🚀 **概述**
RiskEngine-JS 是一个**尖端的基于行为的安全系统**，旨在保护您的 Web 应用程序、API 和实时系统免受滥用、作弊和自动化攻击。通过使用**统计分析、异常检测和机器学习技术**分析用户行为模式，RiskEngine 动态计算风险评分并应用**自适应缓解策略**，以保持您的平台安全。
### **核心功能**
✅ **多层风险评分** – 结合行为分析、模式检测、速率限制和设备指纹识别
✅ **自适应缓解** – 通过可配置的风险阈值自动适应新威胁
✅ **实时保护** – 与 Express.js 及其他 Web 框架无缝集成
✅ **行为分析** – 检测用户交互模式中的异常
✅ **设备与会话跟踪** – 识别可疑的设备行为和会话异常
✅ **速率限制与节流** – 防止暴力破解攻击和 API 滥用
✅ **Bot 与自动化检测** – 使用熵分析和指纹识别来检测 Bot
✅ **威胁情报集成** – 内置已知恶意模式黑名单
✅ **可扩展架构** – 模块化设计，易于定制和集成
### **适用人群**
- **Web 应用程序开发者** – 保护您的应用免受自动化攻击
- **API 提供商** – 通过动态速率限制保护您的端点
- **电子商务平台** – 防止欺诈和支付滥用
- **游戏开发者** – 实时检测并阻止作弊行为
- **社交媒体与社区网站** – 防止垃圾信息和滥用
- **安全团队** – 为您的基础设施添加额外保护层
## ✨ **功能详解**
### **1. 高级行为分析**
- **统计异常检测** – 识别异常的用户行为模式
- **基于熵的自动化检测** – 检测脚本交互
- **时间序列分析** – 分析用户活动节奏和序列
### **2. 模式检测引擎**
- **暴力破解检测** – 阻止重复的登录尝试
- **API 滥用防护** – 限制过度的 API 调用
- **爬虫与抓取检测** – 识别自动化数据采集
- **账户盗用防护** – 检测可疑的密码重置模式
### **3. 速率限制与节流**
- **自适应速率限制** – 根据用户行为调整限制
- **突发流量保护** – 防止请求量突然激增
- **惩罚与奖励系统** – 惩罚滥用用户，奖励良好用户
### **4. 设备与会话跟踪**
- **设备指纹识别** – 创建唯一的设备签名
- **会话异常检测** – 识别可疑的会话行为
- **设备信任评分** – 根据可信度对设备进行排名
### **5. 威胁情报**
- **Bot User-Agent 黑名单** – 阻止已知的 Bot
- **可疑模式检测** – 标记恶意 Payload
- **地理位置与 ASN 风险评分** – 基于位置和网络评估风险
### **6. 中间件集成**
- **Express.js 中间件** – 轻松集成到现有应用中
- **可定制的风险决策** – 定义您自己的缓解策略
- **实时风险标头** – 将风险评分传递给您的应用程序
## 🛠️ **技术栈**
| 类别 | 所用技术 |
|------------------|--------------------------------------------|
| **语言** | JavaScript (ES6+) |
| **框架** | Express.js (用于中间件集成) |
| **依赖项** | `uuid` (用于生成唯一标识符) |
| **数据存储** | 内存存储 (支持 TTL) |
| **数学库** | 自定义统计和熵计算器 |
### **系统要求**
- **Node.js** ≥ 14.0
- **npm** 或 **yarn** 用于包管理
- **Express.js** (用于中间件集成)
## 📦 **安装**
### **前置条件**
确保您已安装 Node.js:
```
node -v # Should be ≥ 14.0
npm -v # Should be ≥ 6.0
```
### **快速开始**
1. **克隆仓库:**
git clone https://github.com/decentholograms/RiskEngine-JS.git
cd RiskEngine-JS
2. **安装依赖:**
npm install
3. **运行演示服务器:**
npm start
服务器将在 `http://localhost:3000` 上启动。
4. **访问演示端点:**
- `/health` – 健康检查端点
- `/metrics` – 风险引擎统计信息
- `/api/users` – 受保护的端点示例
## 🎯 **使用示例**
### **1. 与 Express.js 的基本集成**
```
import express from 'express';
import RiskEngine from 'risk-engine-js';
import createAntiAbuseMiddleware from 'risk-engine-js/middleware/antiAbuse';
const app = express();
const PORT = 3000;
// Initialize RiskEngine with custom thresholds
const riskEngine = new RiskEngine({
thresholds: {
low: 0.25,
medium: 0.5,
high: 0.7,
critical: 0.9
},
weights: {
behavior: 0.25,
patterns: 0.25,
rateLimit: 0.2,
fingerprint: 0.15,
reputation: 0.15
},
onHighRisk: (decision) => {
console.log(`[ALERT] High risk detected for user ${decision.userId}: ${decision.riskScore.toFixed(3)}`);
}
});
// Create anti-abuse middleware
const antiAbuse = createAntiAbuseMiddleware({
engine: riskEngine,
trustProxy: true,
skipPaths: ['/health', '/metrics'],
onDecision: (decision, req, res) => {
if (decision.riskScore > 0.5) {
console.log(`[RISK] ${req.method} ${req.path} - Score: ${decision.riskScore.toFixed(3)}`);
}
}
});
// Apply middleware to all routes
app.use(antiAbuse);
// Example protected route
app.get('/api/users', (req, res) => {
res.json({
users: [{ id: 1, name: 'User 1' }],
riskDecision: req.riskDecision ? {
score: req.riskDecision.riskScore,
level: req.riskDecision.riskLevel
} : null
});
});
app.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
});
```
### **2. 评估用户的风险评分**
```
import RiskEngine from 'risk-engine-js';
const riskEngine = new RiskEngine();
// Simulate a request object
const request = {
ip: '192.168.1.1',
userId: 'user123',
method: 'GET',
path: '/api/users',
headers: {
'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
}
};
// Evaluate the risk
async function evaluateRisk() {
const decision = await riskEngine.evaluate(request);
console.log('Risk Decision:', decision);
// Output: { riskScore: 0.12, riskLevel: 'low', action: { type: 'allow' } }
}
evaluateRisk();
```
### **3. 自定义风险阈值**
```
const riskEngine = new RiskEngine({
thresholds: {
low: 0.3, // Allow users with risk < 0.3
medium: 0.6, // Challenge users with risk between 0.3 and 0.6
high: 0.8, // Throttle users with risk between 0.6 and 0.8
critical: 0.9 // Block users with risk ≥ 0.9
},
weights: {
behavior: 0.3, // Increase weight for behavior analysis
patterns: 0.2, // Decrease weight for pattern detection
rateLimit: 0.25, // Increase weight for rate limiting
fingerprint: 0.15, // Keep fingerprint weight the same
reputation: 0.1 // Decrease weight for reputation
}
});
```
## 📁 **项目结构**
```
RiskEngine-JS/
├── src/
│ ├── core/ # Core risk analysis components
│ │ ├── RiskEngine.js # Main risk engine class
│ │ ├── BehaviorAnalyzer.js
│ │ ├── PatternDetector.js
│ │ ├── RateLimiter.js
│ │ ├── Fingerprinter.js
│ │ ├── AnomalyDetector.js
│ │ ├── ThreatIntelligence.js
│ │ ├── SessionTracker.js
│ │ └── VelocityChecker.js
│ ├── middleware/ # Express middleware
│ │ └── antiAbuse.js
│ ├── storage/ # Data storage implementations
│ │ └── MemoryStore.js
│ ├── utils/ # Utility functions
│ │ ├── MathUtils.js
│ │ ├── EntropyCalculator.js
│ │ └── TimeSeriesAnalyzer.js
│ └── index.js # Main exports
├── server.js # Demo server
├── package.json
├── README.md # This file
└── LICENSE # MIT License
```
## 🔧 **配置**
### **环境变量**
RiskEngine-JS 可以通过环境变量进行配置，以便于部署:
| 变量 | 描述 | 默认值 |
|--------------------------|----------------------------------------------|---------------|
| `RISK_ENGINE_THRESHOLDS` | 风险阈值的 JSON 字符串 | `{ "low": 0.3, "medium": 0.5, "high": 0.7, "critical": 0.9 }` |
| `RISK_ENGINE_WEIGHTS` | 风险因子权重的 JSON 字符串 | `{ "behavior": 0.25, "patterns": 0.25, "rateLimit": 0.2, "fingerprint": 0.15, "reputation": 0.15 }` |
| `RISK_ENGINE_RATE_LIMIT` | 速率限制设置的 JSON 字符串 | `{ "defaultLimit": 100, "windowSize": 60000, "burstMultiplier": 2 }` |
示例:
```
export RISK_ENGINE_THRESHOLDS='{"low": 0.2, "medium": 0.5, "high": 0.8, "critical": 0.95}'
export RISK_ENGINE_WEIGHTS='{"behavior": 0.3, "patterns": 0.2, "rateLimit": 0.3, "fingerprint": 0.15, "reputation": 0.05}'
```
### **自定义风险决策**
您可以根据风险评分定义自定义操作:
```
const riskEngine = new RiskEngine({
actions: {
allow: { maxScore: 0.4 }, // Allow users with risk < 0.4
challenge: { minScore: 0.4, maxScore: 0.6 }, // Challenge users with risk between 0.4 and 0.6
throttle: { minScore: 0.6, maxScore: 0.8 }, // Throttle users with risk between 0.6 and 0.8
block: { minScore: 0.8, maxScore: 0.95 }, // Block users with risk between 0.8 and 0.95
ban: { minScore: 0.95 } // Ban users with risk ≥ 0.95
}
});
```
### **开发环境设置**
1. 克隆仓库:
git clone https://github.com/decentholograns/RiskEngine-JS.git
cd RiskEngine-JS
2. 安装开发依赖:
npm install --dev
3. 以监视模式运行开发服务器:
npm run dev
4. 运行测试:
npm test
### **代码风格指南**
- 使用 **ES6+ JavaScript** 特性。
- 遵循**一致的缩进** (2 个空格)。
- 为复杂逻辑编写**清晰、简洁的注释**。
- 确保**代码结构良好**且模块化。
- 使用 **JSDoc** 进行函数和类的文档编写。
### **Pull Request 流程**
1. 确保您的 PR 描述清楚地解释了更改。
2. 引用任何相关的问题或工单。
3. 如果适用，请包含屏幕截图或示例。
4. 乐于接受反馈并愿意对您的更改进行迭代。
## 📝 **许可证**
RiskEngine-JS 在 **MIT License** 下发布。详情请参阅 [LICENSE](LICENSE) 文件。
## 👥 **作者**
### **维护者**
- **FrannnDev** – [@FrannnDev](https://github.com/decentholograms) (初始开发)
### **致谢**
- 灵感来源于机器学习研究中的**统计异常检测**技术。
- 使用 **Express.js** 进行中间件集成。
- 使用**自定义实用程序库**进行数学和统计计算。
## 🐛 **问题与支持**
### **报告问题**
如果您遇到 Bug 或有功能请求，请：
1. 查看 [GitHub Issues](https://github.com/decentholograms/RiskEngine-JS/issues) 中的现有讨论。
2. 打开一个带有清晰标题和描述的新 Issue。
3. 包含**可重现的步骤**、**错误日志**和**预期行为**。
### **获取帮助**
- **讨论**: 加入我们的 [GitHub Discussions](https://github.com/decentholograms/RiskEngine-JS/discussions) 进行一般性提问。
### **常见问题**
**问: 我可以在生产环境中使用 RiskEngine-JS 吗？**
答: 可以！RiskEngine-JS 专为生产使用而设计，并已通过真实流量的测试。
**问: RiskEngine-JS 支持集群或分布式环境吗？**
答: 目前，RiskEngine-JS 使用内存存储。对于分布式环境，建议使用 Redis 或其他共享存储解决方案。
**问: 如何自定义风险因子？**
答: 您可以在 `weights` 配置对象中调整每个风险因子的权重。
**问: RiskEngine-JS 可以与其他框架集成吗？**
答: 虽然 RiskEngine-JS 是为 Express.js 设计的，但您可以提取核心逻辑并将其与其他框架集成。
## 🗺️ **路线图**
### **计划中的功能**
- **[进行中]** Redis 集成，用于分布式环境
- **[计划中]** 机器学习模型集成 (例如 TensorFlow.js)
- **[计划中]** GraphQL 中间件支持
- **[计划中]** 高级威胁情报源 (例如 AbuseIPDB, VirusTotal)
- **[计划中]** Docker 和 Kubernetes 部署指南
### **已知问题**
- **问题 #1**: 某些模式检测规则在特定情况下可能会产生误报。
- **问题 #2**: 内存存储可能不适用于高流量应用 (Redis 集成将解决此问题)。
### **未来改进**
- **增强的 Bot 检测**: 添加更复杂的 Bot 检测技术。
- **行为学习**: 允许引擎随着时间推移学习并适应新的用户行为。
- **性能优化**: 降低高吞吐量应用程序的延迟。
## 🚀 **立即开始！**
RiskEngine-JS 是您防御滥用、作弊和自动化攻击的**第一道防线**。无论您是在保护 Web 应用、API 还是游戏平台，RiskEngine 都能提供随应用程序增长的**实时、自适应安全性**。
🔗 **[GitHub 仓库](https://github.com/decentholograms/RiskEngine-JS)**
💬 **[加入讨论](https://github.com/decentholograms/RiskEngine-JS/discussions)**
标签：Apex, API安全, API网关安全, Bot检测, C2日志可视化, CISA项目, CMS安全, Express中间件, GNU通用公共许可证, IP 地址批量处理, JavaScript, JSON输出, MITM代理, Node.js, Web安全, 人机验证, 会话追踪, 作弊检测, 反作弊, 反欺诈, 反滥用, 威胁情报, 安全引擎, 实时系统, 开发者工具, 异常检测, 指纹识别, 数据可视化, 机器学习, 模式识别, 流量清洗, 游戏安全, 熵分析, 电商安全, 统计分析, 网络安全, 自动化攻击防御, 自定义脚本, 自适应缓解, 蓝队分析, 设备指纹, 账号安全, 金融科技安全, 防御恶意软件, 防止暴力破解, 隐私保护, 风控系统, 风险控制, 风险评分