Extend Tshark with Lua Scripts

Introduction

In this lab, you will learn how to extend Wireshark's packet analysis capabilities using Lua scripting. You'll explore loading custom scripts via command-line options and passing arguments to enhance functionality.

The exercises guide you through creating Lua scripts, testing them with Wireshark's tshark command, and verifying output. You'll practice script execution with empty captures and learn to interpret verbose packet details.

Skills Graph

Load Script with -X lua_script:script.lua

In this step, you will learn how to load a Lua script in Wireshark using the -X option. Lua is a lightweight scripting language that integrates well with Wireshark, allowing you to extend its functionality for custom packet analysis without modifying the core program.

First, let's create a simple Lua script in the default working directory. This script will serve as our basic test case to verify that Wireshark can successfully load and execute Lua code:

1. Open a terminal and ensure you're in the ~/project directory. This is where we'll create and store our Lua script:

   cd ~/project

2. Create a new Lua script file named script.lua using nano. We're using nano because it's simple and available in most Linux environments:

   nano script.lua

3. Add the following basic Lua code to print a message when loaded. This demonstrates the most fundamental operation - verifying script execution:

   -- Simple Wireshark Lua script
   print("Wireshark Lua script loaded successfully!")

4. Save the file (Ctrl+O, Enter) and exit nano (Ctrl+X). The script is now ready to be loaded by Wireshark.

Now let's load this script using Wireshark's command-line interface. We'll use a special combination of parameters to test the script without processing actual network traffic:

wireshark -X lua_script:script.lua -r /dev/null -k

Let's break down what each part of this command does:

