yakushstanislav/ultravioletSelf-hosted motore di ricerca e scoperta di rete con scansione continua delle porte, sonda approfondita dei protocolli su ~100 servizi, corrispondenza locale delle CVE e ricerca full-text per l'inventario dell'infrastruttura e il monitoraggio dei rischi.
<div align="center">
# UltraViolet
**Network discovery e ricerca self-hosted — il tuo Shodan personale, sulla tua infrastruttura.**
Scansione TCP/UDP · ~100 sonde di protocollo · impronte TLS/JARM · corrispondenza CVE · ricerca full-text · tracciamento delta · avvisi
<br/>
[](service-api/)
[](service-frontend/)
[](service-env/)
[](service-env/)
[](.github/workflows/ci.yml)
[](LICENSE)
[Avvio rapido](#-avvio-rapido) ·
[Funzionalità](#-funzionalità) ·
[Architettura](#-architettura) ·
[Documentazione](#-documentazione) ·
[Checklist di produzione](#-checklist-di-produzione)
</div>
---
> **Importante.** Scansiona solo reti di tua proprietà o per le quali hai **autorizzazione scritta**. UltraViolet esegue ricognizione passiva dei servizi — non sfrutta vulnerabilità.
## Perché UltraViolet
| Caso d'uso | Cosa ottieni |
|----------|--------------|
| Perimetro e inventario | Scoperta continua di porte e servizi aperti su intervalli CIDR |
| Ricerca infrastruttura | Ricerca full-text su corpi HTTP, banner, TLS, DNS e CVE |
| Rischio e conformità | Corrispondenza NVD locale più CISA KEV ed EPSS — nessuna dipendenza dal cloud |
| Distribuzioni air-gapped | Archivio offline con immagini Docker, seed CVE e GeoIP MMDB su disco |
| Tracciamento modifiche | Delta tra scansioni, eventi WebSocket, avvisi su ricerche salvate |
Single tenant, un unico stack Docker Compose, controllo totale sui tuoi dati.
## ✨ Funzionalità
**Scoperta**
- Scanner TCP connect con **masscan** o **zmap** come motore di scoperta
- Sonde UDP su porte configurabili
- Limitato da `SCAN_ALLOWED_CIDRS` con limiti di host e porte
**Sonde approfondite (~100 protocolli)**
- Web: HTTP/HTTPS, HTTP/3, GraphQL, hash favicon, `robots.txt`, `security.txt`, stack tecnologico
- TLS: catene di certificati, JARM, JA3S/JA4S, valutazione configurazione
- Posta e directory: SMTP, POP3/IMAP, LDAP, IPMI
- Database e code: MySQL, PostgreSQL, MongoDB, Redis, Kafka, MQTT, NATS, AMQP…
- ICS/SCADA: Modbus, BACnet, DNP3, IEC 104, S7Comm, ENIP, OPC UA…
- IoT e media: ONVIF, RTSP, Chromecast, AirPlay, UPnP…
- Elenco completo nella [documentazione dei protocolli](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/probes/service-protocols.md)
**Arricchimento**
- DNS inverso, GeoIP (MMDB), ASN
- DNS diretto opzionale e scoperta log CT
**CVE e rischio**
- Mirror NVD locale con sincronizzazione in background e corrispondenza basata su impronte
- CISA KEV e FIRST EPSS
**Operazioni**
- RBAC (`viewer` / `operator` / `admin`), JWT + token di refresh
- Pianificazione scansioni, pausa/ripresa, recupero orfani dopo riavvio worker
- Prometheus `/metrics`, profilo Grafana opzionale
- Log di audit, rate limiting, policy di conservazione
## 🏗 Architettura
```mermaid
flowchart TB
Browser["Browser"]
FE["service-frontend<br/>React + nginx"]
API["uv-api<br/>REST · WS · metrics"]
PG[("PostgreSQL 16")]
SCAN["uv-scanner<br/>probe pipeline"]
Browser --> FE
FE -->|"/api"| API
FE -->|"/realtime"| API
API <--> PG
SCAN <--> PG
API -.->|LISTEN/NOTIFY| API
```
L'immagine UI della release fa da proxy per `/api/` e `/realtime` verso `uv-api` — **origine singola**, nessuna ricompilazione del frontend per URL API.
| Directory | Scopo |
|-----------|---------|
| [`service-api/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-api) | Go: `uv-api` (API HTTP, WebSocket, worker) + `uv-scanner` (pipeline) |
| [`service-frontend/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-frontend) | React 19 + Vite + RTK — scansioni, host, ricerca, dashboard |
| [`service-documentation-frontend/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend) | VitePress — documentazione utente e operatore |
| [`service-env/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env) | docker-compose, segreti, `install.sh` / `upgrade.sh` / backup |
Regole di sviluppo backend: [`CLAUDE.md`](https://github.com/yakushstanislav/ultraviolet/blob/master/CLAUDE.md).
## 🚀 Avvio rapido
**Requisiti:** Go 1.25+, Docker Engine ≥ 24, ~4 GB di RAM. Le immagini di produzione hanno come target Linux **amd64**.
### Esecuzione da Docker Hub (nessuna compilazione da sorgente)
Percorso per principianti — scarica le immagini pubblicate con
[`service-env/docker-compose.registry.yml`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/docker-compose.registry.yml):
```bash
cd service-env
cp env.registry.example .env
# imposta POSTGRES_PASSWORD, AUTH_JWT_SECRET, AUTH_BOOTSTRAP_PASSWORD
mkdir -p geoip catalog-seed
docker compose -f docker-compose.registry.yml pull
docker compose -f docker-compose.registry.yml up -d
# UI → http://localhost:3000
```
Consulta [Docker Registry](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/docker-registry.md) nel sito della documentazione.
### Sviluppo da sorgente
Le immagini API/scanner copiano binari precompilati da `service-api/bin/` (non vengono **compilati** dentro Docker). `make dev` esegue `make -C service-api build-linux` prima di `docker compose … --build`.
```bash
git clone https://github.com/yakushstanislav/UltraViolet.git
cd UltraViolet/service-env
cp .env.example .env
mkdir -p secrets
openssl rand -hex 32 > secrets/postgres_password
openssl rand -hex 32 > secrets/auth_jwt_secret
cd ..
make dev
```
| URL | Scopo |
|-----|---------|
| http://localhost:3000 | UI (API tramite nginx `/api/`) |
| http://localhost:8080 | API direttamente |
| http://localhost:9090/metrics | Prometheus |
**Bootstrap di sviluppo:** `admin` / `admin` (solo quando `APP_ENV≠production`).
## 📖 Documentazione
Guida completa — VitePress in [`service-documentation-frontend/docs/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs):
```bash
make docs-dev # → http://localhost:5173
```
In produzione, abilita il profilo `docs`:
```bash
cd service-env && docker compose --profile docs up -d
# → http://localhost:${UV_DOCUMENTATION_PORT:-3002}
```
Sezioni principali: [installazione](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/getting-started/installation.md) · [scansione](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/scanning) · [API](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/api/overview.md) · [distribuzione](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/docker-compose.md) · [installazione offline](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/offline-install.md).
## 🛠 Sviluppo
### Docker completo
```bash
make dev # build-linux → compose prod + dev override --build
```
Ricompila i binari Go dopo modifiche al backend (`make -C service-api build-linux`), poi riavvia o riesegui `make dev`.
### Modalità ibrida (iterazione backend più veloce)
```bash
make dev-db # solo PostgreSQL su :5432
cd service-api && make build
export LOGGER_NAME=uv-api LOGGER_DEBUG=true
export SERVER_ADDR=0.0.0.0 SERVER_PORT=8080
export METRICS_ADDR=0.0.0.0 METRICS_PORT=9090
export REALTIME_ADDR=0.0.0.0 REALTIME_PORT=8081
export POSTGRES_ADDR=localhost POSTGRES_PORT=5432
export POSTGRES_USERNAME=ultraviolet
export POSTGRES_PASSWORD="$(cat ../service-env/secrets/postgres_password)"
export POSTGRES_DATABASE=ultraviolet
export POSTGRES_SCHEMA_PATH="$(pwd)/deploy/migrations"
export AUTH_JWT_SECRET="$(cat ../service-env/secrets/auth_jwt_secret)"
./bin/uv-api
```
Frontend: `cd service-frontend && npm run dev` (Vite fa da proxy `/api` → `:8080`, `/realtime` → `:8081`).
### GeoIP e CVE
```bash
cd service-env && make geoip-download # IPLocate MMDB → geoip/
make -C service-env cve-catalog-dump # dump CVE (richiede postgres in esecuzione)
```
### Build senza Docker
```bash
make build && make lint && make frontend-build && make docs-build
```
## 📦 Release e installazione
**Piattaforma target:** `linux/amd64`. Su Apple Silicon, imposta `DOCKER_PLATFORM=linux/amd64` per gli archivi offline.
```bash
git tag v0.1.0
make release VERSION=v0.1.0
make release-promote VERSION=v0.1.0 # :latest — richiesto per release locali; GitHub Actions lo fa automaticamente
```
| Archivio | Contenuti |
|---------|----------|
| `ultraviolet-vX.Y.Z.tar.gz` | compose, script, `.env.example` (~50 KB, online) |
| `ultraviolet-vX.Y.Z-offline.tar.gz` | + immagini Docker amd64 |
| `ultraviolet-vX.Y.Z-offline-full.tar.gz` | + seed CVE + GeoIP MMDB |
**Online:** estrai → `cp .env.example .env` → `./install.sh` (pull dal registry).
**Offline:** `./install.sh` (`docker load`, nessun pull). Aggiornamento: mantieni `.env`, `secrets/` e il volume Postgres → `./upgrade.sh`.
Variabili: `UV_REGISTRY` (default `docker.io/styakush`), `DRY_RUN=1` — build di prova locale senza push.
<details>
<summary><strong>Installazione offline — passo dopo passo</strong></summary>
```bash
# dalla macchina di build
scp dist/ultraviolet-v0.1.0-offline.tar.gz user@host:~/
# sul server (Docker ≥ 24, amd64)
tar xzf ultraviolet-v0.1.0-offline.tar.gz && cd ultraviolet-v0.1.0
cp .env.example .env
./install.sh
```
Aggiornamento (preserva i dati):
```bash
docker compose -f docker-compose.yml down
# fai un backup di .env + secrets/, estrai il nuovo archivio, esegui ./upgrade.sh
```
Mantieni stabile il nome della directory (`ultraviolet-v0.1.0`) — il volume Docker `postgres-data` è legato ad essa.
</details>
## ✅ Checklist di produzione
1. Conserva i segreti in `secrets/`, mai in git.
2. Imposta `CORS_ALLOWED_ORIGINS` solo sulle origini UI reali.
3. Configura `SCAN_ALLOWED_CIDRS` e i limiti di host/porte.
4. Cambia la password di bootstrap e `AUTH_JWT_SECRET` (`install.sh` rifiuta i segnaposto).
5. Imposta `APP_ENV=production` — uv-api rifiuta `admin/admin` e password più corte di 8 caratteri.
6. Termina TLS su un reverse proxy — esempio: [`service-env/examples/nginx-tls.conf`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/examples/nginx-tls.conf).
7. Dietro un proxy: imposta `AUDIT_TRUST_PROXY_HEADERS=true`.
8. Esegui il backup di PostgreSQL: [`service-env/scripts/backup.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/backup.sh) + cron; `upgrade.sh` crea anche un dump.
9. Metriche su `:9090/metrics`; Grafana tramite il profilo `observability`.
10. Aggiorna GeoIP: [`service-env/scripts/geoip-refresh.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/geoip-refresh.sh) con cron mensile.
<details>
<summary><strong>HTTPS, distribuzione su sotto-percorso, cron di backup</strong></summary>
**Terminazione TLS su nginx esterno** — vincola la UI solo al loopback:
```yaml
# docker-compose.override.yml
services:
service-frontend:
ports:
- "127.0.0.1:3000:8080"
```
```bash
CORS_ALLOWED_ORIGINS=https://ultraviolet.example.com
AUDIT_TRUST_PROXY_HEADERS=true
```
**Sotto-percorso** (`/ultraviolet/`):
```bash
VITE_BASE_PATH=/ultraviolet/ make frontend-build
# UV_BASE_PATH=/ultraviolet/ in compose — deve corrispondere a VITE_BASE_PATH
```
**Cron di backup** (giornaliero, conservazione 14 giorni):
```cron
0 3 * * * cd /opt/ultraviolet/service-env && ./scripts/backup.sh && find backups -name 'uv-*.dump' -mtime +14 -delete
```
**Aggiornamento GeoIP** (1° di ogni mese):
```cron
0 4 1 * * cd /opt/ultraviolet/service-env && ./scripts/geoip-refresh.sh >> /var/log/uv-geoip.log 2>&1
```
</details>
## 🔐 API e RBAC
Dopo `POST /v1/auth/login` ricevi un `access_token` (Bearer) e un `refresh_token` (`/v1/auth/refresh`).
| Ruolo | Capacità |
|------|--------------|
| `viewer` | Leggere host, ricerca, CVE, dashboard |
| `operator` | + avviare e gestire scansioni |
| `admin` | + utenti, audit, impostazioni |
`GET /v1/me` · `GET /v1/version` · `GET /readyz` (health + versione + commit).
## 🤝 Contributi
Consulta [CONTRIBUTING.md](https://github.com/yakushstanislav/ultraviolet/blob/master/CONTRIBUTING.md). Segnalazioni di sicurezza: [SECURITY.md](https://github.com/yakushstanislav/ultraviolet/blob/master/SECURITY.md).
Standard della community: [CODE_OF_CONDUCT.md](https://github.com/yakushstanislav/ultraviolet/blob/master/CODE_OF_CONDUCT.md).
## 📄 Licenza
UltraViolet è rilasciato sotto la [Licenza MIT](https://github.com/yakushstanislav/ultraviolet/blob/master/LICENSE).
---
<p align="center">
<sub>UltraViolet — scopri cosa possiedi, comprendi cosa è cambiato, tienilo sulla tua rete.</sub>
</p>