SyedShaheerHussain/JavaScript-Malware-Analyzer-HTML

# 🛡️ JS Sentinel ### 静态 JavaScript 恶意软件与混淆分析工具包 **开发者：** Syed Shaheer Hussain **版权所有 © 2026 Syed Shaheer Hussain。保留所有权利。** **许可证：** MIT **类别：** 防御性网络安全 / 静态应用安全测试 (SAST) **语言：** TypeScript / Node.js **界面：** 命令行界面 (CLI) + 独立浏览器 GUI（支持拖拽） # 📷 截图     ## 📑 目录 1. [简介与概述](#-introduction--overview) 2. [使命与目标](#-mission--objectives) 3. [什么是这个项目（通俗说明）](#-what-is-this-project-in-plain-words) 4. [你需要先了解的核心概念](#-core-concepts-you-should-know-first) 5. [功能与特性](#-features--functions) 6. [使用的技术](#️-technologies-used) 7. [架构概述](#️-architecture-overview) 8. [流程图 —— 扫描是如何进行的](#-flow-chart--how-a-scan-happens) 9. [文件夹结构](#-folder-structure) 10. [逐个文件解释](#-file-by-file-explanation) 11. [风险评分详解](#-risk-scoring-explained) 12. [安装指南（分步说明）](#️-installation-guide-step-by-step) 13. [如何运行 —— CLI 模式](#️-how-to-run--cli-mode) 14. [如何运行 —— 浏览器 GUI 模式](#-how-to-run--browser-gui-mode) 15. [它会在哪里打开？有主机/服务器/登录吗？](#-where-does-it-open-is-there-a-hostserverlogin) 16. [GUI 中的每个按钮和界面详解](#-every-button--screen-in-the-gui-explained) 17. [扫描示例演示](#-sample-scan-walkthrough) 18. [优势](#-advantages) 19. [劣势与局限性](#️-disadvantages--limitations) 20. [注意事项与重要提示](#-cautions--important-notes) 21. [安全性：这个工具会让你面临风险吗？](#-safety-does-this-tool-put-you-at-risk) 22. [免责声明](#-disclaimer) 23. [构建此项目所学到的知识](#-what-was-studied--learned-building-this) 24. [未来增强与路线图](#-future-enhancements--roadmap) 25. [标签](#️-tags) 26. [许可证与版权](#-license--copyright) ## 📖 简介与概述 JS Sentinel 是一个用于 JavaScript 文件的**防御性、只读静态分析工具**。它的构建旨在快速且安全地回答一个问题： 它在执行此操作时**绝对不会运行被分析的文件**。相反，它会： - 将文件解析为**抽象语法树 (AST)**，并遍历该树以查找危险的函数调用（如 `eval`、`Function()` 等） - 运行一系列**正则表达式/启发式规则**，以捕获混淆技术（如加壳器、JSFuck、十六进制/unicode 转义、反调试技巧） - 查找并**递归解码**隐藏在文件内部的 base64/十六进制编码字符串 - 扫描**硬编码的机密信息**（AWS 密钥、GitHub token、私钥、JWT）、**加密矿工特征**以及**浏览器指纹**代码 - 将所有内容结合成一个**加权数值风险评分**，并转化为人类易读的级别：`安全 → 低 → 中 → 高 → 严重` 它以**两种工作形式**发布： | 模式 | 它是什么 | 面向人群 | |---|---|---| | 🖥️ **CLI** | 一个 Node.js 命令行工具 (`jssentinel scan file.js`) | 开发者、CI/CD pipeline、终端用户 | | 🌐 **浏览器 GUI** | 一个支持拖拽的、独立的 `.html` 文件 | 任何喜欢可视化、无需使用终端体验的人 | 这两种模式共享**完全相同的分析引擎** —— 相同的规则、相同的评分、相同的结果 —— 因此您可以选择更方便的那种。 ## 🎯 使命与目标 - ✅ 为开发者和学生提供一种**安全、透明的方式**，以便在运行可疑的 JavaScript 之前对其进行检查 - ✅ 展示**真实的静态分析工程**：AST 解析、信息熵计算、正则表达式特征设计、加权风险评分 - ✅ 保持工具**100% 只读** —— 分析过程绝不执行、`eval` 或运行目标文件 - ✅ 让工具能被**终端用户 (CLI) 和非技术用户 (浏览器 GUI)** 共同使用 - ✅ 保持一切**本地且私密** —— 绝不会有文件被上传到服务器或第三方 - ✅ 作为一个可扩展的**作品集级别的安全项目**，并具有发展成完整平台（REST API、dashboard、YARA 规则等）的空间 ## 🧩 什么是这个项目（通俗说明） 想象一下，您从某处下载了一个 `.js` 文件，但不确定运行它是否安全。在文本编辑器中打开它时，它看起来就像是一堵令人困惑的、被压缩过的乱码墙。您肯定不想直接运行它，然后付出惨痛代价才发现问题。 JS Sentinel 就像是**针对 JavaScript 的金属探测器**：您把文件扫过它，如果它检测到以下情况，它就会发出响亮的警报声（高风险评分）： - 隐藏并随后执行自身的代码 (`eval(atob(...))`) - 伪装以阻止您阅读的代码（混淆器、加壳器、JSFuck） - 某人忘记删除的密钥或 token - 加密货币挖矿或浏览器指纹收集的迹象 - 试图检测自身是否被监视/调试的代码（以便在分析环境下表现出不同的行为） 它绝不会告诉您“这个文件 100% 是恶意软件” —— 没有任何静态工具能如实做到这一点 —— 但它为您提供一个**快速的、有证据支持的信号**，让您知道某个文件是否值得进行更深入的手动检查。 ## 🧠 你需要先了解的核心概念 | 概念 | 通俗解释 | |---|---| | **AST (抽象语法树)** | 由解析器生成的代码结构的树状表示。JS Sentinel 不是将代码视为纯文本，而是将其理解为“这是一个函数调用”、“这是一个赋值”等 —— 这比简单的文本搜索要可靠得多。 | | **混淆 (Obfuscation)** | 故意使代码变得难以阅读（将变量重命名为 `_0x1a2b`，将代码打包成压缩的数据块，对字符串进行编码） —— 这对于代码压缩是合法的，但被恶意软件作者大量滥用以隐藏意图。 | | **信息熵 (Shannon Entropy)** | 衡量一段文本看起来有多“随机”的数学指标（0–8 bits/char）。手写代码的信息熵较低；加密或压缩数据的信息熵较高。`.js` 文件中的高信息熵是一个危险信号。 | | **Base64 / Hex 编码** | 将二进制或隐藏文本表示为可打印字符的常用方法。恶意软件通常会对恶意的 URL 或命令进行 base64 编码，使其不会在文件中以纯文本形式出现。 | | **特征扫描** | 查找已知的固定模式（如 AWS 密钥的 `AKIA...`，或已知矿工的 `coinhive`） —— 与防病毒软件的特征数据库原理相同，但针对的是源代码模式而不是二进制文件。 | | **风险评分** | 每个可疑的发现都对应一定的分数。所有分数将累加成一个总分，然后映射到相应的风险级别（安全/低/中/高/严重）。 | | **静态分析** | 在*不运行*代码的情况下对其进行分析 —— 与“动态分析”（沙箱化并实际执行代码以观察行为）相对。JS Sentinel 仅仅是一个静态分析器。 | ## ✨ 功能与特性 ### 1. 基于 AST 的危险 API 检测 - 检测 `eval()`、`Function()` / `new Function()` - 检测使用**字符串**参数调用的 `setTimeout()` / `setInterval()`（一种隐式的 `eval`） - 检测 DOM 注入 sink：`document.write()`、`innerHTML`、`outerHTML`、`insertAdjacentHTML` - 检测网络原语：`fetch`、`XMLHttpRequest`、`WebSocket`、`importScripts` - 检测解码原语：`atob`、`unescape` - 检测可疑的别名（例如 `const e = eval;` 以躲避简单的文本扫描器） - 为每个发现报告**确切的行号**和简短的代码片段 ### 2. 混淆与反分析检测 - Dean Edwards **Packer** 特征 (`eval(function(p,a,c,k,e,d)...`) - **JSFuck** 编码（仅使用 `[]()!+` 编写的代码） - **AAEncode / JJEncode** 风格的编码 - 大量使用 `\xNN` / `\uNNNN` 转义序列 - **字符串数组间接寻址**（`_0x1a2b` 数组 + 解码器函数 —— 像 javascript-obfuscator 等工具的典型特征） - **自我防御 / 防篡改**代码模式 - `debugger;` 语句**泛滥**（会冻结附加的 DevTools） - **DevTools / VM / sandbox 检测**启发式算法（`navigator.webdriver`、窗口大小增量检查等） - **Headless 浏览器指纹检查**（Puppeteer、Playwright、HeadlessChrome） - **控制流平坦化**调度循环模式 (`while(true) { switch(...) }`) - **整体文件信息熵**测量 - 普遍存在的**十六进制风格标识符重命名**检测 ### 3. Base64 / Hex Payload 解码器 - 扫描文件中的每一个字符串字面量 - 自动检测并解码 **base64** 和 **hex** 编码的字符串 - **递归解码**多达 5 个嵌套层（多阶段 dropper 通常会对 payload 进行多次编码） - 标记任何包含 **URL**、**IP 地址**或**类执行关键字**（如 `fetch(`、`powershell`、`/bin/sh` 等）的解码内容 - 报告解码内容的信息熵 ### 4. 特征扫描器（机密信息 / 矿工 / 指纹） - **硬编码的机密信息：** AWS Access Key、GitHub/Slack/Stripe/OpenAI token、PEM 私钥块、类 JWT token（在报告中全部**被脱敏**，绝不完整显示） - **加密矿工引用：** CoinHive/CryptoNight 特征、`stratum+tcp://` 矿池协议、WebAssembly + 算力/Monero 关键字组合 - **浏览器指纹收集：** Canvas 指纹、AudioContext 指纹、navigator 硬件/电池指纹 - **可疑网络模式：** URL 缩短服务、基于 IP 的原始 URL - **反分析：** 覆盖 `console.log`/`warn`/`error`（用于静默调试输出） ### 5. 风险评分引擎 - 根据严重程度，每个发现都带有一个**分值** - 如果解码出的 payload 具有可疑性、高信息熵或存在嵌套，则会增加**额外权重** - 最终得分映射到对应级别：**安全 (0–20) → 低 (21–50) → 中 (51–100) → 高 (101–200) → 严重 (201+)** ### 6. 报告生成 - **控制台报告** —— 带颜色的表格，直接在终端打印 - **JSON 报告** —— 完整的机器可读结果，适用于 CI pipeline 或其他工具 - **Markdown 报告** —— 人类易读的 `.md` 文件，包含表格和代码块 - **HTML 报告** —— 一个精美、带样式的单文件报告，可在任何浏览器中打开 ### 7. 浏览器拖拽 GUI - 单个独立的 `.html` 文件，无需安装 - 将 `.js` 文件拖到页面上（或点击浏览） - 即时显示结果，呈现为相同样式的报告 - “Download JSON”按钮用于保存原始结果 - 100% 客户端 —— 不会向任何地方上传任何内容 ### 8. 对 CI/CD 友好的退出代码 - 如果扫描到的最严重的文件属于高风险或严重风险，`scan` 命令将以代码 `2` 退出 —— 非常适合在 CI 构建中自动触发失败 ## 🛠️ 使用的技术 | 类别 | 技术 | 用途 | |---|---|---| | 语言 | **TypeScript** | 为整个引擎和 CLI 提供类型安全的源代码 | | 运行时 | **Node.js** (18+，已在 22 上测试) | 执行 CLI | | AST 解析 | **@babel/parser**, **@babel/traverse**, **@babel/types** | 将 JavaScript 解析为 AST 并进行遍历 | | CLI 框架 | **commander** | 定义 `scan` / `report` / `decode` 子命令和标志 | | 终端美化 | **chalk** | 带颜色的控制台输出 | | 终端表格 | **cli-table3** | 在终端中渲染发现结果表格 | | 打包工具 (仅限 GUI) | **esbuild** | 将分析引擎打包成单个支持浏览器的 JS 文件 | | 浏览器 API | **File API, Web Crypto API (SubtleCrypto), TextDecoder** | 读取拖拽的文件，计算 SHA-256 并解码字节 —— 全部在浏览器中原生完成，无需外部库 | | 构建工具 | **tsc (TypeScript Compiler)** | 将 `src/*.ts` 编译为可运行的 `dist/*.js` | ## 🏗️ 架构概述 JS Sentinel 拥有一个**单一的共享分析核心**，被两个不同的前端所调用： ``` ┌────────────────────────┐ │ Analysis Core │ │ (src/analyzer/*.ts) │ │ │ │ • astAnalyzer │ │ • obfuscationDetector │ │ • base64Analyzer │ │ • signatureScanner │ │ • riskScorer │ │ • util (entropy, etc.) │ └───────────┬─────────────┘ │ ┌──────────────┴───────────────┐ │ │ ┌────────▼─────────┐ ┌─────────▼──────────┐ │ Node CLI │ │ Browser Bundle │ │ src/scanner.ts │ │ src/web/ │ │ src/cli.ts │ │ browser-entry.ts │ │ (reads files with │ │ (reads dropped │ │ fs, hashes with │ │ files with the │ │ Node crypto) │ │ File API + Web │ │ │ │ Crypto API) │ └────────┬───────────┘ └─────────┬───────────┘ │ │ ┌────────▼─────────┐ ┌───────────▼───────────┐ │ Console / JSON / │ │ jssentinel-web.html │ │ Markdown / HTML │ │ (drag & drop UI, │ │ report files │ │ renders report live) │ └───────────────────┘ └────────────────────────┘ ``` 这两个前端都会调用 `src/analyzer/` 中的相同函数，因此无论您使用哪一个，结果都保证是完全一致的。 ## 🔄 流程图 —— 扫描是如何进行的 ``` START │ ▼ Read source code (from disk in CLI, or via File API in browser) │ ▼ Compute SHA-256 hash + file size │ ▼ ┌────────────────────────────────────────────┐ │ Run 4 engines in parallel (logically): │ │ │ │ 1) astAnalyzer.ts → AST walk findings │ │ 2) obfuscationDetector→ regex/entropy rules │ │ 3) signatureScanner → secrets/miner rules │ │ 4) base64Analyzer.ts → decode + inspect │ └────────────────────────────────────────────┘ │ ▼ Merge all findings + decoded payloads │ ▼ riskScorer.ts → sum weighted points → map to Safe/Low/Medium/High/Critical │ ▼ Build AnalysisResult object │ ▼ ┌───────────────┬───────────────┬───────────────┬───────────────┐ │ Console table │ JSON file │ Markdown file │ HTML file/GUI │ └───────────────┴───────────────┴───────────────┴───────────────┘ │ ▼ END (exit code 2 if High/Critical, for CI use) ``` ## 📁 文件夹结构 ``` js-sentinel/ ├── src/ │ ├── types.ts # Shared TypeScript interfaces (Finding, AnalysisResult, DecodedPayload) │ ├── scanner.ts # Node-only orchestrator: reads a file, calls all engines, hashes it │ ├── cli.ts # Commander-based CLI entry point (scan / report / decode commands) │ │ │ ├── analyzer/ # The shared, environment-agnostic analysis engine │ │ ├── util.ts # Shannon entropy, URL/IP extraction, base64-shape check │ │ ├── astAnalyzer.ts # Babel-parser AST walker — dangerous API detection │ │ ├── obfuscationDetector.ts # Regex + entropy heuristics for obfuscation/anti-analysis │ │ ├── base64Analyzer.ts # Pure-JS recursive base64/hex decoder │ │ ├── signatureScanner.ts # Secrets, crypto-miner, fingerprinting regex signatures │ │ └── riskScorer.ts # Point aggregation + Safe/Low/Medium/High/Critical bands │ │ │ ├── report/ │ │ └── reportGenerator.ts # Console, JSON, Markdown, and HTML renderers │ │ │ └── web/ # Everything needed for the browser GUI │ ├── browser-entry.ts # Browser-safe entry point → exposes window.jsSentinelScan │ ├── index.template.html # Drag-and-drop UI shell (bundle gets injected here) │ └── bundle.js # (generated by esbuild — not committed to git) │ ├── scripts/ │ └── build-web.js # Injects bundle.js into index.template.html → jssentinel-web.html │ ├── samples/ │ ├── benign.js # Scores 0 / Safe — sanity check file │ └── suspicious.js # Synthetic fixture that trips every detection engine │ ├── jssentinel-web.html # ⭐ Generated, ready-to-use standalone browser scanner ├── package.json # Dependencies, scripts, metadata ├── tsconfig.json # TypeScript compiler configuration ├── .gitignore └── README.md ``` ## 📜 逐个文件解释 | 文件 | 功能说明 | |---|---| | `src/types.ts` | 定义所有其他文件依赖的形状：`Finding`（单次检测）、`DecodedPayload`（单个解码出的字符串）、`AnalysisResult`（完整的报告对象）。 | | `src/analyzer/util.ts` | 小型的数学/文本辅助工具：`shannonEntropy()` 计算文本的随机性；`extractUrls()`/`extractIps()` 从任何字符串中提取 URL/IP；`looksLikeBase64()` 在尝试解码之前对字符串的形状进行合理性检查。 | | `src/analyzer/astAnalyzer.ts` | 使用 Babel 的解析器解析文件，然后遍历生成的树结构以查找对 `eval`、`Function`、基于字符串的定时器、DOM sink 和网络 API 的调用。如果严格解析失败，则回退到较宽松的解析模式（处理遗留/格式错误的脚本）。 | | `src/analyzer/obfuscationDetector.ts` | 一个表驱动的规则引擎 —— 每条规则都是一个 `{ title, severity, points, test(code) }` 对象。针对原始源文本运行每一条规则，并额外执行单独的整体文件信息熵检查和十六进制标识符密度检查。 | | `src/analyzer/base64Analyzer.ts` | 查找所有长度 ≥16 个字符的字符串字面量，检查每个字符串是否类似于 base64 或 hex，使用**纯 JavaScript** 解码器对其进行解码（在 Node 和浏览器中的工作方式完全相同），如果解码后的输出本身也是编码过的，则递归执行最多 5 层解码。 | | `src/analyzer/signatureScanner.ts` | 另一个表驱动的规则引擎，这次使用正则表达式特征来检测机密信息、加密矿工和指纹收集。机密信息匹配在放入任何报告之前会自动**脱敏** (`AKIA****************MPLE`)。 | | `src/analyzer/riskScorer.ts` | 累加每个发现的 `points`，为可疑/高信息熵/嵌套的解码 payload 增加奖励权重，并使用固定的评分区间将最终数值转换为 `Safe/Low/Medium/High/Critical` 标签。 | | `src/scanner.ts` | Node 专属的粘合剂：使用 `fs` 从磁盘读取文件，使用 Node 的 `crypto` 模块计算哈希，调用所有四个分析引擎，并返回一个 `AnalysisResult`。 | | `src/cli.ts` | 使用 `commander` 定义 `jssentinel` 命令行工具：包含 `scan`、`report` 和 `decode` 子命令，以及 `--json`、`--quiet`、`--format`、`--out` 标志。 | | `src/report/reportGenerator.ts` | 将 `AnalysisResult` 转换为四种不同的输出：带颜色的终端表格 (`printConsoleReport`)、JSON 文本 (`toJson`)、Markdown 文档 (`toMarkdown`) 以及带样式的独立 HTML 页面 (`toHtml`)。 | | `src/web/browser-entry.ts` | 相当于浏览器版的 `scanner.ts`。包含相同的四个引擎，但使用 **Web Crypto API** (`crypto.subtle.digest`) 计算哈希，而不是 Node 的 `crypto`，因为浏览器中没有 Node 的 `crypto` 模块。将所有功能封装为 `window.jsSentinelScan(code, fileName)` 暴露出来。 | | `src/web/index.template.html` | 视觉外壳：拖拽区域、结果卡片、发现结果表格，以及所有负责连接拖拽事件并将报告渲染为 HTML 的 JavaScript 代码。包含一个占位符 (`__BUNDLE__`)，编译后的引擎将被插入此处。 | | `scripts/build-web.js` | 一个小型的 Node 脚本，用于读取 `index.template.html` 和 `bundle.js`，将占位符替换为打包的内容，并将最终的 `jssentinel-web.html` 写入项目根目录。 | | `samples/benign.js` | 一个小型的无害脚本，用于确认该工具在处理正常代码时能正确报告 **0 / Safe**。 | | `samples/suspicious.js` | 一个合成的测试文件，包含 `eval(atob(...))`、基于字符串的 `setTimeout`、`document.write`、`debugger;` 泛滥以及一个 base64 编码的（无害）payload —— 专门构建以一次性触发所有检测规则。其中的内容实际上没有任何危险行为；“payload” 只是 `console.log`，而危险的调用已被注释掉。 | ## 🧮 风险评分详解 每个发现都有一个**严重程度**和一个**分值**： | 严重程度 | 典型分值 | |---|---| | 低 | 5–10 | | 中 | 10–20 | | 高 | 20–35 | | 严重 | 40–100+ | **计算公式：** ``` riskScore = Σ(points of every finding) + 20 for each decoded payload flagged "suspicious" + 10 for each decoded payload with entropy ≥ 5.5 + 10 for each decoded payload nested 2+ layers deep ``` **最终级别：** | 得分范围 | 风险级别 | 含义 | |---|---|---| | 0 – 20 | 🟢 **安全** | 未发现值得注意的内容 | | 21 – 50 | 🔵 **低** | 模式轻微，可能是良性的 | | 51 – 100 | 🟡 **中** | 值得进行人工检查 | | 101 – 200 | 🟠 **高** | 存在多个强烈的指标 | | 201+ | 🔴 **严重** | 非常强烈的恶意软件特征信号 | ## ⚙️ 安装指南（分步说明） ### ✅ 要求：Node.js 1. 从 **https://nodejs.org** 下载并安装 **Node.js**（版本 18 或更高，推荐 20/22） 2. 确认已正确安装： node -v npm -v ### ✅ 步骤 1 — 获取项目 将项目文件夹 (`js-sentinel`) 解压到您电脑上的任意位置，例如： - Windows: `C:\Projects\js-sentinel` - macOS/Linux: `~/js-sentinel` ### ✅ 步骤 2 — 在文件夹内打开终端 ``` cd js-sentinel ``` ### ✅ 步骤 3 — 安装依赖项 ``` npm install ``` 这会将 `package.json` 中列出的所有内容（Babel 解析器、commander、chalk 等）下载到本地的 `node_modules` 文件夹中。 ### ✅ 步骤 4 — 构建 CLI ``` npm run build ``` 这会将所有 TypeScript 源文件 (`src/**/*.ts`) 编译为位于 `dist/` 中的可执行 JavaScript。 ### ✅ 步骤 5（可选） — 重新构建浏览器 GUI 仅在您更改了任何分析器源代码时才需要执行此操作 —— 提供的 `jssentinel-web.html` 开箱即用。 ``` npm run build:web ``` **安装现已完成。** 接下来，您可以选择使用 CLI 或浏览器 GUI。 ## ▶️ 如何运行 —— CLI 模式 所有命令均在项目文件夹内运行。 ### 扫描单个文件 ``` node dist/cli.js scan path/to/file.js ``` ### 扫描整个文件夹（递归查找 .js/.mjs/.cjs） ``` node dist/cli.js scan path/to/project/ ``` ### 获取原始 JSON 输出（用于脚本 / CI） ``` node dist/cli.js scan file.js --json ``` ### 仅获取分数和级别（快速检查） ``` node dist/cli.js scan file.js --quiet ``` ### 将报告保存到磁盘 ``` node dist/cli.js report file.js --format md -o report.md node dist/cli.js report file.js --format json -o report.json node dist/cli.js report file.js --format html -o report.html ``` ### 仅解码嵌入的 base64/hex 字符串 ``` node dist/cli.js decode file.js ``` ### 立即尝试包含的示例文件 ``` node dist/cli.js scan samples/benign.js # → 0 / Safe node dist/cli.js scan samples/suspicious.js # → 125 / High ``` ### 可选：将其安装为全局 `jssentinel` 命令 ``` npm link jssentinel scan somefile.js ``` ## 🌐 如何运行 —— 浏览器 GUI 模式 此模式完全不需要使用终端。 1. 在项目根目录中**找到** `jssentinel-web.html` 2. **双击它** —— 它将直接在您的默认浏览器中打开（Chrome、Edge、Firefox 等） 3. **将 `.js` 文件拖到**虚线拖拽区域 —— 或者**点击该区域**以打开文件选择器 4. 报告会立即显示在**下方**：风险评分、风险级别、发现结果表格、解码的 payload、URL、IP 5. 点击 **“Scan another file”** 重置并分析不同的文件 6. 点击 **“Download JSON”** 将原始结果保存到您的电脑 如果您愿意，也可以从终端打开它： ``` start report.html # Windows open report.html # macOS xdg-open report.html # Linux ``` *（同样的命令也适用于 `jssentinel-web.html`。）* ## 🌍 它会在哪里打开？有主机/服务器/登录吗？ 这是一个需要澄清的重要问题，因为有些工具确实需要服务器、主机地址或登录凭据 —— **但 JS Sentinel 不需要：** | 问题 | 回答 | |---|---| | 它运行在 `localhost` 上吗？ | **否。** 根本没有服务器进程。 | | 有需要访问的端口号、主机或 URL 吗？ | **没有。** 您直接从文件系统打开 HTML 文件 —— 地址栏将显示 `file:///` 路径，而不是 `http://` 或 `localhost`。 | | 我需要用户名或密码吗？ | **不需要。** 没有登录系统，没有账户，也没有后端。 | | 它会在哪个浏览器中打开？ | 您的**默认浏览器**是什么就是什么（Chrome、Edge、Firefox、Safari、Brave —— 都可以工作，因为它是纯粹的 HTML/CSS/JS）。 | | 我的文件会被上传到任何地方吗？ | **不会。** 文件使用浏览器内置的 `File` API 读取，并完全**在浏览器选项卡内的内存中**进行分析。在扫描过程中，没有任何内容会离开您的设备 —— 根本不会发出任何网络请求。 | | 这会替代或与钓鱼/电子邮件工具有关吗？ | **无关。** 这个项目与网络钓鱼模拟、电子邮件安全或凭据捕获毫无关系 —— 它是一个 **JavaScript 静态恶意软件分析器**。如果您正在考虑与网络钓鱼相关的项目，那将是一个完全独立的工具。 | ## 🖱️ GUI 中的每个按钮和界面详解 | 元素 | 功能说明 | |---|---| | **拖拽区域** (虚线框，“Drag a .js file here, or click to choose one”) | 接受拖拽进来的文件，或者在点击时打开操作系统的文件选择器。仅支持 `.js`、`.mjs`、`.cjs` 文件。 | | **状态行** (拖拽区域下方的小文本) | 显示正在扫描的文件，以及扫描完成时的时间戳。 | | **“Scan another file” 按钮** | 清除当前报告和状态，以便您可以拖入新文件。不会重新加载页面。 | | **“Download JSON” 按钮** | 使用浏览器正常的下载流程，将完整的 `AnalysisResult`（所有发现、解码的 payload、URL、IP、得分）保存为 `.json` 文件。 | | **元数据卡片** (文件 / 大小 / SHA256 / 发现项) | 有关扫描文件的概览信息。SHA256 哈希值可让您在日后唯一地标识该确切文件版本。 | | **风险横幅** (大号彩色数字) | 总体得分和级别 —— 从绿色安全）到红色（严重）。 | | **发现结果表格** | 每一个独立的检测结果：严重性徽章、分值、类别、标题 + 描述，以及（适用时）确切的行号和作为证据的代码片段。 | | **解码 Payload 部分** | 显示任何被发现并解码的 base64/hex 字符串，以及它的信息熵和是否被标记为可疑（例如包含 URL）。 | | **URL / IP 地址部分** | 在原始文件文本中任何位置发现的 URL 或 IP 地址。 | ## 🧪 扫描示例演示 运行包含的 `samples/suspicious.js`（一个无害的测试用例）会产生： ``` Risk score: 125 (High) Findings (7): HIGH 20 pts dynamic-execution Use of eval() MEDIUM 20 pts anti-debugging debugger; statement flooding MEDIUM 20 pts anti-analysis DevTools / VM detection heuristics MEDIUM 15 pts dynamic-execution setTimeout invoked with a string argument MEDIUM 15 pts obfuscation High overall file entropy (5.28 bits/char) MEDIUM 10 pts dom-abuse document.write() usage LOW 5 pts obfuscation Decoding primitive used: atob Decoded Payloads (1): base64, depth 0, entropy 4.78, [suspicious] → fetch("http://198.51.100.23/beacon"); console.log("test payload only, harmless"); ``` 运行 `samples/benign.js`（普通、常规的代码）会产生： ``` Risk score: 0 (Safe) No suspicious patterns detected by current rule set. ``` ## ✅ 优势 - 🔒 **用于不受信任的文件完全安全** —— 绝不会执行被分析的代码 - ⚡ **速度快** —— 纯静态分析，没有沙箱或虚拟机开销 - 🧩 **一个引擎提供两种界面** —— 面向开发者和 CI 的 CLI，面向其他所有人的浏览器 GUI - 🌐 **GUI 无需安装** —— 单个 HTML 文件可在任何地方运行 - 🔐 **尊重隐私** —— 绝不通过网络上传或发送任何内容 - 🧱 **透明的评分** —— 每一分都可以追溯到特定的、有文档记录的规则 - 🧵 **可扩展** —— 新的检测规则只是简单的表单项，不需要深度的重写 - 🖥️ **支持 CI/CD** —— 遇到高风险发现时会以非零状态码退出 ## ⚠️ 劣势与局限性 - 🚫 **并非绝对保证** —— 与所有静态分析器一样，它可能产生**误报**（合法的压缩代码可能会触发信息熵/混淆规则）和**漏报**（一种足够新颖的技术可能不会匹配任何规则） - 🚫 **没有动态/行为分析** —— 它无法看到代码在运行时*实际做了什么*，只能看出它*看起来可能*会做什么 - 🚫 **正则表达式/启发式规则可能会被规避**，前提是攻击者有足够的动机专门设计一个混淆器来绕过已知的特征 - 🚫 **没有内置的威胁情报源** —— 它不会像 VirusTotal 那样针对实时数据库检查哈希/URL（这在当前版本的范围之外） - 🚫 **首次加载的浏览器包较大**（约 1.3MB，因为嵌入了一个完整的 JavaScript 解析器） —— 这对本地使用无关紧要，但值得了解 - 🚫 **报告文本仅限英文** —— 尚未进行本地化 ## 🚨 注意事项与重要提示 - ℹ️ 内置的 `samples/suspicious.js` **仅仅是一个合成的测试用例** —— 其嵌入的“payload”是无害的 (`console.log`)，并且唯一真正具有风险的调用已被注释掉。它的存在纯粹是为了让每条规则都有可检测的内容。 - ℹ️ 机密信息检测结果（AWS 密钥、token 等）在报告中会**脱敏**显示 —— 切勿在外部粘贴报告并假定脱敏能完美隐藏所有内容；应将任何检测到的机密视为已泄露并及时轮换。 - ℹ️ 修改任何源文件后，务必重新构建 (`npm run build` / `npm run build:web`) —— CLI 运行的是编译后的 `dist/` 输出，而 GUI 运行的是打包好的 `jssentinel-web.html`；在重新构建之前，仅修改 `.ts` 文件不会改变其行为。 ## 🛡️ 安全性：这个工具会让你面临风险吗？ **不会，这是由其设计决定的。** 具体原因如下： 1. 分析器**只读取文本并将其解析为一棵树** —— 解析并不等同于运行。Babel 的解析器构建的是描述代码的数据结构；它从不调用在其中发现的任何函数。 2. 在 JS Sentinel 源代码的任何地方，都**没有对被分析文件进行 `eval`、`Function`、`require` 或 `import`** —— 目标文件纯粹是输入数据，绝不会被视为可由工具本身执行的代码。 3. 浏览器 GUI 使用标准的 **File API** (`file.text()`) 读取拖拽的文件，该接口将文件内容作为纯字符串返回 —— 它不会将该文件作为 `