Table of Contents

• Overview
• How to use
  • Validator
  • Generator
• Dissector format
  • Name
  • Endianess
  • Connection
  • Data
• Compatibility matrices
  • Numeric
  • Time
  • Raw
  • Specific
• Import dissector into wireshark
• Roadmap
• Related tools

Overview

Wirdigen (Wireshark Dissector Generator) is a small library that aims to generate LUA dissector for Wireshark based on a JSON description of the packet you want to analyze.

For more information about packet dissection, please refer to Wireshark documentation and wiki.

How to use

The library is composed of two tools:

Validator

Validator compare a JSON packet description with a predefined JSON schema to ensure data integrity for plugin generation.

If the packet description is invalid, errors are automatically reported to the user through stderr with detailled location/description.

use wirdigen::validator::Validator;
use wirdigen::error::WirdigenError;

fn foo() -> Result<(), WirdigenError> {
    // Load JSON file
    let file_path = "./example/example_dissector.json";
    let file = File::open(file_path)?;
    let rdr = BufReader::new(file);

    // Create serde JSON value from the file
    let value: Value = serde_json::from_reader(rdr)?;

    // Create Validator object
    let val = Validator::new()?;

    // Call to validation function
    match val.validate(&value) {
        true => println!("{}: VALID", file_path),
        false => println!("{}: INVALID", file_path)
    }
    Ok(())
}

Generator

Generator generate LUA plugin based on JSON input given by the user.

use wirdigen::generator::Generator;
use wirdigen::error::WirdigenError;

fn foo() -> Result<(), WirdigenError> {
    // Load JSON file
    let file_path = "./example/example_dissector.json";
    let file = File::open(file_path)?;
    let rdr = BufReader::new(file);

    // Create Generator object
    let gen = Generator::default();
    // let gen = Generator::new();   <-- Alternative

    // Generate from a reader source
    let generated_file_path: String = gen.from_reader(rdr)?;
    println!("Generated: {}", generated_file_path);

    Ok(())
}

Note: The Generator does not perform any pre-validation on the user input. This is the role of the Validator. In case of invalid file, method from Generator will return appropriate Err(WirdigenError). To avoid these kinds of problem, it's best to first perform a validation and, then, generate the LUA dissector.

Generator object also have a from_value method in order to reuse the serde-json Value from the validation task for the generation.

fn foo() -> Result<(), WirdigenError> {
    // Open the JSON file
    let file_path = "./example/example_dissector.json";
    let file = File::open(file_path)?;
    let rdr = BufReader::new(file);

    // Create serde JSON value from the file
    let value: Value = serde_json::from_reader(rdr)?;

    // Create Validator object
    let val = Validator::new()?;

    // Call to validation method
    if val.validate(&value) {
        // Create Generator object
        let gen = Generator::default();

        // Generate plugin from validated data
        let generated_file_path: String = gen.from_value(value)?;
        println!("{}", generated_file_path);
    }
    else {
        println!("Invalid user input: {}", file_path);
    }
    
    Ok(())
}

By default, the plugin is generated in the temporary folder defined in environment variable. The user can modify the output directory through set_output_directory() method and retrieve the current one through get_output_directory().

fn foo {
    let mut gen = Generator::default();

    println!("{}", gen.get_output_directory());

    let new_output = "/Documents/MyDissectors";
    gen.set_output_directory(new_output);

    println!("{}", gen.get_output_directory());
}

Note: The method set_output_directory does not create non-existant directory from user input. If the output directory is not reachable, the error will be propagated from the generation method when trying to create the final LUA file.

Dissector format

A JSON dissector description is composed of 4 elements:

• name
• endianness
• connection
• data

Name

name element is a string (max size: 32) representing the name of the protocol to dissect that will be used inside Wireshark ("Protocol" column) to identify your packet.

Note: This name is also used for the generated LUA file. For example, if the attribute is MY_PROTO, the generated plugin will be called dissector_MY_PROTO.lua.

Endianness

String defining which endianness is used by the protocol. Possible values are little and big.

Connection

The connection object contains 2 fields :

• protocol: String. Either udp or tcp.
• ports: Array of port the dissector need to spy (between 1 and 65535).

Data

data is an array of object describing the packet. Each object define a chunk of the packet we want to identify.

Each chunk contains the following attributes:

• name: String (max size: 32).
• format: String representing the data type of the chunk. Refer to format/base matrices below for available values.
• base: String representing how the value should be displayed. Refer to format/base matrices below for available values.
• offset: Position offset, in byte, from the begining of the packet.
• size: Size, in byte, of the chunk inside the packet.
• valstr (Optional) : Array of value/string object to identify specific values in the payload. See below for more information.

About strval:

This attribute can be used to identify and replace specific value by its string representation (max size: 32). For instance, when dealing with webpage status code, it can be usefull to view status code 404 as "NOT FOUND" or 200 as "OK" inside wireshark capture view. This example can be described as follow inside the dissector JSON file :

{
    ..., // First part of data chunk description
    "valstr" : [
        { "value": 404, "string": "NOT FOUND" },
        { "value": 200, "string": "OK"}
    ]
}

Format/Base compatibility matrices

These matrices show which format/base combination are supported by Wirdigen.

Numeric

(*) = For the specified format, the base is ignored by Wireshark.

Time

(*) = For the specified format, the base is ignored by Wireshark.

Raw

Specific

For these specific type of data, display is automatically handled by Wirehsark. Hense, base is ignored. I would recommend using NONE in these case.

• none
• ipv4
• ipv6
• ether
• guid
• oid

Import dissector into Wireshark

First, you need to check in which directory Wireshark is looking for LUA plugin.

To do this, open Wireshark and go to help -> About Wireshark -> Folder.

Find the path associated to "Personal Lua plugins". This is where you need to copy your dissector. If the path does not exist on your machine, you can manually create missing directories.

The dissector script will be active after Wireshark is refreshed. You can either restart Wireshark or press Ctrl + Shift + L to reload all Lua scripts.

Note: You need to reload/restart everytime you make a change in a dissector.

Roadmap

• Missing data type:

  • framenum
  • string
  • stringz
  • ubytes
  • protocol
  • rel_oid
  • systemid
  • eui64

• Support for child subtree to clearly describe more complex packet.

Related tools

• rust_dissector_generator: Simple executable using Wirdigen library
• rust_dissector_udp: Send custom packet over UDP to test generated plugin by the library inside wireshark.