KimiNewt/pyshark
GitHub: KimiNewt/pyshark
tshark 的 Python 封装库，通过调用 Wireshark 协议解析器实现强大的数据包解析能力。
Stars: 2475 | Forks: 445
# pyshark
tshark 的 Python 封装库，允许使用 Wireshark dissectors 进行 Python 数据包解析。
扩展文档：https://github.com/KimiNewt/pyshark-legacy
**寻找贡献者** - 由于各种原因，我目前很难抽出时间来维护和增强这个包。任何 pull-request 都会被审查，如果有任何人感兴趣且合适，我将很高兴将他们纳入项目中。随时可以通过 dorgreen1 at gmail 给我发邮件。
有不少 Python 数据包解析模块，这个模块之所以不同，是因为它实际上并不解析任何数据包，它只是利用 tshark（wireshark 命令行工具）导出 XML 的能力来使用其解析功能。
这个包允许使用你安装的所有 wireshark dissectors，从捕获文件或实时捕获中进行解析。
已在 Windows/Linux 上测试。
## 安装
### 版本支持
支持 Python 3.7+。存在一个不再受支持的 Python 2 版本，名为 [pyshark-legacy](https://github.com/KimiNewt/pyshark-legacy)。
支持所有现代版本的 tshark / wireshark，但某些功能在旧版本上可能不可用。
### 所有平台
只需运行以下命令即可从 pypi 安装最新版本
```
pip install pyshark
```
或者从 git 仓库安装：
```
git clone https://github.com/KimiNewt/pyshark.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
>>> 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
>>> capture[3]
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
>>> capture[3]
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
b'\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')
```
### 使用显示过滤器从文件读取
Pyshark 显示过滤器有助于分析应用程序聚焦的流量。
BPF 过滤器不如 Wireshark 的显示过滤器灵活。
```
>>> cap1 = pyshark.FileCapture('/tmp/capture1.cap', display_filter="dns")
>>> cap2 = pyshark.LiveCapture(interface='en0', display_filter="tcp.analysis.retransmission")
```
## 许可证
本项目根据 MIT 许可。对本项目的贡献接受相同的许可。
标签：DNS解析, GitHub搜索工具, PCAP, Pyshark, Python, Python封装, Tshark, Wireshark, 内核驱动, 协议分析, 句柄查看, 开发库, 开源项目, 抓包工具, 数据包解析, 无后门, 服务管理, 权限提升, 系统分析, 网络分析, 网络协议, 网络嗅探, 网络安全, 逆向工具, 防御绕过, 隐私保护