ubs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UBS - Ultimate Bug Scanner

UBS - 终极漏洞扫描器

Static analysis tool built for AI coding workflows. Catches bugs that AI agents commonly introduce: null safety, async/await issues, security holes, memory leaks. Scans JS/TS, Python, Go, Rust, Java, C++, Ruby, Swift in 3-5 seconds.

专为AI编码工作流打造的静态分析工具。能够捕捉AI Agent常引入的漏洞：空值安全问题、async/await错误、安全漏洞、内存泄漏。可在3-5秒内扫描JS/TS、Python、Go、Rust、Java、C++、Ruby、Swift代码。

Why This Exists

开发背景

AI agents move fast. Bugs move faster. You're shipping features in minutes, but:

Null pointer crashes slip through
Missing
```
await
```
causes silent failures
XSS vulnerabilities reach production
Memory leaks accumulate

UBS is the quality gate: scan before commit, fix before merge.

AI Agent的开发速度很快，但漏洞产生的速度更快。你能在几分钟内完成功能开发，但：

空指针崩溃问题悄悄溜过检测
缺失
```
await
```
导致静默故障
XSS漏洞进入生产环境
内存泄漏不断累积

UBS就是你的质量把关人：提交前扫描，合并前修复。

Golden Rule

核心准则

bash

ubs <changed-files> --fail-on-warning

Exit 0 = safe to commit. Exit 1 = fix and re-run.

bash

ubs <changed-files> --fail-on-warning

退出码0 = 可安全提交。退出码1 = 需要修复后重新运行。

Essential Commands

常用命令

Quick Scans (Use These)

快速扫描（推荐使用）

bash

ubs file.ts file2.py                    # Specific files (< 1s)
ubs $(git diff --name-only --cached)    # Staged files
ubs --staged                            # Same, cleaner syntax
ubs --diff                              # Working tree vs HEAD

bash

ubs file.ts file2.py                    # 指定文件（耗时<1秒）
ubs $(git diff --name-only --cached)    # 已暂存文件
ubs --staged                            # 更简洁的同功能命令
ubs --diff                              # 工作区与HEAD版本对比

Full Project Scans

全项目扫描

bash

ubs .                                   # Current directory
ubs /path/to/project                    # Specific path
ubs --only=js,python src/               # Language filter (faster)

bash

ubs .                                   # 当前目录
ubs /path/to/project                    # 指定路径
ubs --only=js,python src/               # 按语言过滤（扫描更快）

CI/CD Mode

CI/CD模式

bash

ubs --ci --fail-on-warning .            # Strict mode for CI
ubs --format=json .                     # Machine-readable
ubs --format=sarif .                    # GitHub code scanning

bash

ubs --ci --fail-on-warning .            # CI环境严格模式
ubs --format=json .                     # 机器可读格式
ubs --format=sarif .                    # GitHub代码扫描兼容格式

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

⚠️  类别（N个错误）
    file.ts:42:5 – 问题描述
    💡 修复建议
Exit code: 1

解析规则：

file:line:col

→ 问题位置 |

💡

→ 修复方法 | 退出码0/1 → 合格/不合格

The 18 Detection Categories

18种检测类别

Critical (Always Fix)

严重级别（必须修复）

Category	What It Catches
Null Safety	Unguarded property access, missing null checks
Security	XSS, injection, prototype pollution, hardcoded secrets
Async/Await	Missing await, unhandled rejections, race conditions
Memory Leaks	Event listeners without cleanup, timer leaks
Type Coercion	`==` vs `===` , `parseInt` without radix, NaN comparison

类别	检测内容
空值安全	未受保护的属性访问、缺失空值检查
安全漏洞	XSS、注入攻击、原型污染、硬编码密钥
Async/Await问题	缺失await、未处理的拒绝、竞态条件
内存泄漏	未清理的事件监听器、定时器泄漏
类型转换	`==` 与 `===` 混用、无基数的 `parseInt` 、NaN比较

Important (Production Risk)

重要级别（生产环境风险）

Category	What It Catches
Division Safety	Division without zero check
Resource Lifecycle	Unclosed files, connections, context managers
Error Handling	Empty catch blocks, swallowed errors
Promise Chains	`.then()` without `.catch()`
Array Mutations	Mutating during iteration

