Dicklesworthstone/ultimate_bug_scanner

# 🔬 Ultimate Bug Scanner v5.0 ### **AI 编程智能体的秘密武器：尽早标记可能存在的 Bug 以进行修复** [](./LICENSE) [](https://github.com/Dicklesworthstone/ultimate_bug_scanner) [](https://github.com/Dicklesworthstone/ultimate_bug_scanner) 只想在没有任何确认的情况下完成所有操作？在边缘模式下生活，使用简易模式自动安装所有依赖项，接受所有提示，检测本地编程智能体，并零额外问题地连接其质量防护栏： ## 🤖 智能体快速入门 (JSON/TOON) **在智能体上下文中使用机器可读输出。** stdout = 数据, stderr = 诊断, exit 0 = 成功。 ``` # 扫描当前 repo（JSON） ubs . --format=json # Token 优化输出（TOON） ubs . --format=toon # 仅扫描暂存的更改 ubs --staged --format=json # CI 严格模式（遇警告即失败） ubs . --profile=strict --fail-on-warning --format=json ``` ## 💥 **问题所在：AI 动作快，Bug 动作更快** 你正使用 Claude Code、Codex、Cursor 和其他 AI 编程智能体以前所未有的速度编写代码。你在几分钟内交付过去需要几天才能完成的功能。**但这里有一个痛苦的事实：** ### **即使是最优秀的 AI 也会犯这些错误：** **JavaScript/TypeScript 示例** *(Python, Go, Rust, Java, C++, Ruby 中存在类似模式)*： ``` // ❌ CRITICAL BUG #1: Null pointer crash waiting to happen const submitButton = document.getElementById('submit'); submitButton.addEventListener('click', handleSubmit); // 💥 Crashes if element doesn't exist // ❌ CRITICAL BUG #2: XSS vulnerability function displayUserComment(comment) { document.getElementById('comments').innerHTML = comment; // 🚨 Security hole } // ❌ CRITICAL BUG #3: Silent failure (missing await) async function saveUser(data) { const result = validateUser(data); // 💥 Should be 'await validateUser(data)' await saveToDatabase(result); // Saves undefined! } // ❌ CRITICAL BUG #4: Always false comparison if (calculatedValue === NaN) { // 💥 This NEVER works (always false) console.log("Invalid calculation"); } // ❌ CRITICAL BUG #5: parseInt footgun const zipCode = parseInt(userInput); // 💥 "08" becomes 0 in old browsers (octal!) ``` **这些 Bug 中的每一个在生产环境中调试可能需要 3-6 小时。** 类似的问题困扰着每种语言：未受保护的 null 访问、缺少 `await`、`eval()` 带来的安全漏洞、`strcpy()` 导致的缓冲区溢出、`.unwrap()` 恐慌、goroutine 泄漏……**你可能已经遇到过所有这些问题。** ## 🎯 **解决方案：你 24/7 的 Bug 猎手伙伴** ### 🧠 语言感知的元运行器 (Meta-Runner) - `ubs` 在同一个代码库中自动检测 **JavaScript/TypeScript, Python, C/C++, Rust, Go, Java, Ruby, Swift, 和 C#**，并分发给各语言专用扫描器。 - 每个扫描器位于 `modules/ubs-.sh` 下，独立发布，并支持 `--format text|json|jsonl|sarif|toon` 以便下游工具保持一致。 - 模块延迟下载（PATH → 代码库 `modules/` → 缓存在 `${XDG_DATA_HOME:-$HOME/.local/share}/ubs/modules` 下）并在执行前进行验证。 - 来自每种语言的结果通过 `jq` 合并为一个 text/JSON/SARIF 报告，因此 CI 系统和 AI 智能体只需解析单个工件。 ### 🔐 供应链安全保障 - 每个延迟下载的模块（及其辅助资源）都附带固定的 SHA-256 校验和，并内置在元运行器中。从 GitHub 获取的文件在执行前会进行验证，防止版本发布之间的篡改。 - 缓存默认位于 `${XDG_DATA_HOME:-$HOME/.local/share}/ubs/modules` 下；使用 `--module-dir` 重新定位它（例如，在 CI 工作空间内），同时保留相同的验证保证。 - 随时运行 `ubs doctor` 以审核你的环境。它会检查 curl/wget 的可用性、缓存目录的可写性以及各语言模块的完整性。添加 `--fix` 以主动重新下载丢失或损坏的模块。 - 扫描器运行仍然遵循 `--update-modules`，但现在无效的校验和会导致立即失败并附带修复指导，而不是执行未验证的代码。 - **开发者 Pre-commit 钩子**：代码库附带一个 `.githooks/pre-commit` 钩子，当模块更改时自动更新 `SHA256SUMS`，并阻止带有过期校验和的提交。这确保每次发布都有经过验证的校验和，无需人工干预。 - **Minisign 支持**：为了获得额外的保证，设置 `UBS_MINISIGN_PUBKEY` 以通过 [minisign](https://jedisct1.github.io/minisign/) 验证 `SHA256SUMS` 上的加密签名。 ### 🎛 类别包与可共享报告 - `--category=resource-lifecycle` 让扫描器专注于 Python/Go/Java 的资源卫生（上下文管理器、defer 对称性、try-with-resources）。UBS 自动将语言集缩小到启用了生命周期包的语言，并抑制不相关的类别。 - `--comparison=` 将最新的合并摘要与存储的运行进行差异比较。增量数据输入到控制台输出、JSON、HTML 和 SARIF 自动化元数据中，以便 CI 可以检测回归。 - `--report-json=` 写入一个丰富的摘要（项目、总计、git 元数据、可选的比较块），你可以将其归档或与队友/CI 共享。 - `--report-html=` 生成一个独立的 HTML 预览，显示总计、与基线的趋势以及各语言细分——非常适合附加到 PR 或聊天更新中。 - 所有可共享输出在 UBS 于带有 GitHub 远程的 git 代码库中运行时注入 GitHub 永久链接。文本输出自动注释 `path:line` 引用，JSON 增加 `git.*` 元数据，合并的 SARIF 运行现在包含 `versionControlProvenance` 以及按键比较 id 索引的 `automationDetails`。 #### 每种语言的资源生命周期启发式规则 - **Python** – 类别 16 现在将每个 `open()` 调用与匹配的 `with open(...)` 用法和显式的 `encoding=` 参数相关联，而类别 19 使用位于 `modules/helpers/resource_lifecycle_py.py` 的新 AST 辅助程序来遍历每个文件、socket、subprocess、asyncio 任务和上下文取消路径。该辅助程序解析别名导入、上下文管理器和待处理的任务，因此差异计数（`acquire=X, release=Y, context-managed=Z`）显示每个文件的精确不平衡。 - **Go** – 类别 5/17 现在运行一个 Go AST 遍历器（`modules/helpers/resource_lifecycle_go.go`），检测缺少 cancel 的 `context.With*` 调用、没有 `Stop` 的 `time.NewTicker/NewTimer`、没有 `Close` 的 `os.Open/sql.Open`，以及 mutex 的 `Lock`/`Unlock` 对称性。发现直接来自 AST 位置，因此“ticker missing Stop()”行映射到精确的 `file:line` 而不是粗略的 regex 摘要。 - **Java** – 类别 5 揭示了在 try-with-resources 之外创建的 `FileInputStream`、readers/writers、JDBC 句柄等，而类别 19 持续追踪从未关闭的 executor services 和文件流。新的摘要文本与 manifest fixtures 匹配，因此如果回归吞没了这些警告，CI 将失败。 #### 可共享输出快速入门 ``` # 1) 捕获基线 JSON（检入 CI artifacts 或本地历史） ubs --ci --only=python --category=resource-lifecycle \ --report-json .ubs/baseline.json test-suite/python/buggy # 2) 重新运行比较 + HTML 预览，用于 PR 或聊天线程 ubs --ci --only=python --category=resource-lifecycle \ --comparison .ubs/baseline.json \ --report-json .ubs/latest.json \ --html-report .ubs/latest.html \ test-suite/python/buggy ``` `latest.json` 现在包含 git 元数据（代码库 URL、commit、blob_base）以及一个 `comparison.delta` 块，`latest.html` 呈现一个轻量级仪表板总结增量。SARIF 上传也会获取比较 id，因此 CI 中的重复运行通过自动化 id 保持分组。 ## 💡 **基本用法** ``` # 扫描当前目录 ubs . # 扫描特定目录 ubs /path/to/your/project # 详细模式（显示更多代码示例） ubs -v . # 保存报告到文件 ubs . bug-report.txt # CI 模式（遇警告时退出码为 1） ubs . --fail-on-warning # 安静模式（仅摘要） ubs -q . # 跳过特定类别（例如，跳过 TODO 标记） ubs . --skip=11,14 # 自定义文件扩展名 ubs . --include-ext=js,ts,vue,svelte ``` ### 实用的开关 ``` # Git 感知快速扫描（仅限已更改文件） ubs --staged # Scan files staged for commit ubs --diff # Scan working tree changes vs HEAD # 严格性配置文件 ubs --profile=strict # Fail on warnings, enforce high standards ubs --profile=loose # Skip TODO/debug/code-quality nits when prototyping # 机器可读输出 ubs . --format=json # Pure JSON on stdout; logs go to stderr ubs . --format=jsonl # Line-delimited summary per scanner + totals ubs . --format=toon # TOON format (~50% smaller than JSON, LLM-optimized) ubs . --format=jsonl --beads-jsonl out/findings.jsonl # Save JSONL for Beads/"strung" ``` ### 降低噪音 - UBS 自动忽略常见的垃圾文件（`node_modules`、virtualenvs、dist/build/target/vendor、编辑器缓存等）。 - 当发现是有意为之时，可以使用内联抑制：`eval("print('safe')") # ubs:ignore` ## 🚀 **快速安装 (30 秒)** ### **推荐：Homebrew (macOS/Linux)** ``` brew install dicklesworthstone/tap/ubs ``` 此方法提供： - 通过 `brew upgrade` 自动更新 - 依赖管理 - 通过 `brew uninstall` 轻松卸载 ### **Windows: Scoop** ``` scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket scoop install dicklesworthstone/ubs ``` ### **替代方案：自动安装** ``` curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash ``` ### **选项 2：完整性优先安装 (签名校验和)** ``` export UBS_MINISIGN_PUBKEY="RWQg+jMrKiloMT5L3URISMoRzCMc/pVcVRCTfuY+WIzttzIr4CUJYRUk" curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/scripts/verify.sh | bash ``` 验证器从匹配的 release 下载 `SHA256SUMS` + `SHA256SUMS.minisig`，用 minisign 验证它们，检查 `install.sh`，然后才执行它。使用 `--insecure` 绕过验证（不推荐）。 ### **选项 3：Nix** 直接运行（无需安装）： ``` nix run github:Dicklesworthstone/ultimate_bug_scanner ``` 贡献者的开发 shell： ``` nix develop ``` ### **选项 4：Docker / OCI** 拉取并检查： ``` docker run --rm ghcr.io/dicklesworthstone/ubs-tools ubs --help ``` 扫描主机代码（风险感知：授予容器访问主机文件系统的权限）： ``` docker run --rm -v /:/host ghcr.io/dicklesworthstone/ubs-tools bash -c "cd /host/path && ubs ." ``` ⚠️ 仅在你了解写入访问含义时才使用主机挂载模式。 ### 部署与安全 - 发布手册（我们如何切割签名发布版）：[docs/release.md](docs/release.md) - 供应链与验证模型：[docs/security.md](docs/security.md) 安装程序将： - ✅ 全局安装 `ubs` 命令 - ✅ 安装/确保 `ast-grep`（准确扫描 JS/TS 所需；UBS 可以自动供应固定的二进制文件） - ✅ 可选安装 `ripgrep`（用于 10 倍更快的扫描） - ✅ 可选安装 `jq`（跨所有语言扫描器合并 JSON/SARIF 所需） - ✅ 可选安装 `typos`（用于文档和标识符的智能拼写检查器） - ✅ 可选安装 `Node.js + typescript`（启用深度 TypeScript 类型缩窄分析） - ✅ 安装后自动运行 `ubs doctor` 并将会话摘要附加到 `~/.config/ubs/session.md` - ✅ 捕获准备就绪的事实（ripgrep/jq/typos/类型缩窄）并存储它们以供 `ubs sessions --entries 1` 使用 - ✅ 设置 git 钩子（阻止带有严重 Bug 的提交） - ✅ 设置 Claude Code 钩子（文件保存时扫描） - ✅ 将文档添加到你的 AGENTS.md 需要稍后重新查看安装程序发现的内容？运行 `ubs sessions --entries 1` 查看最近的会话日志（或让队友查看相同的摘要）。 需要“让它直接工作”的按钮？使用 `--easy-mode` 运行安装程序以自动安装所有依赖项，接受所有提示，检测本地编程智能体，并零额外问题地连接其质量防护栏： ``` curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" \ | bash -s -- --easy-mode ``` **总时间：** 30 秒到 2 分钟（取决于依赖项） 需要保持你的 shell RC 文件不被修改？将 `--no-path-modify`（以及可选的 `--skip-hooks`）与上述命令结合使用——安装程序仍会将 `ubs` 放入你选择的 `--install-dir`，但它会完全跳过 PATH 编辑和别名辅助程序。 ### **选项 2：手动安装** ``` # 下载并安装统一运行器 curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/ubs \ -o /usr/local/bin/ubs && chmod +x /usr/local/bin/ubs # 验证其工作正常 ubs --help # 安装依赖项（扫描 JS/TS 需要 ast-grep） # 扫描 JS/TS 必需（语法感知 AST 引擎） brew install ast-grep # or: cargo install ast-grep, npm i -g @ast-grep/cli brew install ripgrep # 10x faster searching (or: apt/dnf/cargo install) brew install typos-cli # Spellchecker tuned for code (or: cargo install typos-cli) npm install -g typescript # Enables full tsserver-based type narrowing checks ``` ### **选项 3：不安装直接使用** ``` # 下载一次 curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/ubs \ -o ubs && chmod +x ubs # 运行它 ./ubs . ``` ### 安装程序安全网 #### 从任何 shell 卸载 如果你想移除 UBS 及其所有集成，通过 curl 以 `--uninstall` 模式运行安装程序： ``` curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash -s -- --uninstall --non-interactive ``` 此命令删除 UBS 二进制文件、shell RC 片段/别名、`~/.config/ubs` 下的配置以及安装程序设置的可选 Claude/Git 钩子。因为它传递了 `--non-interactive`，它会自动确认所有提示并在无人值守的情况下运行。 | Flag | 它的作用 | 为什么重要 | |------|--------------|----------------| | `--dry-run` | 打印每个安装操作（下载、PATH 编辑、钩子写入、清理）而不触碰磁盘。Dry runs 仍然解析配置、检测智能体，并向你展示*将*改变的内容。 | 审计安装程序，向队友演示，或验证 CI 步骤而不修改工作站。 | | `--self-test` | 安装后立即运行 `test-suite/install/run_tests.sh`，如果冒烟套件失败则以非零退出。 | CI/CD 作业和经过验证的设置可以证明安装程序在信任 release 之前仍然端到端工作。 | | `--skip-type-narrowing` | 跳过 Node.js + TypeScript 准备就绪探测**以及**跨语言防护分析器（JS/Rust/Kotlin/Swift/C#）。 | 对于物理隔离的主机或希望保持仅启发式模式的环境很有用。 | | `--skip-typos` | 跳过 Typos 拼写检查器安装 + 诊断。 | 当公司镜像已经提供 Typos 或当你故意禁用拼写检查自动化时很方便。 | | `--skip-doctor` | 跳过安装后的自动 `ubs doctor` 运行 + 会话摘要。 | 当 CI 已经单独运行 doctor 或当你在本地迭代并希望更快完成时使用。 | **常见组合** ``` # 预览所有内容而不触碰 dotfiles 或 hooks bash install.sh --dry-run --no-path-modify --skip-hooks --non-interactive # 对 CI 友好的安装，会自测 smoke harness bash install.sh --easy-mode --self-test --skip-hooks ``` ### 🔄 **自动更新** `ubs` 元运行器支持 **选择加入** 的自动更新检查（每 24 小时一次）。为了供应链，这 **默认禁用**。 要启用自动更新： ``` export UBS_ENABLE_AUTO_UPDATE=1 ``` 要禁用它（即使已启用）： ``` export UBS_NO_AUTO_UPDATE=1 # 或 ubs --no-auto-update . ``` Ultimate Bug Scanner 就像让一位高级开发人员在 **5 秒内** 审查每一行代码；它是你最喜欢的编程智能体的完美自动化伴侣： ``` $ ubs . ╔══════════════════════════════════════════════════════════════════════╗ ║ 🔬 ULTIMATE BUG SCANNER v4.4 - Scanning your project... ║ ╚══════════════════════════════════════════════════════════════════════╝ Project: /Users/you/awesome-app Files: 247 JS/TS + 58 Python + 24 Go + 16 Java + 11 Ruby + 12 C++/Rust files Finished: 3.2 seconds ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Summary Statistics: Files scanned: 247 🔥 Critical: 0 ← Would have crashed in production! ⚠️ Warnings: 8 ← Should fix before shipping ℹ️ Info: 23 ← Code quality improvements ✨ EXCELLENT! No critical issues found ✨ ``` ## ⚡ **为什么开发者 + AI 智能体会爱上这个工具** ### 🚀 **1. 捕捉人类和 AI 遗漏的内容** **18 个专门的检测类别** 涵盖 *真正* 重要的 Bug：

