Самостоятельно размещаемый инструмент для обнаружения сети и поисковый движок с непрерывным сканированием портов, глубоким зондированием протоколов по ~100 сервисам, локальным сопоставлением CVE и полнотекстовым поиском для инвентаризации инфраструктуры и мониторинга рисков.
<div align="center">

# UltraViolet

**Самостоятельно размещаемое обнаружение сети и поиск — ваш собственный Shodan на вашем оборудовании.**

Сканирование TCP/UDP · ~100 протокольных проб · отпечатки TLS/JARM · сопоставление CVE · полнотекстовый поиск · отслеживание дельт · оповещения

<br/>

[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go&logoColor=white)](service-api/)
[![React](https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black)](service-frontend/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-4169E1?style=flat-square&logo=postgresql&logoColor=white)](service-env/)
[![Docker](https://img.shields.io/badge/Deploy-Docker%20Compose-2496ED?style=flat-square&logo=docker&logoColor=white)](service-env/)
[![CI](https://img.shields.io/badge/CI-GitHub%20Actions-2088FF?style=flat-square&logo=githubactions&logoColor=white)](.github/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)

[Быстрый старт](#-quick-start) ·
[Возможности](#-features) ·
[Архитектура](#-architecture) ·
[Документация](#-documentation) ·
[Продакшн](#-production-checklist)

</div>

---

> **Важно.** Сканируйте только те сети, которыми владеете или на сканирование которых имеете **письменное разрешение**. UltraViolet выполняет пассивную разведку сервисов — он не эксплуатирует уязвимости.

## Зачем нужен UltraViolet

| Вариант использования | Что вы получаете |
|----------|--------------|
| Периметр и инвентаризация | Непрерывное обнаружение открытых портов и сервисов в диапазонах CIDR |
| Поиск по инфраструктуре | Полнотекстовый поиск по телам HTTP-ответов, баннерам, TLS, DNS и CVE |
| Риски и соответствие | Локальное сопоставление NVD плюс CISA KEV и EPSS — без зависимости от облака |
| Изолированные (air-gapped) развертывания | Офлайн-архив с Docker-образами, начальным набором CVE и GeoIP MMDB на диске |
| Отслеживание изменений | Дельты между сканированиями, WebSocket-события, оповещения по сохраненным поискам |

Один арендатор, один стек Docker Compose, полный контроль над вашими данными.

## ✨ Возможности

**Обнаружение**
- TCP-сканер подключений с **masscan** или **zmap** в качестве движка обнаружения
- UDP-пробы на настраиваемых портах
- Ограничено `SCAN_ALLOWED_CIDRS` с лимитами на хосты и порты

**Глубокие пробы (~100 протоколов)**
- Веб: HTTP/HTTPS, HTTP/3, GraphQL, хеш фавиконки, `robots.txt`, `security.txt`, технологический стек
- TLS: цепочки сертификатов, JARM, JA3S/JA4S, оценка конфигурации
- Почта и каталоги: SMTP, POP3/IMAP, LDAP, IPMI
- Базы данных и очереди: MySQL, PostgreSQL, MongoDB, Redis, Kafka, MQTT, NATS, AMQP…
- ICS/SCADA: Modbus, BACnet, DNP3, IEC 104, S7Comm, ENIP, OPC UA…
- Интернет вещей и медиа: ONVIF, RTSP, Chromecast, AirPlay, UPnP…
- Полный список — в [документации по протоколам](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/probes/service-protocols.md)

**Обогащение**
- Обратный DNS, GeoIP (MMDB), ASN
- Опционально прямой DNS и обнаружение через CT-логи

**CVE и риски**
- Локальное зеркало NVD с фоновой синхронизацией и сопоставлением на основе отпечатков
- CISA KEV и FIRST EPSS

**Эксплуатация**
- RBAC (`viewer` / `operator` / `admin`), JWT + refresh-токены
- Расписания сканирования, пауза/возобновление, восстановление потерянных задач после перезапуска воркера
- Prometheus `/metrics`, опциональный профиль Grafana
- Журнал аудита, ограничение частоты запросов, политики хранения

## 🏗 Архитектура

```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
```

Образ UI из релиза проксирует `/api/` и `/realtime` на `uv-api` — **единый источник (single origin)**, без пересборки фронтенда под каждый URL API.

| Каталог | Назначение |
|-----------|---------|
| [`service-api/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-api) | Go: `uv-api` (HTTP API, WebSocket, воркеры) + `uv-scanner` (конвейер) |
| [`service-frontend/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-frontend) | React 19 + Vite + RTK — сканирования, хосты, поиск, дашборд |
| [`service-documentation-frontend/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend) | VitePress — документация для пользователей и операторов |
| [`service-env/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env) | docker-compose, секреты, `install.sh` / `upgrade.sh` / резервное копирование |

Правила разработки бэкенда: [`CLAUDE.md`](https://github.com/yakushstanislav/ultraviolet/blob/master/CLAUDE.md).

## 🚀 Быстрый старт

**Требования:** Go 1.25+, Docker Engine ≥ 24, ~4 ГБ ОЗУ. Продакшн-образы предназначены для Linux **amd64**.

### Запуск из Docker Hub (без сборки из исходников)

Путь для начинающих — загрузите опубликованные образы с помощью [`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
```

См. раздел [Docker Registry](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/docker-registry.md) на сайте документации.

### Разработка из исходного кода

Образы API/сканера копируют предварительно собранные бинарники из `service-api/bin/` (они **не** компилируются внутри Docker). `make dev` выполняет `make -C service-api build-linux` перед `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 | Назначение |
|-----|---------|
| http://localhost:3000 | UI (API через nginx `/api/`) |
| http://localhost:8080 | API напрямую |
| http://localhost:9090/metrics | Prometheus |

**Бутстрап для разработки:** `admin` / `admin` (только когда `APP_ENV≠production`).

## 📖 Документация

Полное руководство — VitePress в [`service-documentation-frontend/docs/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs):

```bash
make docs-dev    # → http://localhost:5173
```

В продакшене включите профиль `docs`:

```bash
cd service-env && docker compose --profile docs up -d
# → http://localhost:${UV_DOCUMENTATION_PORT:-3002}
```

Ключевые разделы: [установка](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/getting-started/installation.md) · [сканирование](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) · [развертывание](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/docker-compose.md) · [офлайн-установка](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs/deployment/offline-install.md).

## 🛠 Разработка

### Полный Docker

```bash
make dev    # build-linux → compose prod + dev override --build
```

Пересоберите Go-бинарники после изменений бэкенда (`make -C service-api build-linux`), затем перезапустите или выполните `make dev` заново.

### Гибридный режим (более быстрая итерация по бэкенду)

```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
```

Фронтенд: `cd service-frontend && npm run dev` (Vite проксирует `/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)
```

### Сборка без Docker

```bash
make build && make lint && make frontend-build && make docs-build
```

## 📦 Релиз и установка

**Целевая платформа:** `linux/amd64`. На Apple Silicon задайте `DOCKER_PLATFORM=linux/amd64` для офлайн-архивов.

```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
```

| Архив | Содержимое |
|---------|----------|
| `ultraviolet-vX.Y.Z.tar.gz` | compose, скрипты, `.env.example` (~50 КБ, онлайн) |
| `ultraviolet-vX.Y.Z-offline.tar.gz` | + Docker-образы amd64 |
| `ultraviolet-vX.Y.Z-offline-full.tar.gz` | + начальный набор CVE + GeoIP MMDB |

**Онлайн:** распакуйте → `cp .env.example .env` → `./install.sh` (загрузка из реестра).

**Офлайн:** `./install.sh` (`docker load`, без загрузки из реестра). Обновление: сохраните `.env`, `secrets/` и том Postgres → `./upgrade.sh`.

Переменные: `UV_REGISTRY` (по умолчанию `docker.io/styakush`), `DRY_RUN=1` — локальная проверочная сборка без публикации.

<details>
<summary><strong>Офлайн-установка — пошагово</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
```

Обновление (с сохранением данных):

```bash
docker compose -f docker-compose.yml down
# back up .env + secrets/, extract the new archive, run ./upgrade.sh
```

Сохраняйте имя каталога (`ultraviolet-v0.1.0`) неизменным — Docker-том `postgres-data` привязан к нему.

</details>

## ✅ Чек-лист продакшена

1. Храните секреты в `secrets/`, никогда в git.
2. Задайте `CORS_ALLOWED_ORIGINS` только с реальными источниками UI.
3. Настройте `SCAN_ALLOWED_CIDRS` и лимиты хостов/портов.
4. Смените начальный пароль и `AUTH_JWT_SECRET` (`install.sh` отклоняет заглушки).
5. Установите `APP_ENV=production` — uv-api отклоняет `admin/admin` и пароли короче 8 символов.
6. Завершайте TLS на обратном прокси — пример: [`service-env/examples/nginx-tls.conf`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/examples/nginx-tls.conf).
7. За прокси: задайте `AUDIT_TRUST_PROXY_HEADERS=true`.
8. Резервное копирование PostgreSQL: [`service-env/scripts/backup.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/backup.sh) + cron; `upgrade.sh` также создает дамп.
9. Метрики на `:9090/metrics`; Grafana через профиль `observability`.
10. Обновляйте GeoIP: [`service-env/scripts/geoip-refresh.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/geoip-refresh.sh) по ежемесячному cron.

<details>
<summary><strong>HTTPS, развертывание по подпути, cron резервного копирования</strong></summary>

**Завершение TLS на внешнем nginx** — привяжите UI только к 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
```

**Подпуть** (`/ultraviolet/`):

```bash
VITE_BASE_PATH=/ultraviolet/ make frontend-build
# UV_BASE_PATH=/ultraviolet/ in compose — must match VITE_BASE_PATH
```

**Cron резервного копирования** (ежедневно, хранение 14 дней):

```cron
0 3 * * * cd /opt/ultraviolet/service-env && ./scripts/backup.sh && find backups -name 'uv-*.dump' -mtime +14 -delete
```

**Обновление GeoIP** (первого числа каждого месяца):

```cron
0 4 1 * * cd /opt/ultraviolet/service-env && ./scripts/geoip-refresh.sh >> /var/log/uv-geoip.log 2>&1
```

</details>

## 🔐 API и RBAC

После `POST /v1/auth/login` вы получаете `access_token` (Bearer) и `refresh_token` (`/v1/auth/refresh`).

| Роль | Возможности |
|------|--------------|
| `viewer` | Чтение хостов, поиск, CVE, дашборд |
| `operator` | + запуск и управление сканированиями |
| `admin` | + пользователи, аудит, настройки |

`GET /v1/me` · `GET /v1/version` · `GET /readyz` (проверка состояния + версия + коммит).

## 🤝 Участие в разработке

См. [CONTRIBUTING.md](https://github.com/yakushstanislav/ultraviolet/blob/master/CONTRIBUTING.md). Сообщения об уязвимостях: [SECURITY.md](https://github.com/yakushstanislav/ultraviolet/blob/master/SECURITY.md).
Стандарты сообщества: [CODE_OF_CONDUCT.md](https://github.com/yakushstanislav/ultraviolet/blob/master/CODE_OF_CONDUCT.md).

## 📄 Лицензия

UltraViolet распространяется под [лицензией MIT](https://github.com/yakushstanislav/ultraviolet/blob/master/LICENSE).

---

<p align="center">
  <sub>UltraViolet — обнаруживайте то, чем владеете, понимайте, что изменилось, и храните это в своей сети.</sub>
</p>
Скачать инструмент
Популярное

UltraViolet
