aiskillstore 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
awaitcauses silent failures - XSS vulnerabilities reach production
- Memory leaks accumulate
UBS is the quality gate: scan before commit, fix before merge.
Golden Rule
ubs <changed-files> --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) vsubs .(30s) - Use --staged or --diff: Only scan what you're committing
- Language filter:
--only=js,pythonskips irrelevant scanners - Skip categories:
--skip=11,14to 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 <file> → 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 <file> not ubs . |