usbsnoop — متشمم مباشر لنقلات USB من خطافَي fentry

خلاصة مباشرة وملوّنة لحركة USB على مستوى النظام — مبنية على نقطتي الاختناق الشاملتين لـ URB اللتين تمر عبرهما جميع سائقات وحدات التحكم المضيفة، لذا تعمل على xHCI/EHCI/OHCI/dwc على حدٍّ سواء دون نقاط تتبع لكل وحدة تحكم ودون usbmon. محمولة بالكامل عبر CO-RE.

يربط lru_hash المُفهرس بمؤشر URB الحدثين معًا: يسجّل الإرسال (submit) وقت البدء، وتقرؤه عملية الإكمال لحساب زمن الاستجابة من الإرسال إلى الإكمال، ثم تحذفه. يحاكي هذا اقتران الطلب/الاستجابة في httpbody — SUBMIT هي «الطلب» (ما يرسله المضيف)، وCOMPLETE هي «الاستجابة» (ما يعيده الجهاز).

تُفكَّك حزمة SETUP ذات الثمانية بايتات في عمليات نقل التحكم إلى اسم الطلب القياسي (GET_DESCRIPTOR, SET_CONFIGURATION, …)؛ وتُعرض مراحل البيانات كنص عندما تبدو نصّية وكعرض سداسي عشري (hexdump) بخلاف ذلك.

المخرجات سطر واحد لكل حدث (مدمجة). عند أول ظهور لجهاز تُضاف له سطر دليل ▸ («ناقل-جهاز» bus-dev، vid:pid، المنتج، سرعة الارتباط)؛ وبعد ذلك يحمل كل صف وسم DEV القصير فحسب، فتبقى الأعمدة اليسرى متراصة وسهلة المسح تحت حركة المرور الكثيفة. يعرض كل صف الوقت والنوع (SUBMIT/CMPLT) ونوع النقل وepNdir وسهم الاتجاه (← من الجهاز إلى المضيف IN، → من المضيف إلى الجهاز OUT) وعدد البايتات والحالة وزمن الاستجابة وسائق النواة المالك، ثم · وأكثر التفاصيل إفادة (SETUP مفككة، أمر SCSI، أو معاينة حمولة قصيرة). مرِّر --hex للحصول على عرض سداسي عشري كامل متعدد الأسطر بدلاً من ذلك. تُلوَّن البايتات السداسية حسب صنف قيمتها (الخالية أزرق، ASCII القابلة للطباعة سماوي، المسافات البيضاء أخضر، بقية محرفات التحكم أرجواني، القيم العالية/غير ASCII صفراء) على طرفية TTY؛ أما الناتج المُمرَّر عبر pipe فبلا ألوان.

حالات الاستخدام

• هندسة عكسية للملحقات الطرفية — شاهد جهازًا وهو يتعرّف ويتبادل طلبات تحكم المورّد وتقارير HID مباشرة، دون متشمم عتادي أو إعداد usbmon. تُفكَّك حزم SETUP والحمولات بينما تجرّب على الجهاز.
• تصحيح أخطاء السائق / البرنامج الثابت — شاهد بالضبط الأوامر التي يرسلها سائقك أو تطبيقك إلى جهاز وما يعود منها، مع زمن الاستجابة من الإرسال إلى الإكمال في كل عملية نقل.
• فحص التخزين الشامل / SCSI — تُفكَّك أغلفة Bulk-Only Transport إلى أمر SCSI (READ(10) lba=… blocks=…, WRITE(10), CSW PASS/FAIL).
• التقاط الأخطاء — يُظهر --errors-only حالات التوقف (EPIPE)، وانتهاء المهلة، وbabble، وأخطاء CRC عبر جميع الأجهزة في آنٍ واحد.
• رصد الأجهزة الخبيثة — يبيّن الجهاز المُوصَل حديثًا ما يفعله لحظة التحاقه؛ وتظهر حقن HID بأسلوب BadUSB كتقارير INT أو كتابات تحكم SET_REPORT لم تكن أنت من أطلقها.
• التقاط للتحليل دون اتصال — يُصدر --json بصيغة NDJSON؛ مرِّر الناتج إلى jq أو إلى ملف لمقارنة الحمولات بين التشغيلات.
• فرز مشاكل الأداء — عند الخروج الموقوت تحصل على ملخص لكل جهاز ومدرج تكراري لزمن الاستجابة بمقياس log2 لتحديد الأجهزة البطيئة أو كثيرة الإرسال.

التثبيت

curl -fsSL https://yeet.cx | sh

ثم شغّله مباشرة من GitHub — يجلب yeet المثال ويبنيه لك دون الحاجة إلى استنساخ:

