تم تصميم Maltrail لمراقبة الشبكة القائمة على المؤشرات. تكشف اكتشافاته الاستدلالية عن مسار المطابقة، لكنه ليس بديلاً عن القياس عن بُعد لنقاط النهاية أو نظام منع التسلل العام.

## الميزات

- بناء مسار كامل يجمع أكثر من 3,000 ملف ثابت مضمّن، و42 تكاملًا مع خلاصات عامة، ومسارات اختيارية يوفّرها المشغّل.
- مستشعر Rust متعدد الخيوط يستخدم libpcap، مع عمال التقاط Linux `PACKET_FANOUT` الاختياريين.
- خادم Python يوفّر واجهة التقارير، واستقبال الأحداث، وواجهة HTTP API.
- مسارات وقوائم بيضاء مخصّصة بنص عادي يمكن مراجعتها والتحكم في إصداراتها.
- استدلالات للفحص، واستنزاف DNS، وعمليات البحث الشبيهة بـ DGA، والتنزيلات المشبوهة، وفحوص الوكيل، وقيم User-Agent المشبوهة، والنشاط الشبكي ذي الصلة.
- تسجيل الأحداث محليًا، وتسجيل Maltrail عن بُعد، وCEF عبر syslog، وإخراج Logstash JSON.
- التحقق من صحة النشر باستخدام `maltrail-sensor -T` ومقاييس Prometheus الاختيارية.

## المحتويات

