OffSeq Threat Finder

threat-finder يكتشف البرمجيات المعرّضة للخطر قيد التشغيل فعليًا على المضيف — وليس ما تدّعيه قائمة الحزم (manifest) — ويخبرك أيّ النتائج يمكن الوصول إليها عبر الشبكة. يحوّل كل خدمة قيد التشغيل (ومع --scope all، كل حزمة نظام تشغيل مثبّتة) إلى Package-URL دقيق، ويطابقه مع كتالوج OffSeq Radar باستخدام قواعد إصدارات أصلية لكل نظام بيئي، بحيث لا يتم وضع علامة خاطئة على البنيات المُرتدّة/المصحّحة (backported/fixed) على أنها ثغرات.

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.

التثبيت

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) متوفرة في صفحة الإصدارات. يتطلب البناء من المصدر Rust ≥ 1.87. جميع أنظمة Linux وmacOS وأنظمة BSD وWindows مدعومة.

البدء السريع

export OFFSEQ_API_KEY=...    # from https://radar.offseq.com/console
threat-finder

يفحص الخدمات قيد التشغيل، ويعرض ملخصًا مرتّبًا حسب المخاطر، ويكتب تقرير JSON الكامل إلى /tmp/threats.json. أضف --scope all لفحص كل حزمة نظام تشغيل مثبّتة أيضًا.

الاستخدام

threat-finder [OPTIONS]

# 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)، ويُستخرج بالترتيب التالي:

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)، مرتّب حسب التعرض — دون الحاجة إلى إعادة فحص.

بعد فحص تفاعلي، تسأل الأداة:

Add these 42 services to Radar for continuous monitoring & alerts? [Y/n/never]

Y تسجّل هذا المضيف؛ n تتخطى هذه الجولة؛ never يحفظ اختيارك (يُحفظ في الإعدادات ولن تُسأل مرة أخرى). عند إعادة الفحص، يبلّغ أيضًا عن الانحراف (drift) (+added / -removed / ~changed) وأي نتائج جديدة منذ آخر فحص. يمكنك إدارة مضيفيك — تشغيل المراقبة وإيقافها، وعرض النتائج، وإلغاء التسجيل — من قسم Inventory في وحدة تحكم Radar.

للأتمتة، تجاوز الطلب: --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)؛ وتحذّر الأداة عندما يتجاوز المخزون الميزانية. (الاستعلامات مجمّعة مسبقًا؛ والكاش المحلي للنتائج موجود على خارطة الطريق.)

الدعم حسب نظام التشغيل

عندما لا تملك أي حزمة ملفًا تنفيذيًا، يتراجع الإصدار إلى استكشاف --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

التطوير

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 أو Apache-2.0، حسب اختيارك.