pyshark

このリポジトリは、Python2.7+ で動作する pyshark のレガシーバージョン用です。バージョン 0.3.8 以降はバグ修正のみが行われます。
Python 3.5+ のみをサポートする新しいバージョンについては、メインリポジトリ をご利用ください。

tshark の Python ラッパー。Wireshark のディセクタを使用した Python でのパケット解析を可能にします。

拡張ドキュメント: http://kiminewt.github.io/pyshark

Python のパケット解析モジュールはいくつか存在しますが、このモジュールが異なる点は、実際にパケットを解析するのではなく、tshark（Wireshark のコマンドラインユーティリティ）が XML をエクスポートする機能を利用して解析を行うところです。

このパッケージを使用すると、インストールされているすべての Wireshark ディセクタを使って、キャプチャファイルまたはライブキャプチャから解析を行うことができます。 Windows/Linux でテスト済みです。

インストール

すべてのプラットフォーム

pypi から最新版をインストールするには、以下のコマンドを実行してください。

pip install pyshark-legacy

または、Git リポジトリからインストールします。

git clone https://github.com/KimiNewt/pyshark-legacy.git
cd pyshark/src
python setup.py install

Mac OS X

libxml のインストールが必要になる場合があり、予期せぬエラーが発生することがあります。clang のエラーや libxml に関するエラーメッセージが表示された場合は、以下を実行してください。

xcode-select --install
pip install libxml

おそらく XCode の使用許諾契約（EULA）への同意が必要になるので、GUI の「承諾」ダイアログをクリックできるように準備しておいてください。

使用法

キャプチャファイルからの読み取り:

>>> import pyshark
>>> cap = pyshark.FileCapture('/tmp/mycapture.cap')
>>> cap
<FileCapture /tmp/mycapture.cap (589 packets)>
>>> print cap[0]
Packet (Length: 698)
Layer ETH:
        Destination: BLANKED
        Source: BLANKED
        Type: IP (0x0800)
Layer IP:
        Version: 4
        Header Length: 20 bytes
        Differentiated Services Field: 0x00 (DSCP 0x00: Default; ECN: 0x00: Not-ECT (Not ECN-Capable Transport))
        Total Length: 684
        Identification: 0x254f (9551)
        Flags: 0x00
        Fragment offset: 0
        Time to live: 1
        Protocol: UDP (17)
        Header checksum: 0xe148 [correct]
        Source: BLANKED
        Destination: BLANKED
  ...

その他のオプション

• param keep_packets: パケットを next() で読み取った後も保持するかどうか。大きなキャプチャを読み取る際にメモリを節約するために使用します。
• param input_file: パスまたはファイルライクオブジェクト。パケットキャプチャファイル（PCAP、PCAP-NG など）または TShark XML のいずれかを含みます。
• param display_filter: キャプチャを読み取る前に適用する表示（Wireshark）フィルター。
• param only_summaries: パケットサマリーのみを生成します。はるかに高速ですが、含まれる情報は非常に少なくなります。
• param disable_protocol: プロトコルの検出を無効にします（tshark バージョン 2 以降）。
• param decryption_key: キャプチャしたトラフィックの暗号化および復号に使用するキー。
• param encryption_type: キャプチャしたトラフィックで使用される暗号化の標準（'WEP'、'WPA-PWD'、'WPA-PWK' のいずれか。デフォルトは WPA-PWK）。
• param tshark_path: tshark バイナリのパス。

ライブインターフェースからの読み取り:

>>> capture = pyshark.LiveCapture(interface='eth0')
>>> capture.sniff(timeout=50)
>>> capture
<LiveCapture (5 packets)>
>>> capture[3]
<UDP/HTTP Packet>

for packet in capture.sniff_continuously(packet_count=5):
    print 'Just arrived:', packet

その他のオプション

• param interface: キャプチャするインターフェースの名前。指定しない場合は、最初に利用可能なインターフェースが使用されます。
• param bpf_filter: パケットに適用する BPF フィルター。
• param display_filter: 使用する表示（Wireshark）フィルター。
• param only_summaries: パケットサマリーのみを生成します。はるかに高速ですが、含まれる情報は非常に少なくなります。
• param disable_protocol: プロトコルの検出を無効にします（tshark バージョン 2 以降）。
• param decryption_key: キャプチャしたトラフィックの暗号化および復号に使用するキー。
• param encryption_type: キャプチャしたトラフィックで使用される暗号化の標準（'WEP'、'WPA-PWD'、'WPA-PWK' のいずれか。デフォルトは WPA-PWK）。
• param tshark_path: tshark バイナリのパス。
• param output_file: キャプチャしたパケットをこのファイルに追加で保存します。

リングバッファを使用したライブインターフェースからの読み取り

