yakushstanislav/ultravioletMotor de descubrimiento de red y búsqueda autohospedado con escaneo continuo de puertos, sondeo profundo de protocolos en ~100 servicios, coincidencia local de CVE y búsqueda de texto completo para inventario de infraestructura y monitoreo de riesgos.
<div align="center">
# UltraViolet
**Descubrimiento y búsqueda de red autoalojados: tu propio Shodan, en tu propio hardware.**
Escaneo TCP/UDP · sondas de ~100 protocolos · huellas TLS/JARM · coincidencia de CVEs · búsqueda de texto completo · seguimiento de deltas · alertas
<br/>
[](service-api/)
[](service-frontend/)
[](service-env/)
[](service-env/)
[](.github/workflows/ci.yml)
[](LICENSE)
[Inicio rápido](#-quick-start) ·
[Características](#-features) ·
[Arquitectura](#-architecture) ·
[Documentación](#-documentation) ·
[Producción](#-production-checklist)
</div>
---
> **Importante.** Escanea únicamente redes que te pertenezcan o para las que tengas **autorización por escrito**. UltraViolet realiza reconocimiento pasivo de servicios; no explota vulnerabilidades.
## Por qué UltraViolet
| Caso de uso | Qué obtienes |
|----------|--------------|
| Perímetro e inventario | Descubrimiento continuo de puertos y servicios abiertos en rangos CIDR |
| Búsqueda de infraestructura | Búsqueda de texto completo en cuerpos HTTP, banners, TLS, DNS y CVEs |
| Riesgo y cumplimiento | Coincidencia local con NVD más CISA KEV y EPSS, sin dependencia de la nube |
| Despliegues aislados | Archivo sin conexión con imágenes Docker, semilla de CVEs y GeoIP MMDB en disco |
| Seguimiento de cambios | Deltas entre escaneos, eventos WebSocket, alertas en búsquedas guardadas |
Un solo inquilino, una pila de Docker Compose y control total sobre tus datos.
## ✨ Características
**Descubrimiento**
- Escáner de conexión TCP con **masscan** o **zmap** como motor de descubrimiento
- Sondas UDP en puertos configurables
- Acotado por `SCAN_ALLOWED_CIDRS` con límites de hosts y puertos
**Sondas profundas (~100 protocolos)**
- Web: HTTP/HTTPS, HTTP/3, GraphQL, hash de favicon, `robots.txt`, `security.txt`, pila tecnológica
- TLS: cadenas de certificados, JARM, JA3S/JA4S, clasificación de configuración
- Correo y directorios: SMTP, POP3/IMAP, LDAP, IPMI
- Bases de datos y colas: MySQL, PostgreSQL, MongoDB, Redis, Kafka, MQTT, NATS, AMQP…
- ICS/SCADA: Modbus, BACnet, DNP3, IEC 104, S7Comm, ENIP, OPC UA…
- IoT y multimedia: ONVIF, RTSP, Chromecast, AirPlay, UPnP…
- Lista completa en la [documentación de protocolos](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/probes/service-protocols.md)
**Enriquecimiento**
- DNS inverso, GeoIP (MMDB), ASN
- DNS directo opcional y descubrimiento en registros CT
**CVE y riesgo**
- Espejo local de NVD con sincronización en segundo plano y coincidencia basada en huellas
- CISA KEV y FIRST EPSS
**Operaciones**
- RBAC (`viewer` / `operator` / `admin`), JWT + tokens de refresco
- Programación de escaneos, pausa/reanudación, recuperación de huérfanos tras reiniciar workers
- Prometheus `/metrics`, perfil opcional de Grafana
- Registro de auditoría, limitación de tasa, políticas de retención
## 🏗 Arquitectura
```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
```
La imagen de UI publicada redirige `/api/` y `/realtime` a `uv-api` — **origen único**, sin reconstrucción del frontend por URL de API.
| Directorio | Propósito |
|-----------|---------|
| [`service-api/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-api) | Go: `uv-api` (API HTTP, WebSocket, workers) + `uv-scanner` (pipeline) |
| [`service-frontend/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-frontend) | React 19 + Vite + RTK: escaneos, hosts, búsqueda, panel |
| [`service-documentation-frontend/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend) | VitePress: documentación de usuarios y operadores |
| [`service-env/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env) | docker-compose, secrets, `install.sh` / `upgrade.sh` / backup |
Reglas de desarrollo del backend: [`CLAUDE.md`](https://github.com/yakushstanislav/ultraviolet/blob/master/CLAUDE.md).
## 🚀 Inicio rápido
**Requisitos:** Go 1.25+, Docker Engine ≥ 24, ~4 GB de RAM. Las imágenes de producción están dirigidas a Linux **amd64**.
### Ejecutar desde Docker Hub (sin compilar el código)
Camino para principiantes: descarga las imágenes publicadas 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
# set 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) en el sitio de documentación.
### Desarrollar desde el código fuente
Las imágenes de API/scanner copian binarios precompilados desde `service-api/bin/` (no se compilan dentro de Docker). `make dev` ejecuta `make -C service-api build-linux` antes de `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 | Propósito |
|-----|---------|
| http://localhost:3000 | UI (API a través de nginx `/api/`) |
| http://localhost:8080 | API directamente |
| http://localhost:9090/metrics | Prometheus |
**Arranque de desarrollo:** `admin` / `admin` (solo cuando `APP_ENV≠production`).
## 📖 Documentación
Guía completa: VitePress en [`service-documentation-frontend/docs/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs):
```bash
make docs-dev # → http://localhost:5173
```
En producción, habilita el perfil `docs`:
```bash
cd service-env && docker compose --profile docs up -d
# → http://localhost:${UV_DOCUMENTATION_PORT:-3002}
```
Secciones clave: [instalación](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/getting-started/installation.md) · [escaneo](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) · [despliegue](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/docker-compose.md) · [instalación sin conexión](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/offline-install.md).
## 🛠 Desarrollo
### Docker completo
```bash
make dev # build-linux → compose prod + dev override --build
```
Recompila los binarios Go tras cambios en el backend (`make -C service-api build-linux`) y luego reinicia o vuelve a ejecutar `make dev`.
### Modo híbrido (iteración más rápida del backend)
```bash
make dev-db # PostgreSQL only on :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 redirige `/api` → `:8080`, `/realtime` → `:8081`).
### GeoIP y CVE
```bash
cd service-env && make geoip-download # IPLocate MMDB → geoip/
make -C service-env cve-catalog-dump # CVE dump (requires running postgres)
```
### Compilar sin Docker
```bash
make build && make lint && make frontend-build && make docs-build
```
## 📦 Lanzamiento e instalación
**Plataforma objetivo:** `linux/amd64`. En Apple Silicon, define `DOCKER_PLATFORM=linux/amd64` para los archivos sin conexión.
```bash
git tag v0.1.0
make release VERSION=v0.1.0
make release-promote VERSION=v0.1.0 # :latest — required for local releases; GitHub Actions does this automatically
```
| Archivo | Contenido |
|---------|----------|
| `ultraviolet-vX.Y.Z.tar.gz` | compose, scripts, `.env.example` (~50 KB, en línea) |
| `ultraviolet-vX.Y.Z-offline.tar.gz` | + imágenes Docker amd64 |
| `ultraviolet-vX.Y.Z-offline-full.tar.gz` | + semilla de CVEs + GeoIP MMDB |
**En línea:** extrae → `cp .env.example .env` → `./install.sh` (descarga desde el registro).
**Sin conexión:** `./install.sh` (`docker load`, sin descarga). Actualización: conserva `.env`, `secrets/` y el volumen de Postgres → `./upgrade.sh`.
Variables: `UV_REGISTRY` (por defecto `docker.io/styakush`), `DRY_RUN=1`: compilación local de prueba sin publicar.
<details>
<summary><strong>Instalación sin conexión, paso a paso</strong></summary>
```bash
# from the build machine
scp dist/ultraviolet-v0.1.0-offline.tar.gz user@host:~/
# on the server (Docker ≥ 24, amd64)
tar xzf ultraviolet-v0.1.0-offline.tar.gz && cd ultraviolet-v0.1.0
cp .env.example .env
./install.sh
```
Actualización (conserva los datos):
```bash
docker compose -f docker-compose.yml down
# back up .env + secrets/, extract the new archive, run ./upgrade.sh
```
Mantén estable el nombre del directorio (`ultraviolet-v0.1.0`); el volumen de Docker `postgres-data` está vinculado a él.
</details>
## ✅ Checklist de producción
1. Guarda los secretos en `secrets/`, nunca en git.
2. Configura `CORS_ALLOWED_ORIGINS` solo con los orígenes reales de la UI.
3. Configura `SCAN_ALLOWED_CIDRS` y los límites de hosts/puertos.
4. Cambia la contraseña de arranque y `AUTH_JWT_SECRET` (`install.sh` rechaza valores de relleno).
5. Define `APP_ENV=production`; uv-api rechaza `admin/admin` y contraseñas de menos de 8 caracteres.
6. Termina TLS en un proxy inverso, por ejemplo: [`service-env/examples/nginx-tls.conf`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/examples/nginx-tls.conf).
7. Detrás de un proxy: define `AUDIT_TRUST_PROXY_HEADERS=true`.
8. Haz copias de seguridad de PostgreSQL: [`service-env/scripts/backup.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/backup.sh) + cron; `upgrade.sh` también crea un volcado.
9. Métricas en `:9090/metrics`; Grafana mediante el perfil `observability`.
10. Actualiza GeoIP: [`service-env/scripts/geoip-refresh.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/geoip-refresh.sh) con un cron mensual.
<details>
<summary><strong>HTTPS, despliegue en subruta, cron de copias de seguridad</strong></summary>
**Terminación TLS en nginx externo** — vincula la UI solo a 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
```
**Subruta** (`/ultraviolet/`):
```bash
VITE_BASE_PATH=/ultraviolet/ make frontend-build
# UV_BASE_PATH=/ultraviolet/ in compose — must match VITE_BASE_PATH
```
**Cron de copias de seguridad** (diario, retención de 14 días):
```cron
0 3 * * * cd /opt/ultraviolet/service-env && ./scripts/backup.sh && find backups -name 'uv-*.dump' -mtime +14 -delete
```
**Actualización de GeoIP** (el día 1 de cada mes):
```cron
0 4 1 * * cd /opt/ultraviolet/service-env && ./scripts/geoip-refresh.sh >> /var/log/uv-geoip.log 2>&1
```
</details>
## 🔐 API y RBAC
Tras `POST /v1/auth/login` recibes un `access_token` (Bearer) y un `refresh_token` (`/v1/auth/refresh`).
| Rol | Capacidades |
|------|--------------|
| `viewer` | Leer hosts, búsqueda, CVEs, panel |
| `operator` | + iniciar y gestionar escaneos |
| `admin` | + usuarios, auditoría, ajustes |
`GET /v1/me` · `GET /v1/version` · `GET /readyz` (salud + versión + commit).
## 🤝 Contribuciones
Consulta [CONTRIBUTING.md](https://github.com/yakushstanislav/ultraviolet/blob/master/CONTRIBUTING.md). Informes de seguridad: [SECURITY.md](https://github.com/yakushstanislav/ultraviolet/blob/master/SECURITY.md).
Estándares de la comunidad: [CODE_OF_CONDUCT.md](https://github.com/yakushstanislav/ultraviolet/blob/master/CODE_OF_CONDUCT.md).
## 📄 Licencia
UltraViolet se publica bajo la [Licencia MIT](https://github.com/yakushstanislav/ultraviolet/blob/master/LICENSE).
---
<p align="center">
<sub>UltraViolet: descubre lo que posees, entiende qué cambió y mantenlo en tu red.</sub>
</p>