类别	它能防止什么	每个 Bug 节省的时间
Null Safety	"Cannot read property of undefined" 崩溃	2-4 小时
Security Holes	XSS、代码注入、原型污染	8-20 小时 + 声誉损害
Async/Await Bugs	竞态条件、未处理的拒绝	4-8 小时
Memory Leaks	事件监听器、定时器、分离的 DOM	6-12 小时
Type Coercion	JavaScript 的 === vs == 疯狂	1-3 小时
+ 另外 13 个类别		每月节省 100+ 小时

### 💨 **2. 极速（因为你的时间很重要）** ``` Small project (5K lines): 0.8 seconds ⚡ Medium project (50K lines): 3.2 seconds 🚀 Large project (200K lines): 12 seconds 💨 Huge project (1M lines): 58 seconds 🏃 ``` **那是每秒分析 10,000+ 行。** 比你说“但在我机器上能跑”还快。 ### 🤖 **3. 专为 AI 智能体打造，由使用 AI 的开发者构建** 与传统 Linter 与 AI 生成的代码对抗不同，此扫描器 **拥抱** 它： ``` ✅ Designed for Claude Code, Cursor, Windsurf, Aider, Continue, Copilot ✅ Zero configuration - works with ANY JS/TS, Python, C/C++, Rust, Go, Java, or Ruby project ✅ Integrates with git hooks, CI/CD, file watchers ✅ Actionable output (tells you WHAT's wrong and HOW to fix it) ✅ Fails fast in CI (catch bugs before they merge) ✅ React Hooks dependency analysis that spots missing deps, unstable objects, and stale closures ✅ Lightweight taint analysis that traces req.body/window.location/localStorage → innerHTML/res.send/eval/exec/db.query and flags flows without DOMPurify/escapeHtml/parameterized SQL ``` ### 📊 **4. 真实世界的影响**

场景	没有扫描器	有扫描器
AI 实现用户认证	• 3 个 null 指针崩溃（9 小时调试） • 1 个 XSS 漏洞（8 小时 + 事故） • 2 个竞态条件（4 小时调试） 总计：~21 小时 + 安全事故	• 所有问题在 4 秒内被发现 • 提交前修复（15 分钟） 总计：15 分钟 节省：快 84 倍 ⚡
重构支付流程	• 边缘情况下的除以零（3 小时） • 未处理的 promise 拒绝（2 小时） • 缺少错误日志记录（1 小时） 总计：6 小时调试	• 立即发现（3 秒） • 合并前修复（10 分钟） 总计：10 分钟 节省：快 36 倍 🚀

