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)
[بدء سريع](#بدء-سريع) ·
[الميزات](#الميزات) ·
[البنية](#البنية) ·
[الوثائق](#الوثائق) ·
[قائمة التحقق للإنتاج](#قائمة-التحقق-للإنتاج)
</div>
---
> **مهم.** افحص فقط الشبكات التي تملكها أو لديك **إذن كتابي** لفحصها. ينفّذ UltraViolet استطلاعًا سلبيًا للخدمات — فهو لا يستغل الثغرات.
## لماذا UltraViolet؟
| حالة الاستخدام | ما الذي تحصل عليه |
|----------|--------------|
| حدود الشبكة والجرد | اكتشاف مستمر للمنافذ والخدمات المفتوحة عبر نطاقات CIDR |
| البحث في البنية التحتية | بحث نصي كامل عبر محتوى HTTP واللافتات وTLS وDNS والثغرات (CVEs) |
| المخاطر والامتثال | مطابقة محلية مع 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 وتجزئة favicon و`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 + رموز التحديث
- جدولة عمليات الفحص، إيقاف مؤقت/استئناف، استعادة المهام اليتيمة بعد إعادة تشغيل العامل
- 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
```
صورة واجهة المستخدم في الإصدار توجّه `/api/` و`/realtime` إلى `uv-api` — **أصل واحد**، دون إعادة بناء للواجهة الأمامية لكل عنوان 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 ≥ 24 وذاكرة ~4 جيجابايت RAM. صور الإنتاج موجهة لنظام 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) في موقع الوثائق.
### التطوير من المصدر
تنسخ صور الواجهة البرمجية والماسح الضوئي الملفات الثنائية المجمّعة مسبقًا من `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 | واجهة المستخدم (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` على نطاقات واجهة المستخدم الفعلية فقط.
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 خارجي** — اربط واجهة المستخدم بالحلقة المحلية (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` | قراءة المضيفين، البحث، الثغرات (CVEs)، لوحة المعلومات |
| `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>