BBOT TUI Viewer

A self-contained terminal UI for browsing and analyzing BBOT scan results.

Features

• 🚀 Zero Setup - Single self-installing file, no manual dependencies
• 🔴 Live Refresh - Auto-updates while scans are running with accurate status detection
• 🎯 Smart Status Detection - Accurately identifies RUNNING, FINISHED, and INTERRUPTED scans
• 📋 Scan Browser - Navigate multiple scans with separate vulnerability/finding counts and status indicators
• 📦 Archive Management - Compress old scans to save space, restore when needed
• 📝 Work Tracking - Annotate vulnerabilities and findings with status, priority, and notes
• 🔍 Separate Views - Dedicated tabs for vulnerabilities (sorted by severity) and findings
• 🌳 Discovery Tree - Hierarchical view showing parent-child event relationships
• 🌐 Subdomain Tree - Hierarchical view of discovered subdomains (when available)
• 📊 Rich Statistics - Beautiful tables with event distribution, scope analysis, and workflow metrics
• 🔎 Event Explorer - Filter, search, and inspect all scan events
• ⚙️ Config Viewer - View preset.yml configuration

Quick Start

# Copy to server and run (auto-installs on first run)
./bbot-ui

# Or specify custom path
./bbot-ui /path/to/scans

First run creates .bbot_ui_venv/ and installs dependencies. Subsequent runs launch instantly.

Usage

./bbot-ui                          # Default: ~/.bbot/scans
./bbot-ui /path/to/scans          # Browse all scans in directory
./bbot-ui ~/.bbot/scans/scan-name # View specific scan

Command-Line Options

./bbot-ui --help                               # Show all options
./bbot-ui --scan-interval 5                    # Refresh scan view every 5 seconds
./bbot-ui --list-interval 10                   # Refresh scan list every 10 seconds

Available options:

• --scan-interval SECONDS - Refresh interval for scan detail view (default: 2.0)
• --list-interval SECONDS - Refresh interval for scan list view (default: 3.0)

Settings are automatically saved to ~/.bbot_ui_config.json and used as defaults for future sessions.

Interface

Scan List

• Instant startup - UI appears in <200ms, scans load progressively
• Browse all scans in a table with columns: Scan Name, Status, Events, Vulns, Findings, Last Modified
• Header shows total scans, vulnerability/finding counts, and running scan count
• Status column shows real-time scan state:
  • ● RUNNING (green) - Scan actively running with bbot process detected
  • ⚠ INTERRUPTED (yellow) - Scan was stopped/interrupted (no active process)
  • ✓ FINISHED (blue) - Scan completed successfully
  • ○ CHECKING... (dim) - Status being verified (appears during progressive load)
• Vulns and Findings columns show ⚠ indicator for scans with vulnerabilities/findings
• Scans appear one-by-one with live status updates during initial load
• Auto-refreshes every 3 seconds to show new scans and status changes
• ↑/↓ or j/k to navigate, Enter to open, r to refresh manually, a to archive, d to delete
• Press Tab to view archived scans

Archive List

• Browse all archived scans (compressed .zip files)
• Shows: Archive Name, Size, Events, Vulns, Findings, Date Archived
• u to unarchive (restore), d to delete permanently
• Press Tab, q, or Escape to return to scan list

Archive Management

Save disk space by compressing old scans into ZIP archives:

Archiving a scan:

1. From the scan list, navigate to the scan you want to archive
2. Press a to archive
3. Confirm the operation
4. The scan folder is compressed to a .zip file and the original folder is deleted
5. Archive appears in the archive list (press Tab to view)

Restoring an archive:

1. Press Tab to view the archive list
2. Navigate to the archive you want to restore
3. Press u to unarchive
4. Confirm the operation
5. The archive is extracted and the .zip file is deleted
6. Press q to return to scan list and see the restored scan

Safety features:

• Cannot archive RUNNING scans
• Archive integrity is verified before deleting source folder
• Extraction is verified before deleting archive
• All operations require confirmation
• If any step fails, the operation is rolled back safely

Deleting scans/archives:

• From scan list: Press d to permanently delete a scan folder
• From archive list: Press d to permanently delete an archive file
• Cannot delete RUNNING scans
• Requires confirmation (action is permanent and cannot be undone)
• All scan data will be lost

Work Tracking & Annotations

Track your security workflow by annotating vulnerabilities and findings with status, priority, and notes.

How it works:

• Annotations are stored in .bbot_ui_annotations.json alongside each scan
• References events by UUID - never modifies BBOT's original output.json
• Included automatically in archives for backup/restore
• Survives re-scans of the same target

Annotating a vulnerability/finding:

1. Navigate to the Vulnerabilities or Findings tab
2. Select an item (arrow keys or j/k)
3. Press t to open annotation dialog
4. Set status, priority (optional), and notes
5. Click Save or press Enter

Quick shortcuts:

• Press x to mark selected item as False Positive
• Press i to mark selected item as Accepted Risk
• These preserve existing priority and notes while updating status

Status options:

• 🆕 New - Default status for unannotated items
• 🔍 Investigating - Currently analyzing
• ✓ Confirmed - Verified as real issue
• ✗ False Positive - Not a real vulnerability
• 📢 Reported - Submitted to security team
• 🔧 Fixed - Issue has been resolved
• ⚠ Accepted Risk - Known but accepted

Priority levels (optional):

• 🔴 Critical - Requires immediate attention
• 🟠 High - Important, address soon
• 🟡 Medium - Normal priority
• 🟢 Low - Minor issue

Features:

• Status and Priority columns in Vulnerabilities/Findings tables
• Status filter dropdown - filter by specific status or "Actionable" items (default)
• Quick keyboard shortcuts (x/i) for rapid triage
• Workflow status charts in Statistics tab
• Notes field for detailed context
• Clear annotation button to reset
• Annotations persist across sessions and archives

Status Filtering:

• Actionable (default) - Shows only items needing attention (new, investigating, confirmed, reported)
• All - Shows all vulnerabilities/findings regardless of status
• Specific statuses - Filter by individual status (false-positive, fixed, etc.)
• Filter automatically updates when marking items with keyboard shortcuts

Scan Viewer Tabs