ubs

UBS - Ultimate Bug Scanner

Fast static analysis that catches real bugs across multiple languages in seconds.

Prerequisites

Install UBS:

curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/main/install.sh | bash

Dependencies (auto-detected):

• rg (ripgrep) - Pattern matching
• ast-grep - AST analysis
• jq - JSON processing

CLI Reference

Basic Scanning

# Scan specific files (fastest, <1s)
ubs file.ts file2.py

# Scan directory
ubs src/

# Scan current directory
ubs .

# Scan staged files (pre-commit)
ubs --staged

# Scan modified files (working tree vs HEAD)
ubs --diff

Output Formats

# Text (default)
ubs src/

# JSON
ubs src/ --format=json

# JSONL (streaming)
ubs src/ --format=jsonl

# SARIF (for CI integration)
ubs src/ --format=sarif

Strictness Modes

# Strict - fail on warnings
ubs src/ --fail-on-warning
ubs src/ --ci --fail-on-warning

# CI mode
ubs src/ --ci

# Quiet (summary only)
ubs src/ -q

Language Filtering

# Only specific languages (3-5x faster)
ubs src/ --only=js,python
ubs src/ --only=typescript,rust
ubs src/ --only=go,java

Category Filtering

# Focus on specific category packs
ubs src/ --category=resource-lifecycle

Verbose Mode

# Show more code examples per finding
ubs src/ --verbose

Baseline Comparison

# Save baseline
ubs src/ --format=json > baseline.json

# Compare against baseline (detect regressions)
ubs src/ --comparison=baseline.json

# Generate reports
ubs src/ --comparison=baseline.json --report-json=report.json --html-report=report.html

Doctor/Health Check

# Check installation and dependencies
ubs doctor

View Session Logs

# Tail latest session log
ubs sessions --entries 1

Output Format

Warning/Error: Category (N errors)
    file.ts:42:5 - Issue description
    Suggested fix
Exit code: 1

Parse format:

• file:line:col - Location
• Suggested fix - How to fix
• Exit 0/1 - Pass/fail

Bug Categories Detected

Critical (Always Fix)

• Null/undefined safety issues
• XSS and injection vulnerabilities
• async/await problems
• Memory leaks
• Use-after-free

Important (Production)

• Type narrowing issues
• Division by zero risks
• Resource leaks (unclosed handles)
• Race conditions

Contextual (Use Judgment)

• TODO/FIXME comments
• Console.log statements
• Dead code

Workflow Patterns

Pre-Commit Hook

# In .git/hooks/pre-commit
#!/bin/bash
ubs --staged --fail-on-warning || exit 1

CI Pipeline

# Strict mode for CI
ubs . --ci --fail-on-warning

Quick Check During Development

# Scan just the file you're working on
ubs src/component.tsx

# Scan modified files
ubs --diff

Fixing Findings

1. Read the finding (category + description)
2. Navigate to file:line:col
3. View context
4. Verify it's a real issue (not false positive)
5. Fix the root cause, not symptom
6. Re-run ubs <file> to verify
7. Exit code 0 = fixed

Speed Tips

• Scope to changed files - ubs src/file.ts (<1s) vs ubs . (30s)
• Use language filter - --only=js,python for 3-5x speedup
• Never full scan for small edits - Always scope to modified files

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)
Add suppression comments	Fix the actual issue

Best Practices

1. Run before every commit - ubs --staged
2. Exit 0 = safe to commit - Exit >0 = fix and re-run
3. Trust the suggestions - They point to real issues
4. Fix root cause - Don't just silence the warning
5. Use in CI - Catch regressions before merge