jahanzaibwakeel/FraudPulse--Fraud-detection-system

# FraudPulse FraudPulse 是一个完全本地化、开源的实时欺诈检测系统。它模拟银行卡交易，通过 PostgreSQL 事件记录和基于 Valkey 的 BullMQ 评分队列传输数据，生成可解释的欺诈警报，并向风险运营团队展示实时仪表板。 ## 技术栈 - Frontend：Next.js、React、TypeScript、Recharts、Socket.IO client - API：Node.js、Express、TypeScript、Socket.IO、PostgreSQL - Worker：BullMQ、Valkey、可解释的规则/统计评分 - Database：PostgreSQL 迁移和演示种子数据 - Monitoring：Prometheus 和 Grafana OSS - 测试：Vitest、Supertest、Playwright ## 本地运行 ``` cp .env.example .env docker compose up --build ``` 访问地址： - Dashboard：http://localhost:13000 - API 健康检查：http://localhost:14000/health - PostgreSQL：localhost:15432 - Prometheus：http://localhost:19090 - Grafana：http://localhost:13001，登录凭据 `admin` / `fraudpulse` 模拟器会在 Docker Compose 中自动启动。修改 `SIMULATOR_TPS` 以控制交易量。 仪表板还包含以下场景的重放按钮： - 银行卡测试爆发 - 不可能行踪 - 账户接管 每个场景都会写入真实的交易记录，将评分任务加入队列，并通过与后台模拟器相同的流水线生成警报。 ## 本地开发 ``` npm install npm run dev:api npm run dev:worker npm run dev:simulator npm run dev:web ``` 运行测试： ``` npm test ``` 对 Docker Compose 执行部署冒烟检查： ``` npm run smoke ``` 捕获当前的仪表板截图： ``` npm run screenshots ``` 运行重新校准脚本： ``` npm run recalibrate ``` ## 本地安全模型 FraudPulse 内置了本地演示 API token，以确保整个技术栈保持免费、开源且支持单条命令运行。健康检查和 Prometheus 指标是公开的，用于容器检查；运营 API 路由需要提供 `x-api-token` 或 `Authorization: Bearer ...`。 默认角色： - `local-viewer-token`：只读仪表板访问权限 - `local-analyst-token`：案例审查、导出、备注和批量决策权限 - `local-admin-token`：规则调优、模拟器控制、模型重新校准和安全控制台权限 - `local-service-token`：模拟器交易摄取和 worker 广播权限 在真实的本地部署中，请修改 `.env` 文件中的 `API_TOKENS`、`NEXT_PUBLIC_API_TOKEN` 和 `API_SERVICE_TOKEN`。安全页面会显示当前会话、活跃的会话 token、速率限制桶、认证失败的安全事件、审计活动、token 轮换计划以及受保护的报告导出。 ## 架构 ``` flowchart LR S["Transaction Simulator"] --> API["Express API"] API --> DB[("PostgreSQL")] API --> Q["BullMQ / Valkey"] Q --> W["Fraud Scoring Worker"] W --> DB W --> API API --> WS["Socket.IO"] WS --> UI["Next.js Risk Ops Dashboard"] API --> P["Prometheus Metrics"] W --> P P --> G["Grafana OSS"] ``` ## 事件流水线 1. `transaction_created`：API 验证并存储生成或提交的交易，写入事件记录行，并将评分任务加入队列。 2. `transaction_scored`：worker 评估速度、金额异常、地理位置距离、商户风险和用户历史，随后存储欺诈评分。 3. `fraud_alert_created`：worker 针对高风险评分创建警报，并通过 API WebSocket 网桥广播该事件。 失败的评分任务会重试三次，随后移至 BullMQ 失败任务队列，同时由 `transaction_events` 死信记录捕获其 payload 和错误信息。 ## 案例管理 警报支持负责人分配、优先级设定、SLA 到期时间、分析师备注、审查决策以及审计时间线事件。这使得可解释性、工作流状态和人工反馈与同一个警报记录保持绑定。 ## 欺诈团伙检测 团伙图谱页面会从近期已评分的交易中检测出存在关联的可疑实体。它将用户、银行卡、设备、IP 地址和商户联系起来，然后将它们分组为按风险排名的集群，重点突出共享设备、共享 IP、商户趋同以及高交易集中度的情况。 ## 特征存储与规则调优 worker 为每一笔评分后的交易写入特征快照，包括速度窗口、金额 z-score、地理位移速度、商户风险和设备熟悉度。特征存储页面展示近期的异常情况，而规则页面可以在应用更改之前，预览提议的规则权重将如何改变警报数量和模型指标。 ## 分析师运营 运营页面会追踪 SLA 违规、即将到期的工作、未分配的案例、分析师工作负载、已保存的警报队列以及死信评分失败情况。团队主管可以批量分配警报，并将死信事件重新回放到评分队列中。 ## 混合 ML 风格评分与漂移 FraudPulse 将规则评分与从已存储特征计算得出的本地逻辑回归风格模型评分相结合。模型仪表板显示规则评分、ML 评分、混合评分、模型概率、相对于近期基线的漂移情况，以及高分歧交易。重新校准会在不调用任何外部服务的情况下创建新的活跃本地模型版本。 ## 生产环境强化 第 5 阶段增加了基于 token 的角色划分、受角色控制的变更路由、基于 token 的速率限制、审计检查、受保护的 CSV/JSON 报告导出、Socket.IO 身份验证，以及针对强化后接口的 E2E/API 测试。 ## 真实训练的本地模型 第 6 阶段增加了真实的本地训练路径。FraudPulse 利用带有标签的特征存储历史记录（包括合成的真实数据和分析师审查覆盖结果）来训练逻辑回归模型。训练后的模型会将学习到的系数、归一化统计数据、验证指标和训练样本计数写入 `model_versions`，随后评分 worker 会加载活跃模型进行实时推理。为了确保可解释性和操作可控性，规则引擎仍会保留在混合评分体系中。 通过 CLI 进行训练： ``` npm run train:model ``` 或者使用“模型指标”仪表板上的按钮，在运行中的 Docker 应用内直接进行训练。 ## 模型可解释性 第 7 阶段增加了训练模型的特征贡献解释。每个由 ML 驱动的警报都会记录模型类型、概率、线性得分、规则/混合得分，以及影响风险上升或下降的主要特征贡献。警报详情会展示这些贡献供案例审查使用，同时模型仪表板会汇总近期警报中最显著的特征驱动因素。 ## 模型注册表 第 8 阶段引入了冠军/挑战者模型治理机制。模型注册表页面列出所有本地模型版本，识别当前的冠军模型，推荐非活跃的挑战者模型，针对近期的特征存储记录运行影子评分，并允许管理员在不删除模型历史的情况下进行模型提升或回滚。 ## 实体风险记忆 第 9 阶段为用户、银行卡、商户、设备和 IP 地址增加了滚动风险记忆。评分 worker 在每次交易评分后更新 `entity_risk_memory`，综合考量警报评分、速度、异常强度、商户风险和近期证据。风险记忆页面展示风险最高的实体，并且用户/商户画像包含持久化的记忆风险。 ## 案例调查工作台 第 10 阶段将警报详情升级为全方位的案例调查工作台。API 构建了一个单一的证据包，其中包含警报、交易、特征快照、实体记忆、相关的用户/银行卡/设备/IP 活动、商户警报模式、时间线以及建议的分析师操作。分析师可以在最终审查前保存特定时间点的证据快照，以保证可审计性。 ## 数据质量与漂移警报 第 11 阶段为本地事件和特征流水线增加了数据质量监控。FraudPulse 会检查未评分的交易、无效值、缺失的实体关联、特征存储漏洞、孤儿事件、死信事件、评分延迟、数据摄取新鲜度、评分滞后以及特征漂移。运维人员可以从数据质量页面运行检查，持久化质量运行记录，并追踪未解决的漂移/质量警报。 ## 高级模拟实验室 第 12 阶段增加了可配置的欺诈活动实验室。运维人员可以选择目标演示账户，选定一个活动，调整交易数量、节奏、金额倍数、欺诈率、设备策略和 IP 策略，然后将生成的交易注入真实的 API、队列、评分 worker、警报和 WebSocket 路径中。每次运行的结果都会连同其参数、预期信号、交易 ID 和状态一起被持久化存储。 ## 真实模型基准测试 第 13 阶段加入了本地模型基准测试套件。FraudPulse 会使用相同的特征存储验证集，对规则基线、训练后的逻辑回归、高斯朴素贝叶斯和最近中心分类器进行评估。基准测试运行记录将被持久化保存，其中包含各项指标、混淆矩阵、已测试的算法以及基于 F1/召回率选出的最佳算法。 ## 安全强化 V2 第 14 阶段升级了本地安全层，加入了哈希化的 API token 匹配机制、常数时间比较、具有过期机制的本地会话、会话撤销、认证失败锁定、请求 ID、受限的 CORS 和 Socket.IO 来源设置、安全事件遥测以及 token 轮换计划。系统在展示欺诈运营 API 在正式部署前所需的各项控制手段的同时，依然保持完全本地化和免费。 ## 部署完善 第 15 阶段增加了代码仓库的最终展示层：GitHub Actions CI、Docker 冒烟检查、仪表板截图捕获、部署指南以及演示演练。CI 工作流会构建并测试 TypeScript 工作区，验证 Docker Compose，启动本地技术栈，执行冒烟检查，针对仪表板运行 Playwright，并将截图作为构建产物上传。 ## 阶段路线图 已完成： - 第 1 阶段：欺诈团伙检测和图谱视图 - 第 2 阶段：特征存储和规则影响预览 - 第 3 阶段：分析师运营工作流 - 第 4 阶段：混合 ML 评分、漂移监控和重新校准控制 - 第 5 阶段：包含身份验证、安全、报告和 E2E 测试的生产环境强化 - 第 6 阶段：真实训练的本地欺诈模型 - 第 7 阶段：基于训练模型各项特征贡献的模型可解释性 - 第 8 阶段：支持冠军/挑战者提升和回滚的模型注册表 - 第 9 阶段：针对用户、银行卡、设备、IP 和商户的实体风险记忆 - 第 10 阶段：带有证据包的案例调查工作台 - 第 11 阶段：数据质量检查和漂移警报 - 第 12 阶段：用于可配置欺诈活动的高级模拟实验室 - 第 13 阶段：跨多种本地算法的真实模型基准测试 - 第 14 阶段：包含本地会话、锁定、请求 ID 和密钥轮换计划的安全强化 V2 - 第 15 阶段：包含 CI、冒烟检查、截图和演示演练的部署完善 待办： - 无。FraudPulse 已按计划完成了所有路线图内容。 ## 文档 - API 文档：[docs/api.md](docs/api.md) - 案例研究：[docs/case-study.md](docs/case-study.md) - 部署指南：[docs/deployment.md](docs/deployment.md) - Oracle 免费 VM 部署：[docs/oracle-deployment.md](docs/oracle-deployment.md) - 演示演练：[docs/demo-walkthrough.md](docs/demo-walkthrough.md) - 截图：[docs/screenshots](docs/screenshots) - SQL schema：[infra/db/migrations/001_init.sql](infra/db/migrations/001_init.sql) - Grafana 仪表板：[infra/grafana/dashboards/fraudpulse.json](infra/grafana/dashboards/fraudpulse.json)

标签：Apex, BullMQ, Grafana, MITM代理, PostgreSQL, 反欺诈检测, 机器学习, 测试用例, 版权保护, 特征检测, 自动化攻击, 自定义请求头, 风控系统