usbsnoop — 2つのfentryフックを使用したライブUSB転送スニファ

システム全体のUSBトラフィックをリアルタイムで色分け表示 — すべてのホストコントローラドライバが通過する2つの汎用URBチョークポイントに基づいて構築されているため、xHCI/EHCI/OHCI/dwcで動作し、コントローラごとのトレースポイントやusbmonは不要です。完全にCO-REポータブル。

URBポインタをキーとするlru_hashが2つを結合します。サブミットは開始時刻を記録し、完了時にその時刻を読み出してサブミット→完了のレイテンシを計算し、削除します。これはhttpbodyのリクエスト/レスポンスペアリングを反映しています — SUBMITが「リクエスト」（ホストが送信するもの）、COMPLETEが「レスポンス」（デバイスが返すもの）です。

コントロール転送では、8バイトのSETUPパケットがデコードされ、標準的なリクエスト名（GET_DESCRIPTOR, SET_CONFIGURATIONなど）が表示されます。データステージは、テキストのように見える場合はテキストとして表示され、それ以外の場合は16進ダンプとして表示されます。

出力はイベントごとに1行（コンパクト）。デバイスが初めて出現すると、▸凡例行（bus-dev、vid:pid、製品名、リンク速度）が表示されます。その後は各行に短いDEVタグのみが付くため、左側の列は揃ったままで、トラフィックが多い場合でもスキャンしやすくなります。各行には、時刻、種類（SUBMIT/CMPLT）、転送タイプ、epNdir、方向矢印（← デバイス→ホストIN、→ ホスト→デバイスOUT）、バイト数、ステータス、レイテンシ、所有するカーネルドライバ、そして·の後に最も有用な詳細（デコードされたSETUP、SCSIコマンド、または短いペイロードプレビュー）が表示されます。代わりに完全な複数行16進ダンプを表示するには--hexを指定します。16進バイトはTTY上では値クラスごとに色分けされます（nullは青、印字可能ASCIIはシアン、空白は緑、その他の制御文字はマゼンタ、高位/非ASCIIは黄）。パイプ出力ではプレーンです。

ユースケース

• 周辺機器のリバースエンジニアリング — ハードウェアスニファやusbmonのセットアップなしで、デバイスの列挙、ベンダーコントロールリクエスト、HIDレポートのやり取りをライブで監視できます。デバイスを操作すると、SETUPパケットとペイロードがデコードされます。
• ドライバ/ファームウェアのデバッグ — ドライバやアプリがデバイスに送信するコマンドとその応答を、各転送のサブミット→完了レイテンシとともに正確に確認できます。
• マスストレージ/SCSIの検査 — Bulk-Only TransportラッパーがSCSIコマンド（READ(10) lba=… blocks=…, WRITE(10), CSW PASS/FAIL）にデコードされます。
• エラーの検出 — --errors-onlyを使用すると、すべてのデバイスにわたってストール（EPIPE）、タイムアウト、バブル、CRCエラーが一度に表示されます。
• 不正デバイスの発見 — 新しく接続されたデバイスが、接続直後に何を行うかを表示します。BadUSB形式のHIDインジェクションは、トリガーしていないINTレポートやSET_REPORTコントロール書き込みとして現れます。
• オフライン解析のためのキャプチャ — --jsonでNDJSONを出力。jqにパイプするかファイルに保存して、複数回の実行間でペイロードを比較できます。
• パフォーマンスのトリアージ — タイマー終了時に、デバイスごとの集計とlog2レイテンシヒストグラムが表示され、遅いまたは過剰に通信するデバイスを見つけられます。

Install

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

その後、GitHubから直接実行できます — yeetが例を取得してビルドするため、クローンは不要です。

yeet run github:yeet-src/usbsnoop

Build

ローカルチェックアウトからビルドする場合：

make

カーネルのBTFをvmlinux.hにダンプ（struct urb、usb_device、デバイス記述子用）、その後コンパイル。clang、bpftool、BTF対応カーネルが必要です。

Run

yeet run .                              # すべてのデバイス、Ctrl-Cまで実行
yeet run . -- --secs 30                 # 30秒後に停止（サマリーを表示）
yeet run . -- --vid 0x320f              # 特定のベンダー
yeet run . -- --vendor-id 0x046d --product-id 0xc52b # IDでデバイスを指定
yeet run . -- --bus 3 --dev 4           # バスアドレスでデバイスを指定
yeet run . -- --type control,int        # これらの転送タイプのみ
yeet run . -- --no-data                 # メタデータのみ、ペイロードキャプチャをスキップ
yeet run . -- --max-data 64             # 表示するペイロードを64バイトに制限
yeet run . -- --errors-only             # 失敗した完了のみ（ストール、タイムアウト）
yeet run . -- --hex                      # 転送ごとに完全な複数行16進ダンプ
yeet run . -- --json | jq .             # NDJSON、イベントごとに1つのオブジェクト

Flags

すべてのフィルタリングはカーネル側で行われるため、フィルタリングされたトラフィックはユーザー空間に到達しません。

各イベント行の末尾には、所有するカーネルドライバが角括弧で表示されます（[hid_irq_in]、[usb_api_blocking_completion]） — urb->completeはカーネル内でbpf_snprintf("%ps")によりシンボル化されるため、/proc/kallsymsの参照は不要です。マスストレージのバルク転送では、Bulk-Only TransportラッパーがSCSIコマンド（CBW READ(10) lba=… blocks=… / CSW PASS）にデコードされます。タイマー終了時（--secsに達した場合）には、デバイスごとのサマリーとlog2レイテンシヒストグラムが表示されます。Ctrl-Cで終了した場合は表示されません（JSから見えるシグナルフックはありません）。

スキャッターギャザーペイロード

バルクトラフィック（マスストレージなど）は、多くの場合、単一の線形transfer_bufferではなくstruct scatterlist配列（urb->sg）をスタックに渡すため、ペイロードはページ全体に分散して存在します。usbsnoopはその配列を走査し、各セグメントのバイトをコピーしますが、それにアクセスするにはページをそのカーネル仮想アドレスに変換する必要があります — これはx86-64のpage_to_virtの逆であり、実行中のカーネルのpage_offset_baseとvmemmap_base（両方ともKASLRでランダム化）が必要です。

JS分離環境は/proc/kallsymsを読み取ることができず、ローダーにはksymサポートがないため、2つのシンボルアドレスを渡すと、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バイトのみがキャプチャされます（2の累乗 — 検証器の読み取りクランプがこれに依存します）。より大きなバッファは切り詰められます。ヘッダーには実際のactual/requested長が引き続き報告されます。各リングレコードは完全なdata[16384]を持つため、8 MiBリングには約512イベントが格納されます。
• スキャッターギャザーペイロードには、上記の--page-offset-base / --vmemmap-baseフラグとx86-64ホストが必要です。各セグメントは最大1ページまでキャプチャされ、転送の最初の64セグメントのみが走査されます。
• usbsnoopがアタッチされる前に送信された転送には開始タイムスタンプがないため、その完了にはレイテンシが表示されません。
• USB記述子はリトルエンディアンで直接読み取られます — BPFが実行されるリトルエンディアンホストでは正しい動作です。