Database di rilevamenti di vulnerabilità

Un tracker statico lato client per i rilevamenti di vulnerabilità, costruito con Astro + React — disponibile anche come app desktop nativa per Linux (Tauri v2). Registra i rilevamenti di sicurezza, tienine traccia tramite la divulgazione coordinata, cerca in 11 database di vulnerabilità attivi in parallelo e sfoglia le ultime CVE — nel browser o come app desktop, senza bisogno di backend.

Indice

• Funzionalità
• Le Cinque Visualizzazioni
• Modello dei Dati
• Database di Vulnerabilità
• Stack Tecnologico
• Per Iniziare
• App Desktop Nativa
• Chiavi API Opzionali
• Configurazione del Database
• Come Funziona la Pipeline di Ricerca
• Persistenza dei Dati
• Esportazioni
• AI ChatBox
• Test
• Struttura del Progetto
• Note di Ricerca
• Flusso di Lavoro di Progettazione e Pianificazione
• Licenza

Funzionalità

• Gestione dei rilevamenti — crea, modifica, visualizza ed elimina rilevamenti con gravità, CVSS, CWE, CVE, stato, date, tag e link di riferimento
• Dashboard — schede statistiche, grafico a torta della gravità, grafico a barre dello stato e avvisi sulle scadenze di divulgazione
• Viste elenco e griglia — ricerca full-text, filtri (gravità/stato/progetto/tag), ordinamento ed esportazione in CSV o Markdown con un clic
• Ricerca nei database — interroga 11 fonti in parallelo con chip di stato live per singola fonte, arricchimento EPSS e badge CISA KEV
• Sfoglia — navigazione senza input tra le ultime CVE da 4 fonti con filtro per gravità, interruttore "Solo note come sfruttate" e paginazione "carica altri" con deduplicazione
• Persistenza — rilevamenti salvati in localStorage (nessun server, nessun account)
• Modalità offline — scarica i feed di Sfoglia (NVD, GitHub Advisories, CIRCL, CISA KEV) nell'archivio locale e cerca/sfoglia sullo snapshot senza rete
• Database personalizzati — collega qualsiasi API CVE aggiuntiva dalla scheda Impostazioni (URL + chiave bearer opzionale), interrogata insieme alle fonti integrate
• Fonti configurabili — attiva o disattiva qualsiasi database e gestisci le chiavi API dalla scheda Impostazioni integrata (senza dover ricompilare)
• AI ChatBox — assistente AI integrato come barra laterale overlay (il contenuto non viene mai riorganizzato): OpenAI, Claude, Google Gemini, Ollama e OpenCode Zen; specializzato per il progetto tramite un pacchetto di conoscenze incluso; comandi slash; e un AI Marketplace per connessioni MCP/Skill

Le Cinque Visualizzazioni

Il tracker (/tracker) è un'app a pagina singola con cinque schede:

1. Dashboard

• Schede statistiche: totale dei rilevamenti, attivi (non Fixed/Disclosed), gravità critica e conteggio delle scadenze di divulgazione vicine o superate
• Distribuzione della gravità — grafico a ciambella (Critical / High / Medium / Low)
• Rilevamenti per stato — grafico a barre (New / Reported / Acknowledged / Fixed / Disclosed)
• Scadenze imminenti e superate — rilevamenti entro 7 giorni dalla scadenza di divulgazione, ordinati per urgenza, con etichette "X giorni rimasti" / "X giorni in ritardo"

2. Rilevamenti

La vista di gestione per i rilevamenti registrati:

• Ricerca full-text su titolo, descrizione, progetto, ID CVE, ID CWE, note e tag
• Filtri — menu a tendina per gravità, stato, progetto e tag (opzioni derivate dai tuoi dati)
• Ordinamento — per gravità, stato o data di scoperta, crescente o decrescente
• Interruttore tabella / griglia — tabella su desktop, card su mobile; oppure una griglia di card
• Esportazione — CSV o Markdown della vista attualmente filtrata
• Modale di dettaglio — record completo con azioni di modifica ed eliminazione
• Stati vuoti — messaggi distinti per "nessun rilevamento presente" vs. "nessun rilevamento corrisponde ai filtri"

