Crate r_extcap

source ·
Expand description

Write extcap programs in Rust.

The extcap interface is a versatile plugin interface used by Wireshark to allow external binaries to act as capture interfaces. The extcap interface itself is generic and can be used by applications other than Wireshark, like Wireshark’s command line sibling tshark. For the sake of brevity, in the documentation we will refer to the host application simply as Wireshark.

§Extcap overview

  1. --extcap-interfaces: In this step, Wireshark asks the extcap for its list of supported interfaces, version metadata, and the list of toolbar controls.
  2. --extcap-dlts: Invoked once for each interface, Wireshark asks the extcap program for the data link type associated with the interface.
  3. --extcap-config: Invoked for each interface upon user request, Wireshark asks the extcap program for a list of configurations to populate a config dialog in the UI.
  4. --capture: The main part of the extcap program – invoked once when the user selects an interface for capture, to tell the extcap to start capturing packets. Captured packets should be written to the --fifo in the PCAP format.

§Getting started

To create an extcap using this library, these are the high level steps:

  1. Create a struct with #[derive(clap::Parser)], and add ExtcapArgs as one of the fields with the #[command(flatten)] attribute.

    #[derive(Debug, clap::Parser)]
    struct AppArgs {
        #[command(flatten)]
        extcap: r_extcap::ExtcapArgs,
    
        // Other args for extcap (see the `configs` module)
    }
  2. In a lazy_static, define the necessary interfaces, toolbar controls, and configs. If you are unsure, you can simply start with the Interfaces you want to capture and add the others later as needed.

  3. In the main function, parse the arguments and call ExtcapArgs::run. Use the returned ExtcapStep to perform the requested operation. There are 5 steps:

    1. InterfacesStep: List the interfaces that can be captured by this program, as well as the metadata and toolbar controls associated.
    2. DltsStep: Prints the DLTs for a given interface.
    3. ConfigStep: Optional, provide a list of UI configuration options that the user can change.
    4. ReloadConfigStep: Optional, if SelectorConfig::reload is configured in one of the configs, invoked to reload the list of options the user can choose from.
    5. CaptureStep: described below.
  4. In the CaptureStep, start capturing packets from the external interface, and write the packets to CaptureStep::fifo using the pcap_file crate.

§Example

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(())
}

References:

Modules§

  • Module for implementing extcap config (also known as arg), which are UI elements shown in Wireshark that allows the user to customize the capture.
  • Module to interact with the controls for the extcap program. There are two aspects of “controls” handled in this module:
  • Module containg code to define the extcap interfaces. These are data used to popuplate the Capture or interface list in the main page of Wireshark.

Macros§

Structs§

  • When this value is returned in ExtcapArgs::run, the implementation should use these returned values to start capturing packets from the external interface and write them to the fifo in PCAP format.
  • List the configurable UI elements for this interface. This is presented to the user when they click on the gear icon next to the capture interface name, or if they try to start a capture that is lacking a required config value.
  • In the DLTs step, Wireshark asks the extcap program for the DLT for each interface. DLT stands for data link type, and is used to determine how Wireshark analyzes (dissects) the given packets.
  • The arguments defined by extcap. These arguments are usable as a clap parser.
  • The extcap interface expects certain output “sentences” to stdout to communicate with Wireshark, like
  • List the interfaces and toolbar controls supported by this extcap implementation in stdout for Wireshark’s consumption. Corresponds to the --extcap-interfaces argument in extcap. Implementations should call list_interfaces during this step.
  • Reload operation for a particular configuration. This is invoked when the user clicks on the reload button created by a SelectorConfig with the reload field set. Corresponds to the --extcap-reload-option argument in extcap.

Enums§

Traits§

Functions§

  • Get the installation instructions. This is useful to show if the program is used in unexpected ways (e.g. not as an extcap program), so users can easily install with a copy-pastable command.