## 🤖 **AI 智能体集成（真正的魔法）** ### 本地设备智能体防护栏 `install.sh` 现在会检查你的工作站上最常见的编程智能体（下面列出的相同集合），并在被要求时，投放防护栏，提醒这些智能体在声称任务完成之前运行 `ubs --fail-on-warning .`。在 `--easy-mode` 下，这会自动发生；否则你可以单独批准每个集成。 | 智能体 / IDE | 我们连接的内容 | 为什么有帮助 | |-------------|-----------------|--------------| | **Claude Code Desktop** (`.claude/hooks/on-file-write.sh`) | 文件保存钩子，每当 Claude 保存 JS/TS 文件时都会调用 `ubs --ci`。 | 防止 Claude 在没有新鲜扫描的情况下接受“Apply Patch”。 | | **Cursor** (`.cursor/rules`) | 共享规则块，告诉 Cursor plans/tasks 运行 `ubs --fail-on-warning .` 并总结未解决的问题。 | Cursor 的自主作业继承与人类相同的 QA 检查清单。 | | **Codex CLI** (`.codex/rules/ubs.md`) | 为 OpenAI 的 Codex 终端工作流添加相同的规则块。支持文件和目录格式（v0.77.0+）。 | 确保 Codex 会话在长时间重构期间不会跳过扫描器。 | | **Gemini Code Assist** (`.gemini/rules`) | 指导 Gemini 智能体在关闭工单前运行 `ubs` 的指南。 | 保持 Gemini 的异步修复与 UBS 退出标准一致。 | | **Windsurf** (`.windsurf/rules`) | 防护栏文本 + 引用 `ubs` 的示例命令面板片段。 | Windsurf 的多步骤计划保持 grounded 在相同的质量门中。 | | **Cline** (`.cline/rules`) | Cline 的 VS Code 扩展摄取的 Markdown 指令。 | 强制 Cline 的每个“tool call”提及扫描器发现。 | | **OpenCode MCP** (`.opencode/rules`) | 本地 MCP 指令，以便 HTTP 工具在回复前始终调用 `ubs`。 | 使 OpenCode 的多智能体群共享相同的“完成”概念。 | #### Codex CLI v0.77.0+ 迁移说明 从 Codex CLI v0.77.0 开始，规则存储从 **单个文件**（`.codex/rules`）变为包含单个规则文件的 **目录**（`.codex/rules/`）。UBS 安装程序自动处理这两种格式： | Codex 版本 | 规则位置 | UBS 安装程序行为 | |---------------|----------------|------------------------| | < v0.77.0 | `.codex/rules` (文件) | 将 UBS 快速参考附加到文件 | | ≥ v0.77.0 | `.codex/rules/` (目录) | 创建 `.codex/rules/ubs.md` | **如果你升级了 Codex 并遇到问题**，请手动迁移： ``` # 将文件转换为目录结构 mv ~/.codex/rules ~/.codex/rules.backup mkdir ~/.codex/rules mv ~/.codex/rules.backup ~/.codex/rules/ubs.md ``` 安装程序的 `append_quick_reference_block()` 函数在运行时检测存储格式并写入适当的位置，因此在升级 Codex 后重新运行 `install.sh` 将“正常工作”。 ### **为什么这对 AI 工作流很重要** 当你使用 AI 编程时，你的移动速度比传统开发 **快 10-100 倍**。但 Bug 积累得同样快。传统工具会让你慢下来。此扫描器保持节奏： ``` Traditional workflow: AI-powered workflow with scanner: ┌──────────────────┐ ┌──────────────────┐ │ AI writes code │ │ AI writes code │ └────────┬─────────┘ └────────┬─────────┘ │ │ ↓ ↓ ┌──────────────────┐ ┌──────────────────┐ │ You review │ │ Scanner runs │ │ (15 min) │ │ (3 seconds) │ └────────┬─────────┘ └────────┬─────────┘ │ │ ↓ ↓ ┌──────────────────┐ ┌──────────────────┐ │ Tests pass? │ │ Critical bugs? │ └────────┬─────────┘ └────────┬─────────┘ │ NO! │ YES! ↓ ↓ ┌──────────────────┐ ┌──────────────────┐ │ Debug in prod │ │ AI fixes them │ │ (6 hours) │ │ (5 minutes) │ └──────────────────┘ └────────┬─────────┘ ↓ ┌──────────────────┐ │ Ship with │ │ confidence │ └──────────────────┘ Total: 6.25 hours Total: 8 minutes ``` ### **模式 1：Claude Code 集成（实时扫描）** 将此放入 `.claude/hooks/on-file-write.sh`： ``` #!/bin/bash # 保存时自动扫描 UBS 支持的语言（JS/TS, Python, C/C++, Rust, Go, Java, Ruby, Swift, C#） if [[ "$FILE_PATH" =~ \.(js|jsx|ts|tsx|mjs|cjs|py|pyw|pyi|c|cc|cpp|cxx|h|hh|hpp|hxx|rs|go|java|rb|cs|csx)$ ]]; then echo "🔬 Quality check running..." if ubs "${PROJECT_DIR}" --ci 2>&1 | head -30; then echo "✅ No critical issues" else echo "⚠️ Issues detected - review above" fi fi ``` **结果：** 每次 Claude 编写代码时，扫描器都会 **立即** 捕捉 Bug。 ### **模式 2：Git Pre-Commit 钩子（质量门）** 安装程序可以自动设置此功能，或者添加到 `.git/hooks/pre-commit`： ``` #!/bin/bash # 阻止包含严重 bug 的提交 echo "🔬 Running bug scanner..." if ! ubs . --fail-on-warning 2>&1 | tee /tmp/scan.txt | tail -30; then echo "" echo "❌ Critical issues found. Fix them or use: git commit --no-verify" echo "" echo "Top issues:" grep -A 3 "🔥 CRITICAL" /tmp/scan.txt | head -20 exit 1 fi echo "✅ Quality check passed - committing..." ``` **结果：** Bug **无法** 被提交。句号。 ### **模式 3：Cursor/Windsurf/Continue 集成** 添加到你的 `.cursorrules` 或类似文件： ``` ## 代码质量标准 Before marking any task as complete: 1. Run the bug scanner: `ubs .` 2. Fix ALL critical issues (🔥) 3. Review warnings (⚠️) and fix if trivial 4. Only then mark task complete If the scanner finds critical issues, your task is NOT done. ``` **结果：** AI 智能体拥有 **内置的质量标准**。 ### **模式 4：CI/CD 流水线（GitHub Actions 示例）** ``` name: Code Quality Gate on: [push, pull_request] jobs: bug-scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install Bug Scanner run: | curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash -s -- --non-interactive - name: Scan for Bugs run: | ubs . --fail-on-warning --ci ``` **结果：** 带有严重 Bug 的 Pull request **无法合并**。 ### **模式 5：修复-验证循环（用于 AI 智能体）** 这是 AI 编程工作流的黄金模式： ``` #!/bin/bash # 让你的 AI agent 在实现功能后运行此操作 echo "🔬 Post-implementation quality check..." # 运行扫描器 if ubs . --fail-on-warning > /tmp/scan-result.txt 2>&1; then echo "✅ All quality checks passed!" echo "📝 Ready to commit" exit 0 else echo "❌ Issues found:" echo "" # Show critical issues grep -A 5 "🔥 CRITICAL" /tmp/scan-result.txt | head -30 echo "" echo "🤖 AI: Please fix these issues and re-run this check" exit 1 fi ``` **使用模式：** ``` User: "Add user registration with email validation" AI Agent: 1. Implements the feature 2. Runs quality check (scanner finds 3 critical bugs) 3. Fixes the bugs 4. Re-runs quality check (passes) 5. Commits the code Total time: 12 minutes (vs. 6 hours debugging in production) ``` ### **模式 6：“AI 智能体决策树”** 训练你的 AI 智能体使用此决策树： ``` Did I modify code in any supported language? (JS/TS, Python, Go, Rust, Java, C++, Ruby) │ ↓ YES Changed more than 50 lines? │ ↓ YES Run scanner ←──────────┐ │ │ ↓ │ Critical issues found? ────┤ YES │ NO │ ↓ │ Warnings? │ │ │ ↓ YES │ Show to user │ Ask if should fix ───────┤ │ NO │ ↓ ↓ Commit code Fix issues ``` ``` ## UBS AI Agents 快速参考 UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On** **Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash` **Golden Rule:** `ubs ` before every commit. Exit 0 = safe. Exit >0 = fix & re-run. **Commands:** ```bash ubs file.ts file2.py # Specific files (< 1s) — USE THIS ubs $(git diff --name-only --cached) # Staged files — before commit ubs --only=js,python src/ # Language filter (3-5x faster) ubs --ci --fail-on-warning . # CI mode — before PR ubs --help # Full command reference ubs sessions --entries 1 # Tail the latest install session log ubs . # Whole project (ignores things like .venv and node_modules automatically) ``` **Output Format:** ``` ⚠️ Category (N errors) file.ts:42:5 – Issue description 💡 Suggested fix Exit code: 1 ``` Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail **Fix Workflow:** 1. Read finding → category + fix suggestion 2. Navigate `file:line:col` → view context 3. Verify real issue (not false positive) 4. Fix root cause (not symptom) 5. Re-run `ubs ` → exit 0 6. Commit **Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits. **Bug Severity:** - **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks - **Important** (production): Type narrowing, division-by-zero, resource leaks - **Contextual** (judgment): TODO/FIXME, console logs **Anti-Patterns:** - ❌ Ignore findings → ✅ Investigate each - ❌ Full scan per edit → ✅ Scope to file - ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`) ``` ## 🎬 **看它在行动** *示例显示 JavaScript 输出；每种语言都有等效的检测（Python：None 检查，Go：nil 防护，Rust：Option 处理等）* ### **示例 1：捕捉 Null 指针 Bug** ``` $ ubs src/ ▓▓▓ NULL SAFETY & DEFENSIVE PROGRAMMING Detects: Null pointer dereferences, missing guards, unsafe property access 🔥 CRITICAL (5 found) Unguarded property access after getElementById Consider: const el = document.getElementById('x'); if (!el) return; src/components/form.js:42 const submitBtn = document.getElementById('submit-button'); submitBtn.classList.add('active'); // ← Crashes if element missing src/utils/dom.js:87 const modal = document.querySelector('.modal'); modal.style.display = 'block'; // ← Runtime crash guaranteed 💡 Fix: Always check for null before accessing properties ``` **之前：** 本周发生 3 起生产崩溃 **之后：** 0 次崩溃，2 秒内被捕捉 ### **示例 2：安全漏洞检测** ``` ▓▓▓ SECURITY VULNERABILITIES Detects: Code injection, XSS, prototype pollution, timing attacks 🔥 CRITICAL (3 found) innerHTML without sanitization - XSS risk Use textContent or DOMPurify.sanitize() src/comments.js:156 element.innerHTML = userComment; // ← XSS vulnerability! 🔥 CRITICAL (1 found) Hardcoded API keys detected Use environment variables or secret managers src/config.js:23 const apiKey = "sk_live_abc123xyz"; // ← Security breach! ``` **之前：** 安全事故，客户数据面临风险 **之后：** 漏洞在 git commit 前被捕捉 ### **示例 3：Async/Await 陷阱** ``` ▓▓▓ ASYNC/AWAIT & PROMISE PITFALLS Detects: Missing await, unhandled rejections, race conditions 🔥 CRITICAL (8 found) await used in non-async function SyntaxError in JavaScript src/api/users.js:67 function saveUser(data) { await database.insert(data); // ← SyntaxError! } ⚠️ WARNING (12 found) Promises without .catch() or try/catch Unhandled rejections crash Node.js src/services/email.js:45 sendEmail(user.email).then(result => ...) // ← No error handling! ``` **之前：** 静默失败，生产中的神秘 Bug **之后：** 所有 async bug 在部署前被捕捉并修复 ## 📋 **它能检测什么（完整武器库）** *每个语言模块都有专门的检测。以下示例具有代表性（显示 JavaScript；Python 有 `eval()`，Go 有 goroutine 泄漏，Rust 有 `.unwrap()` 恐慌，C++ 有缓冲区溢出等）* ### 🔴 **严重问题（生产阻碍者）** 这些 **将** 导致崩溃、安全漏洞或数据损坏： | 模式 | 示例 | 为什么危险 | |---------|---------|-------------------| | `eval()` 用法 | `eval(userInput)` | 允许任意代码执行 - **RCE 漏洞** | | 直接 NaN 比较 | `if (x === NaN)` | 总是返回 false - **逻辑 bug** | | 缺少 await | async 上下文中的 `asyncFunc()` | 静默失败，竞态条件 - **数据损坏** | | 原型污染 | `obj.__proto__ = {}` | 安全漏洞 - **权限升级** | | 未受保护的 null 访问 | `el.style.color` 无 null 检查 | 保证 **运行时崩溃** | | 不带 radix 的 `parseInt` | `parseInt("08")` | 在某些浏览器中返回 0 - **计算 bug** | | 空 catch 块 | `catch(e) {}` | 吞掉错误 - **调试噩梦** | | 带用户数据的 `innerHTML` | `el.innerHTML = userInput` | **XSS 漏洞** | | 缺少 async 关键字 | 没有 `async function` 的 `await` | **SyntaxError** | | 硬编码密钥 | `const key = "sk_live..."` | **安全漏洞** | ### 🟡 **警告（发布前应修复）** 这些会导致 bug、性能问题或维护麻烦： | 模式 | 示例 | 影响 | |---------|---------|--------| | 不带 `.catch()` 的 Promises | `promise.then(...)` | 未处理的拒绝导致 Node.js 崩溃 | | 不检查零的除法 | `total / count` | 返回 `Infinity` 或 `NaN` | | 不清理的事件监听器 | React 中的 `addEventListener` | **内存泄漏**（应用随时间变慢） | | 不清除的 `setInterval` | `setInterval(fn, 1000)` | **定时器泄漏**（无限定时器） | | 循环内的 `await` | `for(...) { await api.call() }` | **慢**（顺序，非并行） | | 迭代期间数组突变 | `arr.forEach(() => arr.push(...))` | **跳过/重复** 元素 | | 缺少 switch default | `switch(x) { case 1: ... }` | 未处理的值导致静默失败 | | `isNaN()` 而不是 `Number.isNaN()` | `isNaN("foo")` | 类型强制 bug | ### 🔵 **信息（代码质量与最佳实践）** 让代码更清晰、更易维护的改进： - 可选链机会（`obj?.prop?.value`） - Nullish coalescing 机会（`value ?? default`） - TypeScript `any` 用法（降低类型安全性） - `console.log` 语句（生产前移除） - 技术债务标记（TODO, FIXME, HACK） - 性能优化（循环中的 DOM 查询） - `var` 用法（改用 `let`/`const`） - 没有防护的深层属性访问 - 大型内联数组（移至单独文件） - 复杂的嵌套三元组（可读性） ## ⚙️ **高级配置** ### **命令行选项（完整参考）** ``` ubs [OPTIONS] [PROJECT_DIR] [OUTPUT_FILE] Core Options: -v, --verbose Show 10 code samples per finding (default: 3) -q, --quiet Minimal output (summary only) --ci CI mode (stable output, no colors by default) --fail-on-warning Exit with code 1 on warnings (strict mode) --version Print UBS meta-runner version and exit --profile=MODE strict|loose (sets defaults for strictness) --baseline=FILE Compare findings against a baseline JSON (alias for --comparison) -h, --help Show help and exit Git Integration: --staged Scan only files staged for commit --diff, --git-diff Scan only modified files (working tree vs HEAD) Output Control: --format=FMT Output format: text|json|jsonl|sarif|toon (default: text) --beads-jsonl=FILE Write JSONL summary alongside normal output for Beads/"strung" --no-color Force disable ANSI colors OUTPUT_FILE Save report to file (auto-tees to stdout) File Selection: --include-ext=CSV File extensions (default: auto-detect by language) JS: js,jsx,ts,tsx,mjs,cjs | Python: py,pyi,pyx Go: go | Rust: rs | Java: java | C++: cpp,cc,cxx,c,h Ruby: rb,rake,ru | C#: cs,csx | Custom: --include-ext=js,ts,vue --exclude=GLOB[,...] Additional paths to exclude (comma-separated) Example: --exclude=legacy (deps ignored by default) --skip-size-check Skip directory size guard (use with care) Performance: --jobs=N Parallel jobs for ripgrep (default: auto-detect cores) Set to 1 for deterministic output Rule Control: --skip=CSV Skip categories by number (see output for numbers) Example: --skip=11,14 # Skip debug code + TODOs --skip-type-narrowing Disable helper-backed guard analysis (falls back to text heuristics) --rules=DIR Additional ast-grep rules directory Rules are merged with built-in rules --no-auto-update Disable automatic self-update --suggest-ignore Print large-directory candidates to add to .ubsignore (no changes applied) Environment Variables: JOBS Same as --jobs=N NO_COLOR Disable colors (respects standard) CI Enable CI mode automatically UBS_MAX_DIR_SIZE_MB Max directory size in MB before refusing to scan (default: 1000) UBS_SKIP_SIZE_CHECK Skip directory size guard entirely (set to 1) Arguments: PROJECT_DIR Directory to scan (default: current directory) OUTPUT_FILE Save full report to file Exit Codes: 0 No critical issues (or no issues at all) 1 Critical issues found 1 Warnings found (only with --fail-on-warning) 2 Invalid arguments or environment error (e.g., missing ast-grep for JS/TS) ``` **目录大小保护** UBS 在忽略过滤器（默认值 + `.ubsignore`）之后计算扫描大小，并在执行限制之前打印： `Scan size after ignores: XMB (limit YMB)`。通过以下方式覆盖 `UBS_MAX_DIR_SIZE_MB` 或 `UBS_SKIP_SIZE_CHECK=1`，或传递 `--skip-size-check`。 ### 环境错误 (exit 2) 如果 UBS 打印 **Environment error** 并退出 `2`，则缺少或无法使用必需的依赖项。 JS/TS 项目最常见的修复： 或手动安装依赖项： ``` brew install ast-grep # or: cargo install ast-grep, npm i -g @ast-grep/cli ``` 如果你有意仅扫描非 JS 语言，排除 JS： ``` ubs --exclude=js . ``` ### **示例** ``` # 基本扫描 ubs . # 包含完整详情的详细扫描 ubs -v /path/to/project # CI 严格模式（遇任何警告即失败） ubs --fail-on-warning --ci # 保存报告且不 cluttering 终端 ubs . report.txt # 扫描 Vue.js 项目 ubs . --include-ext=js,ts,vue # 跳过你不关心的类别 ubs . --skip=14 # Skip TODO/FIXME markers # 最大性能（使用所有核心） ubs --jobs=0 . # Auto-detect ubs --jobs=16 . # Explicit core count # 排除 vendor 代码 ubs . --exclude=node_modules,vendor,dist,build # 大型目录（大小保护） UBS_MAX_DIR_SIZE_MB=5000 ubs . UBS_SKIP_SIZE_CHECK=1 ubs . # 自定义规则目录 ubs . --rules=~/.config/ubs/custom-rules # 组合多个选项 ubs -v --fail-on-warning --exclude=legacy --include-ext=js,ts,tsx . report.txt ``` ### JSONL schema `--format=jsonl`（和 `--beads-jsonl=FILE`）发出换行分隔的对象，以便轻松管道传输到 Beads 或 `jq` 等工具： ``` {"type":"scanner","project":"/path/to/project","language":"python","files":42,"critical":1,"warning":3,"info":12,"timestamp":"2025-11-22T09:04:20Z"} {"type":"totals","project":"/path/to/project","files":99,"critical":1,"warning":3,"info":27,"timestamp":"2025-11-22T09:04:22Z"} ``` ### **自定义 AST-Grep 规则** 你可以添加自己的 Bug 检测模式： ``` # 创建自定义规则目录 mkdir -p ~/.config/ubs/rules # 添加自定义规则（YAML 格式） cat > ~/.config/ubs/rules/no-console-in-prod.yml <<'EOF' id: custom.no-console-in-prod language: javascript rule: any: - pattern: console.log($$$) - pattern: console.debug($$$) - pattern: console.info($$$) severity: warning message: "console statements should be removed before production" note: "Use a proper logging library or remove debug statements" EOF # 使用自定义规则运行 ubs . --rules=~/.config/ubs/rules ``` **常见的自定义规则：** ``` # 强制执行特定命名约定 id: custom.component-naming language: typescript rule: pattern: export function $NAME() { $$$ } not: pattern: export function $UPPER() { $$$ } severity: info message: "React components should start with uppercase letter" ``` ``` # 捕获 codebase 中的特定反模式 id: custom.no-direct-state-mutation language: typescript rule: pattern: this.state.$FIELD = $VALUE severity: critical message: "Never mutate state directly - use setState()" ``` ### **排除误报** 如果扫描器针对你的特定用例报告误报： ``` # 跳过整个类别 ubs . --skip=11,14 # Skip debug code detection and TODO markers # 排除特定文件/目录 ubs . --exclude=legacy,third-party,generated # 对于永久配置，创建一个包装脚本 cat > ~/bin/ubs-custom <<'EOF' #!/bin/bash ubs "$@" \ --exclude=legacy,generated \ --skip=14 \ --rules=~/.config/ubs/rules EOF chmod +x ~/bin/ubs-custom ``` ## 🎓 **它是如何工作的（底层）** ### **多层分析引擎** 扫描器使用复杂的 4 层方法： ``` Layer 1: PATTERN MATCHING (Fast) ──┐ ├─ Regex-based detection │ ├─ Optimized with ripgrep │ └─ Finds 70% of bugs in <1 second │ ├──► Combined Results Layer 2: AST ANALYSIS (Deep) ──────┤ ├─ Semantic code understanding │ ├─ Powered by ast-grep │ └─ Catches complex patterns │ │ Layer 3: CONTEXT AWARENESS (Smart) ┤ ├─ Understands surrounding code │ ├─ Reduces false positives │ └─ Knows when rules don't apply │ │ Layer 4: STATISTICAL (Insightful) │ ├─ Code smell detection │ ├─ Anomaly identification │ └─ Architectural suggestions │ ↓ Final Report (3-5 sec) ``` ### **技术栈** | 组件 | 技术 | 用途 | 为什么选择这个 | |-----------|-----------|---------|-----------------| | **核心引擎** | Bash 4.0+ | 编排 | 通用兼容性，零依赖 | | **模式匹配** | Ripgrep | 文本搜索 | 比 grep 快 10-100 倍，并行化 | | **AST 解析器** | ast-grep | 语义分析 | 理解代码结构，不仅仅是文本 | | **回退** | GNU grep | 文本搜索 | 适用于任何类 Unix 系统 | | **规则引擎** | YAML | 模式定义 | 人类可读，易于扩展 | ### **AST 规则架构：祖先感知模式匹配** UBS 的 ast-grep 规则使用一种称为 **祖先遍历** 的复杂技术来大幅减少误报。关键指令 `stopBy: end` 确保模式检查 *整个* 祖先链，而不仅仅是直接父级。 **没有祖先遍历的问题：** ``` // This code is SAFE - the fetch is properly handled: async function safeFetch() { try { fetch('/api'); // Inside try block - exception will be caught } catch (e) { handleError(e); } } // Naive AST rule checking only immediate parent: // ❌ False positive! Reports "fetch without catch" because // fetch()'s immediate parent is the ExpressionStatement, // not the try block. ``` **解决方案 - 使用 `stopBy: end` 的祖先遍历：** ``` # 具有适当祖先检查的 ast-grep 规则 rule: all: - pattern: fetch($ARGS) - not: inside: kind: try_statement stopBy: end # ← Key directive: traverse ALL ancestors - not: inside: pattern: $_.catch($$) # Check for .catch() in chain stopBy: end ``` `stopBy: end` 指令指示 ast-grep 向上遍历 *整个* 祖先树，直到找到匹配项（或到达根）。没有它，只检查直接父级——错过 try 块、函数边界和方法链。 **真实世界的影响：** | 场景 | 没有 `stopBy: end` | 有 `stopBy: end` | |----------|----------------------|-------------------| | `try { fetch() } catch {}` | ❌ 误报 | ✅ 正确忽略 | | `fetch().then().catch()` | ❌ 误报 | ✅ 正确忽略 | | `return fetch()` | ❌ 误报 | ✅ 正确忽略 | | `fetch()` 独立 | ✅ 检测到 | ✅ 检测到 | 此技术应用于 JavaScript 模块中的 19+ 规则，涵盖： - Promise 链检测（`.then()`, `.catch()`, `.finally()`） - Try-catch 上下文感知 - Return 语句处理 - Async/await 作用域分析 ### **内联抑制注释** 当发现是有意为之或已知的误报时，内联抑制它： ``` // Suppress a single line: eval(trustedCode); // ubs:ignore // Suppress with reason (recommended): eval(adminScript); // ubs:ignore -- admin-only trusted input ``` ``` # Python 抑制： exec(validated_code) # ubs:ignore # Ruby 抑制： eval(safe_string) # ubs:ignore ``` **抑制规则：** - 必须出现在标记代码的 **同一行** - 适用于所有 9 种支持的语言 - 抑制该行上的所有发现（谨慎使用） - 在保留尾随注释的格式化工具中存活 **要避免的反模式：** ``` // ❌ Wrong - comment on previous line doesn't suppress: // ubs:ignore eval(code); // Still flagged! // ❌ Wrong - don't blanket-suppress large blocks: /* ubs:ignore */ // Doesn't work for block comments ``` ### **跨语言 Async 错误检测** UBS 在所有 9 种语言中一致地检测未处理的 async 错误。这些模式适应每种语言的惯用语，同时提供等效的覆盖范围： | 语言 | 模式 | UBS 检测什么 | |----------|---------|------------------| | **JavaScript/TypeScript** | 没有 `.catch()` 的 `promise.then()` | 悬空 promise，缺少 `await`，未处理的拒绝 | | **Python** | 没有 `await` 的 `asyncio.create_task()` | 孤立任务，缺少 `await`，未关闭的协程 | | **Go** | 没有错误 channel 的 Goroutine | 即发即弃的 goroutine，泄漏的上下文 | | **Rust** | 部分防护后的 `.unwrap()` / `.expect()` | `if let Some` 后的恐慌，缺少 `?` 运算符 | | **Java** | 没有 `.exceptionally()` 的 `CompletableFuture` | 吞掉的异常，缺少 `join()` | | **Ruby** | 没有 `.join` 的 `Thread.new` | Zombie 线程，未处理的线程异常 | | **C++** | 没有 `.get()` 的 `std::async` | 忽略的 future，异常传播 | | **Swift** | 没有错误处理的 `Task {}` | 非结构化并发泄漏 | | **C#** | `Task.Wait()` / `.Result` / `throw ex;` | Sync-over-async 死锁，堆栈跟踪丢失，不安全的异常表面 | **JavaScript Promise 链分析：** 扫描器理解复杂的 promise 链： ``` // ✅ Handled - .catch() at end of chain: fetch('/api') .then(r => r.json()) .then(data => process(data)) .catch(handleError); // Scanner recognizes this catches all above // ✅ Handled - .catch() before .then(): fetch('/api') .catch(e => fallback) // Early catch .then(r => r.json()); // ❌ Unhandled - .finally() doesn't catch: fetch('/api') .then(r => r.json()) .finally(cleanup); // Flagged: finally doesn't handle rejections // ❌ Unhandled - no error handling: async function leaky() { fetch('/api'); // Flagged: fire-and-forget promise } ``` ### **辅助脚本验证** 特定语言的辅助脚本（Python AST 遍历器、Go 分析器、TypeScript 类型检查器）在执行前使用 SHA-256 校验和进行验证： ``` # 嵌入在每个模块中的 Helper 校验和： modules/helpers/ ├── async_task_handles_csharp.py # SHA-256 verified ├── resource_lifecycle_csharp.py # SHA-256 verified ├── resource_lifecycle_py.py # SHA-256 verified ├── resource_lifecycle_go.go # SHA-256 verified ├── resource_lifecycle_java.py # SHA-256 verified ├── type_narrowing_csharp.py # SHA-256 verified ├── type_narrowing_ts.js # SHA-256 verified ├── type_narrowing_rust.py # SHA-256 verified ├── type_narrowing_kotlin.py # SHA-256 verified └── type_narrowing_swift.py # SHA-256 verified ``` `ubs doctor` 命令验证所有辅助校验和： ``` $ ubs doctor 🏥 UBS Environment Audit ──────────────────────── ✓ helper checksum verified (resource_lifecycle_py.py) ✓ helper checksum verified (type_narrowing_ts.js) ... ``` 如果辅助程序被修改或损坏，扫描器会安全地失败并附带修复指导，而不是执行未验证的代码。 ### **统一严重性标准化** 所有 9 个语言模块将其发现标准化为一致的严重性等级，确保无论源语言如何都能获得可预测的输出： ``` ┌─────────────────────────────────────────────────────────────┐ │ Language Tool Output → UBS Normalized Severity │ ├─────────────────────────────────────────────────────────────┤ │ ESLint "error" → critical │ │ Pylint "E" / "F" → critical │ │ Clippy "deny" → critical │ │ Go vet "error" → critical │ │ SpotBugs "High" → critical │ │ RuboCop "Fatal/Error" → critical │ ├─────────────────────────────────────────────────────────────┤ │ ESLint "warn" → warning │ │ Pylint "W" / "R" → warning │ │ Clippy "warn" → warning │ │ Go vet "warning" → warning │ │ SpotBugs "Medium" → warning │ │ RuboCop "Warning" → warning │ ├─────────────────────────────────────────────────────────────┤ │ ESLint "suggestion" → info │ │ Pylint "C" / "I" → info │ │ Clippy "note" → info │ │ SpotBugs "Low" → info │ │ RuboCop "Convention" → info │ └─────────────────────────────────────────────────────────────┘ ``` **标准化的好处：** - **一致的退出代码**：退出 1 总是意味着“发现严重问题”，跨所有语言 - **统一的 JSON/SARIF 输出**：下游工具解析一种 schema，而不是 8 种不同的格式 - **可预测的 `--fail-on-warning`**：无论扫描 Python、Rust 还是 TypeScript，行为都相同 - **跨语言指标**：公平地比较多语言项目的代码质量 每个模块中的 `normalize_severity()` 函数处理边缘情况，如工具特定的严重性字符串、数字级别和旧格式变体。 ### **性能优化** ``` # 自动并行化（使用所有 CPU 核心） - Auto-detects: 16-core = 16 parallel jobs - Manually set: --jobs=N # 智能文件过滤（仅扫描相关文件） - JS/TS: .js, .jsx, .ts, .tsx, .mjs, .cjs (auto-skip node_modules/dist/build) - Python: .py + pyproject/requirements (skip venv/__pycache__) - C/C++: .c/.cc/.cpp/.cxx + headers + CMake files (skip build/out) - Rust: .rs + Cargo manifests (skip target/.cargo) - Go: .go + go.mod/go.sum/go.work (skip vendor/bin) - Java: .java + pom.xml + Gradle scripts (skip target/build/out) - Ruby: .rb + Gemfile/Gemspec/Rakefile (skip vendor/bundle,tmp) - Custom: --include-ext=js,ts,vue # 高效流式传输（低内存占用） - No temp files created - Results streamed as found - Memory usage: <100MB for most projects # 增量扫描（未来功能） - Only scan changed files (git diff) - Cache previous results - 10x faster on large projects ``` ## 🏆 **与其他工具的比较** | 功能 | Ultimate Bug Scanner | ESLint | TypeScript | SonarQube | DeepCode | |---------|---------------------|--------|------------|-----------|----------| | **设置时间** | 30 秒 | 30 分钟 | 1-2 小时 | 2-4 小时 | 需要账户 | | **速度 (50K 行)** | 3 秒 | 15 秒 | 8 秒 | 2 分钟 | 云上传 | | **零配置** | ✅ 是 | ❌ 否 | ❌ 否 | ❌ 否 | ❌ 否 | | **无类型也能工作** | ✅ 是 | ✅ 是 | ❌ 否 | ✅ 是 | ✅ 是 | | **Null Safety** | ✅ 是 | ⚠️ 有限 | ✅ 是 | ⚠️ 有限 | ⚠️ 有限 | | **安全扫描** | ✅ 是 | ⚠️ 插件 | ❌ 否 | ✅ 是 | ✅ 是 | | **内存泄漏** | ✅ 是 | ❌ 否 | ❌ 否 | ⚠️ 有限 | ❌ 否 | | **Async/Await** | ✅ 深度 | ⚠️ 基本 | ✅ 良好 | ⚠️ 基本 | ⚠️ 基本 | | **CI/CD 就绪** | ✅ 是 | ✅ 是 | ✅ 是 | ✅ 是 | ⚠️ 云 | | **离线** | ✅ 是 | ✅ 是 | ✅ 是 | ⚠️ 有限 | ❌ 否 | | **AI 智能体友好** | ✅ 专为此构建 | ⚠️ 配置繁重 | ⚠️ 配置繁重 | ❌ 复杂 | ⚠️ 云 | | **成本** | 免费 | 免费 | 免费 | $$$$ | $$$ | **何时使用什么：** - **Ultimate Bug Scanner**：快速扫描，AI 工作流，无需配置 - **ESLint**：样式强制，自定义规则，团队标准 - **TypeScript**：类型安全（与此扫描器一起使用） - **SonarQube**：企业合规性，详细指标 - **DeepCode**：ML 驱动的分析（如果你信任云） **最佳组合：** TypeScript + ESLint + Ultimate Bug Scanner = 最大安全性 ## 🧠 **项目理由与依据** ### **为什么存在这个项目（以及为什么它不是“又一个 Linter”）** 你可能在想：*“我们已经有 ESLint、Pylint、Clippy、RuboCop……为什么要构建另一个工具？”* **公平的问题。老实说，你的第一反应可能是持怀疑态度，这是对的。** ### **最初的怀疑是有效的（但忽略了重点）** 当你第一次看 UBS 时，自然会想： **那是通过错误的镜头进行分析。** 你正在将它与为 **根本不同的工作流** 设计的工具（人类开发人员手动编写代码）进行比较，而它正在解决一个 **根本不同的问题**（LLM 智能体以 100 倍的速度生成代码）。 这就像比较烟雾探测器与建筑检查员： - **建筑检查员 (ESLint)**：彻底、全面、发现所有问题、花费数小时 - **烟雾探测器 (UBS)**：快速、捕捉关键危险、即时警报、始终运行 **你两者都需要。** 但当你的房子可能着火时（AI 刚刚在 30 秒内生成了 500 行代码），你首先需要烟雾探测器。 ### **范式转变：AI 原生开发** 软件开发正在经历 **根本性的转变**： **2020（LLM 前时代）：** - 开发人员每天手动编写 50-200 行代码 - 每一行之前都要深思熟虑 - 每个项目主要是单一语言 - 审查时间：充足 - 质量门：全面 linting + 代码审查（数小时） **2025（LLM 时代）：** - AI 每天跨项目生成 500-5000 行代码 - 代码在几秒钟内出现 - 多语言项目标准化（Go 中的微服务，TypeScript 中的 UI，Python 中的 ML，Rust 中的 workers） - 审查时间：稀缺 - 需要的质量门：即时反馈（<5s）否则循环会中断 **传统工具不是为此设计的。** 它们是在“代码生成”意味着每天 200 行而不是 2000 行时构建的。 ### **这是根本区别：** ### **1. 此工具专为 AI 智能体构建，而不仅仅是人类** 传统 linter 是为 **人类开发人员** 在 **单一语言代码库** 中工作而设计的。UBS 是为跨 **多语言项目** 工作的 **LLM 编程智能体** 设计的。 **范式转变：** | 传统 Linting（人类优先） | UBS 方法（LLM 优先） | |---|---| | **目标**：全面覆盖 + 自动修复
**速度**：15-60 秒可接受
**设置**：每种语言 30 分钟配置
**语言**：每种语言一个工具
**误报**：必须 <1%（让人类沮丧）
**输出**：人类可读的散文 | **目标**：关键 Bug 检测 + 快速反馈
**速度**：需要 <5 秒
**设置**：零配置（即时启动）
**语言**：一次扫描所有 9 种语言
**误报**：10-20% 可以（LLM 瞬间过滤）
**输出**：供 LLM 解析的结构化 file:line | ### **2. LLM 不需要自动修复——它们本身就是自动修复引擎** **为什么传统 linter 有自动修复：** ``` // ESLint flags: "Use === instead of ==" if (value == null) // ❌ // ESLint auto-fix (rigid, no context): if (value === null) // ✅ Technically correct, but... ``` **为什么 UBS 没有（也不应该）：** ``` // UBS flags: "Type coercion bug: == should be ===" if (value == null) // ❌ // Claude reads the error and understands context: if (value !== null && value !== undefined) // ✅ Better - handles both // OR if (value != null) // ✅ Or keeps == for null/undefined (intentional) ``` **困难的部分是检测，而不是修复。** 一旦标记，LLM 就可以： - 理解语义上下文 - 考虑周围的代码 - 应用正确的修复（不仅仅是机械的修复） - 整体重构 自动修复会 **更糟**，因为它是无上下文的。LLM 需要知道 **哪里出了问题** 以及 **在哪里**，然后它们会正确修复它。 ### **3. 多语言零配置设计是护城河** **想象一下要求 Claude 为多语言项目设置质量门：** **传统方法（每个项目 15-30 分钟）：** ``` # JavaScript/TypeScript npm install --save-dev eslint @eslint/js @typescript-eslint/parser # 创建 .eslintrc.js（200 行配置） # Python pip install pylint black mypy # 创建 .pylintrc, pyproject.toml 部分 # Rust # 添加到 Cargo.toml: [lints] # 配置 clippy 规则 # Go # 安装 golangci-lint，创建 .golangci.yml # Java # 设置 Checkstyle + PMD + SpotBugs + 配置 XMLs # C++ # 设置 clang-tidy，创建 .clang-tidy 配置 # Ruby # 创建 .rubocop.yml，包含 150+ 行 # 现在运行 7 个不同的命令并解析 7 个不同的输出格式... ``` **UBS 方法（30 秒）：** ``` curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash ubs . # 完成。所有 9 种语言已扫描，统一报告。 ``` **这很重要，因为：** - LLM 在一次会话中跨语言生成代码（Python API → Go 服务 → TypeScript UI → Rust worker） - 为 LLM 配置 7 个工具容易出错 - 人类不想维护 7 个不同的配置文件 - CI/CD 流水线想要一个命令，一个退出代码 ### **跨语言的类型缩窄覆盖** - **TypeScript** – 只要 Node.js + `typescript` 包可用，UBS 就会调用 `tsserver`（通过捆绑的辅助程序）。安装程序会显示“Type narrowing readiness”诊断，因此你立即知道 tss 驱动的防护是否正在运行。 - **Rust** – Python 辅助程序检查 `if let Some/Ok` 防护子句，并标记在退出块之外后续的 `.unwrap()`/`.expect()` 调用。Fixtures 和 manifest 案例保持对此的回归测试。 - **Kotlin** – Java 模块扫描 `.kt` 源代码，查找 `if (value == null)` 防护，这些防护只是在命中 `value!!` 之前记录并继续运行，捕获混合 Java + Kotlin 的 JVM 团队上的相同陷阱。 - **Swift** – 专用的 `ubs-swift` 模块现在直接附带 guard-`let` 辅助程序，因此即使你在本地运行 `ubs --only=swift`，可选链/Objective‑C 桥接启发式规则也会触发（无需依附于 Java 模块）。它捕捉代码在强制解包 `value!` 之前记录并继续运行的情况，保护混合 Swift + ObjC 的 iOS/macOS 管道。 ### **资源生命周期 AST 覆盖** - **Python** – `modules/helpers/resource_lifecycle_py.py` 现在对 AST 进行推理，追踪 `with`/`async with`、别名导入和 `.open()`/`.connect()` 调用，因此 `ubs-python` 仅在句柄真正泄漏时发出警告。Pathlib `Path.open()` 和类似模式在没有脆弱 regex 的情况下得到处理。 - **Java** – 新的 ast-grep 规则（`java.resource.executor-no-shutdown`, `java.resource.thread-no-join`, `java.resource.jdbc-no-close`, `java.resource.resultset-no-close`, `java.resource.statement-no-close`）确保 ExecutorServices、原始 `Thread`s、`java.sql.Connection`s、`Statement`/`PreparedStatement`/`CallableStatement` 和 `ResultSet` 句柄都在 regex 回退运行之前获得正确的关闭/停止语义。 - **C#** – `modules/helpers/resource_lifecycle_csharp.py`, `modules/helpers/type_narrowing_csharp.py` 和 `modules/helpers/async_task_handles_csharp.py` 现在捕捉可释放句柄泄漏（`CancellationTokenSource`、流式 readers/writers、`HttpRequestMessage`）、记录但仍落入解引用的 null/`TryGetValue` 防护，以及已创建但从未观察到的 `Task.Run`/`Task.Factory.StartNew` 句柄。C# ast-grep 包现在也作为每个规则的一流发现落地，用于丢弃的即发即弃任务、`lock` 内的 `await` 和 `Parallel.ForEach` async-lambda 误用，而不是仅样本计数的存根。 - **C++ / Rust / Ruby** – 这些模块已经依赖于 ast-grep 规则包；“Universal AST Adoption”史诗现已完成，每个语言模块（JS, Python, Go, C++, Rust, Java, Ruby, Swift, C#）都运行语义检测器，而不是脆弱的 grep-only 启发式规则。 #### Python – AST 辅助程序在行动 ``` import asyncio, subprocess fh = open("/tmp/leaky.txt", "w") proc = subprocess.Popen(["sleep", "1"]) async def leak_task(): task = asyncio.create_task(asyncio.sleep(1)) await asyncio.sleep(0.1) return task asyncio.run(leak_task()) ``` ``` $ ./ubs --only=python test-suite/python/buggy/resource_lifecycle.py 🔥 File handles opened without context manager/close [resource_lifecycle.py:4] File handle fh opened without context manager or close() ⚠ Popen handles not waited or terminated [resource_lifecycle.py:7] ``` 辅助程序捕捉未受保护的文件句柄、僵尸子进程和孤立的 asyncio 任务，因为它遍历 AST（追踪别名和 async 上下文）而不是 grepping 字符串。 #### Go – AST 辅助程序验证清理 ``` ctx, cancel := context.WithTimeout(context.Background(), time.Second) ticker := time.NewTicker(time.Millisecond * 500) timer := time.NewTimer(time.Second) f, _ := os.Open("/tmp/data.txt") _ = ctx _ = cancel _ = ticker _ = timer _ = f ``` ``` $ ./ubs --only=golang test-suite/golang/buggy/resource_lifecycle.go 🔥 context.With* without deferred cancel [resource_lifecycle.go:10] ⚠ time.NewTicker not stopped [resource_lifecycle.go:13] ⚠ time.NewTimer not stopped [resource_lifecycle.go:15] ⚠ os.Open/OpenFile without defer Close() [resource_lifecycle.go:17] ``` 因为辅助程序哈希 AST 位置，manifest 可以断言确定性子字符串，并且我们避免了颜色代码或日志标题的不稳定性。 当你想要绕过所有这些防护分析器时使用 `--skip-type-narrowing`（或 `UBS_SKIP_TYPE_NARROWING=1`）——例如在物理隔离的 CI 环境上或一次验证一种语言的遗留项目时。 ### **4. 速度支持紧密的迭代循环** 对于 AI 工作流，**生成 → 扫描 → 修复** 循环需要 **快**： ``` ┌─────────────────────────────────────────┐ │ Traditional Linter (30-45 seconds) │ ├─────────────────────────────────────────┤ │ Claude generates code: 10s │ │ Run ESLint + Pylint + ... 30s ⏳ │ │ Claude reads findings: 5s │ │ Claude fixes bugs: 15s │ │ Re-run linters: 30s ⏳ │ │ ────────────────────────────────── │ │ Total iteration: 90s │ └─────────────────────────────────────────┘ ┌─────────────────────────────────────────┐ │ UBS (3-5 seconds) │ ├─────────────────────────────────────────┤ │ Claude generates code: 10s │ │ Run UBS: 3s ⚡ │ │ Claude reads findings: 2s │ │ Claude fixes bugs: 10s │ │ Re-run UBS: 3s ⚡ │ │ ────────────────────────────────── │ │ Total iteration: 28s │ └─────────────────────────────────────────┘ 3x faster feedback loop = 3x more iterations in the same time ``` **当你每天在 AI 协助下交付 10+ 个功能时，这会复利增长。** ### **5. 检测 LLM 特定的 Bug 模式** UBS 针对 **AI 智能体实际生成** 的 Bug，而不是所有可能的代码异味。 **LLM 经常产生的 Bug：** | 模式 | 为什么 LLM 生成它 | 传统 Linter | |---------|---------------------|---------------------| | 缺少 `await` | 忘记 `async` 关键字，语法看起来没问题 | ❌ 仅 TypeScript | | 未受保护的 null 访问 | “乐观”编程 - 假设快乐路径 | ⚠️ 需要严格配置 | | `eval()` / 代码注入 | 寻求“简单”的动态解决方案 | ✅ 大多数标记这个 | | 内存泄漏（事件监听器） | 不考虑清理生命周期 | ❌ 需要 ESLint 插件 | | `innerHTML` XSS | 不对用户输入进行威胁建模 | ⚠️ 仅安全插件 | | 除以零 | 不考虑边缘情况 | ❌ 大多数遗漏这个 | | 硬编码密钥 | 使用占位符，忘记外部化 | ⚠️ 需要 secrets scanner | | Goroutine 泄漏 | 忘记上下文取消 | ❌ Go 专用工具 | | `.unwrap()` 恐慌 | 假设成功路径 | ✅ Clippy 捕捉 | | 缓冲区溢出 | 忘记边界检查 | ⚠️ 仅 Sanitizer | **UBS 针对此特定威胁模型进行了优化。** ### **6. 新颖分析：深层属性防护关联** 这是真正 **在标准 linter 中不可用** 的： ``` # 代码 LLM 生成： def get_theme(user): return user.profile.settings.theme # ❌ Unguarded chain # ESLint/Pylint: ✅ 无错误（语法正确） # TypeScript: ✅ 无错误（如果类型声称非空） # UBS Deep Guard 分析： # 1. 扫描：user.profile.settings.theme（发现于第 42 行） # 2. 扫描：if user and user.profile and user.profile.settings # 3. 关联：未找到匹配 GUARD # 4. 报告：⚠️ 未受保护的深度属性访问 ``` **这需要：** - 跨文件的属性链 AST 提取 - 条件防护的 AST 提取 - 具有上下文感知的交叉引用匹配 - 上下文建议 **没有其他人默认这样做**，因为它不是一条 lint 规则——它是跨多种代码模式的 **关联分析**。 ### **7. 互补，而非竞争** **UBS 旨在与现有工具一起工作，而不是取代它们：** ``` ┌────────────────────────────────────────────────────┐ │ Your Quality Stack (Recommended) │ ├────────────────────────────────────────────────────┤ │ TypeScript → Type safety │ │ ESLint/Clippy/etc → Comprehensive linting │ │ Jest/PyTest → Unit tests │ │ ✨ UBS → AI-generated bug oracle │ │ GitHub Actions → CI/CD integration │ └────────────────────────────────────────────────────┘ ``` **使用 UBS 用于：** - ✅ AI 工作流中的快速多语言扫描 - ✅ 提交前的关键 Bug 检测 - ✅ 阻止明显损坏代码的 Git 钩子 - ✅ Claude/Cursor/AI 智能体质量防护栏 - ✅ 配置 7 个 linter 很痛苦的多语言项目 **使用 ESLint/Pylint/Clippy/etc 用于：** - ✅ 全面的样式强制 - ✅ 框架特定的规则（React hooks 等） - ✅ 自定义团队约定 - ✅ 自动格式化 - ✅ 深度单一语言分析 **它们解决不同的问题。** UBS 是“烟雾探测器”（快速，捕捉关键问题）。传统 linter 是“建筑检查员”（彻底，捕捉所有问题）。 ### **8. 技术护城河** 这使得难以复制： **多层分析：** ``` Layer 1: Ripgrep (regex) → 70% of bugs in 0.5s Layer 2: ast-grep (AST) → Complex semantic patterns Layer 3: Correlation logic → Cross-pattern analysis (novel) Layer 4: Metrics collection → Time-series quality tracking ``` **这种速度 + 语义理解 + 关联的组合是独特的。** **统一的多语言运行器：** - 一次扫描自动检测 9 种语言 - 并行执行（Go + Python + Rust 同时进行） - 统一的 JSON/SARIF 输出供工具使用 - 具有延迟下载/缓存的模块系统 **LLM 优化的集成点：** - Git 钩子（阻止不良提交） - Claude Code 文件写入钩子 - `.cursorrules` / `.aiconfig` 集成 - 用于 LLM 解析的干净结构化输出 ### **9. 30 条规则比 600 条更好（对于此用例）** **你可能注意到：** ESLint 有 200+ 核心规则，Clippy 有 600+ lints，但 UBS 每种语言有 ~30 个模式。 **这是故意的，不是限制。** **AI 生成 Bug 的 80/20 规则：** - **80% 的生产破坏性 Bug** 来自 ~30 个常见模式 - **20% 的边缘情况** 需要其他 570 条规则 **对于 LLM 工作流，你需要：** ``` ✅ Fast scan (3s) that catches 80% of critical bugs ↓ LLM fixes them immediately ↓ ✅ Fast re-scan (3s) confirms fixes ↓ Then run comprehensive linters (30s) for the remaining 20% ``` **而不是：** ``` ❌ Comprehensive scan (30s) that catches 100% of issues ↓ LLM waits... workflow broken... context switch... ↓ Slower iteration = fewer features shipped ``` **UBS 针对的 Bug 是：** - 缺少 `await`（崩溃） - Null 指针访问（崩溃） - 安全漏洞：`eval()`、XSS、硬编码密钥（漏洞） - 内存泄漏（性能下降） - 竞态条件（数据损坏） **全面 linter 添加的 Bug 是：** - 不一致的引号样式（样式） - 缺少尾随逗号（样式） - 未重新分配时优先使用 `const` 而不是 `let`（样式） - 函数名应该是 camelCase（样式） - 行太长（样式） **当 AI 刚刚生成了 500 行可能到处都有 `eval()` 和缺少 `await` 时，哪个更重要？** 针对耗费数小时的 **关键 Bug**。让全面 linter 在单独的传递中处理样式。 ### **10. 市场时机：这在 3 年前毫无意义** **为什么这个工具现在存在：** **2021:** - GitHub Copilot 发布（单行补全） - 仍然主要是人工编写的代码 - 传统 linting 工作流工作正常 **2023:** - ChatGPT/GPT-4 可以生成完整功能 - Claude Code、Cursor 出现 - 开发人员开始 AI 辅助工作流 - 痛点出现：“AI 很快但有很多 Bug” **2025:** - LLM 在几分钟内生成整个功能 - 多文件重构在几秒钟内发生 - 多语言微服务成为标准 - **质量门无法跟上生成速度** **UBS 解决的问题在 LLM 编程成为主流之前并不存在。** 此工具 **时机完美**，适合现在正在发生的 AI 编程爆发。 ### **11. 误报哲学** **对于人类开发人员：** - 误报 = 上下文切换 + 调查 + 沮丧 - 可接受率：<1% **对于 LLM 智能体：** - 误报 = 解析（0.1s）+ 分析（0.5s）+ 确定安全（0.2s） - 可接受率：10-20% **LLM 不会沮丧。** 它们以编程方式评估每个发现。 **这意味着 UBS 可以更激进：** - 即使不是 100% 确定也标记可疑模式 - 以一些噪音为代价捕捉更多 Bug - LLM 认知地过滤误报（免费） 标记 100 个问题（其中 20 个是安全的）比漏掉 1 个关键 Bug 更好。 ## **FAQ：常见问题和异议** ### **Q: “这不就是重新发明轮子吗？ESLint 已经存在了。”** **A:** 它不是重新发明轮子——它是为不同的道路制造不同的车辆。 ESLint 是一辆 **卡车**（重型、全面、运送一切）。 UBS 是一辆 **跑车**（快速、有针对性、快速到达）。 你不会在一级方程式比赛中使用卡车。你不会用跑车搬家。 **不同的工具，不同的用例。** 使用 UBS 进行快速 AI 迭代，使用 ESLint 进行全面的质量执行。 ### **Q: “为什么不直接将这些模式贡献给现有的 linter？”** **A:** 三个原因： **1. 不同的设计哲学** - 现有 linter：全面、人类优先、单一语言 - UBS：快速、LLM 优先、多语言、基于关联 这些是根本不兼容的目标。ESLint 永远不会接受“10-20% 误报是可以的”或“完全跳过自动修复”。 **2. 多语言元运行器** - 自动检测 9 种语言的统一运行器是核心创新 - 这不适合任何单一 linter 的架构 - 每个 linter 项目都有不同的维护者、哲学、发布周期 **3. 关联分析是新颖的** - 深层属性防护匹配不是一条“lint 规则” - 它是需要不同架构的跨模式分析 - 现有 linter 没有将这种能力内置到其核心中 贡献模式忽略了重点——**集成本身就是创新。** ### **Q: “Semgrep 呢？它不是做多语言模式匹配吗？”** **A:** Semgrep 非常出色，比传统 linter 更接近 UBS。主要区别： | 功能 | Semgrep | UBS | |---------|---------|-----| | **设置** | 需要配置文件 + 规则选择 | 零配置 | | **速度** | 中型项目约 10-20 秒 | 约 3 秒（针对速度优化） | | **目标用户** | 安全团队，人类开发人员 | LLM 智能体 | | **规则重点** | 安全 + 自定义模式 | AI 生成的 Bug 模式 | | **多语言** | ✅ 是 | ✅ 是 | | **关联分析** | ❌ 仅模式匹配 | ✅ 深层防护，指标 | | **LLM 集成** | 不是为此设计的 | 专用构建 | **如果你需要以下情况，请使用 Semgrep：** 你需要自定义安全规则并且有时间配置它们。 **如果你想要以下情况，请使用 UBS：** 零设置的即时 AI 工作流集成。 **它们是互补的。** 一些用户两者都。 ### **Q: “基于正则表达式的检测不会有大量误报吗？”** **A:** 比你想象的要少，而且对于 LLM 消费者来说是可以接受的。 **现实检查：** - **第 1 层 (ripgrep/regex)**：某些模式约 15-20% 误报率 - **第 2 层 (ast-grep/AST)**：约 2-5% 误报率（语义理解） - **第 3 层 (关联)**：约 1-3% 误报率（上下文分析） **混合方法：** 约 8-12% 的总体误报率。 **为什么这样是可以的：** - LLM 不像人类那样沮丧 - 它们总共在 0.8 秒内评估发现 - 标记 100 个（20 个安全）比漏掉 1 个关键 Bug 更好 - 审查 AI 代码的人类无论如何都必须检查所有内容 **对于关键模式**（eval、XSS、硬编码密钥），我们使用 ast-grep（高精度）。 **对于样式模式**，我们使用 regex（快速，一些 FP 可接受）。 **而且我们一直在改进。** 每次发布都通过更好的启发式规则降低 FP 率。 ### **Q: “为什么是 Bash？为什么不是 Python/Rust/Go？”** **A:** 有争议的选择，但故意的： **Bash 的优点：** - ✅ **零依赖** - 在任何类 Unix 系统上运行 - ✅ **普遍可用** - 每个开发机器都有 Bash 4.0+ - ✅ **Shell 集成** - git 钩子、CI/CD、文件监视器是自然的 - ✅ **模块系统** - 每个语言扫描器都是独立的 - ✅ **快速原型设计** - 添加新模式很简单 - ✅ **LLM 可读** - AI 智能体可以理解和修改规则 **缺点：** - ❌ 不如 Python “优雅” - ❌ 字符串处理可能很冗长 - ❌ 没有静态类型 **底线：** 对于编排现有 CLI 工具（ripgrep、ast-grep、jq、typos）且需要普遍可用的工具来说，Bash 是务实的。 **未来：** 核心模块可能会用 Rust 重写以提高速度，但元运行器将保留 Bash 以保持兼容性。 ### **Q: “如果我不使用 AI 编程工具，我可以使用这个吗？”** **A:** 当然可以！它是为 AI 工作流优化的，但对人类也很有效。 **人类喜欢它的场景：** **1. 代码审查加速** ``` # 审查一个 800+ 行的 PR git checkout feature-branch ubs . # 在深度审查前即时查看严重问题 ``` **2. 遗留代码审计** ``` # “这个 10 年历史的 codebase 中有什么危险？” ubs /path/to/legacy-app # 找出所有的 eval(), XSS, 内存泄漏 ``` **3. 学习新语言** ``` # “我是 Rust 新手，我做错了什么？” ubs . --verbose # 显示你代码中常见的 Rust 陷阱 ``` **4. 多语言项目** ``` # 5 种语言的微服务 ubs . # 一次扫描，检查所有语言 ``` **人类欣赏：** - 零设置（无需维护配置文件） - 快速反馈（3s 对 30s） - 多语言支持（一个命令） - 发现 ESLint 遗漏的 Bug（深层防护） ### **Q: “这与 Snyk 或 GitHub Advanced Security 等安全扫描器有何不同？”** **A:** 不同的重点和范围： **安全扫描器（Snyk、Dependabot 等）：** - 重点：**依赖项漏洞** - 检查：npm 包、CVE 数据库 - 速度：几秒到几分钟 - 输出：“更新包 X 以修复 CVE-2024-1234” **UBS:** - 重点：**你的代码**中的 **代码级 Bug** - 检查：逻辑错误、null safety、内存泄漏、安全反模式 - 速度：3-5 秒 - 输出：“你在第 42 行有未受保护的 null 访问” **它们是互补的：** ``` ┌─────────────────────────────────────┐ │ Complete Security Stack │ ├─────────────────────────────────────┤ │ Snyk/Dependabot → Dependencies │ │ ✨ UBS → Your code bugs │ │ SAST tools → Deep security │ │ GitHub Advanced → Secrets in Git │ └─────────────────────────────────────┘ ``` **安全扫描器不会捕捉：** “你忘记了 `await`，你的 async 函数静默失败。” **UBS 不会捕捉：** “你的 lodash 版本有一个已知的 CVE。” 两者都用。 ### **Q: “将来你会支持语言 X 吗？”** **A:** 可能会！模块系统使添加语言变得容易。 **当前：** JavaScript/TypeScript, Python, Go, Rust, Java, C++, Ruby, Swift, C# (9 种语言) **路线图考虑：** - **PHP** - 高需求，大量遗留代码 - **Swift** - iOS 开发 - **Kotlin** - Android 开发 - **Scala** - JVM 生态系统 - **Elixir** - 采用率增长 **我们如何优先考虑：** 1. 社区需求（GitHub issues） 2. AI 编程工具使用情况（LLM 生成最多的内容） 3. 模块维护者可用性 **想贡献吗？** 编写新模块约需 800-1200 行 Bash。查看现有模块作为模板。 ### **Q: “有什么猫腻？为什么这是免费的？”** **A:** 没有猫腻。它是 MIT 许可的。 **哲学：** - 由开发人员构建，为开发人员服务 - AI 编程正在爆发，质量工具应该易于访问 - 开源启用社区贡献（更多模式，更好的检测） **商业模式：** 目前没有。这是一个 **社区项目**。 **未来可能性：** - 企业支持合同 - 面向团队的托管版本 - 面向特定框架的高级模块 但核心工具将永远免费和开源。 ## **底线** **这不是试图取代 ESLint。** 它正在解决一个不同的问题： 现有工具不这样做是因为： - 传统 linter 是人类优先的（需要自动修复，低 FP 容忍度） - 它们是单一语言聚焦的（多语言 = 7 个不同的工具） - 它们是全面的，而不是快速的（30s 扫描时间扼杀 AI 迭代循环） - 它们不是为 LLM 消耗设计的 **UBS 是专为 AI 编程时代构建的。** 与现有工具一起使用它。让 ESLint 处理样式。让 TypeScript 处理类型。让 UBS 捕捉 AI 智能体生成但看不到的关键 Bug。 ## 🧪 **开发与内部原理** ### **Python 工具 (uv + CPython 3.13)** 所有辅助脚本（manifest runner、fixtures、`ubs` 内的内联分析器）都假定一个单一的真理来源：**由 repo 根目录下 `.venv/` 中的 [uv](https://github.com/astral-sh/uv) 管理的 CPython 3.13**。 ``` # 1) 安装 uv（一次性） curl -LsSf https://astral.sh/uv/install.sh | sh # 2) 创建由 pyproject.toml / uv.lock 定义的托管环境 uv sync --python 3.13 # 3) 每当在此 repo 中工作时激活它（将 .venv/bin 放在 PATH 最前面） source .venv/bin/activate # 4) 通过该环境运行任何 Python 入口点 uv run python test-suite/run_manifest.py --case js-core-buggy # ...或者依赖 'python'/'python3'，现在它们指向 .venv/bin/python3.13 ``` 常见的 uv 驱动入口点： - `uv run python test-suite/run_manifest.py --case js-core-buggy` – 在 CI 或本地运行 manifest，无需手动激活 venv。 - `source .venv/bin/activate && python -m pip list` – 验证每个内联 `python3` 调用映射到 CPython 3.13。 - `uv run python - <<'PY' …` – 镜像语言模块嵌入 Python 辅助程序的方式，但现在保证在托管解释器内执行。 ## 🚫 **使用 `.ubsignore` 忽略路径** 需要代码库范围的扫描来忽略生成的代码或有意 buggy 的 fixtures（像这个项目的 `test-suite/`）？在根目录放置一个 `.ubsignore`。 - 格式镜像 `.gitignore`：每行一个 glob，`#` 用于注释。 - UBS 自动加载 `PROJECT/.ubsignore`；用 `--ignore-file=/path/to/file` 覆盖。 - 内置忽略已经覆盖 `node_modules`、virtualenvs、dist/build/target/vendor、编辑器缓存等，因此你很少需要自己添加它们。 - 使用 `--suggest-ignore` 打印可能需要一个条目的大型顶级目录（不会自动修改文件）。 - 内联抑制适用于有意的一次性操作：`eval("print('safe')") # ubs:ignore`。 - 每个语言模块通过其 `--exclude` 标志接收忽略列表，因此跳过保持一致。 - 此代码库附带默认的 `.ubsignore`，排除 `test-suite/`，保持“真实”源扫描无噪音。 示例： ``` # 忽略 fixtures + 构建输出 test-suite/ dist/ coverage/ ``` ## 🧭 **语言覆盖范围比较** UBS 附带九个专注于语言的分析器。下面的比较侧重于历史最悠久的模块；Swift 在相关处单独列出。下面的每个类别使用以下量表评分： - **0 – 未覆盖** - **1 – 仅简单启发式/regex** - **2 – 多信号/静态启发式（上下文感知传递）** - **3 – 深度分析（AST-grep 规则包，污点/数据流引擎，或工具链集成，如 `cargo clippy`）** | 问题类别 | JS / TS | Python | Go | C / C++ | Rust | Java | Ruby | C# | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Null / Nil Safety | **2** – DOM 防护 & 可选链启发式 (cat.1) | **2** – `None` 防护 + dataclass 回退 | **1** – 基本 nil/指针防护 | **2** – 原始指针/nullptr/RAII 检查 | **3** – 通过 clippy + 规则的借用/Option 误用 | **2** – Optional/null 相等性审计 | **1** – Nil 防护提醒 | **2** – Nullability pragma, `!` 运算符, 异常/null 启发式 | | Numeric & Type Coercion | **2** – NaN/松散相等/浮点相等 (cat.2/4) | **2** – 除以零 & 浮点精度 | **1** – 有限算术启发式 | **2** – UB 风险 & 收窄警告 | **2** – 浮点/溢出监视器 (cat.4) | **1** – 仅基本比较 | **1** – 简单算术陷阱 | **2** – FP 相等, 截断转换, 解析/验证启发式 | | Collections & Memory | **2** – 数组突变/泄漏检测器 | **2** – Dict/list 迭代陷阱 | **1** – Slice/map 启发式 | **3** – malloc/free, 迭代器失效, UB (cat.1/5/7) | **2** – Vec/String/迭代器审计 | **2** – 集合 & 泛型误用 | **1** – Enumerator/default 可变性提示 | **2** – LINQ `.First()` / `.Count()>0` / 分配异味 | | Async / Concurrency | **3** – AST-grep + 回退用于缺少 `await`, React hooks dep 分析器 | **2** – Async/Await 陷阱扫描 | **3** – Goroutine/channel/context/defer 卫生 | **2** – `std::thread` join + `std::async` wait 追踪 | **2** – Async 宏, Send/Sync 检查 | **2** – ExecutorService shutdown, `synchronized` 监视器 | **1** – 基本线程/promise 提示 | **2** – `Task.Wait`, `.Result`, `async void`, lock/await 危险 | | Error Handling & Logging | **2** – Promise rejection / try–catch 审计 | **2** – Exception swallow/logging 检查 | **2** – Error wrapping, panic 用法 | **2** – Throw-in-dtor, catch-by-value | **2** – Result/expect/panic 用法 | **2** – 日志最佳实践, try-with-resources | **1** – Rescue/raise 启发式 | **2** – `throw ex`, 空 catch, 宽泛 catch 模式 | | Security & Taint | **3** – 轻量级污点引擎 + 安全启发式 (cat.7) | **2** – Eval/exec/SQL 字符串启发式 | **2** – HTTP/crypto/command 检查 | **1** – 有限专用安全（主要是 UB） | **2** – 安全类别 (cat.8) | **3** – SQL concat, `Runtime.exec`, SSL/crypto 检查 | **2** – Rails mass-assignment, shell/eval 警告 | **2** – 弱加密, TLS 绕过, 硬编码密钥, ASP.NET web 危险 | | Resource Lifecycle & I/O | **3** – AST 事件监听器/定时器/观察者追踪 + 启发式 | **2** – Context-manager & 文件生命周期提示 | **2** – `defer`/文件关闭 + HTTP 资源卫生 | **2** – 线程 join/malloc/free & 资源关联 | **2** – Drop/RAII 启发式 + 关联 | **3** – Executor/文件流清理检测 | **2** – 文件打开/关闭 + 块用法提示 | **2** – HttpClient/IDisposable/timer/CTS 生命周期启发式 | | Build / Tooling Hygiene | **0** – 尚未覆盖 | **2** – `uv` extras, 打包, notebook 卫生 | **2** – Go 工具链健全性 (`go vet`, module drift) | **1** – CMake/CXX 标准提醒 |3** – `cargo fmt/clippy/test/check` 集成 | **2** – Maven/Gradle 尽力构建 | **2** – Bundler/Rake/AST 规则包 | **2** – 可选 `dotnet format/build/test/list package` 检查 | | Code Quality Markers | **1** – TODO/HACK 检测器 | **1** | **1** | **1** | **1** | **1** | **1** | **1** | | Domain-Specific Extras | **3** – React hooks, Node I/O, 污点流 | **2** – 类型严格性, notebook linting | **2** – Context 传播, HTTP server/client 审查 | **2** – 现代化, macro/STL 惯用语 | **3** – Unsafe/FFI 审计, cargo 清单 | **3** – SQL/Executor/注解/路径处理 | **2** – Rails 实践, bundle 卫生 | **2** – ASP.NET 中间件/CORS 危险, 解析和锁启发式 | 使用此矩阵决定你要优先考虑或扩展哪个语言模块的发现。例如，如果你需要更深入的 Go 资源生命周期审计，你可以扩展类别 5（defer/cleanup）或贡献新的 AST-grep 规则；对于 JavaScript 安全，你可以构建已经在类别 7 中运行的污点引擎。 ## 🛡️ **AI 编程智能体的安全防护** 当 AI 智能体高速修改代码时，单个破坏性命令可能会抹去数小时的工作。UBS 附带一个 **Git 安全防护**，在执行之前拦截危险操作，专为 Claude Code 设计，但适用于任何智能体工作流。 ### 它是如何工作的 防护位于 `.claude/hooks/git_safety_guard.py` 并挂钩到 Claude Code 的命令执行管道。在任何 shell 命令运行之前，防护解析它并阻止可能导致不可逆损害的模式： | 被阻止的命令 | 为什么危险 | 安全替代方案 | |-----------------|-------------------|------------------| | `git checkout -- ` | 永久丢弃未提交的更改 | 先 `git stash` | | `git reset --hard` | 销毁所有未提交的工作 | `git reset --soft` 或 `git stash` | | `git clean -f` | 永远删除未跟踪的文件 | 先 `git clean -n` (dry-run) | | `git push --force` | 重写共享历史 | `git push --force-with-lease` | | 非临时路径上的 `rm -rf` | 不可恢复地删除文件 | 需要显式临时路径 | | `git branch -D` | 删除未合并的分支 | `git branch -d` (安全删除) | | `git stash drop/clear` | 丢失 stash 的工作 | 先手动审查 | ### 智能临时路径检测 防护仅允许针对显式临时目录的 `rm -rf`： - `${TMPDIR}/...` (macOS/Linux temp) - `/tmp/...` 和 `/var/tmp/...` - 系统定义的临时位置 任何针对项目目录、主文件夹或模棱两可路径的 `rm -rf` 都会被阻止并附带清晰的解释。 ### 启用防护 安装程序在检测到 Claude Code（存在 `.claude/` 目录）时自动设置此功能。要手动启用： ``` # 安装程序创建此结构： .claude/ └── hooks/ ├── git_safety_guard.py # Command interceptor └── on-file-write.sh # Auto-scan on save ``` 防护产生可操作的错误消息，解释 *为什么* 命令被阻止以及 *该做什么* 代替，因此 AI 智能体可以在没有人工干预的情况下自我纠正。 ## 🔧 **扩展智能体检测** 除了核心智能体集成（Claude Code、Cursor、Codex），安装程序会自动检测并配置 **12+ 编程智能体**。当使用 `--easy-mode` 运行时，所有检测到的智能体都会在没有提示的情况下接收 UBS 防护栏。 ### 检测到的智能体 | 智能体 | 检测信号 | 集成类型 | |-------|------------------|------------------| | **Claude Code** | `.claude/` 目录 | Hooks + rules | | **Cursor** | `.cursor/` 目录 | Rules 文件 | | **Codex CLI** | `.codex/` 目录 | Rules 文件/目录 | | **Gemini Code Assist** | `.gemini/` 目录 | Rules 文件 | | **Windsurf** | `.windsurf/` 目录 | Rules 文件 | | **Cline** | `.cline/` 目录 | Rules 文件 | | **OpenCode** | `.opencode/` 目录 | Rules 文件 | | **Aider** | `.aider.conf.yml` | Lint 命令配置 | | **Continue** | `.continue/` 目录 | Rules 文件 | | **GitHub Copilot** | VS Code 扩展 | 工作区设置 | | **TabNine** | `.tabnine/` 目录 | 配置 | | **Replit** | `replit.com` 检测 | 环境设置 | ### Aider 特定集成 对于 Aider 用户，安装程序将自动 linting 添加到你的配置中： ``` # 已添加到 ~/.aider.conf.yml lint-cmd: "ubs --fail-on-warning ." auto-lint: true ``` 这使得每个 Aider 会话在完成任务之前自动运行 UBS。 ### 会话日志记录 安装程序将所有检测到的智能体和配置操作记录到 `$XDG_CONFIG_HOME/ubs/session.md`。使用以下命令查看配置了什么： ``` ubs sessions # Show last session ubs sessions --raw # Full log with timestamps ubs sessions --entries=5 # Last 5 sessions ``` ## 🔬 **基于 AST 的类型缩窄分析** 除了 regex 模式匹配，UBS 还包括 **深度基于 AST 的分析器**，用于特定语言的类型安全问题。这些辅助程序提供精确的行号映射，并理解 regex 无法捕获的语言语义。 ### 支持的语言 | 语言 | 辅助程序位置 | 分析重点 | |----------|-----------------|----------------| | TypeScript/JavaScript | `modules/helpers/type_narrowing_ts.js` | Null guards, optional chaining, type predicates | | C# | `modules/helpers/type_narrowing_csharp.py` | Null guards, `TryGetValue` fallthrough, failed narrowing 后的解引用 | | Rust | `modules/helpers/type_narrowing_rust.py - **开源社区** - JavaScript、Python、Rust、Go、Java、C++ 和 Ruby 社区，感谢其在数十年间记录了成千上万的 Bug 模式和反模式 - **AI 编码工具** - Claude、GPT-5、Cursor、Copilot，感谢其激发了这个工具的灵感并加速了开发 ## 📞 **支持** ### **问题与疑问** - 🐛 [报告 Bug](https://github.com/Dicklesworthstone/ultimate_bug_scanner/issues) - 💡 [请求功能](https://github.com/Dicklesworthstone/ultimate_bug_scanner/issues) - 📖 [文档](https://github.com/Dicklesworthstone/ultimate_bug_scanner) ## 💎 **总结** **每花一小时调试生产环境 Bug，就意味着少花一小时构建功能。** The Ultimate Bug Scanner 为您提供： - ✅ **信心**：代码不会在生产环境中失败 - ✅ **速度**（几秒钟内捕获 Bug，而非几小时） - ✅ **质量关卡**：针对 AI 生成的代码 - ✅ **安心**：部署时无后顾之忧 ### **一条命令。三秒钟。零生产 Bug。** ``` curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash ``` **然后再也不必浪费晚上的时间去调试空指针异常了。**