3. Ricerca

Interroga tutti i database abilitati in parallelo con una singola stringa di query:

• 11 fonti interrogate simultaneamente (vedi Database di Vulnerabilità)
• Chip di stato live — ogni fonte mostra idle / loading / ok (con conteggio dei risultati) / error (con motivo)
• Card dei risultati — espandibili, mostrano ID CVE, badge di gravità, CVSS, punteggio EPSS, badge CISA KEV, CWE, riferimenti e un link "Visualizza su NVD"
• Deduplicazione — i risultati provenienti da più fonti vengono uniti in un'unica card per CVE
• Degradazione graduale — una fonte che fallisce mostra un chip di errore; il resto della ricerca viene comunque completato

4. Sfoglia

Navigazione senza input tra le ultime vulnerabilità:

• 4 fonti: NVD (finestra di pubblicazione di 30 giorni), GitHub Advisories, CIRCL, CISA KEV
• Chip di filtro per gravità — All / Critical / High / Medium / Low
• Interruttore "Solo note come sfruttate" — mostra solo le voci CISA KEV
• Carica altri — aggiunge la pagina successiva con deduplicazione e riordinamento per data di pubblicazione
• Riga di riepilogo — "N CVE su X di 4 fonti in Yms"

5. Impostazioni

Il pannello di controllo per la connettività dei database:

