whosthere

# Whosthere

[![Go Version](https://img.shields.io/github/go-mod/go-version/ramonvermeulen/whosthere)](https://go.dev/doc/devel/release)
[![License](https://img.shields.io/github/license/ramonvermeulen/whosthere)](LICENSE)
[![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/ramonvermeulen/whosthere/total)](https://github.com/ramonvermeulen/whosthere/releases)
[![GitHub Release](https://img.shields.io/github/v/release/ramonvermeulen/whosthere)](https://github.com/ramonvermeulen/whosthere/releases)
[![GitHub Repo stars](https://img.shields.io/github/stars/ramonvermeulen/whosthere)](https://github.com/ramonvermeulen/whosthere)

أداة اكتشاف الشبكة المحلية (LAN) مع واجهة مستخدم طرفية تفاعلية (TUI) مكتوبة بلغة Go.
اكتشف شبكتك المحلية واستكشفها وافهمها بطريقة بديهية.

يقوم Whosthere بإجراء **فحوصات متزامنة بدون صلاحيات مرتفعة** باستخدام ماسحات [**mDNS**](https://en.wikipedia.org/wiki/Multicast_DNS)
و[**SSDP**](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol). بالإضافة إلى ذلك، يقوم بمسح
الشبكة الفرعية المحلية عبر محاولة اتصالات TCP/UDP لتحفيز تحليل ARP، ثم يقرأ
[**ذاكرة ARP المؤقتة**](https://en.wikipedia.org/wiki/Address_Resolution_Protocol) لتحديد الأجهزة الموجودة على شبكتك المحلية.
تعمل هذه التقنية على ملء ذاكرة ARP المؤقتة دون الحاجة إلى صلاحيات مرتفعة. يتم إثراء جميع الأجهزة المكتشفة
بالبحث في [**OUI**](https://standards-oui.ieee.org/) لعرض الشركات المصنعة عند توفرها.

يوفر Whosthere طريقة ودية وبديهية للإجابة على السؤال الذي يطرحه كل مسؤول شبكة: "من الموجود على شبكتي؟"

![demo gif](https://assets.kitploit.com/production/public/readmes/11043/f5ed4cd52c401eadc086ff46c39e8c17319438e11c3e79902fc21019128e99e7.gif)

## الميزات

- **واجهة TUI تفاعلية:** تنقّل واستكشف الأجهزة المكتشفة بشكل بديهي.
- **سريع ومتزامن:** يستفيد من طرق اكتشاف متعددة في وقت واحد.
- **لا يتطلب صلاحيات مرتفعة:** يعمل بالكامل في مساحة المستخدم.
- **إثراء الأجهزة:** يستخدم البحث في [**OUI**](https://standards-oui.ieee.org/) لعرض الشركات المصنعة للأجهزة.
- **ماسح منافذ مدمج:** اكتشاف خدمات اختياري على المضيفين المكتشفين (افحص الأجهزة بإذن فقط!).
- **وضع الخدمة الخلفية مع HTTP API:** شغّله في الخلفية ودمجه مع أدوات أخرى.
- **السمات والتكوين:** خصّص المظهر والسلوك عبر تكوين YAML.

## التثبيت

عبر [**Homebrew**](https://brew.sh/) باستخدام `brew`:

```bash
brew install whosthere
```

على [**NixOS**](https://nixos.org/) باستخدام `nix`:

```bash
nix profile install nixpkgs#whosthere
```

على [**Arch Linux**](https://archlinux.org/) باستخدام `yay`:

```bash
yay -S whosthere-bin
```

إذا لم يكن مدير الحزم الخاص بك مدرجًا، يمكنك دائمًا التثبيت باستخدام [**Go**](https://go.dev/):

```bash
go install github.com/ramonvermeulen/whosthere@latest
```

أو **البناء من المصدر**:

```bash
git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build
```

بالإضافة إلى ذلك، يمكنك تنزيل ملفات ثنائية جاهزة من
[**صفحة الإصدارات**](https://github.com/ramonvermeulen/whosthere/releases).

## الاستخدام

شغّل واجهة TUI للاكتشاف التفاعلي:

```bash
whosthere
```

شغّله كـ cli لإجراء فحص واحد وإخراج النتائج:

```bash
whosthere scan -t 5
```

أخرج النتائج إلى ملف JSON:

```bash
whosthere scan -t 5 --json --pretty > devices.json
```

شغّله كخدمة خلفية مع HTTP API:

```bash
whosthere daemon --port=8080
```

استورد الأسماء المستعارة بشكل جماعي من ملف، أو صدّر الأسماء الحالية:

```text
whosthere aliases import ./aliases.yaml
whosthere aliases export --stdout
```

يمكن العثور على خيارات سطر الأوامر الإضافية عبر تشغيل:

```bash
whosthere --help
```

## اختصارات المفاتيح (TUI)

| المفتاح            | الإجراء                     |
| ------------------ | --------------------------- |
| `/`                | بدء البحث بالتعبير النمطي   |
| `k`                | أعلى                        |
| `j`                | أسفل                        |
| `g`                | الانتقال إلى الأعلى         |
| `G`                | الانتقال إلى الأسفل         |
| `y`                | نسخ IP للجهاز المحدد        |
| `Y`                | نسخ MAC للجهاز المحدد       |
| `enter`            | عرض تفاصيل الجهاز           |
| `CTRL+t`           | تبديل محدد السمة            |
| `CTRL+i`           | تبديل محدد الواجهة          |
| `CTRL+c`/`q`       | إيقاف التطبيق               |
| `ESC`              | مسح البحث / الرجوع          |
| `p` (عرض التفاصيل) | بدء فحص المنافذ على الجهاز  |
| `tab` (عرض النافذة) | تبديل تحديد الأزرار        |

## التكوين

يدعم Whosthere طرق تكوين متعددة بالأسبقية التالية (من الأعلى إلى الأدنى):

1. **أعلام سطر الأوامر** - أعلى أولوية. راجع `whosthere --help` للأعلام المتاحة.
1. **متغيرات البيئة** - بادئة `WHOSTHERE__`. راجع [**التكوين عبر متغيرات البيئة**](#configuration-via-environment-variables).
1. **ملف التكوين** - ملف تكوين YAML. راجع [**ملف التكوين**](#configuration-file).
1. **القيم الافتراضية** - القيم الافتراضية الاحتياطية. راجع `DefaultConfig()` في [**config.go**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/config/config.go).

### ملف التكوين

يبحث Whosthere عن ملف التكوين بالترتيب التالي، باستخدام أول ملف يتم العثور عليه:

1. المسار المحدد عبر علم `--config` أو متغير البيئة `WHOSTHERE_CONFIG`
1. `$XDG_CONFIG_HOME/whosthere/config.yaml` (إذا تم تعيين `XDG_CONFIG_HOME`)
1. `~/.config/whosthere/config.yaml` (الموقع الافتراضي)

**مثال على التكوين:**

```yaml
# Uncomment the next line to configure a specific network interface - uses OS default if not set
# network_interface: eth0

# When enabled, devices from all network interfaces are shown and persist when switching interfaces
# Note: if two interfaces share the same subnet (e.g. both use 192.168.1.x), devices may get merged
# since they are identified by IP address. Use with caution on overlapping subnets.
all_interfaces: false

# Optional IPv4 CIDR subnets to sweep. When set, the sweeper skips the auto-detected interface subnet unless it is listed here.
# target_subnets: ["10.0.0.0/24", "10.0.1.0/24"]

# WARNING: scanning subnets larger than /16 sends packets to 65535+ IPs per subnet. Enable only if you understand the traffic implications. Consider using smaller /24 subnets for targeted scanning.
# scan_large_subnets: false

# How often to run discovery scans
scan_interval: 20s

# Maximum timeout for each scan, recommended to be less than the scan interval
scan_timeout: 10s

scanners:
  mdns:
    enabled: true
  ssdp:
    enabled: true
  arp:
    enabled: true

sweeper:
  enabled: true
  interval: 5m
  timeout: 20s

port_scanner:
  timeout: 5s
  # List of TCP ports to scan on discovered devices
  tcp: [21, 22, 23, 25, 80, 110, 135, 139, 143, 389, 443, 445, 993, 995, 1433, 1521, 3306, 3389, 5432, 5900, 8080, 8443, 9000, 9090, 9200, 9300, 10000, 27017]

splash:
  enabled: true
  delay: 1s

theme:
  # When disabled, the TUI will use the terminal it's default ANSI colors
  # Also see the NO_COLOR environment variable to completely disable ANSI colors
  enabled: true

  # See the complete list of available themes at https://github.com/ramonvermeulen/whosthere/tree/main/internal/ui/theme/theme.go
  # Set name to "custom" to use the custom colors below
  # For any color that is not configured it will take the default theme value as fallback
  name: default

  # Disable ANSI colors completely, overrides theme.enabled
  # Can also be set via NO_COLOR or WHOSTHERE__THEME__NO_COLOR environment variables
  # no_color: false

  # Custom theme colors (uncomment and set name: custom to use)
  # primitive_background_color: "#000a1a"
  # contrast_background_color: "#001a33"
  # more_contrast_background_color: "#003366"
  # border_color: "#0088ff"
  # title_color: "#00ffff"
  # graphics_color: "#00ffaa"
  # primary_text_color: "#cceeff"
  # secondary_text_color: "#6699ff"
  # tertiary_text_color: "#ffaa00"
  # inverse_text_color: "#000a1a"
  # contrast_secondary_text_color: "#88ddff"

aliases:
  # Uncomment to import aliases.yaml into the local database on startup (only when it changed)
  # auto_import: false
  # Override the aliases file path - defaults to the app config directory
  # file: "/path/to/aliases.yaml"
```

## متغيرات البيئة

### متغيرات البيئة العامة

| المتغير            | الوصف                                                                           |
| ------------------ | ------------------------------------------------------------------------------- |
| `WHOSTHERE_CONFIG` | مسار ملف التكوين، لتتمكن من تجاوز الموقع الافتراضي.                              |
| `WHOSTHERE_LOG`    | تعيين مستوى السجل (مثل `debug`، `info`، `warn`، `error`). الافتراضي هو `info`.  |
| `NO_COLOR`         | تعطيل ألوان ANSI في واجهة TUI.                                                  |

### التكوين عبر متغيرات البيئة

أي خيار تكوين متاح في تكوين YAML، يمكن تعيينه عبر متغيرات البيئة باستخدام
بادئة `WHOSTHERE__` (لاحظ الشرطة السفلية المزدوجة). يتم فصل مفاتيح التكوين المتداخلة بشرطتين سفليتين،
والمفاتيح غير حساسة لحالة الأحرف.

أمثلة:

- `WHOSTHERE__SPLASH__ENABLED=false` - تعطيل شاشة البداية، مكافئ لـ `splash.enabled: false` في تكوين YAML
- `WHOSTHERE__SPLASH__DELAY=2s` - تعيين تأخير شاشة البداية إلى ثانيتين، مكافئ لـ `splash.delay: 2s` في تكوين YAML
- `WHOSTHERE__SCAN_INTERVAL=30s` - تعيين فاصل الفحص إلى 30 ثانية، مكافئ لـ `scan_interval: 30s` في تكوين YAML
- `WHOSTHERE__TARGET_SUBNETS=10.0.0.0/24,10.0.1.0/24` - تعيين الشبكات الفرعية المستهدفة، مكافئ لـ `target_subnets: ["10.0.0.0/24", "10.0.1.0/24"]` في تكوين YAML
- `WHOSTHERE__SCANNERS__MDNS__ENABLED=false` - تعطيل ماسح mDNS، مكافئ لـ `scanners.mdns.enabled: false` في تكوين YAML
- `WHOSTHERE__PORT_SCANNER__TCP=80,443,8080` - تعيين منافذ TCP المخصصة للفحص، مكافئ لـ `port_scanner.tcp: [80, 443, 8080]` في تكوين YAML
- `WHOSTHERE__THEME__NAME=cyberpunk` - تعيين السمة إلى cyberpunk، مكافئ لـ `theme.name: cyberpunk` في تكوين YAML

## الأسماء المستعارة للأجهزة

توجد الأسماء المستعارة في قاعدة بيانات [bbolt](https://github.com/etcd-io/bbolt) محلية في دليل الحالة. لتعيين
العديد منها دفعة واحدة، استوردها من ملف YAML (`aliases.yaml` في دليل التكوين؛ تجاوزه
بمفتاح التكوين `aliases.file` أو بوسيطة مسار).

الملف هو **تصحيح، وليس نسخة مطابقة**، ويُقرأ فقط: الاستيراد يضيف أو يحدّث عناوين MAC التي يحتويها
ويترك الأخرى دون تغيير، وتعديلات TUI **لا تُكتب أبدًا مرة أخرى إلى الملف**. استخدم `export` لإعادة
إنشائه.

```yaml
version: 1
aliases:
  aa:bb:cc:dd:ee:ff: "Living Room TV"
  de:ad:be:ef:00:01: "Office Printer"
```

- `version` هو إصدار تنسيق الملف؛ استخدم `1` (الملفات التي لا تحتويه تُعامل افتراضيًا كـ 1).
- يتم قبول عناوين MAC بأي تنسيق شائع وتطبيعها، لذا `AA:BB:CC:DD:EE:FF` و`aa-bb-cc-dd-ee-ff`
  و`aabbccddeeff` متكافئة. الاسم المستعار الفارغ (`""`) يمسح واحدًا.
- يتم تخطي عناوين MAC غير الصالحة والإبلاغ عنها؛ ويستمر باقي الاستيراد.

```bash
whosthere aliases import            # from the default location
whosthere aliases import ./aliases.yaml
whosthere aliases export            # to the default location
whosthere aliases export --stdout   # to stdout
```

اشترك في الاستيراد عند بدء التشغيل باستخدام `aliases.auto_import: true`. يتم التحقق من تجزئة الملف
ولا يُعاد استيراده إلا عند تغييره، لذا لا يطمس ملف لم يُمَس تعديلات TUI الخاصة بك — لكن **الملف
المتغيّر يستبدل** الأسماء المستعارة لكل عنوان MAC يحتويه. أبقِ الأسماء المستعارة الخاصة بـ TUI خارج الملف،
أو استخدم `export` بعد التحرير لإبقائه متزامنًا.

## واجهة HTTP API لوضع الخدمة الخلفية

عند تشغيل Whosthere في وضع الخدمة الخلفية، فإنه يعرض واجهة HTTP API مبسطة جدًا بالنقاط الطرفية التالية:

| الطريقة | النقطة الطرفية | الوصف                              |
| -------- | -------------- | ---------------------------------- |
| GET      | `/devices`     | الحصول على قائمة بجميع الأجهزة المكتشفة |
| GET      | `/device/{ip}` | الحصول على تفاصيل جهاز محدد        |
| GET      | `/health`      | فحص الحالة                         |

## السمات

يمكن تكوين السمة عبر ملف التكوين، أو في وقت التشغيل عبر اختصار المفتاح `CTRL+t`.
يمكن العثور على قائمة كاملة بالسمات المتاحة [**هنا**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go)، لا تتردد في فتح PR لإضافة سمتك الخاصة!

مثال على تكوين السمة:

```yaml
theme:
  enabled: true
  name: cyberpunk
```

عند تعيين `name` إلى `custom`، يمكن استخدام خيارات الألوان الأخرى لإنشاء سمتك المخصصة.
عند تعيين خيار `enabled` إلى `false`، ستستخدم واجهة TUI ألوان ANSI الافتراضية للطرفية.
عند تعيين متغير البيئة `NO_COLOR`، سيتم تعطيل جميع ألوان ANSI.

## التسجيل

تُكتب السجلات في دليل حالة التطبيق:

- `$XDG_STATE_HOME/whosthere/app.log` (إذا تم تعيين `XDG_STATE_HOME`)
- `~/.local/state/whosthere/app.log` (احتياطي Linux/MacOS)
- `%LOCALAPPDATA%/whosthere/app.log` (احتياطي Windows)

عند عدم التشغيل في وضع TUI، تُكتب السجلات أيضًا إلى وحدة التحكم.

## المنصات

Whosthere مدعوم على المنصات التالية:

- [x] Linux
- [x] macOS
- [x] Windows

## المشكلات المعروفة

لكي تعمل وظيفة الحافظة، يتم استخدام [**نسخة متفرعة من go-clipboard**](https://github.com/dece2183/go-clipboard).
تأكد من تثبيت أداة النسخ المناسبة لنظام التشغيل الخاص بك:

| نظام التشغيل                          | أدوات النسخ المدعومة                         |
| -------------------------------------- | -------------------------------------------- |
| Darwin                                 | `pbcopy`                                     |
| Windows                                | `clip.exe`                                   |
| Linux/FreeBSD/NetBSD/OpenBSD/Dragonfly | X11: `xsel`، `xclip` <br> Wayland: `wl-copy` |

## إخلاء المسؤولية

Whosthere مخصص للاستخدام على الشبكات التي لديك إذن بإجراء اكتشاف وفحص الشبكة عليها،
مثل شبكتك المنزلية الخاصة. قد يكون الفحص غير المصرح به للشبكات غير قانوني وغير أخلاقي.
احصل دائمًا على التصريح المناسب قبل استخدام هذه الأداة على أي شبكة.

تم إنشاء هذه الأداة بشكل أساسي لأغراض تعليمية واستكشاف الشبكات المنزلية. على الرغم من أنها
وظيفية ومفيدة، إلا أنه لا ينبغي اعتبارها حلاً احترافيًا لمراقبة الشبكات. تستند النتائج
إلى تقنيات فحص بدون صلاحيات مرتفعة وقد لا تكون شاملة. لتحليل الشبكات الحرج
أو تقييمات الأمان، فكّر في استخدام أدوات احترافية راسخة مع دعم رسمي.

## المساهمة

المساهمات والاقتراحات مثل طلبات الميزات وتقارير الأخطاء أو التحسينات مرحب بها!
لا تتردد في فتح المشكلات أو تقديم طلبات السحب على مستودع GitHub.
يرجى التأكد من مناقشة أي تغييرات كبيرة في مشكلة على Github قبل تنفيذها.