类别	检测内容
除法安全	未做零值检查的除法操作
资源生命周期	未关闭的文件、连接、上下文管理器
错误处理	空catch块、被吞掉的错误
Promise链	`.then()` 未搭配 `.catch()`
数组突变	迭代过程中修改数组

Code Quality (Contextual)

代码质量（视场景判断）

Category	What It Catches
Debug Code	`console.log` , `debugger` , `print()` statements
TODO Markers	`TODO` , `FIXME` , `HACK` comments
Type Safety	TypeScript `any` usage
Readability	Complex ternaries, deep nesting

类别	检测内容
调试代码	`console.log` 、 `debugger` 、 `print()` 语句
待办标记	`TODO` 、 `FIXME` 、 `HACK` 注释
类型安全	TypeScript中 `any` 类型的使用
可读性	复杂三元表达式、深层嵌套

Language-Specific Detection

语言专属检测

Language	Key Patterns
JavaScript/TypeScript	innerHTML XSS, eval(), missing await, React hooks deps
Python	eval(), open() without with, missing encoding=, None checks
Go	Nil pointer, goroutine leaks, defer symmetry, context cancel
Rust	`.unwrap()` panics, `unsafe` blocks, Option handling
Java	Resource leaks (try-with-resources), null checks, JDBC
C/C++	Buffer overflows, strcpy(), memory leaks, use-after-free
Ruby	eval(), send(), instance_variable_set
Swift	Force unwrap (!), ObjC bridging issues

语言	核心检测模式
JavaScript/TypeScript	innerHTML XSS、eval()、缺失await、React hooks依赖问题
Python	eval()、未使用with的open()、缺失encoding=、None值检查
Go	Nil指针、goroutine泄漏、defer对称性、context取消
Rust	`.unwrap()` panic、 `unsafe` 块、Option处理
Java	资源泄漏（try-with-resources）、空值检查、JDBC问题
C/C++	缓冲区溢出、strcpy()、内存泄漏、释放后使用
Ruby	eval()、send()、instance_variable_set
Swift	强制解包(!)、ObjC桥接问题

Profiles

扫描配置文件

bash

ubs --profile=strict .    # Fail on warnings, enforce high standards
ubs --profile=loose .     # Skip TODO/debug nits when prototyping

bash

ubs --profile=strict .    # 严格模式：遇到警告即失败，执行高标准检查
ubs --profile=loose .     # 宽松模式：原型开发时跳过TODO/调试代码检查

Category Packs (Focused Scans)

类别包（聚焦扫描）

bash

ubs --category=resource-lifecycle .    # Python/Go/Java resource hygiene

Narrows scan to relevant languages and suppresses unrelated categories.

bash

ubs --category=resource-lifecycle .    # 仅扫描Python/Go/Java的资源生命周期问题

自动缩小扫描范围至相关语言，屏蔽无关类别。

Comparison Mode (Regression Detection)

对比模式（回归检测）

bash

undefined

bash

undefined

Capture baseline

生成基准报告

ubs --ci --report-json .ubs/baseline.json .

Compare against baseline

与基准报告对比

ubs --ci --comparison .ubs/baseline.json --report-json .ubs/latest.json .


Useful for CI to detect regressions vs. main branch.

ubs --ci --comparison .ubs/baseline.json --report-json .ubs/latest.json .


适用于CI环境，检测与主分支相比的代码回归问题。

Output Formats

输出格式

Format	Flag	Use Case
text	(default)	Human-readable terminal output
json	`--format=json`	Machine parsing, scripting
jsonl	`--format=jsonl`	Line-delimited, streaming
sarif	`--format=sarif`	GitHub code scanning
html	`--html-report=file.html`	PR attachments, dashboards

格式	参数	使用场景
文本	默认	终端可读的人类友好输出
JSON	`--format=json`	机器解析、脚本处理
JSONL	`--format=jsonl`	行分隔格式、流式处理
SARIF	`--format=sarif`	GitHub代码扫描兼容
HTML	`--html-report=file.html`	PR附件、数据面板

Inline Suppression

行内忽略

When a finding is intentional:

javascript

eval(trustedCode);  // ubs:ignore

