yakushstanislav/ultravioletSelbstgehostete Netzwerkerkennungs- und Suchmaschine mit kontinuierlichem Port-Scanning, tiefer Protokollanalyse über ~100 Dienste, lokaler CVE-Abgleich und Volltextsuche für Inventarisierung der Infrastruktur und Risikoüberwachung.
<div align="center">
# UltraViolet
**Selbst gehostete Netzwerkerkennung & -suche — dein eigenes Shodan, auf deiner Hardware.**
TCP/UDP-Scans · ~100 Protokoll-Probes · TLS/JARM-Fingerprints · CVE-Abgleich · Volltextsuche · Delta-Tracking · Alarme
<br/>
[](service-api/)
[](service-frontend/)
[](service-env/)
[](service-env/)
[](.github/workflows/ci.yml)
[](LICENSE)
[Schnellstart](#-quick-start) ·
[Funktionen](#-features) ·
[Architektur](#-architecture) ·
[Dokumentation](#-documentation) ·
[Produktion](#-production-checklist)
</div>
---
> **Wichtig.** Scanne nur Netzwerke, die dir gehören oder für die du eine **schriftliche Genehmigung** zum Scannen hast. UltraViolet führt passive Diensterkennung durch — es nutzt keine Schwachstellen aus.
## Warum UltraViolet
| Anwendungsfall | Was du bekommst |
|----------|--------------|
| Perimeter & Inventar | Kontinuierliche Erkennung offener Ports und Dienste über CIDR-Bereiche |
| Infrastruktur-Suche | Volltextsuche über HTTP-Bodies, Banner, TLS, DNS und CVEs |
| Risiko & Compliance | Lokaler NVD-Abgleich plus CISA KEV und EPSS — keine Cloud-Abhängigkeit |
| Air-Gapped-Bereitstellung | Offline-Archiv mit Docker-Images, CVE-Seed und GeoIP-MMDB auf der Festplatte |
| Änderungsverfolgung | Deltas zwischen Scans, WebSocket-Ereignisse, Alarme bei gespeicherten Suchanfragen |
Einzelmandant, ein Docker-Compose-Stack, volle Kontrolle über deine Daten.
## ✨ Funktionen
**Erkennung**
- TCP-Connect-Scanner mit **masscan** oder **zmap** als Erkennungs-Engine
- UDP-Probes auf konfigurierbaren Ports
- Eingegrenzt durch `SCAN_ALLOWED_CIDRS` mit Host- und Port-Limits
**Tiefen-Probes (~100 Protokolle)**
- Web: HTTP/HTTPS, HTTP/3, GraphQL, Favicon-Hash, `robots.txt`, `security.txt`, Tech-Stack
- TLS: Zertifikatsketten, JARM, JA3S/JA4S, Konfigurationsbewertung
- Mail & Verzeichnisse: SMTP, POP3/IMAP, LDAP, IPMI
- Datenbanken & Queues: MySQL, PostgreSQL, MongoDB, Redis, Kafka, MQTT, NATS, AMQP…
- ICS/SCADA: Modbus, BACnet, DNP3, IEC 104, S7Comm, ENIP, OPC UA…
- IoT & Medien: ONVIF, RTSP, Chromecast, AirPlay, UPnP…
- Vollständige Liste in der [Protokoll-Dokumentation](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/probes/service-protocols.md)
**Anreicherung**
- Reverse-DNS, GeoIP (MMDB), ASN
- Optionale Forward-DNS- und CT-Log-Erkennung
**CVE & Risiko**
- Lokaler NVD-Spiegel mit Hintergrund-Synchronisierung und Fingerprint-basiertem Abgleich
- CISA KEV und FIRST EPSS
**Betrieb**
- RBAC (`viewer` / `operator` / `admin`), JWT + Refresh-Tokens
- Scan-Zeitpläne, Pause/Fortsetzen, Übernahme verwaister Scans nach Worker-Neustart
- Prometheus `/metrics`, optionales Grafana-Profil
- Audit-Log, Ratenbegrenzung, Aufbewahrungsrichtlinien
## 🏗 Architektur
```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
```
Das Release-UI-Image proxyt `/api/` und `/realtime` an `uv-api` — **Single Origin**, kein Frontend-Rebuild pro API-URL.
| Verzeichnis | Zweck |
|-----------|---------|
| [`service-api/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-api) | Go: `uv-api` (HTTP-API, WebSocket, Worker) + `uv-scanner` (Pipeline) |
| [`service-frontend/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-frontend) | React 19 + Vite + RTK — Scans, Hosts, Suche, Dashboard |
| [`service-documentation-frontend/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend) | VitePress — Benutzer- und Betreiber-Dokumentation |
| [`service-env/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env) | docker-compose, Secrets, `install.sh` / `upgrade.sh` / Backup |
Backend-Entwicklungsregeln: [`CLAUDE.md`](https://github.com/yakushstanislav/ultraviolet/blob/master/CLAUDE.md).
## 🚀 Schnellstart
**Voraussetzungen:** Go 1.25+, Docker Engine ≥ 24, ~4 GB RAM. Produktions-Images zielen auf Linux **amd64**.
### Von Docker Hub ausführen (kein Quellcode-Build)
Einsteiger-Pfad — veröffentlichte Images pullen mit
[`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
```
Siehe [Docker Registry](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/docker-registry.md) in der Dokumentations-Site.
### Aus dem Quellcode entwickeln
Die API/Scanner-Images kopieren vorgebaute Binaries aus `service-api/bin/` (sie werden **nicht** innerhalb von Docker kompiliert). `make dev` führt `make -C service-api build-linux` aus, bevor `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 | Zweck |
|-----|---------|
| http://localhost:3000 | UI (API über nginx `/api/`) |
| http://localhost:8080 | API direkt |
| http://localhost:9090/metrics | Prometheus |
**Dev-Bootstrap:** `admin` / `admin` (nur wenn `APP_ENV≠production`).
## 📖 Dokumentation
Vollständige Anleitung — 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 Produktion das `docs`-Profil aktivieren:
```bash
cd service-env && docker compose --profile docs up -d
# → http://localhost:${UV_DOCUMENTATION_PORT:-3002}
```
Wichtige Abschnitte: [Installation](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/getting-started/installation.md) · [Scannen](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) · [Bereitstellung](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/docker-compose.md) · [Offline-Installation](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/offline-install.md).
## 🛠 Entwicklung
### Vollständiges Docker
```bash
make dev # build-linux → compose prod + dev override --build
```
Go-Binaries nach Backend-Änderungen neu bauen (`make -C service-api build-linux`), dann neu starten oder `make dev` erneut ausführen.
### Hybrid-Modus (schnellere Backend-Iteration)
```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 proxyt `/api` → `:8080`, `/realtime` → `:8081`).
### GeoIP & CVE
```bash
cd service-env && make geoip-download # IPLocate MMDB → geoip/
make -C service-env cve-catalog-dump # CVE dump (requires running postgres)
```
### Ohne Docker bauen
```bash
make build && make lint && make frontend-build && make docs-build
```
## 📦 Release & Installation
**Zielplattform:** `linux/amd64`. Auf Apple Silicon `DOCKER_PLATFORM=linux/amd64` für Offline-Archive setzen.
```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
```
| Archiv | Inhalt |
|---------|----------|
| `ultraviolet-vX.Y.Z.tar.gz` | compose, Skripte, `.env.example` (~50 KB, online) |
| `ultraviolet-vX.Y.Z-offline.tar.gz` | + amd64-Docker-Images |
| `ultraviolet-vX.Y.Z-offline-full.tar.gz` | + CVE-Seed + GeoIP-MMDB |
**Online:** entpacken → `cp .env.example .env` → `./install.sh` (Pull aus der Registry).
**Offline:** `./install.sh` (`docker load`, kein Pull). Upgrade: `.env`, `secrets/` und das Postgres-Volume behalten → `./upgrade.sh`.
Variablen: `UV_REGISTRY` (Standard `docker.io/styakush`), `DRY_RUN=1` — lokaler Smoke-Build ohne Push.
<details>
<summary><strong>Offline-Installation — Schritt für Schritt</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
```
Upgrade (Daten erhalten):
```bash
docker compose -f docker-compose.yml down
# back up .env + secrets/, extract the new archive, run ./upgrade.sh
```
Verzeichnisnamen (`ultraviolet-v0.1.0`) stabil halten — das Docker-Volume `postgres-data` ist daran gebunden.
</details>
## ✅ Produktions-Checkliste
1. Secrets in `secrets/` aufbewahren, niemals in Git.
2. `CORS_ALLOWED_ORIGINS` auf echte UI-Origins setzen.
3. `SCAN_ALLOWED_CIDRS` sowie Host- und Port-Limits konfigurieren.
4. Bootstrap-Passwort und `AUTH_JWT_SECRET` ändern (`install.sh` lehnt Platzhalter ab).
5. `APP_ENV=production` setzen — uv-api lehnt `admin/admin` und Passwörter mit weniger als 8 Zeichen ab.
6. TLS an einem Reverse-Proxy terminieren — Beispiel: [`service-env/examples/nginx-tls.conf`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/examples/nginx-tls.conf).
7. Hinter einem Proxy: `AUDIT_TRUST_PROXY_HEADERS=true` setzen.
8. PostgreSQL sichern: [`service-env/scripts/backup.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/backup.sh) + Cron; `upgrade.sh` erstellt ebenfalls einen Dump.
9. Metriken unter `:9090/metrics`; Grafana über das `observability`-Profil.
10. GeoIP aktualisieren: [`service-env/scripts/geoip-refresh.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/geoip-refresh.sh) per Monats-Cron.
<details>
<summary><strong>HTTPS, Sub-Pfad-Bereitstellung, Backup-Cron</strong></summary>
**TLS-Terminierung auf externem nginx** — die UI nur an Loopback binden:
```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
```
**Sub-Pfad** (`/ultraviolet/`):
```bash
VITE_BASE_PATH=/ultraviolet/ make frontend-build
# UV_BASE_PATH=/ultraviolet/ in compose — must match VITE_BASE_PATH
```
**Backup-Cron** (täglich, 14 Tage Aufbewahrung):
```cron
0 3 * * * cd /opt/ultraviolet/service-env && ./scripts/backup.sh && find backups -name 'uv-*.dump' -mtime +14 -delete
```
**GeoIP-Aktualisierung** (jeden 1. des Monats):
```cron
0 4 1 * * cd /opt/ultraviolet/service-env && ./scripts/geoip-refresh.sh >> /var/log/uv-geoip.log 2>&1
```
</details>
## 🔐 API & RBAC
Nach `POST /v1/auth/login` erhältst du einen `access_token` (Bearer) und einen `refresh_token` (`/v1/auth/refresh`).
| Rolle | Fähigkeiten |
|------|--------------|
| `viewer` | Hosts lesen, suchen, CVEs, Dashboard |
| `operator` | + Scans starten und verwalten |
| `admin` | + Benutzer, Audit, Einstellungen |
`GET /v1/me` · `GET /v1/version` · `GET /readyz` (Health + Version + Commit).
## 🤝 Mitwirken
Siehe [CONTRIBUTING.md](https://github.com/yakushstanislav/ultraviolet/blob/master/CONTRIBUTING.md). Sicherheitsmeldungen: [SECURITY.md](https://github.com/yakushstanislav/ultraviolet/blob/master/SECURITY.md).
Community-Standards: [CODE_OF_CONDUCT.md](https://github.com/yakushstanislav/ultraviolet/blob/master/CODE_OF_CONDUCT.md).
## 📄 Lizenz
UltraViolet ist unter der [MIT-Lizenz](https://github.com/yakushstanislav/ultraviolet/blob/master/LICENSE) veröffentlicht.
---
<p align="center">
<sub>UltraViolet — entdecke, was dir gehört, verstehe, was sich geändert hat, und behalte es in deinem Netzwerk.</sub>
</p>