Visualizzatore TUI per BBOT

Un'interfaccia terminale autonoma per sfogliare e analizzare i risultati delle scansioni BBOT.

Caratteristiche

• 🚀 Zero configurazione - Singolo file autoinstallante, nessuna dipendenza manuale
• 🔴 Aggiornamento live - Si aggiorna automaticamente mentre le scansioni sono in esecuzione con rilevamento accurato dello stato
• 🎯 Rilevamento intelligente dello stato - Identifica con precisione le scansioni RUNNING, FINISHED e INTERRUPTED
• 📋 Browser delle scansioni - Naviga tra più scansioni con conteggi separati di vulnerabilità/riscontri e indicatori di stato
• 📦 Gestione archivi - Comprimi le vecchie scansioni per risparmiare spazio, ripristinale quando serve
• 📝 Tracciamento del lavoro - Annota vulnerabilità e riscontri con stato, priorità e note
• 🔍 Viste separate - Schede dedicate per vulnerabilità (ordinate per gravità) e riscontri
• 🌳 Albero delle scoperte - Vista gerarchica che mostra le relazioni genitore-figlio tra gli eventi
• 🌐 Albero dei sottodomini - Vista gerarchica dei sottodomini scoperti (quando disponibili)
• 📊 Statistiche complete - Tabelle eleganti con distribuzione degli eventi, analisi dello scope e metriche del workflow
• 🔎 Esploratore eventi - Filtra, cerca e ispeziona tutti gli eventi della scansione
• ⚙️ Visualizzatore configurazione - Visualizza la configurazione preset.yml

Avvio rapido

# Copia sul server ed esegui (si autoinstalla al primo avvio)
./bbot-ui

# Oppure specifica un percorso personalizzato
./bbot-ui /path/to/scans

Al primo avvio viene creata la cartella .bbot_ui_venv/ e installate le dipendenze. I successivi avvii partono istantaneamente.

Utilizzo

./bbot-ui                          # Predefinito: ~/.bbot/scans
./bbot-ui /path/to/scans          # Sfoglia tutte le scansioni nella directory
./bbot-ui ~/.bbot/scans/scan-name # Visualizza una scansione specifica

Opzioni da riga di comando

./bbot-ui --help                               # Mostra tutte le opzioni
./bbot-ui --scan-interval 5                    # Aggiorna la vista della scansione ogni 5 secondi
./bbot-ui --list-interval 10                   # Aggiorna l'elenco delle scansioni ogni 10 secondi

Opzioni disponibili:

• --scan-interval SECONDS - Intervallo di aggiornamento per la vista dettaglio della scansione (predefinito: 2.0)
• --list-interval SECONDS - Intervallo di aggiornamento per la vista elenco scansioni (predefinito: 3.0)

Le impostazioni vengono salvate automaticamente in ~/.bbot_ui_config.json e usate come predefinite per le sessioni future.

Interfaccia

Elenco scansioni

• Avvio istantaneo - L'interfaccia appare in <200ms, le scansioni vengono caricate progressivamente
• Sfoglia tutte le scansioni in una tabella con le colonne: Nome scansione, Stato, Eventi, Vuln, Riscontri, Ultima modifica
• L'intestazione mostra il totale delle scansioni, i conteggi di vulnerabilità/riscontri e il numero di scansioni in esecuzione
• La colonna Stato mostra lo stato della scansione in tempo reale:
  • ● RUNNING (verde) - Scansione attivamente in esecuzione con processo bbot rilevato
  • ⚠ INTERRUPTED (giallo) - Scansione interrotta/fermata (nessun processo attivo)
  • ✓ FINISHED (blu) - Scansione completata con successo
  • ○ CHECKING... (attenuato) - Stato in fase di verifica (appare durante il caricamento progressivo)
• Le colonne Vuln e Riscontri mostrano l'indicatore ⚠ per le scansioni con vulnerabilità/riscontri
• Le scansioni appaiono una ad una con aggiornamenti di stato in tempo reale durante il caricamento iniziale
• Si aggiorna automaticamente ogni 3 secondi per mostrare nuove scansioni e cambi di stato
• ↑/↓ o j/k per navigare, Enter per aprire, r per aggiornare manualmente, a per archiviare, d per eliminare
• Premi Tab per vedere le scansioni archiviate

Elenco archivi

• Sfoglia tutte le scansioni archiviate (file .zip compressi)
• Mostra: Nome archivio, Dimensione, Eventi, Vuln, Riscontri, Data di archiviazione
• u per ripristinare (estrarre), d per eliminare definitivamente
• Premi Tab, q o Escape per tornare all'elenco delle scansioni

Gestione archivi

Risparmia spazio su disco comprimendo le vecchie scansioni in archivi ZIP:

Archiviare una scansione:

