r-extcap

使用 Rust 编写 extcap 程序。

extcap 接口是 Wireshark 用于允许外部二进制文件作为捕获接口的通用插件接口。extcap 接口本身是通用的，可以由除 Wireshark 之外的应用程序使用，如 Wireshark 的命令行兄弟 tshark。为了简洁起见，在文档中我们将主应用程序简称为 Wireshark。

extcap 概述

1. --extcap-interfaces：在这一步中，Wireshark 会请求 extcap 支持的接口列表、版本元数据和工具栏控件列表。
2. --extcap-dlts：为每个接口调用一次，Wireshark 会请求 extcap 程序提供与接口关联的数据链路类型。
3. --extcap-config：在用户请求时为每个接口调用，Wireshark 会请求 extcap 程序提供一个配置列表，以填充 UI 中的配置对话框。
4. --capture：extcap 程序的主要部分 - 在用户选择接口进行捕获时调用一次，告诉 extcap 开始捕获数据包。捕获到的数据包应按 PCAP 格式写入 --fifo。

入门

要使用此库创建 extcap，以下是高级步骤

1. 创建一个使用 #[derive(clap::Parser)] 的 struct，并将 ExtcapArgs 作为具有 #[command(flatten)] 属性的一个字段添加。

   #[derive(Debug, clap::Parser)]
   struct AppArgs {
       #[command(flatten)]
       extcap: r_extcap::ExtcapArgs,
   
       // Other args for extcap (see the `configs` module)
   }
   

2. 在 lazy_static 中，定义必要的 接口、工具栏控件 和 配置。如果您不确定，可以简单地从您想要捕获的 Interfaces 开始，以后根据需要添加其他内容。

3. 在 main 函数中，解析参数并调用 ExtcapArgs::run。使用返回的 ExtcapStep 执行请求的操作。共有 5 个步骤

   1. InterfacesStep：列出此程序可以捕获的接口，以及相关的元数据和工具栏控件。
   2. DltsStep：打印给定接口的 DLTs。
   3. ConfigStep：可选，提供用户可以更改的 UI 配置选项列表。
   4. ReloadConfigStep：可选，如果其中一个配置中配置了 SelectorConfig::reload，将调用以重新加载用户可以选择的选项列表。
   5. CaptureStep：下面将进行描述。

4. 在 CaptureStep 中，开始从外部接口捕获数据包，并使用 pcap_file 包写入数据包到 CaptureStep::fifo。

示例

use clap::Parser;
use r_extcap::{cargo_metadata, ExtcapArgs, ExtcapStep, interface::*, controls::*, config::*};

#[derive(Debug, Parser)]
struct AppArgs {
    #[command(flatten)]
    extcap: ExtcapArgs,
}

lazy_static! {
    // static ref CONFIG_FOO: SelectorConfig = ...;
    // static ref CONFIG_BAR: StringConfig = ...;

    // static ref CONTROL_A: BooleanControl = ...;

    // static ref INTERFACE_1: Interface = ...;
}

fn main() -> anyhow::Result<()> {
    match AppArgs::parse().extcap.run()? {
        ExtcapStep::Interfaces(interfaces_step) => {
            interfaces_step.list_interfaces(
                &cargo_metadata!(),
                &[
                    // &*INTERFACE_1,
                ],
                &[
                    // &*CONTROL_A,
                    // &*CONTROL_B,
                ],
            );
        }
        ExtcapStep::Dlts(dlts_step) => {
            dlts_step.print_from_interfaces(&[
                // &*INTERFACE_1,
            ])?;
        }
        ExtcapStep::Config(config_step) => config_step.list_configs(&[
            // &*CONFIG_FOO,
            // &*CONFIG_BAR,
        ]),
        ExtcapStep::ReloadConfig(reload_config_step) => {
            reload_config_step.reload_from_configs(&[
                // &*CONFIG_FOO,
                // &*CONFIG_BAR,
            ])?;
        }
        ExtcapStep::Capture(capture_step) => {
            // Run capture
        }
    }
    Ok(())
}

参考

• https://www.wireshark.org/docs/wsdg_html_chunked/ChCaptureExtcap.html
• https://www.wireshark.org/docs/man-pages/extcap.html
• https://gitlab.com/wireshark/wireshark/-/blob/master/doc/extcap_example.py

贡献

任何形式的贡献都受到欢迎。新功能、错误修复、文档改进、额外的测试或带有失败测试用例的 PR 都受欢迎。