• Interruttori per fonte — ogni database (e l'arricchimento EPSS) può essere attivato o disattivato; le modifiche si applicano subito dopo il salvataggio, senza ricompilare
• Etichette del metodo di connessione — ogni fonte indica se si collega direttamente o se richiede una chiave API
• Campi per le chiavi API — inserisci nell'app le chiavi per Vulners, MEND, VulDB e OpenCVE (campo password con mostra/nascondi); le chiavi sovrascrivono i valori .env definiti in fase di build
• Modalità offline — interruttore principale più pulsanti Scarica / Rimuovi per fonte per i feed di Sfoglia (NVD, GitHub Advisories, CIRCL, CISA KEV); gli snapshot scaricati vengono salvati localmente e utilizzati da Ricerca/Sfoglia quando si è offline
• Database personalizzati — aggiungi qualsiasi API CVE extra (nome, URL con segnaposto {query} opzionale, chiave bearer opzionale), testala o rimuovila; i database personalizzati collegati compaiono come chip aggiuntive nella vista Ricerca
• Salva / Reimposta — salva le modifiche o ripristina i valori predefiniti
• Le chiavi vengono salvate localmente nell'app e inviate solo al provider corrispondente

Modello dei Dati

Un Finding è il record principale. Campi:

La validazione è applicata nel modulo: campi obbligatori, formato URL, lunghezza della descrizione e intervallo CVSS.

Database di Vulnerabilità

11 database integrati, più l'arricchimento EPSS. Sette si collegano direttamente senza chiave; quattro richiedono una credenziale da .env.

Non integrati (con motivazioni): Snyk (limitato all'organizzazione, nessuna API di ricerca pubblica), JFrog Xray (self-hosted, restituisce artefatti non record CVE), Trivy (scanner CLI, nessuna API REST), MSRC (documenti CVRF mensili, non ricercabili per parola chiave), VulnCheck (solo endpoint di backup bulk), Debian/Ubuntu (dump multi-GB, non ricercabili lato client), Exploit-DB/Sploitus (nessuna API pubblica), CNVD/CNNVD (download XML manuali), Sonatype OSS Index (basato su purl/componenti, non su parole chiave).

Stack Tecnologico

Sistema di design: il tema "Dark Sunset Boulevard" — superfici scure con sottotono viola intenso (ink-950 #1A2226, ink-900 #223036, ink-800 #264653), testo color sabbia calda (ink-100 #F2EAE0, ink-400 #A49A8C) e un accento arancio bruciato (#E76F51). Tutti i colori sono token Tailwind 4 definiti in src/styles/global.css — nessun hex hardcoded nei componenti.

Per Iniziare

Richiede Node.js >= 20.```bash

Install dependencies

npm install

Start the dev server (http://localhost:4321)

npm run dev

Type-check (Astro + TypeScript)

npm run check

Production build (outputs to dist/)

npm run build

Preview the production build

npm run preview

La build produce un sito completamente statico (`dist/`) — distribuibile su qualsiasi host statico (GitLab Pages, Netlify, Cloudflare Pages, GitHub Pages, nginx…). La stessa build è anche inclusa in un'app desktop nativa — vedi [App Desktop Nativa](#native-desktop-app).

---

## App Desktop Nativa

**Un unico codebase, ogni formato di distribuzione.** Lo stesso sorgente genera il sito web, le app desktop e un'app Android — non esistono branch separati per web/app. Le app sono la build statica racchiusa in un piccolo shell Rust **Tauri v2** che la renderizza nella webview di sistema (WebKitGTK su Linux, WKWebView su macOS, WebView2 su Windows, Android WebView). Nessun server, nessuna scheda del browser; impostazioni e risultati persistono nella directory dati dell'app.

### Linux (predefinito)

I bundle desktop distribuiti hanno come target Linux (`.deb`, `.rpm`, AppImage).

**Dipendenze di sistema (Debian/Ubuntu):**```bash
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

Sviluppa (hot-reload: server di sviluppo Astro + finestra Tauri):```bash npm run tauri:dev

**Crea pacchetti installabili** (`.deb`, `.rpm`, AppImage — output in `src-tauri/target/release/bundle/`):```bash
npm run tauri:build

La shell Rust è volutamente minimale — zero comandi IPC in v1; tutta la logica resta nel layer web, quindi la build del browser e l'app desktop si comportano in modo identico.

macOS

Il supporto desktop macOS non è abilitato nella configurazione predefinita — i bundle distribuiti sono solo per Linux. Il codebase stesso è completamente multipiattaforma (il layer web gira in qualsiasi browser e la shell Rust ha zero comandi IPC), quindi abilitare macOS è una piccola modifica alla configurazione più una build su un Mac. Vedi docs/macos-development.md per la guida completa: prerequisiti, abilitazione del target dmg, icone, firma e notarizzazione, e un esempio di GitLab CI.

Windows 11

Il supporto desktop Windows non è abilitato nella configurazione predefinita — i bundle distribuiti sono solo per Linux. Il codebase è completamente multipiattaforma e le build Windows girano su una macchina Windows 11 con la toolchain MSVC (WebView2 è preinstallato). Vedi docs/windows-development.md per la guida completa: prerequisiti, abilitazione dei target nsis / msi, icone, firma del codice e SmartScreen, e un esempio di GitLab CI.

Android

Il target Android non è inizializzato nel repository — un solo comando lo inizializza (npm run tauri android init). Il codebase è completamente multipiattaforma (il layer web gira in Android WebView e la UI del tracker è già responsive per i telefoni). Vedi docs/android-development.md per la guida completa: prerequisiti (Android Studio, SDK, NDK, JDK 17), inizializzazione del target, creazione di APK/AAB e un esempio di GitLab CI.

Chiavi API opzionali

Quattro fonti di ricerca richiedono credenziali. Copia .env.example in .env, inserisci le chiavi e ricompila:

Nota sulla sicurezza: questo è un sito statico — le variabili PUBLIC_* vengono incorporate nel bundle client in fase di build e sono visibili nel sorgente della pagina. Usa chiavi a bassi privilegi o un proxy lato server per una reale segretezza. Le fonti senza chiave mostrano semplicemente un chip di errore; il resto della ricerca funziona comunque.

Suggerimento: puoi anche inserire queste chiavi nella scheda Settings dell'app — le chiavi runtime sovrascrivono i valori .env della build, senza bisogno di ricompilare.

I file .env sono in gitignore; viene committato solo .env.example.

Configurazione del database

Gli interruttori on/off del database e le chiavi API sono gestiti a runtime tramite la scheda Settings — nessuna modifica ai file o rebuild necessaria. I valori predefiniti si trovano in src/tracker/lib/dbConfig.ts e le sovrascritture runtime sono salvate nell'app (localStorage, chiave settings:all).

Precedenza: impostazioni runtime (scheda Settings) > valori .env della build > predefiniti di dbConfig.ts.

Ogni voce di configurazione ha:

• enabled — lo stato predefinito; la scheda Settings può sovrascriverlo per sessione
• search / browse — a quali viste la fonte partecipa
• needsKey + keyVar — contrassegna le fonti che leggono una credenziale (da .env o dalla scheda Settings)

La UI è interamente derivata dalla configurazione effettiva: getSearchSources() (chip di Search) e getBrowseSources() (chip di Browse) vengono filtrati sulle fonti abilitate, e gli adapter vengono filtrati al momento della query — disattivare una fonte in Settings la rimuove subito dalla UI e dalle query.

I database personalizzati vengono salvati nelle stesse impostazioni runtime (customDbs). Ogni voce ha un nome, un URL (che può contenere un segnaposto {query} — altrimenti la query viene aggiunta come ?q=) e una chiave bearer opzionale. Sono solo di ricerca: appaiono come chip extra nella vista Search e vengono interrogati in parallelo con le fonti integrate. Le risposte sono accettate come CVE JSON 5.0 ({ "vulnerabilities": [{ "cve": ... }] }) o come un semplice array di record con nomi di campo flessibili.

Come funziona la pipeline di ricerca

Tutto l'accesso ai database risiede in src/tracker/lib/, suddiviso per responsabilità (dbSearch.ts è un barrel che riesporta la precedente superficie pubblica):

• dbFetch.ts — helper fetch con timeout + costanti condivise
• dbAdapters.ts — gli 11 adapter di ricerca integrati + parser di record
• dbBrowse.ts — i 4 adapter di browse + pipeline browseDatabases
• dbCustom.ts — l'adapter per i database personalizzati configurati dall'utente
• dbPipeline.ts — meccanismo merge / KEV / EPSS + `searchDatabases```` query ──► Promise.all over enabled adapters ──► normalizeDbItem ──► mergeDbItems (dedup by CVE / ID / title, cross-merge) ──► attachKevBadges (CISA KEV catalog, cached) ──► enrichWithEpss (FIRST EPSS API, batched by CVE) ──► sorted results + per-source statuses + timing

- **Adapter** — uno per sorgente, ciascuno restituisce `RawDbItem` normalizzati. Gli adapter con chiave generano un errore chiaro "no API key configured" quando manca la credenziale.
- **Merge** — la stessa CVE trovata in più sorgenti diventa una singola scheda; i campi (sommario, gravità, CVSS, CWE, riferimenti, sorgenti) vengono uniti da tutti i contributori.
- **Badge KEV** — il catalogo CISA viene recuperato una volta e messo in cache; gli elementi che vi compaiono ricevono un badge "Known Exploited".
- **EPSS** — ricerca in batch su `api.first.org`; ogni scheda mostra il punteggio EPSS e il percentile.
- **Isolamento dei guasti** — ogni adapter intercetta i propri errori e li segnala tramite la callback di stato; una sorgente non disponibile non blocca mai le altre.

La pipeline **Browse** usa lo stesso meccanismo di merge/KEV/EPSS sulle quattro sorgenti di browse, con paginazione (`hasMore` quando una qualsiasi sorgente ha restituito una pagina piena).

La **modalità offline** sostituisce la pipeline live con lo snapshot scaricato: Search e Browse leggono la cache IndexedDB (`src/tracker/lib/offline.ts`), saltano l'arricchimento EPSS e aggiungono i badge KEV solo se anche il feed KEV CISA è stato scaricato. Le sorgenti senza snapshot scaricato mostrano un chip "error / not downloaded" invece di rimanere appese. **Database personalizzati** vengono interrogati attraverso la stessa interfaccia adapter: il segnaposto `{query}` dell'URL viene sostituito (o si aggiunge `?q=`), una chiave bearer opzionale viene inviata come `Authorization` e le risposte vengono normalizzate da CVE JSON 5.0 o da un semplice array.

---

## Persistenza dei dati

I findings sono memorizzati in `localStorage` con la chiave `findings:all` — nessun server, nessun account, funziona offline.

- Le scritture sono soggette a debounce a ogni modifica e salvate automaticamente
- Se l'API di storage del browser non è disponibile (o è presente un'API host di archiviazione artefatti), l'app torna con eleganza a un fallback
- Un payload corrotto viene trattato come vuoto anziché causare un crash
- Un errore di salvataggio mostra un banner con un pulsante **Riprova**

> I dati vivono nel profilo del browser. La cancellazione dei dati del sito elimina i tuoi findings — esporta prima in CSV/Markdown se ti serve un backup.

Gli **snapshot offline** vivono in IndexedDB (database `vulnbook-offline`, store `items` + `meta`) — scaricati per sorgente dalla scheda Impostazioni e usati da Search/Browse mentre la modalità offline è attiva. Sopravvivono ai ricaricamenti e vengono rimossi solo quando clicchi **Rimuovi** per quella sorgente o cancelli i dati del sito.

---

## Esportazioni

Dalla vista Findings, esporta l'elenco **attualmente filtrato e ordinato**:

- **CSV** — 15 colonne (titolo, progetto, URL repo, gravità, CVSS, stato, CWE, CVE, versioni interessate, date di scoperta/segnalazione/divulgazione, riferimenti, note, tag). Virgolette/escaping corretti per virgole, virgolette e newline.
- **Markdown** — una tabella in stile GitHub con le stesse colonne.

I file sono nominati `findings-YYYY-MM-DD.csv` / `.md` e scaricati automaticamente.

---

## AI ChatBox

L'assistente AI integrato nel tracker — una **sidebar sovrapposta** che scorre sopra il contenuto senza modificarne il layout. Vedi **[docs/ai-chatbox.md](https://gitlab.com/t-beckett/vulnbook/-/blob/main/docs/ai-chatbox.md)** per la guida completa (configurazione del provider, note di sicurezza, risoluzione dei problemi).

- **Cinque provider** — OpenAI, Claude (Anthropic), Google Gemini, **Ollama** (locale, offline) e **OpenCode Zen** (include modelli del piano gratuito). Configurati nell'app (chiave + modello), persistiti in `localStorage` (`chat:config`), inviati solo all'endpoint del provider stesso
- **Specializzato sul progetto** — ogni conversazione è basata su un **knowledge pack** incluso su vulnbook (architettura, modello dati, sorgenti del database, convenzioni); attivabile/disattivabile tramite **Contesto progetto** nel pannello di configurazione
- **Risposte in streaming** — output markdown in tempo reale con un pulsante **Stop**; un fallback non streaming subentra automaticamente
- **Comandi slash** — digita `/` nel compositore: `/mcp` e `/skill` aprono l'AI Marketplace, `/new` avvia una conversazione, `/clear` la svuota, `/help` elenca i comandi
- **AI Marketplace** — una scheda nella sidebar che elenca le voci **MCP** e **Skill** disponibili in una griglia; **Connect** attiva/disattiva una voce (persistito), **Download** è nella roadmap (Coming soon)
- **Cronologia chat** — le conversazioni vengono salvate (`chat:history`, con limite e troncamento dai più vecchi)

> **Sicurezza:** le chiavi restano locali e vanno solo al provider; il markdown dell'assistente viene renderizzato tramite un sanitizer rigoroso (niente HTML grezzo); le voci MCP/skill connesse sono solo di stato nella v1 — non viene scaricato o eseguito nulla.

---

## Test

Il progetto non ha un framework di unit test (decisione consolidata) — la verifica è un gate a tre passaggi:```bash
# 1. Type-check
npm run check

# 2. Build
npm run build

# 3. E2E smoke test (Playwright, 16 checks)
npx http-server dist -p 8899 -a 127.0.0.1 &
NODE_PATH=<path-to-playwright-node_modules> node scripts/smoke.cjs

Il test smoke (scripts/smoke.cjs) copre: rendering della landing page + idratazione, idratazione dell'isola tracker, CRUD dei finding, persistenza di localStorage al ricaricamento, vista elenco + controlli di esportazione, modale dei dettagli (apertura/Escape), eliminazione, ricerca nel database che produce schede di risultati, la vista browse che produce schede di risultati, la scheda impostazioni (disattivare una sorgente rimuove il suo chip, riattivarla lo ripristina), modalità offline (l'interruttore mostra il banner offline in Search e ripristina la modalità live) e validazione del modulo per database personalizzati (URL non valido respinto).

• Il binario di Chromium viene risolto da PLAYWRIGHT_CHROMIUM_PATH o da un percorso di cache predefinito
• I controlli 9–11 chiamano API live (NVD, GHSA, CIRCL, KEV, EPSS) e richiedono accesso a Internet
• I guasti delle sorgenti degradano a stati di errore per-chip per progettazione — i controlli prevedono che almeno una sorgente risponda

Per le modifiche all'app nativa, eseguire anche npm run tauri:build (vedi App desktop nativa).

Struttura del progetto```

├── src/ │ ├── components/ # Shared Astro components + animation primitives │ │ └── anim/ # Skeleton, Spinner, FadeInUp, CountUp │ ├── layouts/ # SiteLayout (fonts, meta, theme) │ ├── pages/ # index.astro (landing), tracker.astro, 404.astro │ ├── styles/ # global.css — Tailwind 4 design tokens │ └── tracker/ │ ├── components/ # Tracker UI │ │ ├── TrackerApp.tsx # Shell: tabs, modals, state │ │ ├── Dashboard.tsx # Stats + charts + deadlines │ │ ├── FindingsList.tsx / FilterBar.tsx │ │ ├── DbSearchView.tsx / BrowseView.tsx / SettingsView.tsx │ │ ├── FindingFormModal.tsx / FindingDetailModal.tsx │ │ ├── ConfirmDeleteDialog.tsx / EmptyState.tsx / ErrorBanner.tsx │ │ ├── SourceChip.tsx / SearchResultCard.tsx / StatCard.tsx / badges.tsx │ └── lib/ # Logic │ ├── types.ts # Finding, DbItem, KevEntry, View, … │ ├── constants.ts # Severity/status order + styles, button classes │ ├── dbConfig.ts # ← per-source defaults (on/off, key vars) │ ├── settings.ts # ← runtime settings store (Settings tab overrides) │ ├── offline.ts # IndexedDB offline snapshot store (download/remove/query) │ ├── dbSearch.ts # barrel: re-exports the db layer (see "How the Search Pipeline Works") │ ├── dbFetch.ts # fetch-with-timeout helper + shared constants │ ├── dbAdapters.ts # 11 built-in search adapters + record parsers │ ├── dbBrowse.ts # browse adapters + browseDatabases pipeline │ ├── dbCustom.ts # user-configured custom database adapter │ ├── dbPipeline.ts # merge/KEV/EPSS pipeline + searchDatabases │ ├── findings.ts # CRUD + validation │ ├── storage.ts # localStorage + artifact-API fallback │ ├── export.ts # CSV / Markdown export │ └── format.ts # date/URL/id helpers, cvssToSeverity ├── scripts/smoke.cjs # Playwright E2E smoke test (16 checks) ├── docs/ # Developer guides (macOS, Windows 11, Android development) ├── src-tauri/ # Tauri v2 native shell (Rust, minimal) ├── research/ # Vulnerability database & tooling research notes ├── .env.example # Documented API-key template └── astro.config.mjs

---

## Note di ricerca

La directory `research/` contiene la ricerca di base che ha guidato le integrazioni con i database:

- **`vulnerability-databases.md`** — ~60 database catalogati (modello di accesso, disponibilità API, avvertenze), incluse le modifiche all'arricchimento del NVD di aprile 2026, i dettagli delle API di EUVD/OpenCVE/VulDB e l'elenco dei "perché no"
- **`vulnerability-finding-tools.md`** — il panorama più ampio degli strumenti di individuazione delle vulnerabilità (SAST/SCA/fuzzing/pentest) e una pipeline per il singolo professionista

---

## Workflow di progettazione e pianificazione

Questo progetto segue un flusso di lavoro progettazione → pianificazione → esecuzione.

Le nuove funzionalità partono con un documento di progettazione, vengono validate, quindi pianificate ed eseguite in micro-attività. Consulta `CONTRIBUTING.md` per le convenzioni complete (branching, gate di verifica, stile dei commit, regole di accessibilità).

---

## Licenza

[MIT](https://gitlab.com/t-beckett/vulnbook/-/blob/main/LICENSE) © 2026 T. Beckett