yeet run github:yeet-src/usbsnoop

البناء

للبناء من نسخة محلية بدلاً من ذلك:

make

يُفرغ BTF النواة في vmlinux.h (من أجل struct urb وusb_device ووصف الجهاز)، ثم يترجم. يتطلب clang وbpftool ونواة تدعم BTF.

التشغيل

yeet run .                              # all devices, runs until Ctrl-C
yeet run . -- --secs 30                 # stop after 30s (prints a summary)
yeet run . -- --vid 0x320f              # one vendor
yeet run . -- --vendor-id 0x046d --product-id 0xc52b # one device by id
yeet run . -- --bus 3 --dev 4           # one device by bus address
yeet run . -- --type control,int        # only these transfer types
yeet run . -- --no-data                 # metadata only, skip payload capture
yeet run . -- --max-data 64             # cap rendered payload at 64 bytes
yeet run . -- --errors-only             # only failed completions (stalls, timeouts)
yeet run . -- --hex                      # full multi-line hexdump per transfer
yeet run . -- --json | jq .             # NDJSON, one object per event

الخيارات

تتم جميع عمليات التصفية داخل النواة، لذا لا تصل حركة المرور المستبعَدة إلى مساحة المستخدم أبدًا.

ينتهي كل سطر حدث بسائق النواة المالك بين قوسين ([hid_irq_in]، [usb_api_blocking_completion]) — يُرمَّز urb->complete داخل النواة عبر bpf_snprintf("%ps")، فلا حاجة للبحث في /proc/kallsyms. تفكّك عمليات النقل الشامل من نوع Bulk غلاف Bulk-Only Transport إلى أمر SCSI (CBW READ(10) lba=… blocks=… / CSW PASS). عند الخروج الموقوت (بلوغ --secs) يُطبع ملخص لكل جهاز ومدرج تكراري لزمن الاستجابة بمقياس log2؛ أما الخروج عبر Ctrl-C فيتخطى ذلك (لا يتوفر خطاف إشارة مرئي في JS).

حمولات scatter-gather

غالبًا ما تُسلَّم النواة في حركة مرور Bulk (التخزين الشامل وأمثاله) مصفوفة struct scatterlist (urb->sg) بدلاً من transfer_buffer خطي واحد، لذا تنتشر الحمولة عبر الصفحات. يمشي usbsnoop عبر تلك المصفوفة وينسخ بايتات كل مقطع، لكن الوصول إليها يتطلب ترجمة الصفحة إلى عنوانها الافتراضي في النواة — وهو عكس page_to_virt في x86-64، الذي يحتاج page_offset_base وvmemmap_base للنواة الجارية (وكلاهما عشوائي عبر KASLR).

لا يمكن لبيئة JS المعزولة قراءة /proc/kallsyms ولا يدعم المحمِّل ksym، لذا تمرّر عنوانَي الرمزين وتقوم جهة BPF بفك الإشارة إليهما:

yeet run . -- \
  --page-offset-base 0x$(sudo awk '$3=="page_offset_base"{print $1}' /proc/kallsyms) \
  --vmemmap-base     0x$(sudo awk '$3=="vmemmap_base"{print $1}'     /proc/kallsyms)

بدون تلك الخيارات، تظل عمليات نقل SG تعرض البيانات الوصفية كاملة، لكن دون بايتات الحمولة — وهو السلوك السابق. هذا المسار خاص بـ x86-64 فقط: على البنى الأخرى اترك الخيارات معطّلة.

الحدود

• لا يُلتقط سوى أول 16384 بايتًا من كل عملية نقل (قوة للعدد اثنين — يعتمد مشبك القراءة في المدقِّق عليها). تُقتطع المخازن الأكبر حجمًا؛ وتظل الترويسة تُظهر الطول الحقيقي actual/requested. يحمل كل سجل حلقي data[16384] كاملة، لذا تتسع الحلقة البالغة 8 MiB لنحو 512 حدثًا.
• تتطلب حمولات scatter-gather خيارَي --page-offset-base / --vmemmap-base أعلاه ومضيف x86-64؛ يُلتقط كل مقطع حتى حجم صفحة، ويُمرّ على أول 64 مقطعًا فقط من أي عملية نقل.
• أي عملية نقل أُرسلت قبل التحاق usbsnoop لا تحمل طابع بدء، لذا لا يُعرض زمن استجابة عند إكمالها.
• أوصاف USB بصيغة little-endian وتُقرأ مباشرة — وهو صحيح على المضيفات ذات البنية little-endian التي تعمل عليها BPF.