• -X lua_script:script.lua tells Wireshark to load our Lua script file
• -r /dev/null specifies an empty capture file (we're just testing script loading, not analyzing packets)
• -k starts the capture immediately without waiting for user input

When you run this command, you should see the message "Wireshark Lua script loaded successfully!" in the terminal output. This confirms that Wireshark successfully located, loaded, and executed your Lua script. If you don't see this message, check that the script file exists in the correct location and contains no syntax errors.

Pass Argument with -X lua_script1:arg1

In this step, you will learn how to pass arguments to a Lua script in Wireshark using the -X lua_script1: option. This technique is useful when you want to make your scripts more flexible by accepting different inputs without modifying the script itself each time.

First, let's understand how argument passing works in Wireshark's Lua environment. The -X lua_script1: option allows you to send a string value to your script, which can then be accessed using the get_string() function. This is similar to how command-line arguments work in other programming languages.

Let's modify our existing Lua script to accept and process an argument:

1. Open the script.lua file from the previous step:

   nano ~/project/script.lua

2. Replace the content with the following code that accepts and displays an argument:

   -- Lua script with argument handling
   local arg1 = get_string("lua_script1")
   print("Received argument: " .. (arg1 or "no argument provided"))

   The get_string("lua_script1") function retrieves the argument passed with -X lua_script1:. The or "no argument provided" part provides a default message if no argument was given.

3. Save the file (Ctrl+O, Enter) and exit nano (Ctrl+X).

Now let's execute the script with an argument:

wireshark -X lua_script:script.lua -X lua_script1:test123 -r /dev/null -k

Breaking down this command:

• -X lua_script:script.lua loads our Lua script file
• -X lua_script1:test123 passes "test123" as an argument to the script
• -r /dev/null specifies an empty capture file (since we're just testing the script)
• -k starts the capture immediately without waiting for user input

You should see output similar to:

Received argument: test123

To verify the script works with different inputs, try running it with another value:

wireshark -X lua_script:script.lua -X lua_script1:another_value -r /dev/null -k

This demonstrates how you can reuse the same script with different arguments, making your analysis more dynamic and adaptable to different scenarios.

Process File with -r capture.pcap

In this step, you'll learn how to process a pre-recorded network capture file using Wireshark's command-line tool Tshark with the -r option. This is useful when you want to analyze saved network traffic rather than capturing live packets.

First, we need a sample packet capture file to work with. PCAP files contain actual network traffic data that we can analyze. Let's download a standard HTTP traffic sample:

1. Download a sample pcap file to your project directory:

   wget https://wiki.wireshark.org/SampleCaptures/http.cap -O ~/project/capture.pcap

2. Verify the file was downloaded correctly by checking its size and location:

   ls -lh ~/project/capture.pcap

Now we'll modify our Lua script to analyze this capture file. The script will count all packets in the file and report the total. Here's how to update it:

1. Open the script for editing:

   nano ~/project/script.lua

2. Update the content with this packet counting logic:

   -- Packet counter script
   local arg1 = get_string("lua_script1") or "default"
   local packet_count = 0
   
   -- Called for each packet
   function tap.packet(pinfo,tvb)
       packet_count = packet_count + 1
   end
   
   -- Called after processing all packets
   function tap.draw()
       print("Argument received: " .. arg1)
       print("Total packets processed: " .. packet_count)
   end
   
   -- Register the tap
   tap = Listener.new()

3. Save the file (Ctrl+O, Enter) and exit nano (Ctrl+X).

Now let's run our script against the capture file. This command tells Tshark to:

• Use our Lua script (-X lua_script)
• Pass an argument to the script (-X lua_script1)
• Process our downloaded file (-r)
• Run quietly without GUI (-q)

wireshark -X lua_script:script.lua -X lua_script1:analysis -r ~/project/capture.pcap -q

After processing, you should see output showing:

• The argument we passed to the script
• The total number of packets counted

Example output:

Argument received: analysis
Total packets processed: 83

Check Custom Output with -V

In this step, we'll explore how to verify the output of your Lua script using Wireshark's -V (verbose) option. This is particularly useful when you need to see detailed analysis results from your custom script alongside the standard packet information.

First, let's improve our Lua script to provide more meaningful statistics. We'll modify it to track different protocol types:

1. Open the script for editing in nano:

   nano ~/project/script.lua

2. Update the script with this enhanced version that counts HTTP and TCP packets:

   -- Enhanced packet analyzer
   local arg1 = get_string("lua_script1") or "default"
   local stats = {
       total = 0,
       http = 0,
       tcp = 0
   }
   
   function tap.packet(pinfo,tvb)
       stats.total = stats.total + 1
       if pinfo.visited then return end
   
       if pinfo.protocols:find("http") then
           stats.http = stats.http + 1
       end
       if pinfo.protocols:find("tcp") then
           stats.tcp = stats.tcp + 1
       end
   end
   
   function tap.draw()
       print("=== Analysis Report ===")
       print("Argument received: " .. arg1)
       print("Total packets: " .. stats.total)
       print("HTTP packets: " .. stats.http)
       print("TCP packets: " .. stats.tcp)
       print("======================")
   end
   
   tap = Listener.new()

3. Save the file (Ctrl+O, Enter) and exit nano (Ctrl+X).

Now let's execute our script with verbose output enabled. The -V flag tells Wireshark to display all available information, including our custom script output:

wireshark -X lua_script:script.lua -X lua_script1:final_run -r ~/project/capture.pcap -q -V

You should see output similar to this, showing both packet details and your script's analysis:

=== Analysis Report ===
Argument received: final_run
Total packets: 83
HTTP packets: 10
TCP packets: 83
======================

To save this output for future reference, redirect it to a file:

wireshark -X lua_script:script.lua -X lua_script1:final_run -r ~/project/capture.pcap -q -V > ~/project/analysis_output.txt

Finally, verify the saved output by viewing the file contents:

cat ~/project/analysis_output.txt

Summary

In this lab, you have learned how to extend Wireshark's functionality using Lua scripts through command-line operations. The key steps included loading Lua scripts with the -X lua_script:script.lua option and testing them with Wireshark's CLI interface.

Additionally, you explored passing arguments to Lua scripts using -X lua_script1:arg1, demonstrating how to create flexible scripts that accept external parameters. This technique enhances Wireshark's packet analysis capabilities through customizable Lua extensions.