### 准备好停止调试，开始交付了吗？ [](https://github.com/Dicklesworthstone/ultimate_bug_scanner#-quick-install-30-seconds) [](https://github.com/Dicklesworthstone/ultimate_bug_scanner) [](https://github.com/Dicklesworthstone/ultimate_bug_scanner/wiki) 如果这个项目帮您避免了一次生产环境 Bug，请给这个仓库 **点个 Star** ⭐

## ✉️ **与 MCP Agent Mail 配合极佳** [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) 是一个基于 Git 的邮箱系统，让您的编码 Agent 能够协调工作、移交任务，并保留每次变更讨论的持久历史记录。 - **UBS + MCP Agent Mail 结合使用**：在您的 MCP Agent Mail 工作流中，将 `ubs --fail-on-warning .` 作为标准护栏步骤运行，这样任何提议代码更改的 Agent 都必须在其回复中附上一份干净的扫描报告（或剩余问题的摘要）。 - **理想模式**：一个 Agent 编写或重构代码，通过 MCP Agent Mail 触发的“QA Agent”针对受影响的路径运行 UBS，然后将简明的发现报告发布回同一个线程中，供人类或其他 Agent 采取行动。 - **结果**：您的多 Agent 自动化系统将所有通信历史保留在 MCP Agent Mail 中，同时 UBS 持续对每次变更执行快速、语言无关的质量检查。 ## 🤝 **关于贡献**

标签：AI编程助手, Bug检测, DevSecOps, Linter, LNA, pptx, Python, SAST, 上游代理, 代码卫士, 代码安全, 多语言支持, 威胁情报, 安全测试框架, 应用安全, 开发者工具, 无后门, 漏洞枚举, 盲注攻击, 自动化审查, 质量门禁, 软件开发, 错误基检测, 错误模式识别, 静态代码分析