// ubs:ignore-next-line
dangerousOperation();

当检测结果为预期情况时：

javascript

eval(trustedCode);  // ubs:ignore

// ubs:ignore-next-line
dangerousOperation();

Exit Codes

退出码说明

Code	Meaning
`0`	No critical issues (safe to commit)
`1`	Critical issues or warnings (with `--fail-on-warning` )
`2`	Environment error (missing ast-grep, etc.)

代码	含义
`0`	无严重问题（可安全提交）
`1`	存在严重问题或警告（搭配 `--fail-on-warning` 参数时）
`2`	环境错误（缺失ast-grep等依赖）

Doctor Command

诊断命令

bash

ubs doctor                # Check environment
ubs doctor --fix          # Auto-fix missing dependencies

Checks: curl/wget, ast-grep, ripgrep, jq, typos, Node.js + TypeScript.

bash

ubs doctor                # 检查环境依赖
ubs doctor --fix          # 自动修复缺失的依赖

检查内容：curl/wget、ast-grep、ripgrep、jq、typos、Node.js + TypeScript。

Agent Integration

Agent集成

UBS auto-configures hooks for coding agents during install:

Agent	Hook Location
Claude Code	`.claude/hooks/on-file-write.sh`
Cursor	`.cursor/rules`
Codex CLI	`.codex/rules/ubs.md`
Gemini	`.gemini/rules`
Windsurf	`.windsurf/rules`
Cline	`.cline/rules`

UBS在安装时会自动为编码Agent配置钩子：

Agent	钩子位置
Claude Code	`.claude/hooks/on-file-write.sh`
Cursor	`.cursor/rules`
Codex CLI	`.codex/rules/ubs.md`
Gemini	`.gemini/rules`
Windsurf	`.windsurf/rules`
Cline	`.cline/rules`

Claude Code Hook Pattern

Claude Code 钩子示例

bash

#!/bin/bash

bash

#!/bin/bash

.claude/hooks/on-file-write.sh

if [[ "$FILE_PATH" =~ .(js|jsx|ts|tsx|py|go|rs|java|rb)$ ]]; 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

undefined

if [[ "$FILE_PATH" =~ .(js|jsx|ts|tsx|py|go|rs|java|rb)$ ]]; then echo "🔬 正在执行质量检查..." if ubs "${PROJECT_DIR}" --ci 2>&1 | head -30; then echo "✅ 未发现严重问题" else echo "⚠️ 检测到问题 - 请查看上方内容" fi fi

undefined

Git Pre-Commit Hook

Git 提交前钩子

bash

#!/bin/bash

bash

#!/bin/bash

.git/hooks/pre-commit

echo "🔬 Running bug scanner..." if ! ubs . --fail-on-warning 2>&1 | tail -30; then echo "❌ Critical issues found. Fix or: git commit --no-verify" exit 1 fi echo "✅ Quality check passed"

undefined

echo "🔬 正在运行漏洞扫描..." if ! ubs . --fail-on-warning 2>&1 | tail -30; then echo "❌ 发现严重问题。修复后重新提交，或执行：git commit --no-verify" exit 1 fi echo "✅ 质量检查通过"

undefined

Performance

性能表现

Small (5K lines):     0.8 seconds
Medium (50K lines):   3.2 seconds
Large (200K lines):   12 seconds
Huge (1M lines):      58 seconds

10,000+ lines per second. Use

--jobs=N

to control parallelism.

小型项目（5千行代码）：     0.8秒
中型项目（5万行代码）：   3.2秒
大型项目（20万行代码）：   12秒
超大型项目（100万行代码）：      58秒

每秒可扫描1万行以上代码。使用

--jobs=N

参数控制并行扫描数量。

Speed Tips

提速技巧

Scope to changed files:
```
ubs src/file.ts
```
(< 1s) vs
```
ubs .
```
(30s)
Use --staged or --diff: Only scan what you're committing
Language filter:
```
--only=js,python
```
skips irrelevant scanners
Skip categories:
```
--skip=11,14
```
to skip debug/TODO markers

