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. Create a struct that implements ExtcapApplication. It is recommended to define the application in a lazy_static. There 4 things need to be provided for an extcap implementation:

    1. metadata: The version information and metadata for this program, used by Wireshark to display in the UI.
    2. interfaces: The list of interfaces that can be captured by this program.
    3. toolbar_controls: Optional, a list of toolbar controls shown in the Wireshark UI.
    4. configs: Optional, a list of UI configuration options that the user can change.

  3. In the main function, parse the arguments and call ExtcapArgs::run. Use the returned CaptureContext to start capturing packets, and write the packets to CaptureContext::fifo using the pcap_file crate.

    ⓘ
    fn main() -> anyhow::Result<()> {
    if let Some(capture_context) = AppArgs::parse().extcap.run(&*APPLICATION)? {
        // Run capture
    }
    Ok(())
}

Example

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

struct ExampleExtcapApplication {}
impl ExtcapApplication for ExampleExtcapApplication {
      fn metadata(&self) -> &Metadata { todo!() }
      fn interfaces(&self) -> &[Interface] { todo!() }
      fn toolbar_controls(&self) -> Vec<&dyn ToolbarControl> { todo!() }
      fn configs(&self, interface: &Interface) -> Vec<&dyn ConfigTrait> { todo!() }
}

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

lazy_static! {
    static ref APPLICATION: ExampleExtcapApplication = ExampleExtcapApplication {
        // ...
    };
}

fn main() -> anyhow::Result<()> {
    if let Some(capture_context) = AppArgs::parse().extcap.run(&*APPLICATION)? {
        // Run capture
    }
    Ok(())
}

References:

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

Structs

  • CaptureContext
    When this value is returned in ExtcapArgs::run, the implementation should use these returned values to start capturing 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

Enums

Traits

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.