garvindsamy55-commits/TwinTrap

# TwinTrap – 用于凭据攻击检测的自适应数字孪生蜜罐  **TwinTrap** 是一个企业级网络安全 SaaS 原型，实现了**自适应数字孪生蜜罐**。它专为检测、隔离和消除云环境中的凭据攻击、暴力破解尝试和未经授权的权限提升而设计。 当用户尝试登录时，TwinTrap 会运行 **AI 风险评估引擎**来评估上下文信号。低风险的合法用户将被引导至**真实云控制台**。可疑会话或 OTP 验证失败会无缝重新路由到一个逼真的**自适应数字孪生蜜罐**中，在隔离攻击者行为的同时，将详细的取证遥测数据记录到**管理员威胁情报控制台**中。 ## 📐 架构图 ``` flowchart TD A[User Authentication / Login] --> B[AI Risk Assessment Engine] B -->|Contextual Analysis| C{Risk Score Threshold} C -->|Score 0 - 49: Legitimate| D[Real Cloud Dashboard] C -->|Score 50 - 100: Suspicious| E[Verification Sandbox OTP Challenge] E -->|Valid OTP: 123456| D E -->|Invalid OTP / Timeout| F["Digital Twin Deployment Engine ('Creating Digital Twin...')"] F --> G[Adaptive Digital Twin Honeypot Console] G --> H[Fake Cloud Admin Console & Bait Targets] G --> I[Interactive Cloud Shell CLI Terminal] H -->|Attacker Clicks Bait / Commands| J[Deceptive Delay & Decoy Engine] I -->|Executes Shell Commands| J J --> K[(Silent Telemetry Store / LocalStorage)] K --> L[SOC Threat Activity Monitor] K --> M[Admin Threat Intelligence Dashboard] ``` ### 认证与路由序列 ``` sequenceDiagram autonumber actor Attacker as Attacker / User participant App as TwinTrap Frontend SPA participant RiskEngine as AI Risk Engine participant Sandbox as Verification Sandbox participant Honeypot as Digital Twin Honeypot participant Telemetry as Telemetry & SOC Engine Attacker->>App: Submits Login Credentials App->>RiskEngine: Run 8-Metric Contextual Analysis RiskEngine-->>App: Calculates Composite Risk Score (e.g. 88/100) alt Low Risk (0-49) App-->>Attacker: Redirect to Real Cloud Console else High Risk (50-100) App->>Sandbox: Require 2FA OTP Code alt Correct OTP (123456) Sandbox-->>Attacker: Grant Access to Real Cloud Console else Incorrect OTP Sandbox->>Honeypot: Deploy Digital Twin Environment Honeypot-->>Attacker: Render Fake Enterprise Cloud Console loop Attacker Interactions Attacker->>Honeypot: Clicks "Download DB" / Types CLI Commands Honeypot-->>Attacker: Show Deceptive Loading Spinners & Fake Success Honeypot->>Telemetry: Silently Log Timestamp, Action, Risk Score, IP & UserAgent end Telemetry->>App: Update SOC & Admin Threat Intelligence Real-time Dashboards end end ``` ## 📂 文件夹结构 ``` TwinTrap/ │ ├── index.html # Main SPA interface containing all 6 core view containers & modals ├── css/ │ └── styles.css # Enterprise SOC design system (Glassmorphism, dark themes, CSS tokens, animations) ├── js/ │ └── app.js # Core JS application engine (State router, AI Risk Engine, Honeypot traps, Telemetry) ├── README.md # Complete documentation & technical guide └── implementation_plan.md # Architecture and design plan document ``` ## 🚀 安装与本地执行指南 TwinTrap 是作为零后端、高性能 Web 应用程序构建的，使用了 **HTML5、原生 CSS3、JavaScript (ES6+) 和 LocalStorage**。无需安装数据库或复杂的构建工具。 ### 选项 1：直接文件启动 只需在任何现代 Web 浏览器（Google Chrome、Mozilla Firefox、Microsoft Edge、Brave、Safari）中打开 `index.html`。 ### 选项 2：本地 HTTP 服务器（推荐） #### 使用 Python（内置） ``` # 导航到项目根目录 cd TwinTrap # 在端口 8080 上启动 Python HTTP Server python -m http.server 8080 ``` 打开浏览器并导航至：**`http://localhost:8080/index.html`** #### 使用 Node.js `serve` / `http-server` ``` # 如有需要，全局安装 serve npm install -g serve # 在当前目录运行 server serve . ``` 导航至提供的 localhost URL（例如 `http://localhost:3000`）。 ## 💾 数据库架构（LocalStorage 遥测存储） 所有会话状态、风险评估结果、攻击者行为和审计日志均在客户端使用 `localStorage` 进行管理，存储于键名 **`twintrap_logs`** 下。 ### 遥测记录架构 ``` { "id": "LOG-89101", "timestamp": "8/1/2026, 11:30:45 AM", "action": "Download Production Customer Database", "category": "Digital Twin Trap Triggered", "riskScore": 98, "isHoneypot": true, "ip": "185.220.101.45", "location": "Frankfurt, DE (Tor Exit Node)", "userAgent": "Mozilla/5.0 (X11; Linux x86_64; rv:109.0)", "sessionId": "SESS-9821" } ``` ### 数据字段定义 | 字段 | 类型 | 描述 | | :--- | :--- | :--- | | `id` | `String` | 唯一的遥测日志标识符（例如 `LOG-XXXXX`、`TRAP-XXXXX`、`CLI-XXXXX`） | | `timestamp` | `String` | 事件发生的本地化日期和时间字符串 | | `action` | `String` | 用户或攻击者执行操作的描述 | | `category` | `String` | 事件类别（`Honeypot Trap Hit`、`Interactive Attacker Terminal`、`Authentication Failure`、`Real Dashboard Access`） | | `riskScore` | `Number` | 计算出的风险得分，介于 `0`（安全）到 `100`（严重威胁）之间 | | `isHoneypot` | `Boolean` | 如果事件发生在数字孪生蜜罐内则为 `true`，否则为 `false` | | `ip` | `String` | 客户端 IP 地址（模拟或真实的客户端地址） | | `location` | `String` | 基于 IP 信誉的地理位置预估 | | `userAgent` | `String` | 客户端浏览器 User-Agent 字符串 | | `sessionId` | `String` | 链接到活动浏览器会话的唯一会话标识符 | ## 🔌 内部 API 与模块参考（`js/app.js`） `js/app.js` 暴露了管理应用程序流程、风险计算、蜜罐诱捕和遥测存储的模块化函数： ### 1. 视图导航与路由 - `switchView(viewId)` - **参数**：`viewId` (`String`) – 目标视图 ID（`login-view`、`risk-view`、`sandbox-view`、`real-dashboard-view`、`honeypot-view`、`threat-monitor-view`、`admin-view`）。 - **行为**：激活目标视图容器，更新顶部导航栏链接状态，触发背景画布过渡，并刷新 Chart.js 图表实例。 ### 2. 风险评估引擎 - `triggerLoginFlow(forceRiskScore)` - **参数**：`forceRiskScore` (`Number`) – 用于测试预设的可选分数覆盖。 - **行为**：在调用 `runRiskAssessment()` 之前，显示多步骤扫描模态覆盖层（`Authenticating...` → `Connecting...` → `Scanning...` → `Initializing...`）。 - `runRiskAssessment(forcedScore)` - **行为**：计算 8 项风险指标的数值，渲染带有指针动画的 Chart.js 速度计仪表盘，并将用户路由到真实控制台（分数 <50）或沙盒（分数 >=50）。 ### 3. 验证沙盒 - `verifyOtpCode()` - **行为**：检查 6 位 OTP 输入。如果为 `123456`，则记录成功并重定向到真实云控制台。如果不正确，则记录失败事件，显示矩阵覆盖层 *"Creating Digital Twin Environment..."*，并重定向到蜜罐。 ### 4. 蜜罐与欺骗引擎 - `triggerHoneypotDecoy(actionName)` - **参数**：`actionName` (`String`) – 被点击的诱饵按钮名称。 - **行为**：模拟逼真的多步骤授权加载动画（`Processing...` → `Decrypting...` → `Success...`），打开带有虚假模拟 payload 的诱饵对话框，并静默将遥测记录到 `localStorage`。 - `setupTerminalInput()` - **行为**：监听交互式 Cloud Shell CLI 上的 Enter 键。支持命令：`ls`、`cat secret_keys.env`、`dump_db`、`whoami`、`help`、`clear`。将执行的命令记录到 `localStorage`。 ### 5. 遥测与数据管理 - `getLogsFromStorage()`：从 `localStorage` 检索已解析的日志数组。 - `saveLogToStorage(logEntry)`：将新的日志条目插入到 `localStorage` 并更新活动的 UI 计数器。 - `exportLogsCSV()`：将遥测日志转换为可下载的 `.csv` 文件。 - `exportLogsJSON()`：将遥测日志转换为可下载的格式化 `.json` 文件。 - `clearTelemetryLogs()`：确认后从 `localStorage` 清除 `twintrap_logs`。 - `startAttackSimulator()` / `stopAttackSimulator()`：切换用于演示目的的蜜罐诱捕连续自动模拟。 ## 🧪 测试与验证指南 请按照此分步指南在黑客马拉松演示或代码审查期间验证所有安全路径： ### 测试用例 1：合法用户工作流 1. 在**登录页面**，点击预设按钮 **`Legitimate Admin (Low Risk)`**。 2. 点击 **Authenticate Session**。 3. 观察 AI 风险评估扫描序列。 4. 验证**风险得分**计算低于 50（例如 `18/100`），并带有绿色的 **Verified** 状态徽章。 5. 点击 **Enter Cloud Dashboard**，观察带有实时网络流量图表的**真实云控制台**。 ### 测试用例 2：可疑用户与 OTP 验证通过 1. 在**登录页面**，点击 **`Employee (High Risk)`**。 2. 认证会话 → 观察风险得分计算高于 50（例如 `85/100`），带有红色的 **Suspicious** 徽章。 3. 点击 **Proceed to Sandbox** → 您将进入**验证沙盒**。 4. 输入有效的 OTP 代码：**`123456`**。 5. 点击 **Verify Two-Factor Token** → 确认重定向到**真实云控制台**。 ### 测试用例 3：攻击者被困在数字孪生蜜罐中 1. 在**登录页面**，点击 **`Attacker (Suspicious IP)`**。 2. 完成风险引擎扫描（风险得分约 94/100） → 重定向到验证沙盒。 3. 输入错误的 OTP 代码（例如 **`999999`**）。 4. 点击 **Verify Two-Factor Token**。 5. 观察红色失败消息和矩阵模态：**`Creating Digital Twin Environment...`**。 6. 您将进入**自适应数字孪生蜜罐**控制台。 ### 测试用例 4：蜜罐诱饵交互与交互式终端 1. 在**数字孪生蜜罐**内，点击任意诱饵目标按钮（例如 **Download DB Dump**、**View API Keys**、**Export Credit Cards**）。 2. 观察多阶段授权模态（`Decrypting Secure Object Store...` → `Success`）。 3. 向下滚动到 **Interactive Cloud Shell** 终端并输入： ls cat secret_keys.env dump_db whoami 4. 确认终端窗口中输出的逼真 bash 响应。 ### 测试用例 5：遥测检查与数据导出 1. 点击顶部导航栏中的 **SOC Monitor**。 2. 确认测试用例 4 中的所有诱饵点击和 CLI 命令都出现在 **Recent Attacker Event Stream** 和图表中。 3. 点击顶部导航栏中的 **Admin Intelligence**。 4. 按严重性筛选或搜索特定术语（例如 `cat` 或 `Download`）。 5. 点击任意日志行上的 **Inspect** 以查看取证会话详情。 6. 点击 **Export CSV** 或 **Export JSON** 以验证数据导出功能。 7. 点击 **Executive Report** 生成可打印的高管安全 PDF 报告。 ## 🧠 必要的技术概念与原则 ### 1. 自适应数字孪生蜜罐欺骗 传统的蜜罐作为独立的静态服务器存在，老练的攻击者可以轻易对其进行指纹识别并加以规避。TwinTrap 实现了一种**自适应数字孪生**方法： - 当检测到凭据攻击或认证异常时，TwinTrap 会动态实例化一个企业云控制台的隔离“孪生”镜像。 - 该环境的外观、感觉和响应都像真实的生产控制台，包含逼真的加载延迟、虚假的 API key 和欺骗性的数据库转储。 - 这使得攻击者沉浸在一个无害的沙盒中，同时防御者可以收集威胁情报。 ### 2. 零信任上下文 AI 风险引擎 TwinTrap 不仅依赖于正确的密码，还在登录期间评估 8 个多维风险因素： 1. **设备信任**：浏览器指纹识别与硬件一致性。 2. **地理异常**：与历史登录位置的距离差异。 3. **浏览器指纹**：User-Agent 和 header 签名。 4. **登录时间差异**：非工作时间访问检测。 5. **行为得分**：打字节奏与交互速度。 6. **IP 威胁等级**：检查已知的 Tor 出口节点和代理。 7. **速度检查**：每分钟请求速率检测。 8. **会话一致性**：历史模式匹配。 ### 3. 玻璃拟态与赛博朋克 SOC 设计系统 旨在模仿如 Microsoft Defender XDR、CrowdStrike Falcon 和 SentinelOne 等高端现代安全运营中心 (SOC) 应用程序： - **玻璃拟态**：背景模糊滤镜（`backdrop-filter: blur(16px)`）、半透明的深色面板以及微妙的青色/紫色发光边框。 - **微动画**：脉冲发光效果、旋转的雷达加载圈、平滑的 CSS 三次贝塞尔过渡、悬浮的盾牌图形。 - **精选调色板**：主色调青色（`#00E5FF`），霓虹翠绿（`#00FFC8`），电紫色（`#7B61FF`），深邃的背景色（`#050816`、`#081221`、`#111827`）。 ### 4. 交互式数据可视化 集成 **Chart.js** 用于实时分析： - **环形速度计仪表盘**：自定义的半环形仪表盘，通过动画指针反馈可视化风险得分。 - **区域折线图**：显示云网络吞吐量和攻击者交互时间线，带有平滑的渐变填充。 - **饼图与柱状图**：对目标诱饵点击和资源存储分布进行分类。 ## 🛠️ 技术栈 - **核心逻辑**：HTML5，原生 JavaScript (ES6+) - **样式**：自定义 CSS3，现代 Flexbox 与 Grid，CSS Design Tokens - **排版**：Google Fonts (*Orbitron*, *Inter*, *Poppins*, *JetBrains Mono*) - **图标**：Font Awesome 6.5.0 - **数据可视化**：Chart.js v4.4.1 - **动画与特效**：GSAP v3.12.5，Particles.js v2.0.0 - **数据持久化**：HTML5 `localStorage` ## 📄 许可证与使用说明 发布 TwinTrap 旨在用于教育、黑客马拉松和演示目的。怀对现代网络安全、零信任架构和欺骗技术的热情倾力打造。

标签：安全运营中心(SOC), 网络安全, 自定义脚本, 蜜罐技术, 隐私保护, 风险控制