yakushstanislav/ultravioletセルフホスト型のネットワークディスカバリおよび検索エンジンで、継続的なポートスキャン、約100のサービスにわたる深いプロトコルプロービング、ローカルCVEマッチング、インフラストラクチャのインベントリとリスク監視のための全文検索を備えています。
<div align="center">
# UltraViolet
**セルフホスト型ネットワーク探索＆検索 — あなたのハードウェア上で動く、あなた専用のShodan。**
TCP/UDPスキャン · 約100種のプロトコルプローブ · TLS/JARMフィンガープリント · CVEマッチング · 全文検索 · 差分追跡 · アラート
<br/>
[](service-api/)
[](service-frontend/)
[](service-env/)
[](service-env/)
[](.github/workflows/ci.yml)
[](LICENSE)
[クイックスタート](#-quick-start) ·
[機能](#-features) ·
[アーキテクチャ](#-architecture) ·
[ドキュメント](#-documentation) ·
[本番運用](#-production-checklist)
</div>
---
> **重要。** スキャンするのは、自分が所有するネットワーク、またはスキャンについて**書面による許可**を得たネットワークだけにしてください。UltraVioletは受動的なサービス偵察を行うものであり、脆弱性を悪用することはありません。
## UltraVioletを選ぶ理由
| ユースケース | 得られるもの |
|----------|--------------|
| 境界＆インベントリ管理 | CIDRレンジ全体にわたるオープンポートとサービスの継続的な発見 |
| インフラ検索 | HTTPボディ、バナー、TLS、DNS、CVEにわたる全文検索 |
| リスク＆コンプライアンス | ローカルNVDマッチングに加え、CISA KEVとEPSSに対応 — クラウド依存なし |
| エアギャップ環境での展開 | Dockerイメージ、CVEシード、GeoIP MMDBをディスクに保持するオフラインアーカイブ |
| 変更追跡 | スキャン間の差分、WebSocketイベント、保存済み検索に対するアラート |
シングルテナント、単一のDocker Composeスタック、データを完全にコントロール。
## ✨ 機能
**ディスカバリ**
- **masscan** または **zmap** を探索エンジンとして使用するTCPコネクトスキャナ
- 設定可能なポートへのUDPプローブ
- `SCAN_ALLOWED_CIDRS` によるスコープ指定と、ホスト・ポート数の制限
**ディーププローブ（約100プロトコル）**
- Web: 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…
- IoT＆メディア: 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＋リフレッシュトークン
- スキャンのスケジュール、一時停止／再開、ワーカー再起動後のオーファン回収
- 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` にプロキシします — **シングルオリジン**で、API URLごとのフロントエンド再ビルドは不要です。
| ディレクトリ | 目的 |
|-----------|---------|
| [`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、RAM約4 GB。本番イメージは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/scannerイメージは `service-api/bin/` からビルド済みバイナリをコピーします（Docker内では**コンパイルされません**）。`make dev` は `docker compose … --build` の前に `make -C service-api build-linux` を実行します。
```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（nginx `/api/` 経由でAPIへ） |
| http://localhost:8080 | API直接 |
| http://localhost:9090/metrics | Prometheus |
**開発用初期認証情報:** `admin` / `admin`（`APP_ENV≠production` の場合のみ）。
## 📖 ドキュメント
完全ガイド — [`service-documentation-frontend/docs/`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-documentation-frontend/docs) 内のVitePress:
```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 KB、オンライン） |
| `ultraviolet-vX.Y.Z-offline.tar.gz` | + amd64 Dockerイメージ |
| `ultraviolet-vX.Y.Z-offline-full.tar.gz` | + CVEシード + GeoIP MMDB |
**オンライン:** 展開 → `cp .env.example .env` → `./install.sh`（レジストリから取得）。
**オフライン:** `./install.sh`（`docker load`、pullなし）。アップグレード: `.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`）は固定してください — `postgres-data` Dockerボリュームはそれに紐づいています。
</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を更新する: 月次cronで [`service-env/scripts/geoip-refresh.sh`](https://github.com/yakushstanislav/ultraviolet/blob/master/service-env/scripts/geoip-refresh.sh) を実行。
<details>
<summary><strong>HTTPS、サブパスでのデプロイ、バックアップcron</strong></summary>
**外部nginxでのTLS終端** — UIをループバックのみにバインド:
```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更新**（毎月1日）:
```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` (health + version + commit)。
## 🤝 コントリビューション
[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>