1. Dall'elenco delle scansioni, vai alla scansione che vuoi archiviare
2. Premi a per archiviare
3. Conferma l'operazione
4. La cartella della scansione viene compressa in un file .zip e la cartella originale viene eliminata
5. L'archivio appare nell'elenco archivi (premi Tab per vederlo)

Ripristinare un archivio:

1. Premi Tab per vedere l'elenco degli archivi
2. Vai all'archivio che vuoi ripristinare
3. Premi u per estrarre
4. Conferma l'operazione
5. L'archivio viene estratto e il file .zip viene eliminato
6. Premi q per tornare all'elenco delle scansioni e vedere la scansione ripristinata

Funzioni di sicurezza:

• Non è possibile archiviare scansioni RUNNING
• L'integrità dell'archivio viene verificata prima di eliminare la cartella sorgente
• L'estrazione viene verificata prima di eliminare l'archivio
• Tutte le operazioni richiedono conferma
• Se un passaggio fallisce, l'operazione viene annullata in modo sicuro

Eliminare scansioni/archivi:

• Dall'elenco scansioni: Premi d per eliminare definitivamente una cartella di scansione
• Dall'elenco archivi: Premi d per eliminare definitivamente un file di archivio
• Non è possibile eliminare scansioni RUNNING
• Richiede conferma (l'azione è permanente e irreversibile)
• Tutti i dati della scansione andranno persi

Tracciamento del lavoro e annotazioni

Tieni traccia del tuo workflow di sicurezza annotando vulnerabilità e riscontri con stato, priorità e note.

Come funziona:

• Le annotazioni sono salvate in .bbot_ui_annotations.json accanto a ciascuna scansione
• Fanno riferimento agli eventi tramite UUID - non modificano mai il output.json originale di BBOT
• Incluse automaticamente negli archivi per backup/ripristino
• Sopravvivono a nuove scansioni dello stesso target

Annotare una vulnerabilità/riscontro:

1. Vai alla scheda Vulnerabilità o Riscontri
2. Seleziona un elemento (frecce o j/k)
3. Premi t per aprire il dialogo di annotazione
4. Imposta stato, priorità (facoltativa) e note
5. Clicca Salva o premi Enter

Scorciatoie rapide:

• Premi x per contrassegnare l'elemento selezionato come Falso Positivo
• Premi i per contrassegnare l'elemento selezionato come Rischio Accettato
• Queste preservano priorità e note esistenti aggiornando lo stato

Opzioni di stato:

• 🆕 Nuovo - Stato predefinito per gli elementi non annotati
• 🔍 In Indagine - Attualmente in analisi
• ✓ Confermato - Verificato come problema reale
• ✗ Falso Positivo - Non è una vulnerabilità reale
• 📢 Segnalato - Inviato al team di sicurezza
• 🔧 Risolto - Il problema è stato risolto
• ⚠ Rischio Accettato - Noto ma accettato

Livelli di priorità (facoltativi):

• 🔴 Critica - Richiede attenzione immediata
• 🟠 Alta - Importante, da affrontare presto
• 🟡 Media - Priorità normale
• 🟢 Bassa - Problema minore

Funzionalità:

• Colonne Stato e Priorità nelle tabelle Vulnerabilità/Riscontri
• Menu a tendina filtro stato - filtra per stato specifico o elementi "Azione Richiesta" (predefinito)
• Scorciatoie da tastiera rapide (x/i) per triage veloce
• Grafici dello stato del workflow nella scheda Statistiche
• Campo note per contesto dettagliato
• Pulsante per cancellare l'annotazione e ripristinare
• Le annotazioni persistono tra sessioni e archivi

Filtro per stato:

• Azione Richiesta (predefinito) - Mostra solo gli elementi che necessitano attenzione (nuovo, in indagine, confermato, segnalato)
• Tutti - Mostra tutte le vulnerabilità/riscontri indipendentemente dallo stato
• Stati specifici - Filtra per singolo stato (falso positivo, risolto, ecc.)
• Il filtro si aggiorna automaticamente quando contrassegni elementi con le scorciatoie da tastiera

Schede del visualizzatore di scansione

• Barra di stato: Mostra lo stato della scansione con conteggio eventi in tempo reale
  • ● RUNNING (verde) - Aggiornamento attivo con nuovi eventi
  • ✓ FINISHED (blu) - Scansione completata, nessun altro aggiornamento
  • ⚠ INTERRUPTED (giallo) - Scansione interrotta/fermata
• Aggiornamento automatico: Tutte le schede si aggiornano ogni 2 secondi quando la scansione è RUNNING
• Rilevamento intelligente: Interrompe automaticamente il polling per le scansioni FINISHED e INTERRUPTED
• Premi r per aggiornare manualmente e vedere una notifica con il conteggio dei nuovi eventi

1. Vulnerabilità - Eventi VULNERABILITY ordinati per gravità (CRITICAL→HIGH→MEDIUM→LOW→INFO→UNKNOWN), con stato, priorità e annotazioni (aggiornamenti live) 2. Riscontri - Eventi FINDING con stato, priorità e annotazioni (aggiornamenti live) 3. Eventi - Tutti gli eventi con filtro per tipo, filtro per distanza dallo scope, ricerca multi-termine e dettagli JSON (aggiornamenti live) 4. Albero - Due modalità di visualizzazione (aggiornamenti live):

• Discovery: Mostra come gli eventi sono stati trovati tramite i moduli di scansione (relazioni genitore-figlio)
• Topologia: Gerarchia logica di rete (IP_RANGE → IP → OPEN_TCP_PORT) 5. Statistiche - Distribuzione degli eventi, top 15 moduli (classificati), grafici della distanza dallo scope, stato del workflow e distribuzione delle priorità (aggiornamenti live) 6. Sottodomini - Vista ad albero gerarchica dei sottodomini scoperti (mostrata solo quando subdomains.txt esiste, tipicamente dal preset subdomain-enum) 7. Configurazione - preset.yml con evidenziazione della sintassi

Ricerca multi-termine

La scheda Eventi supporta una potente ricerca multi-termine:

• Termini separati da spazio: Usa gli spazi per cercare più termini (es. httpx in-scope)
• Logica AND: Gli eventi devono corrispondere a TUTTI i termini per apparire nei risultati
• Campi cercati: data, type, module, host, tags, discovery_context
• Combinabile con i filtri: Funziona insieme ai filtri Tipo e Distanza dallo scope

Esempi:

• httpx in-scope - Eventi dal modulo httpx con tag in-scope
• k11h HIGH - Eventi relativi a k11h.de con gravità HIGH
• nuclei VULNERABILITY - Vulnerabilità scoperte dal modulo nuclei

Vista albero dei sottodomini

Quando si esegue BBOT con il preset subdomain-enum (o qualsiasi scansione che genera subdomains.txt), una scheda Sottodomini appare automaticamente nel visualizzatore di scansione mostrando un albero gerarchico dei sottodomini scoperti.

Funzionalità:

• Visualizzazione gerarchica: Sottodomini organizzati per struttura di dominio (es. api.example.com sotto example.com)
• Albero espandibile: Naviga tra i livelli di dominio con una navigazione ad albero intuitiva
• Indicatore di conteggio: L'etichetta della scheda mostra il numero totale di sottodomini (es. "Sottodomini (42)")
• Rilevamento automatico: La scheda appare solo quando subdomains.txt esiste nella cartella della scansione

Esempio di gerarchia:

example.com
  ├─ api.example.com
  ├─ dev.example.com
  └─ www.example.com

Scorciatoie da tastiera

Navigazione: ↑/↓ o j/k | Annota: t (solo Vuln/Riscontri) | Falso Positivo: x (solo Vuln/Riscontri) | Rischio Accettato: i (solo Vuln/Riscontri) | Vedi archivi: Tab (dall'elenco scansioni) | Cerca: f | Aggiorna: r | Archivia: a (elenco scansioni) | Estrai: u (elenco archivi) | Elimina: d | Regola ripartizione: ←/→ | Indietro/Esci: q o Escape

Nota: Le scorciatoie di annotazione (t, x, i) appaiono nella barra inferiore solo quando si visualizzano le schede Vulnerabilità o Riscontri.

Aggiornamento live e rilevamento dello stato

bbot-ui rileva e mostra automaticamente gli aggiornamenti dalle scansioni in esecuzione in tempo reale:

Rilevamento intelligente dello stato

L'interfaccia usa una catena di rilevamento multi-metodo per determinare con precisione lo stato della scansione:

1. Analisi evento SCAN: Legge il campo status dell'ultimo evento SCAN da output.json

   • "FINISHED" → Scansione completata (ha i campi finished_at e duration)
   • "RUNNING" → Verifica se è realmente in esecuzione (procedi al punto 2)

2. Rilevamento processo attivo (per stato RUNNING):

   • psutil (autoinstallato, multipiattaforma) - Controlla se qualche processo ha output.json aperto

3. Stato finale:

   • RUNNING: L'evento SCAN dice RUNNING + un processo ha attivamente il file aperto
   • INTERRUPTED: L'evento SCAN dice RUNNING + nessun processo ha il file aperto (la scansione è stata interrotta con Ctrl+C)
   • FINISHED: L'evento SCAN dice FINISHED (ha dati di completamento)

Funzionalità

• Caricamento progressivo: Le scansioni appaiono una ad una con aggiornamenti di stato in tempo reale all'avvio
• Rilevamento accurato: Identifica immediatamente le scansioni interrotte senza attendere timeout
• Prestazioni ottimizzate:
  • Iterazione progressiva delle directory (non bloccante, 1ms per directory)
  • Una scansione caricata ogni 10ms di tick del timer
  • Memorizza nella cache i controlli dei processi per 5 secondi (evita di scansionare tutti i processi ripetutamente)
  • Controlla solo le scansioni RUNNING (salta i controlli costosi per le scansioni FINISHED)
  • Il polling intelligente smette di controllare le scansioni FINISHED e INTERRUPTED
• Caricamento incrementale: Legge in modo efficiente solo i nuovi eventi da output.json
• Non bloccante: L'interfaccia rimane completamente reattiva durante gli aggiornamenti
• Preservazione del cursore: Mantiene la tua posizione nelle tabelle durante l'aggiornamento
• Gestione corretta: Salta le righe JSON incomplete/malformate dalle scansioni in esecuzione
• Intervalli configurabili: Personalizza le frequenze di aggiornamento secondo le tue esigenze

Configurazione

Puoi personalizzare il comportamento dell'aggiornamento live:

Tramite riga di comando:

./bbot-ui --scan-interval 5 --list-interval 10

Predefiniti:

• La vista dettaglio della scansione si aggiorna ogni 2 secondi
• La vista elenco scansioni si aggiorna ogni 3 secondi

Casi d'uso:

• Reti veloci/scansioni locali: Usa intervalli più brevi (es. --scan-interval 1)
• Sistemi remoti/lenti: Usa intervalli più lunghi (es. --scan-interval 5)
• Ridurre l'uso della CPU: Aumenta tutti gli intervalli per controlli meno frequenti

Le impostazioni vengono salvate in ~/.bbot_ui_config.json e persistono tra le sessioni.

Risoluzione dei problemi

La configurazione non è stata completata correttamente?

rm -rf ~/.bbot_ui_venv && ./bbot-ui

Avviso su psutil non installato? Se vedi un avviso che psutil manca, il tuo venv è di una versione precedente. Reinstalla:

rm -rf ~/.bbot_ui_venv && ./bbot-ui

Nessun output.json trovato? Assicurati che la directory della scansione contenga output.json (BBOT lo genera automaticamente)

Python non trovato?

# Ubuntu/Debian
sudo apt install python3 python3-venv

# macOS
brew install python3

Requisiti

• Python 3.8+
• Autoinstallazione: textual>=0.47.0, rich>=13.0.0, psutil>=5.9.0

Nota: psutil viene usato per il rilevamento accurato dello stato della scansione controllando se qualche processo ha aperto il file della scansione.

Prestazioni

L'interfaccia è ottimizzata per scansioni di grandi dimensioni e molte directory:

Prestazioni di avvio:

• Caricamento progressivo - L'interfaccia viene renderizzata istantaneamente (<200ms), le scansioni vengono caricate una ad una
• L'elenco delle directory avviene in modo incrementale (1ms per directory)
• Funziona in modo efficiente su filesystem di rete e mount remoti
• Nessuna operazione bloccante durante l'avvio

Limiti di visualizzazione:

• Scheda Vulnerabilità: massimo 1000 righe (ordinate per gravità)
• Scheda Riscontri: massimo 1000 righe
• Scheda Eventi: massimo 1000 righe (usa i filtri per scansioni grandi)
• Viste ad albero: massimo 500 nodi (usa i filtri per concentrarti su aree specifiche)
• Elenco scansioni: Il caricamento progressivo mostra le scansioni man mano che vengono scoperte

Lettura dei file:

• Legge da entrambe le estremità del file per trovare gli eventi SCAN (gestisce directory di scansione riutilizzate)
• Rileva la scansione più recente tramite timestamp (supporta più esecuzioni nella stessa directory)
• Stima i conteggi degli eventi per scansioni grandi usando dimensione del file e campionamento
• Memorizza nella cache i controlli di stato per evitare scansioni di processo ripetute

Aggiornamento automatico:

• Il timer si ferma automaticamente per le scansioni FINISHED/INTERRUPTED
• Controlla solo le scansioni RUNNING per gli aggiornamenti
• Risultati memorizzati nella cache per 5 secondi
• Il flag initial_load_phase previene conflitti di aggiornamento durante l'avvio

Suggerimenti

• Usa i filtri (tipo, distanza dallo scope) per concentrarti su eventi specifici nelle scansioni grandi
• I conteggi degli eventi per scansioni grandi (>1MB) sono stime per motivi di prestazioni
• Le scorciatoie di annotazione (t, x, i) sono sensibili al contesto e appaiono solo nelle schede pertinenti
• Il caricamento progressivo ti permette di iniziare a lavorare subito - non devi aspettare che tutte le scansioni vengano caricate
• Su filesystem di rete lenti, le scansioni appariranno gradualmente - è un comportamento normale
• Elimina ~/.bbot_ui_venv/ per forzare una reinstallazione pulita

Licenza

MIT