- [البنية](#architecture)
- [واجهة التقارير](#reporting-interface)
- [الأداء](#performance)
- [التثبيت](#installation)
  - [المثبّت](#installer)
  - [البناء من المصدر](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [الإعداد](#configuration)
- [المسارات](#trails)
- [الأحداث وواجهة API](#events-and-api)
- [العمليات](#operations)
  - [المراقبة](#monitoring)
  - [الاحتفاظ بالأحداث](#event-retention)
- [التوثيق](#documentation)
- [المساهمة](#contributing)
- [المشروع](#project)
  - [الترخيص](#license)
  - [المشرفون](#maintainers)
  - [الرعاة](#sponsors)
  - [العروض والمنشورات](#presentations-and-publications)
  - [القائمة السوداء المشتقة](#derived-blacklist)
  - [تكاملات الطرف الثالث](#third-party-integrations)
  - [شكر وتقدير](#acknowledgements)

## البنية

يتكوّن Maltrail من عمليتين مستقلتين قد تعملان على نفس المضيف أو على مضيفين منفصلين:```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

يُستخدم عامل التقاط واحد افتراضيًا. يمكن لعوامل إضافية زيادة سعة الالتقاط، لكن تجزئة تدفق Linux تقسم الحالة لكل مصدر بين العمال وبالتالي تقلل حساسية بعض استدلالات الفحص. في الاختبار الموثق، بقيت 91% من تنبيهات الاستدلال بعامل واحد مع عاملين، و86% مع أربعة، و65% مع ثمانية. لم يتغير المطابقة الدقيقة للأثر. لا تزد `CAPTURE_FANOUT` إلا عندما تُظهر مقاييس فقدان الالتقاط أن ذلك ضروري.

منهجية القياس المرجعي، ونتائج العتاد، ومخرجات المحلل، وقياسات الذاكرة، وفحوصات التوزيع الحية موثقة في [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md).

## التثبيت

### المثبّت

تم التحقق من المثبّت على اثنتي عشرة توزيعة Linux — Debian وUbuntu وFedora وRocky وAlmaLinux وArch وopenSUSE Leap وTumbleweed وAlpine — بالإضافة إلى FreeBSD وmacOS، في كل إصدار، مع تسجيل النتيجة الكاملة في [`docs/compat`](https://github.com/stamparm/maltrail/blob/master/docs/compat). تستخدم Raspberry Pi OS وأنظمة ARM الأخرى ذات 64 بت بناء `aarch64`؛ بينما لا يتوفر لـ ARM 32 بت مستشعر جاهز ويجب بناؤه من المصدر.```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

خيارات المثبّت الشائعة:```bash
sh install.sh --role sensor      # Install only the sensor
sh install.sh --ref 3.1.2        # Install a release tag instead of master
sh install.sh --no-service       # Install without changing systemd
sh install.sh --dry-run          # Print commands without applying them
sh install.sh --uninstall        # Remove the managed installation; keep logs and state

ثم قم ببناء المستشعر والتحقق من صحته:```bash
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail

cargo build --release --manifest-path sensor/Cargo.toml

sudo setcap cap_net_raw,cap_net_admin=eip \
  sensor/target/release/maltrail-sensor

sudo install -d -o "$USER" -g "$(id -gn)" -m 750 /var/log/maltrail

sensor/target/release/maltrail-sensor -T
sensor/target/release/maltrail-sensor

تُرفَق ملفات sensor الثنائية الجاهزة بالإصدارات الحالية مع مجاميع تحقق SHA-256: Linux `x86_64`
و `aarch64` مقابل كل من glibc و musl، و macOS على شرائح Apple و Intel، و FreeBSD `amd64`، و
Windows `x86_64`.

تربط إصدارات glibc مكتبة libpcap بشكل ثابت وتستهدف glibc 2.28، لذا فإن مكتبة C هي الشيء الوحيد
الذي تحتاجه — لا شيء لتثبيته، على RHEL 8+ و Debian 10+ و Ubuntu 18.04+ و Leap 15.x على حد سواء. إصدارات musl
ثابتة بالكامل، لذا لا تحتاج Alpine إلى أي شيء على الإطلاق. إصدار Windows هو 64-bit ويحتاج إلى Windows 10 أو أحدث بالإضافة إلى
[Npcap](https://npcap.com) مثبّتاً قبل أن يبدأ — `wpcap.dll` هو تبعية وقت التحميل،
لذا بدونه يرفض المُحمِّل الملف التنفيذي بدلاً من الفشل عند الالتقاط. الأرشيف يقول ذلك
أيضاً.

الملفات الثنائية من **3.1.1 وما قبلها** لم تفعل ذلك: كانت تربط libpcap ديناميكياً، وتطلبها بالاسم
الذي يستخدمه مضيف بناء AlmaLinux الخاص بها. تشحن Debian و Ubuntu المكتبة نفسها تحت
الاسم الأقدم `libpcap.so.0.8`، لذا تتوقف تلك الملفات الثنائية قبل أن تبدأ —```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file

### Systemd

تقوم وحدات `packaging/systemd/` المرفقة بتشغيل كلتا العمليتين تحت المستخدم غير المتميز `maltrail`. ينشئ Systemd الدليلين `/var/log/maltrail` و `/var/lib/maltrail`، ويقيد
الوصول إلى نظام الملفات، ويمنح المستشعر `CAP_NET_RAW` و `CAP_NET_ADMIN`.

يقوم المثبّت بتهيئة هذه الوحدات تلقائيًا. بالنسبة لتثبيت مصدري موجود، اتبع
إجراء الخدمة اليدوي في [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md).

تحقق من حالة الخدمة والسجلات باستخدام:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

تُوثَّق إعدادات الحاوية والتخزين والصلاحيات وفحوصات السلامة في
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/master/docker/README.md).

## الإعدادات

يقرأ Maltrail ملف `maltrail.conf`، الذي يحتوي على إعدادات منفصلة لكل من `[Sensor]` و`[Server]`. يضع المُثبِّت الإعدادات المُدارة في `/etc/maltrail.conf`.

تشمل خيارات المستشعر الشائعة الاستخدام ما يلي:

| الخيار | الغرض |
| --- | --- |
| `MONITOR_INTERFACE` | واجهة أو واجهات الالتقاط؛ يحدد `any` جميع الواجهات المدعومة |
| `CAPTURE_FILTER` | مرشح الالتقاط BPF |
| `CAPTURE_FANOUT` | عدد مقابس الالتقاط في Linux؛ القيمة الافتراضية واحد |
| `CAPTURE_WORKERS` | عمال الالتقاط، مقبس واحد لكل منهم؛ القيمة الافتراضية هي `CAPTURE_FANOUT`، أي واحد ما لم يُضبط أي منهما |
| `LOG_DIR` | دليل سجل الأحداث المحلي |
| `TRAILS_FILE` | قاعدة بيانات الآثار المُولَّدة |
| `LOG_SERVER` | خادم أحداث Maltrail البعيد |
| `SYSLOG_SERVER` | وجهة أو وجهات CEF syslog |
| `LOGSTASH_SERVER` | وجهة أو وجهات Logstash JSON |
| `STATS_ADDRESS` | مستمع مقاييس Prometheus؛ معطَّل ما لم يُضبط |
| `UPDATE_PERIOD` | الفاصل الزمني لتحديث الآثار |
| `STATIC_TRAILS_URL` | المصدر الذي تُجلب منه مجموعة الآثار الثابتة المُجمَّعة؛ ثبّتها على إصدار مؤرَّخ للتحكم في وقت وصول المحتوى الجديد |
| `USER_WHITELIST` | المؤشرات التي يديرها المشغّل والتي لا ينبغي أن تُنبِّه |
| `CUSTOM_TRAILS_DIR` | دليل الآثار الذي يديره المشغّل |
| `STATIC_TRAILS_DIR` | نسخة اختيارية من مستودع الآثار؛ تُستخدم فقط لعرض الاستشهاد بمصدر الأثر في واجهة المستخدم |

ينطبق `PROCESS_COUNT` على مستشعر Python المتقاعد وعلى مُخنِّق سجل الأحداث القديم؛ وهو **لا** يحدد عدد عمال مستشعر Rust. اضبط عمال الالتقاط باستخدام `CAPTURE_FANOUT` أو `CAPTURE_WORKERS` بدلاً من ذلك.

شغّل فحص النشر بعد تغيير الإعدادات:```bash
sensor/target/release/maltrail-sensor -T

وجّهه إلى إصدار `content-YYYYMMDD-HHMM` محدد بدلاً من ذلك لتثبيت نسخة، حتى لا يصبح نشر سيئ عالميًا على الفور. تُخزَّن المجموعة مؤقتًا بجوار `TRAILS_FILE`، وهو ما يجعل إعادة البناء دون اتصال أو في بيئة معزولة ممكنة؛ يتم التحقق من `sha256` المنشور قبل التنزيل، لذا فإن عملية نشر تُحدَّث أكثر مما يتغير المحتوى تنقل 65 بايت بدلاً من 11 ميغابايت، ويُرفض أي حمولة لا تطابق بصمتها لصالح النسخة المخزنة مؤقتًا.

ينشر `update_trails()` ملف `TRAILS_FILE` جديدًا بشكل ذرّي وفقط بعد بناء ناجح. يتم الإبلاغ عن التغذيات التي لا تُرجع شيئًا بالاسم، حتى لا تعتمد عملية نشر بصمت على مصدر تقاعد بهدوء.

أضف مؤشراتك الخاصة تحت `CUSTOM_TRAILS_DIR`، وأي شيء يجب ألا يُطلق حدثًا أبدًا إلى `USER_WHITELIST`. أبقِ كليهما خارج دليل التثبيت حتى لا تتمكن الترقية من الكتابة فوقهما.

تذهب مساهمات الآثار الثابتة إلى [stamparm/trails](https://github.com/stamparm/trails)؛ أما التغذيات الجديدة فتذهب هنا. في كلتا الحالتين يحتاج المؤشر إلى تصنيف ومصدر يمكن لأي شخص التحقق منه — راجع [المساهمة](#contributing).

## الأحداث وواجهة API

يسجّل Maltrail حدثًا واحدًا مفصولًا بمسافة بيضاء لكل اكتشاف، باستخدام اقتباس CSV حيث تحتوي القيمة على مسافات:```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

## التثبيت

### المتطلبات الأساسية

- Python 3.8 أو أحدث
- pip (مدير حزم Python)
- Git (اختياري، للاستنساخ)

### التثبيت السريع

```bash
# استنساخ المستودع
git clone https://github.com/yourusername/kitploit-tool.git
cd kitploit-tool

# إنشاء بيئة افتراضية
python3 -m venv venv
source venv/bin/activate  # على Windows: venv\Scripts\activate

# تثبيت التبعيات
pip install -r requirements.txt

# تثبيت الأداة
pip install -e .

pip install kitploit-tool

# بناء صورة Docker
docker build -t kitploit-tool .

# تشغيل الحاوية
docker run -it --rm kitploit-tool --help

# التحقق من الإصدار
kitploit-tool --version

# عرض المساعدة
kitploit-tool --help

# تشغيل الفحص الأساسي
kitploit-tool scan --target example.com

# تشغيل الفحص مع الإخراج المفصل
kitploit-tool scan --target example.com --verbose

# حفظ النتائج في ملف
kitploit-tool scan --target example.com --output results.json

# تحديد المنافذ
kitploit-tool scan --target example.com --ports 80,443,8080

# استخدام ملف التكوين
kitploit-tool scan --config config.yaml

# تشغيل الفحص المتوازي
kitploit-tool scan --target example.com --threads 10

kitploit-tool scan --target 192.168.1.1

kitploit-tool scan --target example.com --report detailed --format html

kitploit-tool scan --targets targets.txt --parallel

# إعدادات عامة
general:
  timeout: 30
  verbose: false
  log_level: INFO

# إعدادات الفحص
scan:
  ports: [80, 443, 8080, 8443]
  threads: 5
  retry: 3

# إعدادات الإخراج
output:
  format: json
  directory: ./results
  overwrite: false

# تعيين متغيرات البيئة
export KITPLOIT_TIMEOUT=60
export KITPLOIT_LOG_LEVEL=DEBUG
export KITPLOIT_OUTPUT_DIR=/path/to/output

حقل `confidence` (من 0 إلى 100، أو `null` عند عدم توفره) يوضح مدى قوة دعم المصادر للقائمة: 40 لمصدر تغذية واحد، و+15 لكل مصدر تغذية إضافي يتفق بشكل مستقل حتى 100، وعلامات كاملة لإدخالات المشغّل المخصصة والثابتة. يُحسب في وقت تحديث المسار من اتفاق مصادر التغذية إلى ملف جانبي `trails.confidence` بجوار `trails.csv`؛ والخادم الذي يسحب المسارات من `UPDATE_SERVER` ليس لديه مصدر بيانات لتقييمه ويُبلّغ عن `null`. استخدمه لترتيب أولويات الفرز - قائمة من مصدر تغذية واحد بدرجة 40 تستحق نظرة ثانية قبل أن تستحق قاعدة جدار حماية.

يمكن لبحث النطاق الفرعي أن يطابق النطاق الأصلي المدرج. تتحقق عمليات بحث URL من `host/path` قبل التحقق من المضيف وحده. يقرأ الخادم قاعدة بيانات المسارات المعيّنة في الذاكرة ويلاحظ تحديثات المسارات دون إعادة تشغيل.

تتوفر مسارات المصادر العامة والثابتة دون مصادقة، بما يتوافق مع نقطة النهاية `/trails` المستخدمة من قبل المستشعرات البعيدة. تتطلب المسارات المخصصة جلسة مصرّح بها؛ ويُبلّغ عن بحث مخصص فقط غير مصرّح به كفشل في المطابقة. تظل بيانات الأحداث تتطلب المصادقة.

## العمليات

### المراقبة

استخدم `maltrail-sensor -T` كبوابة للنشر والتهيئة. تشغّله وحدة systemd المرفقة كـ `ExecStartPre`.

للتأكد من أن الكشف نفسه يعمل — وليس فقط أن العمليات تبدأ — شغّل:```bash
python3 server.py --detect-test

`--keep` يعيد أيضًا تشغيل `sensor/tests/corpus/` إلى نفس السجل ويطبع أي من الأشكال التي تعرضها لوحة المعلومات بشكل مختلف لديها حدث خلفها، بحيث يكون الرمز أو اللون أو الحرف الرسومي المفقود مرئيًا بدلًا من افتراضه. يتم إزاحة الطوابع الزمنية بحيث يكون أحدث يوم هو اليوم. مطلوب ملف ثنائي للحساس (`cargo build --release --manifest-path sensor/Cargo.toml`).

يتم إعادة توليد بيانات العرض التوضيحي العام من تشغيل كهذا:```bash
python3 sensor/tools/gen_demo_js.py --from DIR/logs   # tops up html/js/demo.js

يقوم بتشغيل التنسيق، وClippy مع رفض التحذيرات، ومجموعات اختبارات وضعي التصحيح والإصدار. شغّل مجموعة خادم Python باستخدام:```bash
bash tests/run.sh python3

يتم تجميع المستشعر عبر المنصات باستخدام mingw-w64، واستخراج مكتبة Npcap الخاصة بمساحة المستخدم من مثبّتها
(أرشيف NSIS، لذا لا يتم تثبيت أي شيء)، وتشغيل النتيجة تحت Wine — مجموعة الاختبارات الكاملة،
`-T` مقابل الإعدادات المُرفقة، ومجموعة pcap تُقارن بايت ببايت مقابل الملف التنفيذي الأصلي،
والخادم يستجيب لـ `/ping` تحت Python الخاص بـ Windows. الالتقاط المباشر هو الشيء الوحيد الذي
لا يمكن تغطيته؛ فهو يحتاج إلى برنامج تشغيل النواة الخاص بـ Npcap وجهاز Windows حقيقي. المتطلبات الأساسية هي
`gcc-mingw-w64-x86-64` و`wine` و`p7zip-full`.

## المشروع

### الترخيص

**باختصار:** Maltrail مرخّص بموجب MIT، لكن مجموعة بيانات Maltrail Trails لها شروط منفصلة. البحث/المرجع المستقل عن مؤشرات الاختراق (IOC) مقبول؛ الاستخدام المنهجي لـ Trails كمصدر استخباراتي في منتج أو خدمة تجارية يتطلب إذنًا/ترخيصًا.

يُوزَّع Maltrail بموجب رخصة MIT. راجع [`LICENSE`](https://github.com/stamparm/maltrail/blob/master/LICENSE).

هذا هو المحرّك. مجموعة الـ trails الثابتة عمل منفصل بموجب شروط منفصلة: مجانية للاستخدام الدفاعي الداخلي،
والبحث والتدريس، لكن المنتج التجاري، أو الخدمة، أو عرض MSSP أو MDR، أو
موجز مُعاد توزيعه يحتاج إلى ترخيص. محرّك بترخيص MIT لا يجعل المحتوى مجانيًا للبيع — راجع
[`LICENSE.md`](https://github.com/stamparm/trails/blob/main/LICENSE.md) في
[stamparm/trails](https://github.com/stamparm/trails) قبل تضمينه في شيء تتقاضى مقابله
رسومًا.

### المشرفون

- Miroslav Stampar ([@stamparm](https://github.com/stamparm))
- Mikhail Kasimov ([@MikhailKasimov](https://github.com/MikhailKasimov))

### الرعاة

- [Sansec](https://sansec.io/) (2024–2025)
- [Sansec](https://sansec.io/) (2020–2021)

### العروض التقديمية والمنشورات

- الاجتماع السابع والأربعون لـ TF-CSIRT، براغ، 2016
  ([الشرائح](https://web.archive.org/web/20161109135211/https://www.terena.org/activities/tf-csirt/meeting47/M.Stampar-Maltrail.pdf))
- _Detect attacks on your network with Maltrail_، Linux Magazine، 2022
  ([المقال](https://www.linux-magazine.com/Issues/2022/258/Maltrail))
- _Best Cyber Threat Intelligence Feeds_، Silent Push، 2022
  ([المراجعة](https://www.silentpush.com/blog/best-cyber-threat-intelligence-feeds))
- _Research on Network Malicious Traffic Detection System Based on Maltrail_، Nanotechnology
  Perceptions، 2024
  ([الورقة البحثية](https://nano-ntp.com/index.php/nano/article/view/1915/1497))

### تكاملات الطرف الثالث

- [FreeBSD Port](https://www.freshports.org/security/maltrail)
- [OPNsense Gateway Plugin](https://github.com/opnsense/plugins/pull/1257)
- [D4 Project](https://www.d4-project.org/2019/09/25/maltrail-integration.html)
- [BlackArch Linux](https://github.com/BlackArch/blackarch/blob/master/packages/maltrail/PKGBUILD)
- [Validin](https://x.com/ValidinLLC/status/1719666086390517762)
- [Maltrail Add-on for Splunk](https://splunkbase.splunk.com/app/7211)
- [Maltrail decoder and rules for Wazuh](https://github.com/MikhailKasimov/maltrail-wazuh-decoder-and-rules)
- [GScan](https://github.com/grayddq/GScan) (trails فقط)
- [MalwareWorld](https://www.malwareworld.com/) (trails فقط)
- [oisd domain blocklist](https://oisd.nl/?p=inc) (trails فقط)
- [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json) (trails فقط)
- [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md) (trails فقط)
- [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables) (trails فقط)
- [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876) (trails فقط)
- [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json) (trails فقط)
- [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license) (trails فقط)
- [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed) (موصل trail)

### شكر وتقدير

- Thomas Kristner
- Eduardo Arcusa Les
- James Lay
- Ladislav Baco (@laciKE)
- John Kristoff (@jtkdpu)
- Michael Münz (@mimugmail)
- David Brush
- @Godwottery
- Chris Wild (@briskets)
- Keith Irwin (@ki9us)
- Simon Szustkowski (@simonszu)