录制数据包捕获检查¶

inspect_packet_capture 回答 TShark 在现有捕获文件中观察到的选定协议字段。当已安装的 TShark 支持网络、USB 或蓝牙录制文件的封装格式和解剖器时，这些录制文件可以使用相同的字段/过滤器接口。此工具不会采集流量、打开接口或控制设备。HAR/SAZ/mitmproxy Web 捕获工作流保持独立。

在 Linux 上提供现有的 TShark 4.x 安装，且 util-linux prlimit 位于 /usr/bin/prlimit。如有需要，可通过 REA_TSHARK_PRLIMIT_COMMAND 覆盖其绝对路径。包括 macOS 和 Windows 在内的不受支持的主机在检查前会被拒绝，因为此集成需要强制执行的地址空间限制。

TShark 的选择遵循与 inspect_pcap_capture 相同的规则：使用绝对的 REA_TSHARK_COMMAND，否则从第一个包含可执行文件的绝对 PATH 条目中选取 tshark。相对路径的 REA_TSHARK_COMMAND 会被拒绝，而不会进行查找。无论哪种方式，选定的可执行文件都会被解析、计算哈希并在每次运行后重新检查，Evidence 会记录其 selection_source（environment 或 path）：

export REA_TSHARK_COMMAND=/absolute/path/to/tshark   # optional when tshark is on PATH
rea inspect-packet-capture /artifacts/device.pcapng \
  --fields ip.addr --fields udp.port --fields data.data \
  --display_filter 'udp' --format json

对应的 MCP 调用是：

{
  "name": "inspect_packet_capture",
  "arguments": {
    "path": "/artifacts/device.pcapng",
    "fields": ["ip.addr", "udp.port", "data.data"],
    "display_filter": "udp"
  }
}

frame.number 始终包含在内。重复值是有序字符串数组，例如 "ip.addr": ["192.0.2.1", "192.0.2.2"]。缺失字段保持缺席状态；不会转换为零或空数组。仅用于导出的索引/评分元数据会被丢弃。不会自动添加载荷字节；需要时请选择受支持的字节字段，例如 data.data 或 @data。

选择器在 argv 展开前受到限制：最多 1,024 个字段和 1,024 条 decode_as 规则，每个选择器 8,192 个 UTF-16 代码单元，以及总共 32 KiB 的编码后选择器参数（UTF-8 文本、终止符、选项名称和 argv 指针）。这为 Linux 的 execve 参数/环境限制 留出了余量；异常庞大的继承环境仍可能阻止启动。

输出在过滤后进行分页：match_limit 默认为 50，match_offset 默认为 0。结果保留原始帧编号，并报告 output_window，其中包含输入读取范围内的匹配数、返回计数和 has_more。使用偏移量请求后续页面，或使用显式 match_limit: null（CLI 为 --all_matches）获取所有剩余匹配。分页不会缩短输入读取，也不会改变两遍重组。生产者输出仍必须符合其资源限制；当解剖输出过大时，请使用选定字段、显示过滤器或输入数据包限制。每次调用都会检查录制文件的当前摘要，因此不同来源摘要的页面不得合并。

对于关于已知输入前缀的问题，请为该前缀选择 packet_limit、回答问题所需的字段以及匹配的输出窗口。例如，关于原始帧 1–2,000 内前十二个 PostgreSQL TCP 数据包的问题，可以使用字段 tcp.srcport、tcp.dstport、tcp.flags，过滤器 tcp.port == 5432，packet_limit: 2000 和 match_limit: 12。此时的匹配计数描述的是该输入前缀。包含 frame.number <= 2000 而没有输入限制的过滤器仍会读取整个捕获文件；返回十二行并不会限制生产者输出。这些控制用于回答有界的问题，不得用于推断整个捕获文件中不存在相关流量。

使用 inspect_packet_fields 发现不熟悉的字段名称，使用精确的协议和狭窄的查询。如果已安装的名称已经确定，直接选择字段可避免额外的术语表探测。在比较调查成本时，请将发现过程和任何重试计入；仅凭一个小页面并不能证明工作流更快。

其他选择：

• display_filter：Wireshark 显示过滤器语法；省略表示不过滤。
• decode_as：显式解剖器覆盖，例如 ["udp.port==5555,dns"]。在 CLI 中重复 --decode_as 以指定多个覆盖。
• packet_limit：可选的最大 过滤前读取的输入数据包数。因此，即使后续帧匹配，限制为 1 也可能产生零个匹配数据包。省略表示在资源限制内读取到 EOF。报告记录 to-eof 或 up-to-input-packet-limit，绝不会根据返回的数据包计数推断捕获文件总大小。
• two_pass：对于需要后续数据包和重组依赖的字段，默认值为 true。MCP 可设为 false；CLI 使用 --no-two_pass 进行单遍处理。

字段名称、显示过滤器、decode-as 语法和遍处理语义请参阅 TShark 手册。无效的字段或过滤器会返回生产者诊断信息。空结果并不能证明所选录制、过滤器或读取范围之外不存在流量。解剖器结果是观察结果，而非独立验证的设备行为。TShark 可能会将选定的别名解析为数据包输出中的规范字段名称；报告会保留所请求的确切选择和生产者的输出键。

