Crate r_extcap

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:

• 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

Modules

• config
  Module for implementing extcap config (also known as arg), which are UI elements shown in Wireshark that allows the user to customize the capture.
• controls
  Module to interact with the controls for the extcap program. There are two aspects of “controls” handled in this module:
• interface
  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

• cargo_metadata
  Creates a Metadata from information in Cargo.toml, using the mapping as follows:

Structs

• CaptureStep
  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.
• ConfigStep
  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.
• DltsStep
  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.
• ExtcapArgs
  The arguments defined by extcap. These arguments are usable as a clap parser.
• ExtcapFormatter
  The extcap interface expects certain output “sentences” to stdout to communicate with Wireshark, like
• InterfacesStep
  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.
• ReloadConfigStep
  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

• CaptureError
  Error during the --capture phase of extcap.
• ExtcapError
  Error reported when running ExtcapArgs::run.
• ExtcapStep
  The step of extcap to execute, which is returned from ExtcapArgs::run. Each step has its own type which contains the relevant methods for each step. See the docs for each individual step to for details on what operations should be performed.
• ListConfigError
  Error listing configs.
• PrintDltError
  Error printing DLTs to Wireshark.
• ReloadConfigError
  Error when reloading configs. Config reload happens when a config, like crate::config::SelectorConfig specifics the reload field and the user clicks on the created reload button.

Traits

• PrintSentence
  Elements that has a printable extcap sentence. See the documentation for ExtcapFormatter for details.

Functions

• installation_instructions
  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.