UBS - Ultimate Bug Scanner

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.

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.

Golden Rule ubs --fail-on-warning

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

Essential Commands Quick Scans (Use These) 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

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

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

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

The 18 Detection Categories 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 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 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 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 Profiles ubs --profile=strict . # Fail on warnings, enforce high standards ubs --profile=loose . # Skip TODO/debug nits when prototyping

Category Packs (Focused Scans) ubs --category=resource-lifecycle . # Python/Go/Java resource hygiene

Narrows scan to relevant languages and suppresses unrelated categories.

Comparison Mode (Regression Detection)

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.

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 Inline Suppression

When a finding is intentional:

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.) Doctor Command ubs doctor # Check environment ubs doctor --fix # Auto-fix missing dependencies

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

Agent Integration

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 Claude Code Hook Pattern

!/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

Git Pre-Commit Hook

!/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"

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.

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 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

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 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 Installation

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

Custom AST Rules 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 ubs . --exclude=legacy,generated,vendor

Auto-ignored: node_modules, .venv, dist, build, target, editor caches.

Session Logs ubs sessions --entries 1 # View latest install session

Integration with 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 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 not ubs .