offseq/threat-finderماسح ثغرات وقت التشغيل: يكتشف ثغرات CVE في الخدمات الفعلية قيد التشغيل على مضيف ويصنّفها حسب درجة التعرّض للشبكة.
# OffSeq Threat Finder
[](https://github.com/offseq/threat-finder/actions/workflows/ci.yml)
[](https://crates.io/crates/threat-finder)
[](https://docs.rs/threat-finder)
[](#license)
**threat-finder** يكتشف البرمجيات المعرّضة للخطر _قيد التشغيل فعليًا_ على المضيف — وليس ما تدّعيه قائمة الحزم (manifest) — ويخبرك أيّ النتائج **يمكن الوصول إليها عبر الشبكة**. يحوّل كل خدمة قيد التشغيل (ومع `--scope all`، كل حزمة نظام تشغيل مثبّتة) إلى [Package-URL](https://github.com/package-url/purl-spec) دقيق، ويطابقه مع كتالوج [OffSeq Radar](https://radar.offseq.com) باستخدام قواعد إصدارات أصلية لكل نظام بيئي، بحيث لا يتم وضع علامة خاطئة على البنيات المُرتدّة/المصحّحة (backported/fixed) على أنها ثغرات.
```text
Vulnerability summary (highest risk first):
openssh-server@1:8.9p1-3ubuntu0.6 — 1 finding(s) [PUBLIC tcp 0.0.0.0:22]
[ACT-NOW 92] HIGH CVE-2024-6387 [KEV] regreSSHion: remote code execution in OpenSSH
→ fix: 1:8.9p1-3ubuntu0.10 https://radar.offseq.com/threat/…
[email protected] — 1 finding(s)
[SCHEDULE 41] MED CVE-2023-44487 HTTP/2 Rapid Reset
2 confirmed finding(s) across 2 asset(s); 1 exposed, 1 known-exploited.
```
## التثبيت
```sh
brew install offseq/tap/threat-finder # Homebrew (macOS/Linux), prebuilt
cargo binstall threat-finder # prebuilt binary, no toolchain
cargo install threat-finder # from source
```
الأرشيفات المجمّعة مسبقًا لأنظمة Linux وmacOS (x86_64 + arm64) وWindows (x86_64) متوفرة في [صفحة الإصدارات](https://github.com/offseq/threat-finder/releases/latest). يتطلب البناء من المصدر Rust ≥ 1.87. جميع أنظمة Linux وmacOS وأنظمة BSD وWindows مدعومة.
## البدء السريع
```sh
export OFFSEQ_API_KEY=... # from https://radar.offseq.com/console
threat-finder
```
يفحص الخدمات قيد التشغيل، ويعرض ملخصًا مرتّبًا حسب المخاطر، ويكتب تقرير JSON الكامل إلى `/tmp/threats.json`. أضف `--scope all` لفحص كل حزمة نظام تشغيل مثبّتة أيضًا.
## الاستخدام
```sh
threat-finder [OPTIONS]
```
| العلامة | الوصف |
|------|-------------|
| `-o, --output <PATH>` | كتابة تقرير JSON إلى `PATH` (الافتراضي: طلب إدخال، أو `/tmp/threats.json`) |
| `--json` | طباعة تقرير JSON إلى stdout بدلاً من ملف |
| `--scope <SCOPE>` | `running` (الافتراضي) أو `all` (+ كل حزمة نظام تشغيل مثبّتة) |
| `--severity <LEVEL>` | الإبلاغ فقط عن النتائج بمستوى `critical\|high\|medium\|low` أو أعلى |
| `--strict` | تجاهل النتائج غير المؤكَّدة على مستوى الإحداثيات (الإبلاغ عن المؤكَّد فقط) |
| `--fail-on <WHAT>` | الخروج بالرمز `5` إذا وُجدت نتائج مطابقة: `any\|critical\|high\|medium\|low\|kev\|exposed` |
| `--sarif <PATH>` | كتابة تقرير SARIF 2.1.0 أيضًا (لواجهات فحص الكود) |
| `--include <GLOB>` / `--exclude <GLOB>` | تصفية الأصول حسب نمط glob للاسم (قابل للتكرار) |
| `-q, --quiet` | إخفاء اللافتة (banner) والتقدم والملخص |
| `--no-color` | تعطيل ألوان ANSI |
| `-y, --yes` | اعتماد القيم الافتراضية دون أي طلب إدخال (CI/cron) |
| `--reset` | إعادة إدخال مفتاح API متجاهلاً المفتاح المحفوظ |
| `--register` | تسجيل المضيف المفحوص لدى Radar للمراقبة المستمرة (بدون طلب إدخال) |
| `--no-register` | عدم التسجيل أو طلب المراقبة في هذه الجولة |
| `--host-name <NAME>` | اسم مضيف مخصص يُرسَل مع التسجيل |
| `--unregister` | إزالة مخزون هذا المضيف من Radar والخروج |
| `--windows-missing-updates` | (Windows) سرد تحديثات الأمان المعلّقة من Windows Update Agent أيضًا (فحص عبر الإنترنت؛ شغّله بصلاحيات مرتفعة) |
| `-h, --help` / `-V, --version` | المساعدة / الإصدار |
```sh
# CI: only high+ findings, JSON to stdout, no prompts
OFFSEQ_API_KEY=… threat-finder --yes --json --severity high > report.json
# Fail the build only when a network-exposed service has a known-exploited CVE
OFFSEQ_API_KEY=… threat-finder --yes --quiet --fail-on exposed
```
**رموز الخروج:** `0` نجاح · `1` خطأ بحث/إدخال-إخراج · `2` لا يوجد مفتاح API · `3` نظام تشغيل غير مدعوم · `4` تجاوز حد المعدل/الحصة، أو مطلوب وصول إلى API (يلزم ترقية) · `5` تم بلوغ عتبة `--fail-on`.
**مفتاح API** (يمكنك الحصول عليه من [وحدة تحكم Radar](https://radar.offseq.com/console))، ويُستخرج بالترتيب التالي:
1. متغير البيئة `OFFSEQ_API_KEY` (الأفضل لـ CI/cron).
2. المفتاح المحفوظ في `$XDG_CONFIG_HOME/offseq-rust/config.toml` (`0600`)، ما لم يُمرَّر `--reset`.
3. طلب إدخال تفاعلي مخفي على طرفية TTY — ثم يُحفظ للمرة القادمة.
في الوضع غير التفاعلي (`--yes` / بدون TTY) ومع عدم توفر مفتاح، يُخرج البرنامج بالرمز `2`.
اضبط `OFFSEQ_CONFIG_DIR` لتغيير مكان التخزين (الافتراضي: مجلد الإعدادات الخاص بالمستخدم في نظام التشغيل) — مفيد للحاويات/CI التي تحتاج مسارًا ثابتًا.
## كيف يعمل
**المطابقة بالإحداثيات الدقيقة.** يتحول كل أصل إلى purl يحمل _الإصدار الكامل_ (epoch + مراجعة التوزيعة) ومُعدِّل `?distro=`، مثل `pkg:deb/ubuntu/openssh-server@1:8.9p1-3ubuntu0.6?distro=jammy`. تتم مطابقة المخزون عبر استدعاءات مجمّعة `POST /match/batch` (طلب واحد لكل شريحة بحجم الطبقة) **من جانب الخادم، مع قواعد إصدارات أصلية لكل نظام بيئي** (dpkg/rpm/apk/semver) — لذا فإن البنية المرتدّة والمصحّحة مثل `1.18.0-6+deb11u3` لا يتم وضع علامة خاطئة عليها، ولا يوجد أي تخمين للإصدارات من جانب العميل. تُقسَّم النتائج حسب علامة `confirmed` في API: النتائج المؤكدة يتم الإبلاغ عنها؛ أما مطابقات الإحداثيات التي لا يمكن تأكيد إصدارها فتظهر منفصلة كـ **غير مؤكدة / فرز أولي (triage)** (مستبعدة من العدد، ومن `byCve`، ومن `--fail-on`؛ يمكنك التخلص منها باستخدام `--strict`).
**ربط التعرض للشبكة.** أدوات فحص قوائم الحزم (Trivy, Grype, osv-scanner) تقرأ قوائم الحزم؛ أما أدوات الفحص الخارجية (Nessus, OpenVAS) فتحتاج مضيفًا ثانيًا. تعمل هذه الأداة على ربط عملية كل خدمة قيد التشغيل بالمآخذ (sockets) التي **تستمع** عليها (`/proc/net` في Linux، و`lsof` في أنظمة Unix الأخرى، و`Get-NetTCPConnection` / `netstat` في Windows) وتصنّف قابلية الوصول — `loopback` / `private` / `public`. الخدمة المعرّضة للخطر على `0.0.0.0` تمثل خطرًا مختلفًا تمامًا عن تلك الموجودة على `127.0.0.1`: تُرتَّب النتائج بحيث تظهر المكشوفة أولًا، و`--fail-on exposed` يضبط CI على هذا بالضبط. لا تُرسَل أي حزم. تحمل النتائج أيضًا **KEV** الصادر عن CISA و**EPSS**.
**تحديد الأولويات حسب التعرض.** تحصل كل نتيجة على `riskScore` (0–100) ونطاق `decision` على غرار SSVC — **`act-now` · `soon` · `schedule` · `track`** — مدمج من الخطورة وEPSS وKEV و**التعرض الشبكي** للأصل المعني. يبدأ الملخص كل سطر بشارة من نمط `[ACT-NOW 92]` ويُرتبه حسبها، بحيث تطفو المشكلات العامة المواجهة للإنترنت والمعروفة بالاستغلال إلى أعلى مضيف مزدحم بالنتائج. تستخدم الدرجة نفس الصيغة محليًا ومن جانب الخادم (تضيف شاشة مراقبة Radar مكافأة صغيرة عندما تتجاوز نتيجة KEV تاريخ استحقاقها — وهو تاريخ لا تملكه واجهة CLI)، وتظهر في `--json` وSARIF (`properties`).
## المراقبة المستمرة
الفحص لمرة واحدة هو لقطة زمنية. سجّل مضيفًا مرة واحدة وسيبقى Radar يراقب: عندما تؤثر **CVE منشورة حديثًا** على أحد إحداثياته، يصلك تنبيه (بريد إلكتروني + Console)، مرتّب حسب التعرض — دون الحاجة إلى إعادة فحص.
بعد فحص تفاعلي، تسأل الأداة:
```text
Add these 42 services to Radar for continuous monitoring & alerts? [Y/n/never]
```
`Y` تسجّل هذا المضيف؛ `n` تتخطى هذه الجولة؛ `never` يحفظ اختيارك (يُحفظ في الإعدادات ولن تُسأل مرة أخرى). عند إعادة الفحص، يبلّغ أيضًا عن **الانحراف (drift)** (`+added / -removed / ~changed`) وأي نتائج **جديدة منذ آخر فحص**. يمكنك إدارة مضيفيك — تشغيل المراقبة وإيقافها، وعرض النتائج، وإلغاء التسجيل — من قسم **Inventory** في [وحدة تحكم Radar](https://radar.offseq.com/console).
للأتمتة، تجاوز الطلب: `--register` يسجّل بطريقة غير تفاعلية (مغلق افتراضيًا في CI)، و`--no-register` يختار عدم التسجيل، و`--host-name <NAME>` يضع اسمًا للمضيف، و`--unregister` يزيله. يوجد معرّف مضيف ثابت لكل مضيف وتفضيلك للطلب في `$XDG_CONFIG_HOME/offseq-rust/config.toml`. لا يغيّر التسجيل رمز الخروج أبدًا — فلن يفشل فحصك بسبب خلل بسيط في المراقبة. يتطلب خطة Basic/Pro/Enterprise (أو Pro Console).
## النطاق والتغطية
`--scope running` (الافتراضي) يفحص الخدمات الحية — المجموعة الصغيرة عالية الإشارة التي يمكن ربط تعرضها. `--scope all` يعدّ أيضًا **كل حزمة نظام تشغيل مثبّتة** (`dpkg`/`rpm`/`pacman`/`apk`/`brew`/`pkg`/`pkg_info`)، مما يوسّع السطح المطابق 10–50×. الحزمة التي تشغّل أيضًا عملية حية ومكشوفة تحتفظ بذلك التعرض (تتم إزالة التكرارات ودمج الأصول حسب الإحداثي). تتم تغطية النواة كحزمة خاصة بها (`linux-image…`) ضمن `--scope all`.
> يمكن أن يُنتج `--scope all` مئات إلى آلاف الحزم. في الخطة المجانية (15 استعلامًا/ساعة) سيؤدي ذلك إلى تجاوز حد المعدل (rate-limit)؛ وتحذّر الأداة عندما يتجاوز المخزون الميزانية. (الاستعلامات مجمّعة مسبقًا؛ والكاش المحلي للنتائج موجود على خارطة الطريق.)
## الدعم حسب نظام التشغيل
| نظام التشغيل | الاكتشاف | مصدر الإحداثيات |
|----|-----------|-------------------|
| Linux (systemd) | `ListUnits` → `/proc/<pid>/exe` | dpkg / rpm / pacman / apk |
| Linux (SysV/OpenRC) | `service --status-all` / `rc-status` | قاعدة بيانات الحزم |
| macOS | `launchctl list` → `ps` (لجهات خارجية فقط) | Homebrew |
| FreeBSD / DragonFly | `service -e` | `pkg` |
| OpenBSD | `rcctl ls started` | `pkg_info` |
| NetBSD | `/etc/rc.d` status | `pkg_info` |
| Solaris / illumos | `svcs` → `svcprop` | استكشاف (`--version`) |
| Windows | `Win32_Service` → `Get-NetTCPConnection` / `netstat` | سجل النظام / winget / Appx / Chocolatey / Scoop → CPE; npm / pip / dotnet → purl; بناء نظام التشغيل → CPE |
عندما لا تملك أي حزمة ملفًا تنفيذيًا، يتراجع الإصدار إلى استكشاف `--version` محصّن (بمسار مطلق فقط، وبيئة مُنقّاة). في macOS، يتم تخطي خدمات Apple النظامية (`com.apple.*`، والمسارات المحمية بـ SIP) — لأنها مغطاة بإصدار نظام التشغيل، وفحص مئات منها لا طائل منه.
في **Windows**، يتم جمع كل شيء عبر `powershell.exe` المدمج (بدون أي بيئة تشغيل إضافية، وبدون صلاحيات مسؤول للمخزون الأساسي). يتم ربط التطبيقات المثبتة بمعرّفات NVD CPE عبر جدول أسماء منسّق (التطبيقات غير المرتبطة تلجأ إلى بحث بالاسم بدلاً من تخمين خاطئ)؛ ويصبح إصدار/بناء نظام التشغيل معرّف CPE لنظام تشغيل مؤهل بالميزات (مثل `windows_11_23h2`)؛ ويضيف `--windows-missing-updates` إشعارًا اختياريًا من Windows Update Agent بالتحديثات الأمنية المعلّقة.
## المخرجات
JSON، بمفاتيح حتمية (مرتّبة) وبدون طابع زمني، بحيث تظهر الفروقات بين التقارير بشكل نظيف:
- **`services`** — `pkg@version` → النتائج المؤكدة (`cveId`, `severity`, `cvssScore`, `epss`, `kev`, `riskScore`, `decision`, `confirmed`, `matchedRange`, `matchBasis`, `fixedVersions`, `remediation`, `cwes`, `references`, `radarUrl`)، حسب الأعلى خطرًا أولًا.
- **`unconfirmed`** — مطابقات الإحداثيات التي تعذّر تأكيد إصدارها (فرز أولي triage).
- **`assets`** — `pkg@version` → `{ exe, versionSource, exposed, reachability, listeners }` (`versionSource` = `package-db` | `probe`؛ `reachability` يغطي TCP **و** UDP).
- **`byCve`** — كل CVE مجمّعة عبر كل الأصول المتأثرة ("صحّح مرة واحدة، أصلح الكثير").
- **`errors`** — إخفاقات البحث لكل أصل، بحيث لا يبدو الإخفاق أبدًا وكأنه "نظيف".
- **`registration`** — موجود عند تسجيل الجولة للمضيف: `host_id`, `monitoring`, `drift`, `summary`, `newSinceLastCount`.
- **`meta`** — `{ tool, version, schemaVersion }` (`schemaVersion` 2).
تقرير SARIF 2.1.0 (`--sarif`) متاح أيضًا لواجهات فحص الكود.
## منظومة OffSeq
| | |
|---|---|
| [**OffSeq**](https://offseq.com) | تدقيقات أمنية في الاتحاد الأوروبي، مراقبة التهديدات، CISO كخدمة، الامتثال لـ NIS2 |
| [**Radar**](https://radar.offseq.com) | استخبارات التهديدات في الوقت الفعلي — الكتالوج الذي تطابقه threat-finder |
| [**Radar Console**](https://radar.offseq.com/console) | الاشتراكات والخلاصات المخصصة ومفتاح `OFFSEQ_API_KEY` الخاص بك |
| [**Radar API**](https://radar.offseq.com/api-docs) | وثائق REST لنقطة النهاية `/match` المستخدمة هنا |
| [**Radar Threats**](https://radar.offseq.com/threats) | قاعدة بيانات قابلة للبحث لـ CVE والبرمجيات الخبيثة والجهات الفاعلة في التهديدات |
| [**Radar Feeds**](https://radar.offseq.com/feeds) | خلاصات مخصصة تجمع CISA وCIRCL وThreatFox و... |
| [**Radar Pricing**](https://radar.offseq.com/pricing) | من الخطة المجانية إلى Enterprise |
| [**Breach**](https://breach.offseq.com) | مراقبة تسريبات بيانات الويب المظلم وبيانات الاعتماد المكشوفة |
| [**Veil**](https://veil.offseq.com) | إخفاء بيانات PNG من جهة العميل (AES-256-GCM) |
| [**Guard**](https://offseq.com/guard/) | محلل أمان وامتثال لمواقع الويب بالذكاء الاصطناعي |
| [**Training**](https://training.offseq.com) | دورات أمنية وخصوصية معتمدة من PECB |
## التطوير
```sh
cargo build --release
cargo test # unit tests
cargo test -- --ignored # + macOS live-discovery smoke test
cargo clippy --all-targets
```
المحرك هو حزمة مكتبية (crate) باسم `find_threats` مع تجريد `Collector` (خدمات قيد التشغيل وحزم نظام التشغيل حاليًا؛ وملفات lockfiles / الحاويات / SBOM لاحقًا)، لذا فإن الملف التنفيذي هو مجرد CLI رفيع فوقه.
## الترخيص
مرخّص بترخيص مزدوج بموجب [MIT](https://github.com/offseq/threat-finder/blob/main/LICENSE) أو [Apache-2.0](https://github.com/offseq/threat-finder/blob/main/LICENSE)، حسب اختيارك.