>>> capture = pyshark.LiveRingCapture(interface='eth0')
>>> capture.sniff(timeout=50)
>>> capture
<LiveCapture (5 packets)>
>>> capture[3]
<UDP/HTTP Packet>

for packet in capture.sniff_continuously(packet_count=5):
    print 'Just arrived:', packet

その他のオプション

• param ring_file_size: リングファイルのサイズ（kB 単位）。デフォルトは 1024。
• param num_ring_files: 保持するリングファイルの数。デフォルトは 1。
• param ring_file_name: リングファイルの名前。デフォルトは /tmp/pyshark.pcap。
• param interface: キャプチャするインターフェースの名前。指定しない場合は、最初に利用可能なインターフェースが使用されます。
• param bpf_filter: パケットに適用する BPF フィルター。
• param display_filter: 使用する表示（Wireshark）フィルター。
• param only_summaries: パケットサマリーのみを生成します。はるかに高速ですが、含まれる情報は非常に少なくなります。
• param disable_protocol: プロトコルの検出を無効にします（tshark バージョン 2 以降）。
• param decryption_key: キャプチャしたトラフィックの暗号化および復号に使用するキー。
• param encryption_type: キャプチャしたトラフィックで使用される暗号化の標準（'WEP'、'WPA-PWD'、'WPA-PWK' のいずれか。デフォルトは WPA-PWK）。
• param tshark_path: tshark バイナリのパス。
• param output_file: キャプチャしたパケットをこのファイルに追加で保存します。

リモートインターフェースからのライブ読み取り:

>>> capture = pyshark.RemoteCapture('192.168.1.101', 'eth0')
>>> capture.sniff(timeout=50)
>>> capture

その他のオプション

• param remote_host: キャプチャを実行するリモートホスト（IP またはホスト名）。rpcapd が実行されている必要があります。
• param remote_interface: リモートマシン上のリモートインターフェースでキャプチャするインターフェース。Windows では、デバイスの表示名ではなく、実際のインターフェース名（例：\Device\NPF_..）であることに注意してください。
• param remote_port: rpcapd サービスがリッスンしているリモートポート。
• param bpf_filter: キャプチャを読み取る前に適用する BPF（tcpdump）フィルター。
• param only_summaries: パケットサマリーのみを生成します。はるかに高速ですが、含まれる情報は非常に少なくなります。
• param disable_protocol: プロトコルの検出を無効にします（tshark バージョン 2 以降）。
• param decryption_key: キャプチャしたトラフィックの暗号化および復号に使用するキー。
• param encryption_type: キャプチャしたトラフィックで使用される暗号化の標準（'WEP'、'WPA-PWD'、'WPA-PWK' のいずれか。デフォルトは WPA-PWK）。
• param tshark_path: tshark バイナリのパス。

パケットデータへのアクセス:

データには複数の方法でアクセスできます。 パケットはレイヤーに分割されています。最初に適切なレイヤーに到達し、その後フィールドを選択します。

以下のすべてが機能します:

>>> packet['ip'].dst
192.168.0.1
>>> packet.ip.src
192.168.0.100
>>> packet[2].src
192.168.0.100

レイヤーがパケット内に存在するかどうかをテストするには、その名前を使用します:

>>> 'IP' in packet
True

すべてのフィールド名を確認するには、packet.layer.field_names 属性（例：packet.ip.field_names）またはインタプリタのオートコンプリート機能を使用します。

フィールドの元のバイナリデータや、その詳細な説明を取得することもできます:

>>> p.ip.addr.showname
Source or Destination Address: 10.0.0.10 (10.0.0.10)
# さらに新しい属性もあります:
>>> p.ip.addr.int_value
167772170
>>> p.ip.addr.binary_value
'\n\x00\x00\n'

パケットキャプチャの復号化

Pyshark は、WEP、WPA-PWD、WPA-PSK の各標準を使用したトレースの自動復号化をサポートしています（デフォルトは WPA-PWD）。

>>> cap1 = pyshark.FileCapture('/tmp/capture1.cap', decryption_key='password')
>>> cap2 = pyshark.LiveCapture(interface='wi0', decryption_key='password', encryption_type='wpa-psk')

サポートされている暗号化標準のタプル SUPPORTED_ENCRYPTION_STANDARDS が各キャプチャクラスに存在します。

>>> pyshark.FileCapture.SUPPORTED_ENCRYPTION_STANDARDS
('wep', 'wpa-pwd', 'wpa-psk')
>>> pyshark.LiveCapture.SUPPORTED_ENCRYPTION_STANDARDS
('wep', 'wpa-pwd', 'wpa-psk')

ライセンス

このプロジェクトは MIT ライセンスの下で提供されています。このプロジェクトへのコントリビューションは、同じライセンスの下で受け付けられます。