聚焦修改文件：
```
ubs src/file.ts
```
（耗时<1秒） vs
```
ubs .
```
（耗时30秒）
使用--staged或--diff：仅扫描待提交的内容
按语言过滤：
```
--only=js,python
```
跳过无关语言的扫描器
跳过指定类别：
```
--skip=11,14
```
跳过待办/调试代码的检查

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 <file> → exit 0
6. Commit

1. 查看检测结果 → 类别 + 修复建议
2. 定位到file:line:col → 查看上下文
3. 确认是否为真实问题（而非误报）
4. 修复问题根源（而非表面症状）
5. 重新运行ubs <file> → 退出码为0
6. 提交代码

Bug Severity Guide

漏洞严重程度指南

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

严重级别（必须修复）：空值安全、XSS/注入攻击、async/await问题、内存泄漏
重要级别（生产环境风险）：类型收窄、除零错误、资源泄漏
场景级别（自主判断）：TODO/FIXME标记、控制台日志

Common Anti-Patterns

常见反模式

Don't	Do
Ignore findings	Investigate each
Full scan per edit	Scope to changed files
Fix symptom ( `if (x) { x.y }` )	Fix root cause ( `x?.y` )
Suppress without understanding	Verify false positive first

错误做法	正确做法
忽略检测结果	逐一排查每个问题
每次编辑都全量扫描	仅扫描修改的文件
修复表面症状（ `if (x) { x.y }` ）	修复问题根源（ `x?.y` ）
未理解原因就忽略检测	先确认是否为误报

Installation

安装方法

bash

undefined

bash

undefined

One-liner (recommended)

一键安装（推荐）

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash -s -- --easy-mode

Manual

手动安装

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/ubs
-o /usr/local/bin/ubs && chmod +x /usr/local/bin/ubs

undefined

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/ubs
-o /usr/local/bin/ubs && chmod +x /usr/local/bin/ubs

undefined

Custom AST Rules

自定义AST规则

bash

mkdir -p ~/.config/ubs/rules

cat > ~/.config/ubs/rules/no-console.yml <<'EOF'
id: custom.no-console
language: javascript
rule:
  pattern: console.log($$$)
severity: warning
message: "Remove console.log before production"
EOF

ubs . --rules=~/.config/ubs/rules

bash

mkdir -p ~/.config/ubs/rules

cat > ~/.config/ubs/rules/no-console.yml <<'EOF'
id: custom.no-console
language: javascript
rule:
  pattern: console.log($$$)
severity: warning
message: "Remove console.log before production"
EOF

ubs . --rules=~/.config/ubs/rules

Excluding Paths

排除路径

bash

ubs . --exclude=legacy,generated,vendor

Auto-ignored:

node_modules

.venv

dist

build

target

, editor caches.

bash

ubs . --exclude=legacy,generated,vendor

自动忽略路径：

node_modules

.venv

dist

build

target

, 编辑器缓存目录。

Session Logs

会话日志

bash

ubs sessions --entries 1    # View latest install session

bash

ubs sessions --entries 1    # 查看最近一次安装会话日志

Integration with Flywheel

与Flywheel集成

Tool	Integration
BV	`--beads-jsonl=out.jsonl` exports findings for Beads
CASS	Search past sessions for similar bug patterns
CM	Extract rules from UBS findings
Agent Mail	Notify agents of scan results
DCG	UBS runs inside DCG protection

工具	集成方式
BV	`--beads-jsonl=out.jsonl` 导出检测结果给Beads
CASS	搜索历史会话中的相似漏洞模式
CM	从UBS检测结果中提取规则
Agent Mail	向Agent发送扫描结果通知
DCG	在DCG保护环境内运行UBS

Troubleshooting

故障排查

Error	Fix
"Environment error" (exit 2)	`ubs doctor --fix`
"ast-grep not found"	`brew install ast-grep` or `cargo install ast-grep`
Too many false positives	Use `--skip=N` or `// ubs:ignore`
Slow scans	Scope to files: `ubs <file>` not `ubs .`

错误信息	修复方法
"Environment error"（退出码2）	执行 `ubs doctor --fix`
"ast-grep not found"	执行 `brew install ast-grep` 或 `cargo install ast-grep`
误报过多	使用 `--skip=N` 或 `// ubs:ignore` 忽略指定内容
扫描速度慢	聚焦到具体文件： `ubs <file>` 而非 `ubs .`

undefined