Evidence 包括源路径/摘要/大小、确切选择、类型化数据包字段、配置的和解析出的可执行文件路径/摘要/完整版本横幅、参数和 stderr。即使退出码为零，警告仍然可见。tool.version_diagnostics 也会保留来自单独版本探测的警告。运行后的身份校验失败会标识受影响的私有副本、可执行文件或限制器；资源信号错误会保留信号和有效上限。两遍模式无法恢复缺失的捕获字节。

每次调用使用私有只读捕获副本和空个人配置目录（WIRESHARK_CONFIG_DIR），并禁用名称解析。执行后重新检查可执行文件、资源限制器和私有输入副本。其拥有的进程、文件描述符和私有文件会被清理；清理失败则保留所有权和已完成观察结果以供重试。一次性 CLI 会等待清理重试，同时保留原始失败和已完成的 Evidence。取消或清理失败后，已完成的观察结果仍保留在 MCP 会话中；有界的运行后完整性检查会在响应迟到的中止请求之前完成。源文件绝不会传递给 TShark。已安装的库、全局配置和插件仍然受信任，不会被完整指纹识别，并可能影响解剖。这不是操作系统沙箱。

输入在读取前限制为 32 MiB，每个命令限制为 30 秒，采集期间合并的 stdout/stderr 限制为 4 MiB。输出溢出时直接失败，而不是返回截断的成功结果。执行前，prlimit 强制实施每进程 1 GiB 地址空间、每文件 64 MiB、30 CPU 秒且禁止核心转储。继承的更严格的软/硬限制会被保留；Evidence 记录有效的上限。两个限制都在执行前设置，因此解析器分配和压缩抓包展开不能超过每进程地址空间上限。这些并非进程内存总量或文件系统配额。所选限制器是受信任的；其路径、摘要和参数均保留在 Evidence 中。不接受任意进程标志。

验证¶

npm run build:cached
REA_TSHARK_COMMAND=/absolute/path/to/tshark node scripts/verify-packet-capture.mjs

验证器会生成自己的 Ethernet/IPv4/UDP/DNS 和 Bluetooth HCI PCAP 文件。它测试了真实的编译后 CLI/MCP 一致性、公布的 schema、重复/缺失字段、过滤、decode-as、两种传递模式、匹配帧之前的包数量限制、Evidence 持久化、失败诊断、来源身份和清理。一个可选的位置参数 REA 入口点可验证已安装的软件包。

真实工具通道要求 Linux 和 TShark 4.x。单独的内核限制回归测试检查继承的软/硬限制，并验证超大的分配在被其消耗内存之前即被拒绝。Ubuntu 工作流使用其发行版软件包；在声称该构建已验证之前，请检查其结果。之前的 macOS 检查并不能证明当前有界集成的有效性，后者明确拒绝不支持的主机。其他格式（包括 PCAPNG）、USB、BLE ATT 和实际的物理抓包均不由这些测试夹具验证。

每个提供者一次只允许一项检查，包括采集和清理。被占用的提供者在获取另一个文件或工作进程之前会返回可重试的容量错误。关闭提供者会停止新的准入并排空已接受的工作；失败的清理仍归其所有，并且可以重试。

发现协议和字段名¶

inspect_packet_fields / inspect-packet-fields 在选择用于抓包检查的字段之前，会查询已安装的 TShark 注册术语表：

rea inspect-packet-fields --query usb
rea inspect-packet-fields --kind fields --protocol usb --query idVendor
rea inspect-packet-fields --kind fields --protocol udp --all

kind 默认为 protocols；fields 选择字段定义。protocol 选择精确的协议缩写（协议本身或其子字段）。query 是名称、缩写或字段描述中的不区分大小写的字面子串。offset 跳过匹配的记录；limit 默认为 50。MCP limit: null 或 CLI --all 请求在资源预算内返回所有剩余匹配项。--all 和 --limit 互斥。窗口会报告所选种类在过滤前检查的记录数、匹配的记录数、返回的记录数以及 has_more；它从不计算抓包数据包。

返回的记录保留字段类型、父协议、显示基数、位掩码、描述和原始术语表行号。空的生产者字符串保持为空；协议记录的仅字段属性为 null。重复的缩写保持为单独的注册项。列出的字段表示安装能力，而非该字段出现在所选录制中的证明。

适配器在其现有私有空配置文件和 Linux 进程限制下，使用文档化的 tshark -G fields 语法。TShark 4.6.9 的完整术语表测量为 22,303,197 字节；发现（discovery）最多接受 32 MiB 合并命令输出（抓包检查仍为 4 MiB）。解析只遍历行一次，并且仅为所选页面构建对象。返回的字符串会被复制，因此保留的页面不会保留完整的术语表字符串。在构造所选记录之前，它会按源 UTF-8 字节数的六倍加上 512 字节，对 8 MiB 的表示预算计费，以覆盖 JSON 转义和记录记账。如果该预算将被超出，请缩小查询或页面大小；结果不会被静默截断。这是保守的准入预算，而非实测堆使用量。父管道缓冲区和生产者每进程限制仍保持独立。

工具/限制器身份、版本、stderr 和所选参数均保留在 Evidence 中。不会打开任何抓包、接口或设备。发现共享抓包分析的准入槽位和清理所有者。每次调用都会重新读取术语表；已安装的插件、库和全局配置保持受信任，且不会被完全指纹识别。不存在缓存或快照一致性分页的声明。真实 Linux 通道会将公开的 CLI/MCP 查询与直接术语表进行比较，包括 USB vendor-ID 类型、负查询和分页。